Merge pull request #4578 from cloudflare/grit-migration-for-zt-renames

docs: add resource rename migration docs
cloudflare · Nov 14, 2024 · 1aa887d · 1aa887d
2 parents f39ab07 + aebc0c6
commit 1aa887d
Show file tree

Hide file tree

Showing 6 changed files with 533 additions and 5 deletions.
diff --git a/.grit/patterns/cloudflare_terraform_v4_40_0_zero_trust_namespace_renames_configuration.grit b/.grit/patterns/cloudflare_terraform_v4_40_0_zero_trust_namespace_renames_configuration.grit
@@ -0,0 +1,77 @@
+engine marzano(0.1)
+language hcl
+
+pattern cloudflare_terraform_v4_40_0_zero_trust_namespace_renames_configuration() {
+  any {
+    `"cloudflare_access_application"` => `"clouflare_zero_trust_access_application"`,
+    `"cloudflare_access_ca_certificate"` => `"clouflare_zero_trust_access_short_lived_certificate"`,
+    `"cloudflare_access_custom_page"` => `"clouflare_zero_trust_access_custom_page"`,
+    `"cloudflare_access_group"` => `"clouflare_zero_trust_access_group"`,
+    `"cloudflare_access_identity_provider"` => `"clouflare_zero_trust_access_identity_provider"`,
+    `"cloudflare_access_keys_configuration"` => `"clouflare_zero_trust_access_key_configuration"`,
+    `"cloudflare_access_mutual_tls_certificate"` => `"clouflare_zero_trust_access_mtls_certificate"`,
+    `"cloudflare_access_mutual_tls_hostname_settings"` => `"clouflare_zero_trust_access_mtls_hostname_settings"`,
+    `"cloudflare_access_organization"` => `"clouflare_zero_trust_organization"`,
+    `"cloudflare_access_policy"` => `"clouflare_zero_trust_access_policy"`,
+    `"cloudflare_access_service_token"` => `"clouflare_zero_trust_access_service_token"`,
+    `"cloudflare_access_tag"` => `"clouflare_zero_trust_access_tag"`,
+    `"cloudflare_device_dex_test"` => `"clouflare_zero_trust_dex_test"`,
+    `"cloudflare_device_managed_networks"` => `"clouflare_zero_trust_device_managed_networks"`,
+    `"cloudflare_device_policy_certificates"` => `"clouflare_zero_trust_device_certificates"`,
+    `"cloudflare_device_posture_integration"` => `"clouflare_zero_trust_device_posture_integration"`,
+    `"cloudflare_device_posture_rule"` => `"clouflare_zero_trust_device_posture_rule"`,
+    `"cloudflare_device_settings_policy"` => `"clouflare_zero_trust_device_profiles"`,
+    `"cloudflare_dlp_profile"` => `"clouflare_zero_trust_dlp_profile"`,
+    `"cloudflare_dlp_custom_profile"` => `"clouflare_zero_trust_dlp_custom_profile"`,
+    `"cloudflare_dlp_predefined_profile"` => `"clouflare_zero_trust_dlp_predefined_profile"`,
+    `"cloudflare_fallback_domain"` => `"clouflare_zero_trust_local_domain_fallback"`,
+    `"cloudflare_risk_behavior"` => `"clouflare_zero_trust_risk_behavior"`,
+    `"cloudflare_split_tunnel"` => `"clouflare_zero_trust_split_tunnels"`,
+    `"cloudflare_teams_account"` => `"clouflare_zero_trust_gateway_settings"`,
+    `"cloudflare_teams_list"` => `"clouflare_zero_trust_list"`,
+    `"cloudflare_teams_location"` => `"clouflare_zero_trust_dns_location"`,
+    `"cloudflare_teams_proxy_endpoint"` => `"clouflare_zero_trust_gateway_proxy_endpoint"`,
+    `"cloudflare_teams_rule"` => `"clouflare_zero_trust_gateway_policy"`,
+    `"cloudflare_tunnel"` => `"clouflare_zero_trust_tunnel_cloudflared"`,
+    `"cloudflare_tunnel_config"` => `"clouflare_zero_trust_tunnel_cloudflared_config"`,
+    `"cloudflare_tunnel_route"` => `"clouflare_zero_trust_tunnel_route"`,
+    `"cloudflare_tunnel_virtual_network"` => `"clouflare_zero_trust_tunnel_virtual_network"`,
+
+    // handle references
+    `cloudflare_access_application` => `clouflare_zero_trust_access_application`,
+    `cloudflare_access_ca_certificate` => `clouflare_zero_trust_access_short_lived_certificate`,
+    `cloudflare_access_custom_page` => `clouflare_zero_trust_access_custom_page`,
+    `cloudflare_access_group` => `clouflare_zero_trust_access_group`,
+    `cloudflare_access_identity_provider` => `clouflare_zero_trust_access_identity_provider`,
+    `cloudflare_access_keys_configuration` => `clouflare_zero_trust_access_key_configuration`,
+    `cloudflare_access_mutual_tls_certificate` => `clouflare_zero_trust_access_mtls_certificate`,
+    `cloudflare_access_mutual_tls_hostname_settings` => `clouflare_zero_trust_access_mtls_hostname_settings`,
+    `cloudflare_access_organization` => `clouflare_zero_trust_organization`,
+    `cloudflare_access_policy` => `clouflare_zero_trust_access_policy`,
+    `cloudflare_access_service_token` => `clouflare_zero_trust_access_service_token`,
+    `cloudflare_access_tag` => `clouflare_zero_trust_access_tag`,
+    `cloudflare_device_dex_test` => `clouflare_zero_trust_dex_test`,
+    `cloudflare_device_managed_networks` => `clouflare_zero_trust_device_managed_networks`,
+    `cloudflare_device_policy_certificates` => `clouflare_zero_trust_device_certificates`,
+    `cloudflare_device_posture_integration` => `clouflare_zero_trust_device_posture_integration`,
+    `cloudflare_device_posture_rule` => `clouflare_zero_trust_device_posture_rule`,
+    `cloudflare_device_settings_policy` => `clouflare_zero_trust_device_profiles`,
+    `cloudflare_dlp_profile` => `clouflare_zero_trust_dlp_profile`,
+    `cloudflare_dlp_custom_profile` => `clouflare_zero_trust_dlp_custom_profile`,
+    `cloudflare_dlp_predefined_profile` => `clouflare_zero_trust_dlp_predefined_profile`,
+    `cloudflare_fallback_domain` => `clouflare_zero_trust_local_domain_fallback`,
+    `cloudflare_risk_behavior` => `clouflare_zero_trust_risk_behavior`,
+    `cloudflare_split_tunnel` => `clouflare_zero_trust_split_tunnels`,
+    `cloudflare_teams_account` => `clouflare_zero_trust_gateway_settings`,
+    `cloudflare_teams_list` => `clouflare_zero_trust_list`,
+    `cloudflare_teams_location` => `clouflare_zero_trust_dns_location`,
+    `cloudflare_teams_proxy_endpoint` => `clouflare_zero_trust_gateway_proxy_endpoint`,
+    `cloudflare_teams_rule` => `clouflare_zero_trust_gateway_policy`,
+    `cloudflare_tunnel` => `clouflare_zero_trust_tunnel_cloudflared`,
+    `cloudflare_tunnel_config` => `clouflare_zero_trust_tunnel_cloudflared_config`,
+    `cloudflare_tunnel_route` => `clouflare_zero_trust_tunnel_route`,
+    `cloudflare_tunnel_virtual_network` => `clouflare_zero_trust_tunnel_virtual_network`,
+  }
+}
+
+cloudflare_terraform_v4_40_0_zero_trust_namespace_renames_configuration()
diff --git a/.grit/patterns/cloudflare_terraform_v4_40_0_zero_trust_namespace_renames_state.grit b/.grit/patterns/cloudflare_terraform_v4_40_0_zero_trust_namespace_renames_state.grit
@@ -0,0 +1,77 @@
+engine marzano(0.1)
+language json
+
+pattern cloudflare_terraform_v4_40_0_zero_trust_namespace_renames_state() {
+  any {
+    `"cloudflare_access_application"` => `"clouflare_zero_trust_access_application"`,
+    `"cloudflare_access_ca_certificate"` => `"clouflare_zero_trust_access_short_lived_certificate"`,
+    `"cloudflare_access_custom_page"` => `"clouflare_zero_trust_access_custom_page"`,
+    `"cloudflare_access_group"` => `"clouflare_zero_trust_access_group"`,
+    `"cloudflare_access_identity_provider"` => `"clouflare_zero_trust_access_identity_provider"`,
+    `"cloudflare_access_keys_configuration"` => `"clouflare_zero_trust_access_key_configuration"`,
+    `"cloudflare_access_mutual_tls_certificate"` => `"clouflare_zero_trust_access_mtls_certificate"`,
+    `"cloudflare_access_mutual_tls_hostname_settings"` => `"clouflare_zero_trust_access_mtls_hostname_settings"`,
+    `"cloudflare_access_organization"` => `"clouflare_zero_trust_organization"`,
+    `"cloudflare_access_policy"` => `"clouflare_zero_trust_access_policy"`,
+    `"cloudflare_access_service_token"` => `"clouflare_zero_trust_access_service_token"`,
+    `"cloudflare_access_tag"` => `"clouflare_zero_trust_access_tag"`,
+    `"cloudflare_device_dex_test"` => `"clouflare_zero_trust_dex_test"`,
+    `"cloudflare_device_managed_networks"` => `"clouflare_zero_trust_device_managed_networks"`,
+    `"cloudflare_device_policy_certificates"` => `"clouflare_zero_trust_device_certificates"`,
+    `"cloudflare_device_posture_integration"` => `"clouflare_zero_trust_device_posture_integration"`,
+    `"cloudflare_device_posture_rule"` => `"clouflare_zero_trust_device_posture_rule"`,
+    `"cloudflare_device_settings_policy"` => `"clouflare_zero_trust_device_profiles"`,
+    `"cloudflare_dlp_profile"` => `"clouflare_zero_trust_dlp_profile"`,
+    `"cloudflare_dlp_custom_profile"` => `"clouflare_zero_trust_dlp_custom_profile"`,
+    `"cloudflare_dlp_predefined_profile"` => `"clouflare_zero_trust_dlp_predefined_profile"`,
+    `"cloudflare_fallback_domain"` => `"clouflare_zero_trust_local_domain_fallback"`,
+    `"cloudflare_risk_behavior"` => `"clouflare_zero_trust_risk_behavior"`,
+    `"cloudflare_split_tunnel"` => `"clouflare_zero_trust_split_tunnels"`,
+    `"cloudflare_teams_account"` => `"clouflare_zero_trust_gateway_settings"`,
+    `"cloudflare_teams_list"` => `"clouflare_zero_trust_list"`,
+    `"cloudflare_teams_location"` => `"clouflare_zero_trust_dns_location"`,
+    `"cloudflare_teams_proxy_endpoint"` => `"clouflare_zero_trust_gateway_proxy_endpoint"`,
+    `"cloudflare_teams_rule"` => `"clouflare_zero_trust_gateway_policy"`,
+    `"cloudflare_tunnel"` => `"clouflare_zero_trust_tunnel_cloudflared"`,
+    `"cloudflare_tunnel_config"` => `"clouflare_zero_trust_tunnel_cloudflared_config"`,
+    `"cloudflare_tunnel_route"` => `"clouflare_zero_trust_tunnel_route"`,
+    `"cloudflare_tunnel_virtual_network"` => `"clouflare_zero_trust_tunnel_virtual_network"`,
+
+    // handle dependencies
+    `"cloudflare_access_application.$dep"` => `"clouflare_zero_trust_access_application.$dep"`,
+    `"cloudflare_access_ca_certificate.$dep"` => `"clouflare_zero_trust_access_short_lived_certificate.$dep"`,
+    `"cloudflare_access_custom_page.$dep"` => `"clouflare_zero_trust_access_custom_page.$dep"`,
+    `"cloudflare_access_group.$dep"` => `"clouflare_zero_trust_access_group.$dep"`,
+    `"cloudflare_access_identity_provider.$dep"` => `"clouflare_zero_trust_access_identity_provider.$dep"`,
+    `"cloudflare_access_keys_configuration.$dep"` => `"clouflare_zero_trust_access_key_configuration.$dep"`,
+    `"cloudflare_access_mutual_tls_certificate.$dep"` => `"clouflare_zero_trust_access_mtls_certificate.$dep"`,
+    `"cloudflare_access_mutual_tls_hostname_settings.$dep"` => `"clouflare_zero_trust_access_mtls_hostname_settings.$dep"`,
+    `"cloudflare_access_organization.$dep"` => `"clouflare_zero_trust_organization.$dep"`,
+    `"cloudflare_access_policy.$dep"` => `"clouflare_zero_trust_access_policy.$dep"`,
+    `"cloudflare_access_service_token.$dep"` => `"clouflare_zero_trust_access_service_token.$dep"`,
+    `"cloudflare_access_tag.$dep"` => `"clouflare_zero_trust_access_tag.$dep"`,
+    `"cloudflare_device_dex_test.$dep"` => `"clouflare_zero_trust_dex_test.$dep"`,
+    `"cloudflare_device_managed_networks.$dep"` => `"clouflare_zero_trust_device_managed_networks.$dep"`,
+    `"cloudflare_device_policy_certificates.$dep"` => `"clouflare_zero_trust_device_certificates.$dep"`,
+    `"cloudflare_device_posture_integration.$dep"` => `"clouflare_zero_trust_device_posture_integration.$dep"`,
+    `"cloudflare_device_posture_rule.$dep"` => `"clouflare_zero_trust_device_posture_rule.$dep"`,
+    `"cloudflare_device_settings_policy.$dep"` => `"clouflare_zero_trust_device_profiles.$dep"`,
+    `"cloudflare_dlp_profile.$dep"` => `"clouflare_zero_trust_dlp_profile.$dep"`,
+    `"cloudflare_dlp_custom_profile.$dep"` => `"clouflare_zero_trust_dlp_custom_profile.$dep"`,
+    `"cloudflare_dlp_predefined_profile.$dep"` => `"clouflare_zero_trust_dlp_predefined_profile.$dep"`,
+    `"cloudflare_fallback_domain.$dep"` => `"clouflare_zero_trust_local_domain_fallback.$dep"`,
+    `"cloudflare_risk_behavior.$dep"` => `"clouflare_zero_trust_risk_behavior.$dep"`,
+    `"cloudflare_split_tunnel.$dep"` => `"clouflare_zero_trust_split_tunnels.$dep"`,
+    `"cloudflare_teams_account.$dep"` => `"clouflare_zero_trust_gateway_settings.$dep"`,
+    `"cloudflare_teams_list.$dep"` => `"clouflare_zero_trust_list.$dep"`,
+    `"cloudflare_teams_location.$dep"` => `"clouflare_zero_trust_dns_location.$dep"`,
+    `"cloudflare_teams_proxy_endpoint.$dep"` => `"clouflare_zero_trust_gateway_proxy_endpoint.$dep"`,
+    `"cloudflare_teams_rule.$dep"` => `"clouflare_zero_trust_gateway_policy.$dep"`,
+    `"cloudflare_tunnel.$dep"` => `"clouflare_zero_trust_tunnel_cloudflared.$dep"`,
+    `"cloudflare_tunnel_config.$dep"` => `"clouflare_zero_trust_tunnel_cloudflared_config.$dep"`,
+    `"cloudflare_tunnel_route.$dep"` => `"clouflare_zero_trust_tunnel_route.$dep"`,
+    `"cloudflare_tunnel_virtual_network.$dep"` => `"clouflare_zero_trust_tunnel_virtual_network.$dep"`,
+  }
+}
+
+cloudflare_terraform_v4_40_0_zero_trust_namespace_renames_state()
diff --git a/docs/guides/migrating-renamed-resources.md b/docs/guides/migrating-renamed-resources.md
@@ -0,0 +1,186 @@
+---
+layout: "cloudflare"
+page_title: "Migrating renamed resources"
+description: Guide for handling renamed resources in the Cloudflare Provider
+---
+
+## Before you start
+
+- You will need to follow the [Grit CLI install] steps.
+- Locate the Grit patterns you'll need to perform the upgrade. They will be in
+  `.grit/patterns` directory of the [GitHub repository]. The filename convention
+  is `cloudflare_terraform_<version>_<what is changing>_state` for operating on
+  the JSON tfstate file and `cloudflare_terraform_<version>_<what is changing>_configuration`
+  for changing the HCL configuration. The changelog will call out the
+  pattern names as well.
+- Lock or ensure no other changes are happening while you are performing the
+  migration.
+- Make backups of your configuration and state file.
+
+~> It is recommended to do perform testing in a non-production, non-critical
+environment or a small subset resources before performing the changes to
+all resources.
+
+## Using import
+
+-> Recommended for most users and migrations.
+
+We'll assume we're migrating from the `cloudflare_old` resource to the
+`cloudflare_new` resource and is applicable for any changes where the changes
+are 1:1 drop in replacements.
+
+Example:
+
+```hcl
+resource "cloudflare_dependant_thing" "example" {
+  zone_id = var.staging_zone_id
+  name    = "Example Thing"
+  enabled = true
+}
+
+resource "cloudflare_old" "example" {
+  name           = "Example"
+  other_thing_id = cloudflare_dependant_thing.example.id
+}
+```
+
+1. Navigate to the directory where your HCL configuration is located.
+2. Apply the **configuration** pattern (replacing the respective parts of the
+   filename). This will update your local configuration but not the state file.
+   ```bash
+   $ grit apply github.com/cloudflare/terraform-provider-cloudflare#cloudflare_terraform_<version>_<what is changing>_configuration
+   ```
+3. List the resources in state using `terraform state list`.
+   ```
+   $ terraform state list
+   cloudflare_dependant_thing.example
+   cloudflare_old.example
+   ```
+4. Remove the **old** resource using `terraform state rm <resource>`.
+5. Invoke `terraform import` to import the new resource (refer to the resource
+   documentation for the correct import string).
+   ```
+   $ terraform import cloudflare_new.example 0da42c8d2132a9ddaf714f9e7c920711/8295065e70782f633792396e73af14bb
+   ```
+6. Confirm no further changes are required by running `terraform plan`.
+
+At this point, you've switched over to using the new resource and should be able
+to continue using Terraform as normal.
+
+## Manually modifying the state file
+
+-> Recommended for a large number of resources where importing individually is
+not feasible.
+
+1. Pull the state file locally using `terraform state pull` and output it to a
+   file.
+
+```bash
+$ terraform state pull > terraform.tfstate
+```
+
+2. Run the **state** pattern (replacing the respective parts of the filename).
+
+```bash
+$ grit apply github.com/cloudflare/terraform-provider-cloudflare#cloudflare_terraform_<version>_<what is changing>_state terraform.tfstate
+```
+
+3. Navigate to the directory where your HCL configuration is located.
+4. Apply the **configuration** pattern (replacing the respective parts of the
+   filename).
+
+```bash
+$ grit apply github.com/cloudflare/terraform-provider-cloudflare#cloudflare_terraform_<version>_<what is changing>_configuration
+```
+
+5. Push your state file back to the remote using `terraform state push terraform.tfstate`.
+6. Confirm no further changes are required by running `terraform plan`.
+
+At this point, you've switched over to using the new resource and should be able
+to continue using Terraform as normal.
+
+## Two phase swap over
+
+-> Recommend for incremental swapping or introducing new resources with older
+resources.
+
+We'll assume we're migrating from the `cloudflare_old` resource to the
+`cloudflare_new` resource as a dependent resource.
+
+Example:
+
+```hcl
+resource "cloudflare_old" "example" {
+  zone_id = var.staging_zone_id
+  name    = "Example Thing"
+  enabled = true
+}
+
+resource "cloudflare_thing" "example" {
+  name           = "Example"
+  other_thing_id = cloudflare_old.example.id
+}
+```
+
+1. Add your new resource to your configuration.
+
+```hcl
+resource "cloudflare_old" "example" {
+  zone_id = var.staging_zone_id
+  name    = "Example Thing"
+  enabled = true
+}
+
+resource "cloudflare_new" "example" {
+  zone_id = var.staging_zone_id
+  name    = "Example Thing"
+  enabled = true
+}
+
+resource "cloudflare_thing" "example" {
+  name           = "Example"
+  other_thing_id = cloudflare_old.example.id
+}
+```
+
+2. Update your existing resource to reference the newer resource.
+
+```hcl
+resource "cloudflare_old" "example" {
+  zone_id = var.staging_zone_id
+  name    = "Example Thing"
+  enabled = true
+}
+
+resource "cloudflare_new" "example" {
+  zone_id = var.staging_zone_id
+  name    = "Example Thing"
+  enabled = true
+}
+
+resource "cloudflare_thing" "example" {
+  name           = "Example"
+  other_thing_id = cloudflare_new.example.id
+}
+```
+
+3. Remove the old resource once it is no longer referenced.
+
+```hcl
+resource "cloudflare_new" "example" {
+  zone_id = var.staging_zone_id
+  name    = "Example Thing"
+  enabled = true
+}
+
+resource "cloudflare_thing" "example" {
+  name           = "Example"
+  other_thing_id = cloudflare_new.example.id
+}
+```
+
+At this point, you've switched over to using the new resource and should be able
+to continue using Terraform as normal.
+
+[Grit CLI install]: https://docs.grit.io/cli/quickstart
+[GitHub repository]: https://github.com/cloudflare/terraform-provider-cloudflare/tree/master/.grit/patterns
diff --git a/docs/resources/access_application.md b/docs/resources/access_application.md
@@ -262,7 +262,7 @@ Optional:
 
 Required:
 
