From ea25d78ca8c3d1ff2cff72a227ca04d3a74d13d5 Mon Sep 17 00:00:00 2001 From: Andrei Ciobanu Date: Wed, 27 May 2026 13:19:33 +0300 Subject: [PATCH] [Backport][v1.12] website: Update the documentation on "import" blocks (#4157) Signed-off-by: Martin Atkins Co-authored-by: Martin Atkins --- website/docs/language/import/index.mdx | 74 ++++++++++++++++---------- 1 file changed, 47 insertions(+), 27 deletions(-) diff --git a/website/docs/language/import/index.mdx b/website/docs/language/import/index.mdx index 2593e2185a..3ddad530fa 100644 --- a/website/docs/language/import/index.mdx +++ b/website/docs/language/import/index.mdx @@ -9,11 +9,11 @@ description: >- While we do not expect to make backwards-incompatible changes to syntax, the `-generate-config-out` flag and how OpenTofu processes imports during the plan stage and generates configuration may change in future releases. ::: -Use the `import` block to import existing infrastructure resources into OpenTofu, bringing them under OpenTofu's management. Unlike the `tofu import` command, configuration-driven import using `import` blocks is predictable, works with CICD pipelines, and lets you preview an import operation before modifying state. +Use the `import` block to import existing infrastructure objects into OpenTofu, bringing them under OpenTofu's management. Unlike the `tofu import` command, configuration-driven import using `import` blocks is predictable, works with CICD pipelines, and lets you preview an import operation before modifying state. -Once imported, OpenTofu tracks the resource in your state file. You can then manage the imported resource like any other, updating its attributes and destroying it as part of a standard resource lifecycle. +Once imported, OpenTofu tracks the object as a resource instance in your state file. You can then manage the imported object like any other, updating its attributes and destroying it as part of a standard resource lifecycle. -The `import` block records that OpenTofu imported the resource and did not create it. After importing, you can optionally remove import blocks from your configuration or leave them as a record of the resource's origin. +The `import` block represents that OpenTofu imported the object and did not create it. After importing, you can optionally remove import blocks from your configuration or leave them as a record of the object's origin. ## Syntax @@ -21,8 +21,10 @@ You can add an `import` block to any OpenTofu configuration file. A common patte ```hcl import { + identity = { + id = "i-abcd1234" + } to = aws_instance.example - id = "i-abcd1234" } resource "aws_instance" "example" { @@ -34,44 +36,62 @@ resource "aws_instance" "example" { The above `import` block defines an import of the AWS instance with the ID "i-abcd1234" into the `aws_instance.example` resource in the root module. The `import` block has the following arguments: -- `to` - The instance address this resource will have in your state file. -- `id` - A string with the [import ID](#import-id) of the resource. -- `provider` (optional) - An optional custom resource provider, see [The Resource provider Meta-Argument](../../language/meta-arguments/resource-provider.mdx) for details. -- `for_each` (optional) - Import several resources by iterating over a map or a set. See [Importing multiple resources](#importing-multiple-resources) below. +- Either `identity` or `id` - To [specify which remote object to import](#import-id). +- `to` - The resource instance address that OpenTofu will use to track this object in [OpenTofu state](../state/index.mdx). +- `provider` (optional) - The provider instance to use for importing, as with [The Resource provider Meta-Argument](../../language/meta-arguments/resource-provider.mdx). +- `for_each` (optional) - Import several objects as multiple instances of the same resource by iterating over a map or a set. See [Importing multiple resources](#importing-multiple-resources) below. If you do not set the `provider` argument, OpenTofu attempts to import from the default provider. -### Import ID +### Specifying what to import {#import-id} -The import block requires you to provide the `id` argument with a literal string of your resource's import ID. OpenTofu needs this import ID to locate the resource you want to import. +The `identity` and `id` arguments offer two different ways to specify which remote object you intend to import. These arguments are mutually-exclusive. -The identifier you use for a resource's import ID is resource-specific. You can find the required ID in the provider's documentation for the resource you wish to import. +The `identity` argument is the modern approach which specifies the remote object by specifying one or more attributes whose names and types vary depending on the resource type's _identity schema_. For example, importing into an `aws_instance` resource instance requires an object with a single `id` attribute: + +```hcl +import { + identity = { + id = "i-abcd1234" + } + to = aws_instance.example +} +``` + +Not all resource types have been updated to support `identity` yet. For older resource types you must use the top-level `id` argument instead and specify the remote object using a single string in whatever form the provider is expecting. For example, `aws_instance` expects the instance ID directly when using this legacy approach: + +```hcl +import { + id = "i-abcd1234" + to = aws_instance.example +} +``` + +Refer to the documentation for the resource type you are importing into to learn whether that resource type has an identity schema to use with `identity`, or if it still requires you to use the legacy `id` argument. ## Plan and apply an import -OpenTofu processes the `import` block during the plan stage. Once a plan is approved, OpenTofu imports the resource into its state during the subsequent apply stage. +OpenTofu processes the `import` block during the plan stage. Once a plan is approved, OpenTofu imports the object into its state during the subsequent apply stage. -To import a resource using `import` blocks, you must: -1. Define an `import` block for the resource(s). -1. Add a corresponding `resource` block to your configuration , or [generate configuration](../../language/import/generating-configuration.mdx) for that resource. -1. Run `tofu plan` to review how OpenTofu will import the resource(s). -1. Apply the configuration to import the resources and update your OpenTofu state. +To import an object using `import` blocks, you must: +1. Write `import` blocks describing the relationship between the remote objects and the resource instance addresses OpenTofu should use to track them. +1. Add the corresponding `resource` blocks to your configuration , or [generate initial configuration automatically](../../language/import/generating-configuration.mdx). +1. Run `tofu plan` to review how OpenTofu will import the objects. +1. Apply the plan to import the objects and update your OpenTofu state. -The `import` block is [_idempotent_](https://en.wikipedia.org/wiki/Idempotence), meaning that applying an import action and running another plan will not generate another import action as long as that resource remains in your state. - -OpenTofu only needs to import a given resource once. Attempting to import a resource into the same address again is a harmless no-op. You can remove `import` blocks after completing the import or safely leave them in your configuration as a record of the resource's origin for future module maintainers. For more information on maintaining configurations over time, see [Refactoring](../../language/modules/develop/refactoring.mdx). +An `import` block is active only if OpenTofu is not already tracking an object with the address given in `to`. After importing is successful, an `import` block becomes inert and you can optionally remove it from your configuration or retain it as a historical record for future maintainers. For more information on maintaining configurations over time, refer to [Refactoring](../../language/modules/develop/refactoring.mdx) ## Resource configuration -Before importing, you must add configuration for every resource you want OpenTofu to import. Otherwise, OpenTofu throws an error during planning, insisting you add resource configuration before it can successfully import. You can create resource configuration manually or [generate it using OpenTofu](../../language/import/generating-configuration.mdx). +Before importing, you must add a `resource` block for every object (or collection of related objects) you want OpenTofu to import. Otherwise, OpenTofu raises an error during planning, insisting you add resource configuration before it can successfully import. You can create resource configuration manually or [generate it using OpenTofu](../../language/import/generating-configuration.mdx). We recommend writing a `resource` block if you know what most of the [resource's arguments](../../language/resources/syntax.mdx#resource-arguments) will be. For example, your configuration may already contain a similar resource whose configuration you can copy and modify. -We recommend [generating configuration](../../language/import/generating-configuration.mdx) when importing multiple resources or a single complex resource that you do not already have the configuration for. +We recommend [generating configuration](../../language/import/generating-configuration.mdx) when importing multiple objects or a single complex object that you do not already have the configuration for. ### Add a `resource` block -Add a `resource` block for the resource to import. The resource address must match the import block's `to` argument. +Add a `resource` block for the resource to import into. The `to` argument in the `import` block must refer to that resource. ```hcl import { @@ -86,8 +106,8 @@ resource "aws_instance" "example" { ### Generate configuration -OpenTofu can generate HCL for resources that do not already exist in configuration. -For more details, see [Generating Configuration](../../language/import/generating-configuration.mdx). +OpenTofu can generate `resource` blocks for resources that are not already declared in your configuration. +For more details, refer to [Generating Configuration](../../language/import/generating-configuration.mdx). ## Examples @@ -133,9 +153,9 @@ import { } ``` -### Importing multiple resources +### Importing multiple objects {#importing-multiple-resources} -You can import multiple resources with one import block by using a `for_each` expression. This expression accepts [a set, a tuple or a map](../../language/expressions/types.mdx) and provides the `each.key` and `each.value` variables to access the individual elements. +You can import multiple resources instances with one import block by using a `for_each` expression. This expression accepts [a set, a tuple or a map](../../language/expressions/types.mdx) and provides the `each.key` and `each.value` variables to access the individual elements. In the example below, you can specify a list of server IDs to be imported. If you specify an empty list, the `random_id` resource will generate all IDs randomly. If you specify some IDs, the import block will import the specified IDs and the resource will randomly generate the rest. Note, the `random_id` resource requires the IDs to be in base64 format.