docs: product enablement

docs/guides/product_enablement.md

@@ -0,0 +1,43 @@
+______________________________________________________________________
+
+## page_title: Product Enablement subcategory: Guides
+
+## Product Enablement
+
+The [Product Enablement](https://developer.fastly.com/reference/api/products/enablement/) APIs allow customers to enable and disable specific products.
+
+Not all customers are entitled to use these endpoints and so care needs to be given when configuring a `product_enablement` block in your Terraform configuration.
+
+## Create
+
+When defining the `product_enablement` block in either your `fastly_service_compute` or `fastly_service_vcl` resource, if you set one attribute (e.g. `brotli_compression`), then the Create function inside the provider will check if the attribute value is set to `true`.
+
+Only if the product attribute is set to `true` will the provider attempt to enable the product.
+
+If a product is not defined in your Terraform config, it is assigned a default value of `false`, meaning none of those products will be 'disabled'.
+
+## Read
+
+The Read function is used to update the Terraform state file. The Terraform provider calls the Fastly API to identify if a product is enabled or not, and it will assign the relevant `true` or `false` values to the state file.
+
+If the Terraform configuration doesn't align with what the state file determines is how things are set up in the 'real world', then the Terraform plan/apply will indicate this in its diff when it compares the state file to your config file.
+
+## Update
+
+The Update function checks to see if the product has a different value to what it was set to originally (e.g. have you changed a product from `true` to `false` or vice-versa) and if it has been modified, then the value assigned to a product is compared to see if it's set to `true` or `false`.
+
+If it's set to `true`, then the provider will attempt to call the Fastly API to 'enable' that product. Otherwise, if the value is set to `false`, then the provider will attempt to call the Fastly API to 'disable' that product.
+
+The important part to pay attention to here is the 'entitlement' to call the Fastly API. Some customers don't have access to programmatically enable/disable products. Products have to then be set up manually by Fastly customer support.
+
+If you _do_ have programmatic access to the [Product Enablement](https://developer.fastly.com/reference/api/products/enablement/) APIs, then you should ensure the correct value is assigned in your Terraform configuration to avoid accidentally disabling a product.
+
+If you're unsure about whether you have API access, then we recommend reaching out to [support@fastly.com](mailto:support@fastly.com) to have them review your account settings.
+
+## Delete
+
+When deleting the `product_enablement` block from your Terraform configuration, the Delete function inside the provider will attempt to disable each product.
+
+If the API returns an error, then that error will be returned to the user and consequently the `terraform apply` will fail. But, the error is only returned if it is _not_ an error related to permissions/access to the API endpoint itself.
+
+This means, that if you delete the `product_enablement` block and you don't have access to disable Image Optimizer, then the error that is returned from the API to the Terraform provider will indicate that it failed because you don't have access to disable the product and that particular error will be ignored by the provider, subsequently allowing the `terraform apply` to complete successfully.

docs/index.md

@@ -15,7 +15,7 @@ Pricing and signup information can be found at https://www.fastly.com/signup
 Use the navigation to the left to read about the available resources.
 
 The Fastly provider prior to version v0.13.0 requires using
-[--parallelism=1](/docs/commands/apply.html#parallelism-n) for `apply` operations.
+[--parallelism=1](https://developer.hashicorp.com/terraform/cli/commands/apply#parallelism-n) for `apply` operations.
 
 ## Example Usage
 

docs/resources/service_compute.md

@@ -46,6 +46,14 @@ resource "fastly_service_compute" "example" {
 The `package` block supports uploading or modifying Wasm packages for use in a Fastly Compute@Edge service. See Fastly's documentation on
 [Compute@Edge](https://www.fastly.com/products/edge-compute/serverless)
 
+## Product Enablement
+
+The [Product Enablement](https://developer.fastly.com/reference/api/products/enablement/) APIs allow customers to enable and disable specific products.
+
+Not all customers are entitled to use these endpoints and so care needs to be given when configuring a `product_enablement` block in your Terraform configuration.
+
+Consult the [Product Enablement Guide](/docs/guides/product_enablement) to understand the internal workings for the `product_enablement` block.
+
 ## Import
 
 Fastly Services can be imported using their service ID, e.g.

docs/resources/service_vcl.md

@@ -210,9 +210,14 @@ Fastly documentation on [Amazon S3][fastly-s3].
 
 [fastly-s3]: https://docs.fastly.com/en/guides/amazon-s3
 [fastly-cname]: https://docs.fastly.com/en/guides/adding-cname-records
-[fastly-conditionals]: https://docs.fastly.com/en/guides/using-conditions
-[fastly-sumologic]: https://developer.fastly.com/reference/api/logging/sumologic/
-[fastly-gcs]: https://developer.fastly.com/reference/api/logging/gcs/
+
+## Product Enablement
+
+The [Product Enablement](https://developer.fastly.com/reference/api/products/enablement/) APIs allow customers to enable and disable specific products.
+
+Not all customers are entitled to use these endpoints and so care needs to be given when configuring a `product_enablement` block in your Terraform configuration.
+
+Consult the [Product Enablement Guide](/docs/guides/product_enablement) to understand the internal workings for the `product_enablement` block.
 
 ## Import
 

fastly/block_fastly_service_product_enablement.go

@@ -308,6 +308,26 @@ func (h *ProductEnablementServiceAttributeHandler) Read(_ context.Context, d *sc
 }
 
 // Update updates the resource.
+//
+// IMPORTANT: The Update method is never called due to an implementation bug.
+//
+// It's a side-effect of the SetDiff logic https://github.com/fastly/terraform-provider-fastly/blob/6e03cce3127a30db94c1cdfa8eb621d9a7231989/fastly/service_crud_attribute_definition.go#L89-L95
+// The SetDiff logic uses `name` as a computed key (i.e. if there’s a change to
+// `name`, then it means the resource has changed and needs to be recreated).
+//
+// The problem is we defined `name` as a Computed attribute, which means it will
+// always be marked as being changed as it's reset to an empty string due to it
+// being a Computed attribute where the value is known only AFTER an apply.
+//
+// Fixing this bug would mean needing to change `name` from being Computed to
+// Optional and also setting a default to match the hardcoded value "products"
+// that we used when it was Computed, and to configure the attribute to be
+// ignored by the Terraform diff processing logic. That should in theory make it
+// a non-breaking change.
+//
+// This isn't the end of the world, it just means there are a few more API calls
+// made. We're also (as of Sept 2023) in the process of rewriting the Terraform
+// provider and so it might be best to resolve this as part of the rewrite.
 func (h *ProductEnablementServiceAttributeHandler) Update(_ context.Context, d *schema.ResourceData, _, modified map[string]any, serviceVersion int, conn *gofastly.Client) error {
 	serviceID := d.Id()
 
@@ -336,8 +356,6 @@ func (h *ProductEnablementServiceAttributeHandler) Update(_ context.Context, d *
 	}
 
 	if h.GetServiceMetadata().serviceType == ServiceTypeVCL {
-		// FIXME: Looks like `modified` contains products that haven't been updated.
-		// The only practical issue here is that an unnecessary API request is made.
 		if v, ok := modified["brotli_compression"]; ok {
 			if v.(bool) {
 				log.Println("[DEBUG] brotli_compression set")

templates/guides/product_enablement.md

@@ -0,0 +1,43 @@
+______________________________________________________________________
+
+## page_title: Product Enablement subcategory: Guides
+
+## Product Enablement
+
+The [Product Enablement](https://developer.fastly.com/reference/api/products/enablement/) APIs allow customers to enable and disable specific products.
+
+Not all customers are entitled to use these endpoints and so care needs to be given when configuring a `product_enablement` block in your Terraform configuration.
+
+## Create
+
+When defining the `product_enablement` block in either your `fastly_service_compute` or `fastly_service_vcl` resource, if you set one attribute (e.g. `brotli_compression`), then the Create function inside the provider will check if the attribute value is set to `true`.
+
+Only if the product attribute is set to `true` will the provider attempt to enable the product.
+
+If a product is not defined in your Terraform config, it is assigned a default value of `false`, meaning none of those products will be 'disabled'.
+
+## Read
+
+The Read function is used to update the Terraform state file. The Terraform provider calls the Fastly API to identify if a product is enabled or not, and it will assign the relevant `true` or `false` values to the state file.
+
+If the Terraform configuration doesn't align with what the state file determines is how things are set up in the 'real world', then the Terraform plan/apply will indicate this in its diff when it compares the state file to your config file.
+
+## Update
+
+The Update function checks to see if the product has a different value to what it was set to originally (e.g. have you changed a product from `true` to `false` or vice-versa) and if it has been modified, then the value assigned to a product is compared to see if it's set to `true` or `false`.
+
+If it's set to `true`, then the provider will attempt to call the Fastly API to 'enable' that product. Otherwise, if the value is set to `false`, then the provider will attempt to call the Fastly API to 'disable' that product.
+
+The important part to pay attention to here is the 'entitlement' to call the Fastly API. Some customers don't have access to programmatically enable/disable products. Products have to then be set up manually by Fastly customer support.
+
+If you _do_ have programmatic access to the [Product Enablement](https://developer.fastly.com/reference/api/products/enablement/) APIs, then you should ensure the correct value is assigned in your Terraform configuration to avoid accidentally disabling a product.
+
+If you're unsure about whether you have API access, then we recommend reaching out to [support@fastly.com](mailto:support@fastly.com) to have them review your account settings.
+
+## Delete
+
+When deleting the `product_enablement` block from your Terraform configuration, the Delete function inside the provider will attempt to disable each product.
+
+If the API returns an error, then that error will be returned to the user and consequently the `terraform apply` will fail. But, the error is only returned if it is _not_ an error related to permissions/access to the API endpoint itself.
+
+This means, that if you delete the `product_enablement` block and you don't have access to disable Image Optimizer, then the error that is returned from the API to the Terraform provider will indicate that it failed because you don't have access to disable the product and that particular error will be ignored by the provider, subsequently allowing the `terraform apply` to complete successfully.

templates/index.md.tmpl

@@ -15,7 +15,7 @@ Pricing and signup information can be found at https://www.fastly.com/signup
 Use the navigation to the left to read about the available resources.
 
 The Fastly provider prior to version v0.13.0 requires using
-[--parallelism=1](/docs/commands/apply.html#parallelism-n) for `apply` operations.
+[--parallelism=1](https://developer.hashicorp.com/terraform/cli/commands/apply#parallelism-n) for `apply` operations.
 
 ## Example Usage
 

templates/resources/service_compute.md.tmpl

@@ -26,6 +26,14 @@ Basic usage:
 The `package` block supports uploading or modifying Wasm packages for use in a Fastly Compute@Edge service. See Fastly's documentation on
 [Compute@Edge](https://www.fastly.com/products/edge-compute/serverless)
 
+## Product Enablement
+
+The [Product Enablement](https://developer.fastly.com/reference/api/products/enablement/) APIs allow customers to enable and disable specific products.
+
+Not all customers are entitled to use these endpoints and so care needs to be given when configuring a `product_enablement` block in your Terraform configuration.
+
+Consult the [Product Enablement Guide](/docs/guides/product_enablement) to understand the internal workings for the `product_enablement` block.
+
 ## Import
 
 Fastly Services can be imported using their service ID, e.g.

templates/resources/service_vcl.md.tmpl

@@ -48,9 +48,14 @@ Fastly documentation on [Amazon S3][fastly-s3].
 
 [fastly-s3]: https://docs.fastly.com/en/guides/amazon-s3
 [fastly-cname]: https://docs.fastly.com/en/guides/adding-cname-records
-[fastly-conditionals]: https://docs.fastly.com/en/guides/using-conditions
-[fastly-sumologic]: https://developer.fastly.com/reference/api/logging/sumologic/
-[fastly-gcs]: https://developer.fastly.com/reference/api/logging/gcs/
+
+## Product Enablement
+
+The [Product Enablement](https://developer.fastly.com/reference/api/products/enablement/) APIs allow customers to enable and disable specific products.
+
+Not all customers are entitled to use these endpoints and so care needs to be given when configuring a `product_enablement` block in your Terraform configuration.
+
+Consult the [Product Enablement Guide](/docs/guides/product_enablement) to understand the internal workings for the `product_enablement` block.
 
 ## Import