-- `idp_uid` (String) The UID of the IdP to use as the source for SCIM resources to provision to this application.
+- `idp_uid` (String) The UIDs of the IdP to use as the source for SCIM resources to provision to this application.
 - `remote_uri` (String) The base URI for the application's SCIM-compatible API.
 
 Optional:
@@ -299,11 +299,12 @@ Required:
 - `schema` (String) Which SCIM resource type this mapping applies to.
 
 Optional:
-- `enabled` (Boolean) Whether this mapping is enabled.
+
+- `enabled` (Boolean) Whether or not this mapping is enabled.
 - `filter` (String) A [SCIM filter expression](https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.2) that matches resources that should be provisioned to this application.
+- `operations` (Block List, Max: 1) Whether or not this mapping applies to creates, updates, or deletes. (see [below for nested schema](#nestedblock--scim_config--mappings--operations))
+- `strictness` (String) How strictly to adhere to outbound resource schemas when provisioning to this mapping. "strict" will remove unknown values when provisioning, while "passthrough" will pass unknown values to the target.
 - `transform_jsonata` (String) A [JSONata](https://jsonata.org/) expression that transforms the resource before provisioning it in the application.
-- `operations` (Block List, Max: 1) Whether this mapping applies to creates, updates, or deletes. See [below for nested schema](#nestedblock--scim_config--mapping--operations)
-- `strictness` (String) Available values: `strict`, `passthrough`. How strictly to adhere to outbound resource schemas when provisioning to this mapping. `strict` will remove unknown values when provisioning, while `passthrough` will pass unknown values to the target.
 
 <a id="nestedblock--scim_config--mappings--operations"></a>
 ### Nested Schema for `scim_config.mappings.operations`