From e8a0e9dbd8d01fc86e70a2d095cc4cfb11aae1b2 Mon Sep 17 00:00:00 2001 From: Jacob Bednarz Date: Thu, 14 Nov 2024 14:43:16 +1100 Subject: [PATCH] docs: add guide for migrating resources --- .../guides/migrating-renamed-resources.md | 186 ++++++++++++++++++ 1 file changed, 186 insertions(+) create mode 100644 templates/guides/migrating-renamed-resources.md diff --git a/templates/guides/migrating-renamed-resources.md b/templates/guides/migrating-renamed-resources.md new file mode 100644 index 0000000000..294105d722 --- /dev/null +++ b/templates/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___state` for operating on + the JSON tfstate file and `cloudflare_terraform___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___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 `. +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___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___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