cdktf: update documentation (#347)

hashicorp · May 28, 2024 · be573fb · be573fb
1 parent 5da2bc7
commit be573fb
Show file tree

Hide file tree

Showing 4 changed files with 356 additions and 6 deletions.
diff --git a/docs/cdktf/python/guides/terraform-migration.md b/docs/cdktf/python/guides/terraform-migration.md
@@ -0,0 +1,168 @@
+---
+page_title: "terraform_data Migration Guide"
+description: |-
+  Migration guide for moving `null_resource` resources to `terraform_data`
+---
+
+
+<!-- Please do not edit this file, it is generated. -->
+# 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:
+
+```python
+# DO NOT EDIT. Code generated by 'cdktf convert' - Please report bugs at https://cdk.tf/bug
+from cdktf import FileProvisioner
+from constructs import Construct
+from cdktf import TerraformStack
+#
+# Provider bindings are generated by running `cdktf get`.
+# See https://cdk.tf/provider-generation for more details.
+#
+from imports.null.resource import Resource
+class MyConvertedCode(TerraformStack):
+    def __init__(self, scope, name):
+        super().__init__(scope, name)
+        Resource(self, "example",
+            provisioners=[FileProvisioner(
+                type="local-exec",
+                command="echo 'Hello, World!'"
+            )
+            ]
+        )
+```
+
+Replace this configuration with a `terraform_data` managed resource and `moved` configuration:
+
+```python
+# DO NOT EDIT. Code generated by 'cdktf convert' - Please report bugs at https://cdk.tf/bug
+from cdktf import FileProvisioner
+from constructs import Construct
+from cdktf import DataResource, TerraformStack
+class MyConvertedCode(TerraformStack):
+    def __init__(self, scope, name):
+        super().__init__(scope, name)
+        DataResource(self, "example",
+            provisioners=[FileProvisioner(
+                type="local-exec",
+                command="echo 'Hello, World!'"
+            )
+            ]
+        )
+```
+
+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:
+
+```python
+# DO NOT EDIT. Code generated by 'cdktf convert' - Please report bugs at https://cdk.tf/bug
+from cdktf import FileProvisioner
+from constructs import Construct
+from cdktf import TerraformStack
+#
+# Provider bindings are generated by running `cdktf get`.
+# See https://cdk.tf/provider-generation for more details.
+#
+from imports.null.resource import Resource
+class MyConvertedCode(TerraformStack):
+    def __init__(self, scope, name):
+        super().__init__(scope, name)
+        Resource(self, "example",
+            triggers=[{
+                "examplekey": "examplevalue"
+            }
+            ],
+            provisioners=[FileProvisioner(
+                type="local-exec",
+                command="echo 'Hello, World!'"
+            )
+            ]
+        )
+```
+
+Replace this configuration with the following `terraform_data` managed resource and `moved` configuration:
+
+```python
+# DO NOT EDIT. Code generated by 'cdktf convert' - Please report bugs at https://cdk.tf/bug
+from cdktf import FileProvisioner
+from constructs import Construct
+from cdktf import DataResource, TerraformStack
+class MyConvertedCode(TerraformStack):
+    def __init__(self, scope, name):
+        super().__init__(scope, name)
+        DataResource(self, "example",
+            triggers_replace=[{
+                "examplekey": "examplevalue"
+            }
+            ],
+            provisioners=[FileProvisioner(
+                type="local-exec",
+                command="echo 'Hello, World!'"
+            )
+            ]
+        )
+```
+
+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.
+
+<!-- cache-key: cdktf-0.20.1 input-b6d8b6e38d80ac78f65d066ea25cd2dea7b7ecc2b9e41cb6603cc5a8cfa21f9d -->
diff --git a/docs/cdktf/python/resources/resource.md b/docs/cdktf/python/resources/resource.md
@@ -5,13 +5,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.
 
@@ -76,4 +76,4 @@ class MyConvertedCode(TerraformStack):
 - `id` (String) This is set to a random value at create time.
 
 
-<!-- cache-key: cdktf-0.20.1 input-63b48b841b04abe2967ff224f186b1f32a497a024e9fa833ce9444eccb45113e -->
+<!-- cache-key: cdktf-0.20.1 input-89ea6e8dae79e8917aacba471b3635623c77f324236527d549276a55d3fa9c13 -->
diff --git a/docs/cdktf/typescript/guides/terraform-migration.md b/docs/cdktf/typescript/guides/terraform-migration.md
@@ -0,0 +1,182 @@
+---
+page_title: "terraform_data Migration Guide"
+description: |-
+  Migration guide for moving `null_resource` resources to `terraform_data`
+---
+
+
+<!-- Please do not edit this file, it is generated. -->
+# 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:
+
+```typescript
+// DO NOT EDIT. Code generated by 'cdktf convert' - Please report bugs at https://cdk.tf/bug
+import { Construct } from "constructs";
+import { TerraformStack } from "cdktf";
+/*
+ * Provider bindings are generated by running `cdktf get`.
+ * See https://cdk.tf/provider-generation for more details.
+ */
+import { Resource } from "./.gen/providers/null/resource";
+class MyConvertedCode extends TerraformStack {
+  constructor(scope: Construct, name: string) {
+    super(scope, name);
+    new Resource(this, "example", {
+      provisioners: [
+        {
+          type: "local-exec",
+          command: "echo 'Hello, World!'",
+        },
+      ],
+    });
+  }
+}
+
+```
+
+Replace this configuration with a `terraform_data` managed resource and `moved` configuration:
+
+```typescript
+// DO NOT EDIT. Code generated by 'cdktf convert' - Please report bugs at https://cdk.tf/bug
+import { Construct } from "constructs";
+import { DataResource, TerraformStack } from "cdktf";
+class MyConvertedCode extends TerraformStack {
+  constructor(scope: Construct, name: string) {
+    super(scope, name);
+    new DataResource(this, "example", {
+      provisioners: [
+        {
+          type: "local-exec",
+          command: "echo 'Hello, World!'",
+        },
+      ],
+    });
+  }
+}
+
+```
+
+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:
+
+```typescript
+// DO NOT EDIT. Code generated by 'cdktf convert' - Please report bugs at https://cdk.tf/bug
+import { Construct } from "constructs";
+import { TerraformStack } from "cdktf";
+/*
+ * Provider bindings are generated by running `cdktf get`.
+ * See https://cdk.tf/provider-generation for more details.
+ */
+import { Resource } from "./.gen/providers/null/resource";
+class MyConvertedCode extends TerraformStack {
+  constructor(scope: Construct, name: string) {
+    super(scope, name);
+    new Resource(this, "example", {
+      triggers: [
+        {
+          examplekey: "examplevalue",
+        },
+      ],
+      provisioners: [
+        {
+          type: "local-exec",
+          command: "echo 'Hello, World!'",
+        },
+      ],
+    });
+  }
+}
+
+```
+
+Replace this configuration with the following `terraform_data` managed resource and `moved` configuration:
+
+```typescript
+// DO NOT EDIT. Code generated by 'cdktf convert' - Please report bugs at https://cdk.tf/bug
+import { Construct } from "constructs";
+import { DataResource, TerraformStack } from "cdktf";
+class MyConvertedCode extends TerraformStack {
+  constructor(scope: Construct, name: string) {
+    super(scope, name);
+    new DataResource(this, "example", {
+      triggers_replace: [
+        {
+          examplekey: "examplevalue",
+        },
+      ],
+      provisioners: [
+        {
+          type: "local-exec",
+          command: "echo 'Hello, World!'",
+        },
+      ],
+    });
+  }
+}
+
+```
+
+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.
+
+<!-- cache-key: cdktf-0.20.1 input-b6d8b6e38d80ac78f65d066ea25cd2dea7b7ecc2b9e41cb6603cc5a8cfa21f9d -->