From 4fb60bb67984a60cf83a59021ff5c972dfdd1bce Mon Sep 17 00:00:00 2001 From: Integralist Date: Thu, 28 Sep 2023 15:51:58 +0100 Subject: [PATCH 1/3] doc(product_enablement): document Update flow bug --- ...block_fastly_service_product_enablement.go | 22 +++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/fastly/block_fastly_service_product_enablement.go b/fastly/block_fastly_service_product_enablement.go index 54be88c50..6555a030c 100644 --- a/fastly/block_fastly_service_product_enablement.go +++ b/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") From b64baea303f48736a03a7da06ec883d332b85cde Mon Sep 17 00:00:00 2001 From: Integralist Date: Thu, 28 Sep 2023 15:54:59 +0100 Subject: [PATCH 2/3] doc(fastly_service_vcl): remove unused links which break HTML rendering --- templates/resources/service_vcl.md.tmpl | 3 --- 1 file changed, 3 deletions(-) diff --git a/templates/resources/service_vcl.md.tmpl b/templates/resources/service_vcl.md.tmpl index 20da42062..19e33b181 100644 --- a/templates/resources/service_vcl.md.tmpl +++ b/templates/resources/service_vcl.md.tmpl @@ -48,9 +48,6 @@ 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/ ## Import From e10472b9093b554e51bf09103f26bda2817d36eb Mon Sep 17 00:00:00 2001 From: Integralist Date: Thu, 28 Sep 2023 16:17:04 +0100 Subject: [PATCH 3/3] docs: product enablement guide --- docs/guides/product_enablement.md | 43 +++++++++++++++++++++ docs/index.md | 2 +- docs/resources/service_compute.md | 8 ++++ docs/resources/service_vcl.md | 11 ++++-- templates/guides/product_enablement.md | 43 +++++++++++++++++++++ templates/index.md.tmpl | 2 +- templates/resources/service_compute.md.tmpl | 8 ++++ templates/resources/service_vcl.md.tmpl | 8 ++++ 8 files changed, 120 insertions(+), 5 deletions(-) create mode 100644 docs/guides/product_enablement.md create mode 100644 templates/guides/product_enablement.md diff --git a/docs/guides/product_enablement.md b/docs/guides/product_enablement.md new file mode 100644 index 000000000..4395fb711 --- /dev/null +++ b/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. diff --git a/docs/index.md b/docs/index.md index f703b0b2e..bdcd4e09d 100644 --- a/docs/index.md +++ b/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 diff --git a/docs/resources/service_compute.md b/docs/resources/service_compute.md index 97b527bd6..8fa672e3b 100644 --- a/docs/resources/service_compute.md +++ b/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. diff --git a/docs/resources/service_vcl.md b/docs/resources/service_vcl.md index 5f05b8230..5ec8970c6 100644 --- a/docs/resources/service_vcl.md +++ b/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 diff --git a/templates/guides/product_enablement.md b/templates/guides/product_enablement.md new file mode 100644 index 000000000..4395fb711 --- /dev/null +++ b/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. diff --git a/templates/index.md.tmpl b/templates/index.md.tmpl index 3a17b5cda..79bb1fc07 100644 --- a/templates/index.md.tmpl +++ b/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 diff --git a/templates/resources/service_compute.md.tmpl b/templates/resources/service_compute.md.tmpl index 54a9b2c9d..cf07e8256 100644 --- a/templates/resources/service_compute.md.tmpl +++ b/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. diff --git a/templates/resources/service_vcl.md.tmpl b/templates/resources/service_vcl.md.tmpl index 19e33b181..b61411ac3 100644 --- a/templates/resources/service_vcl.md.tmpl +++ b/templates/resources/service_vcl.md.tmpl @@ -49,6 +49,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 +## 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.