docs: Add terraform_data migration guide (#342)

Terraform 1.9 and later will support using the `moved` configuration block to migrate from `null_resource` to `terraform_data`. This guide and the resource description updates are added to show the process and raise awareness.
hashicorp · May 20, 2024 · 8b8eb1c · 8b8eb1c
1 parent 0d68dbe
commit 8b8eb1c
Show file tree

Hide file tree

Showing 4 changed files with 262 additions and 6 deletions.
diff --git a/docs/guides/terraform-migration.md b/docs/guides/terraform-migration.md
@@ -0,0 +1,128 @@
+---
+page_title: "terraform_data Migration Guide"
+description: |-
+  Migration guide for moving `null_resource` resources to `terraform_data`
+---
+
+# terraform_data Migration Guide
+
+Terraform 1.4 introduced the [`terraform_data` managed resource](https://developer.hashicorp.com/terraform/language/resources/terraform-data) as a built-in replacement for the `null_resource` managed resource.
+
+The built-in `terraform_data` managed resource is designed similar to the `null_resource` managed resource with added benefits:
+
+* The `hashicorp/null` provider is no longer required to be downloaded and installed.
+* Resource replacement trigger configuration supports any value type.
+* Optional data storage.
+
+Use `terraform_data` instead of `null_resource` with all new Terraform configurations running on Terraform 1.4 and later.
+
+## Migrating existing configurations
+
+-> Migrating from the `null_resource` managed resource to the `terraform_data` managed resource with the `moved` configuration block requires Terraform 1.9 and later.
+
+### Without triggers
+
+Use the [`moved` configuration block](https://developer.hashicorp.com/terraform/language/moved) to migrate from `null_resource` to `terraform_data`.
+
+Given this example configuration with a `null_resource` managed resource:
+
+```terraform
+resource "null_resource" "example" {
+  provisioner "local-exec" {
+    command = "echo 'Hello, World!'"
+  }
+}
+```
+
+Replace this configuration with a `terraform_data` managed resource and `moved` configuration:
+
+```terraform
+resource "terraform_data" "example" {
+  provisioner "local-exec" {
+    command = "echo 'Hello, World!'"
+  }
+}
+
+moved {
+  from = null_resource.example
+  to   = terraform_data.example
+}
+```
+
+Run a plan operation, such as `terraform plan`, to verify that the move will occur as expected.
+
+Example output with no changes:
+
+```console
+$ terraform plan
+terraform_data.example: Refreshing state... [id=892002337455008838]
+
+Terraform will perform the following actions:
+
+  # null_resource.example has moved to terraform_data.example
+    resource "terraform_data" "example" {
+        id = "892002337455008838"
+    }
+
+Plan: 0 to add, 0 to change, 0 to destroy.
+```
+
+Run an apply operation, such as `terraform apply`, to move the resource and complete the migration. Remove the `moved` configuration block at any time afterwards.
+
+### With triggers
+
+Use the [`moved` configuration block](https://developer.hashicorp.com/terraform/language/moved) to migrate from `null_resource` to `terraform_data`. Replace the `null_resource` managed resource `triggers` argument with the `terraform_data` managed resource `triggers_replace` argument when moving.
+
+Given this example configuration with a `null_resource` managed resource that includes the `triggers` argument:
+
+```terraform
+resource "null_resource" "example" {
+  triggers = {
+    examplekey = "examplevalue"
+  }
+
+  provisioner "local-exec" {
+    command = "echo 'Hello, World!'"
+  }
+}
+```
+
+Replace this configuration with the following `terraform_data` managed resource and `moved` configuration:
+
+```terraform
+resource "terraform_data" "example" {
+  triggers_replace = {
+    examplekey = "examplevalue"
+  }
+
+  provisioner "local-exec" {
+    command = "echo 'Hello, World!'"
+  }
+}
+
+moved {
+  from = null_resource.example
+  to   = terraform_data.example
+}
+```
+
+Run a plan operation, such as `terraform plan`, to verify that the move will occur as expected.
+
+Example output with no changes:
+
+```console
+$ terraform plan
+terraform_data.example: Refreshing state... [id=1651348367769440250]
+
+Terraform will perform the following actions:
+
+  # null_resource.example has moved to terraform_data.example
+    resource "terraform_data" "example" {
+        id               = "1651348367769440250"
+        # (1 unchanged attribute hidden)
+    }
+
+Plan: 0 to add, 0 to change, 0 to destroy.
+```
+
+Run an apply operation, such as `terraform apply`, to move the resource and complete the migration. Remove the `moved` configuration block at any time afterwards.
diff --git a/docs/resources/resource.md b/docs/resources/resource.md
@@ -3,13 +3,13 @@
 page_title: "null_resource Resource - terraform-provider-null"
 subcategory: ""
 description: |-
-  The null_resource resource implements the standard resource lifecycle but takes no further action. On Terraform 1.4 and later, use the terraform_data resource type https://developer.hashicorp.com/terraform/language/resources/terraform-data instead.
+  The null_resource resource implements the standard resource lifecycle but takes no further action. On Terraform 1.4 and later, use the terraform_data resource type https://developer.hashicorp.com/terraform/language/resources/terraform-data instead. Terraform 1.9 and later support the moved configuration block from null_resource to terraform_data.
   The triggers argument allows specifying an arbitrary set of values that, when changed, will cause the resource to be replaced.
 ---
 
 # null_resource
 
-The `null_resource` resource implements the standard resource lifecycle but takes no further action. On Terraform 1.4 and later, use the [terraform_data resource type](https://developer.hashicorp.com/terraform/language/resources/terraform-data) instead.
+The `null_resource` resource implements the standard resource lifecycle but takes no further action. On Terraform 1.4 and later, use the [`terraform_data` resource type](https://developer.hashicorp.com/terraform/language/resources/terraform-data) instead. Terraform 1.9 and later support the `moved` configuration block from `null_resource` to `terraform_data`.
 
 The `triggers` argument allows specifying an arbitrary set of values that, when changed, will cause the resource to be replaced.
 

diff --git a/internal/provider/resource.go b/internal/provider/resource.go
@@ -34,10 +34,10 @@ func (n *nullResource) Metadata(ctx context.Context, req resource.MetadataReques
 
 func (n *nullResource) Schema(ctx context.Context, req resource.SchemaRequest, resp *resource.SchemaResponse) {
 	resp.Schema = schema.Schema{
-		Description: `The ` + "`null_resource`" + ` resource implements the standard resource lifecycle but takes no further action. ` +
-			`On Terraform 1.4 and later, use the [terraform_data resource type](https://developer.hashicorp.com/terraform/language/resources/terraform-data) instead.
-
-The ` + "`triggers`" + ` argument allows specifying an arbitrary set of values that, when changed, will cause the resource to be replaced.`,
+		Description: "The `null_resource` resource implements the standard resource lifecycle but takes no further action. " +
+			"On Terraform 1.4 and later, use the [`terraform_data` resource type](https://developer.hashicorp.com/terraform/language/resources/terraform-data) instead. " +
+			"Terraform 1.9 and later support the `moved` configuration block from `null_resource` to `terraform_data`.\n\n" +
+			"The `triggers` argument allows specifying an arbitrary set of values that, when changed, will cause the resource to be replaced.",
 		Attributes: map[string]schema.Attribute{
 			"triggers": schema.MapAttribute{
 				Description: "A map of arbitrary strings that, when changed, will force the null resource to be replaced, re-running any associated provisioners.",

diff --git a/templates/guides/terraform-migration.md.tmpl b/templates/guides/terraform-migration.md.tmpl
@@ -0,0 +1,128 @@
+---
+page_title: "terraform_data Migration Guide"
+description: |-
+  Migration guide for moving `null_resource` resources to `terraform_data`
+---
+
+# terraform_data Migration Guide
+
+Terraform 1.4 introduced the [`terraform_data` managed resource](https://developer.hashicorp.com/terraform/language/resources/terraform-data) as a built-in replacement for the `null_resource` managed resource.
+
+The built-in `terraform_data` managed resource is designed similar to the `null_resource` managed resource with added benefits:
+
+* The `hashicorp/null` provider is no longer required to be downloaded and installed.
+* Resource replacement trigger configuration supports any value type.
+* Optional data storage.
+
+Use `terraform_data` instead of `null_resource` with all new Terraform configurations running on Terraform 1.4 and later.
+
+## Migrating existing configurations
+
+-> Migrating from the `null_resource` managed resource to the `terraform_data` managed resource with the `moved` configuration block requires Terraform 1.9 and later.
+
+### Without triggers
+
+Use the [`moved` configuration block](https://developer.hashicorp.com/terraform/language/moved) to migrate from `null_resource` to `terraform_data`.
+
+Given this example configuration with a `null_resource` managed resource:
+
+```terraform
+resource "null_resource" "example" {
+  provisioner "local-exec" {
+    command = "echo 'Hello, World!'"
+  }
+}
+```
+
+Replace this configuration with a `terraform_data` managed resource and `moved` configuration:
+
+```terraform
+resource "terraform_data" "example" {
+  provisioner "local-exec" {
+    command = "echo 'Hello, World!'"
+  }
+}
+
+moved {
+  from = null_resource.example
+  to   = terraform_data.example
+}
+```
+
+Run a plan operation, such as `terraform plan`, to verify that the move will occur as expected.
+
+Example output with no changes:
+
+```console
+$ terraform plan
+terraform_data.example: Refreshing state... [id=892002337455008838]
+
+Terraform will perform the following actions:
+
+  # null_resource.example has moved to terraform_data.example
+    resource "terraform_data" "example" {
+        id = "892002337455008838"
+    }
+
+Plan: 0 to add, 0 to change, 0 to destroy.
+```
+
+Run an apply operation, such as `terraform apply`, to move the resource and complete the migration. Remove the `moved` configuration block at any time afterwards.
+
+### With triggers
+
+Use the [`moved` configuration block](https://developer.hashicorp.com/terraform/language/moved) to migrate from `null_resource` to `terraform_data`. Replace the `null_resource` managed resource `triggers` argument with the `terraform_data` managed resource `triggers_replace` argument when moving.
+
+Given this example configuration with a `null_resource` managed resource that includes the `triggers` argument:
+
+```terraform
+resource "null_resource" "example" {
+  triggers = {
+    examplekey = "examplevalue"
+  }
+
+  provisioner "local-exec" {
+    command = "echo 'Hello, World!'"
+  }
+}
+```
+
+Replace this configuration with the following `terraform_data` managed resource and `moved` configuration:
+
+```terraform
+resource "terraform_data" "example" {
+  triggers_replace = {
+    examplekey = "examplevalue"
+  }
+
+  provisioner "local-exec" {
+    command = "echo 'Hello, World!'"
+  }
+}
+
+moved {
+  from = null_resource.example
+  to   = terraform_data.example
+}
+```
+
+Run a plan operation, such as `terraform plan`, to verify that the move will occur as expected.
+
+Example output with no changes:
+
+```console
+$ terraform plan
+terraform_data.example: Refreshing state... [id=1651348367769440250]
+
+Terraform will perform the following actions:
+
+  # null_resource.example has moved to terraform_data.example
+    resource "terraform_data" "example" {
+        id               = "1651348367769440250"
+        # (1 unchanged attribute hidden)
+    }
+
+Plan: 0 to add, 0 to change, 0 to destroy.
+```
+
+Run an apply operation, such as `terraform apply`, to move the resource and complete the migration. Remove the `moved` configuration block at any time afterwards.