Skip to content

add details about identity arg in import ref #924

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Sep 11, 2025
Merged

add details about identity arg in import ref #924

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
98492c3
add details about identity arg in import ref
trujillo-adam Sep 8, 2025
d458f10
update 'Complete configuration' section
trujillo-adam Sep 8, 2025
4b59a75
Merge branch 'main' into docs/reintroduce-identity-argument
trujillo-adam Sep 10, 2025
f95e96c
Apply suggestions from code review
trujillo-adam Sep 11, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 39 additions & 15 deletions content/terraform/v1.12.x/docs/language/block/import.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,8 +14,8 @@ An `import` block supports the following configuration:

- [`import`](#import) &nbsp block
- [`to`](#to) &nbsp address | required
- [`id`](#id) &nbsp string
<!-- - [`identity`](#identity) &nbsp map | mutually exclusive with `id` -->
- [`id`](#id) &nbsp string | mutually exclusive with `identity`
- [`identity`](#identity) &nbsp map | mutually exclusive with `id`
- [`for_each`](#for_each) &nbsp map or set of strings
- [`provider`](#provider) &nbsp reference

Expand All @@ -26,11 +26,14 @@ The following `module` block includes all built-in arguments:
```hcl
import {
to = resource.type.address
id = "cloud-provider-id"
for_each = { # `for_each` accepts a map or a set of strings
id = "cloud-provider-id" # `id` is mutually exclusive with `identity`
identity = { # `identity` is mutually exclusive with `id`
<ATTRIBUTE> = <VALUE>
}
for_each = { # `for_each` accepts a map or a set of strings
<KEY> = <VALUE>
}
for_each = [ # `for_each` accepts a map or a set of strings
for_each = [ # `for_each` accepts a map or a set of strings
"<VALUE>",
"<VALUE>"
]
Expand Down Expand Up @@ -95,20 +98,18 @@ You must specify a string or an expression that evaluates to a string. The ID mu

The value of the `id` argument depends on the type of resource you are importing. You can only import resources that are supported by the provider. For information on how to import a resource, refer to the provider documentation.

<!--// HIDING INFO ABOUT IDENTITY FOR NOW //
You cannot use the `id` argument and [`identity` argument](#identity) in the same `import` block.
-->

#### Summary

- Data type: String
- Default: None
- Example: [Import a single resource](#import-a-single-resource)

<!-- leave out for now - providers are not using this yet

### `identity`

The `identity` argument specifies a resource identity object that uniquely identifies a resource.
The `identity` argument specifies a set of attributes that uniquely identifies a resource.

```hcl
import {
Expand All @@ -118,9 +119,7 @@ import {
}
```

The `identity` argument is an object of key-value pairs that uniquely identify a resource. The keys and values are specific to the resource type and provider.

The key-value pair for the `identity` object depends on the type of resource you are importing. You can only import resources that are supported by the provider. Refer to the provider documentation for information about how to retrieve the `identity`.
The keys of the `identity` argument are specific to the resource type and provider. You can only import resources that are supported by the provider. Refer to your provider documentation for details.

You cannot use the `identity` argument and [`id` argument](#id) in the same `import` block.

Expand All @@ -130,7 +129,6 @@ You cannot use the `identity` argument and [`id` argument](#id) in the same `imp
- Default: None
- Example: [Import a single resource](#import-a-single-resource)

-->

### `for_each`

Expand Down Expand Up @@ -204,8 +202,13 @@ The following examples show how to write configuration for common use cases.

### Import a single resource

In the following example, Terraform imports `example-bucket` into a resource at `aws_s3_bucket.this`:
You can import an individual resource by specifying its ID with the `id` argument or by specifying the set of identifying attributes in the `identity` argument.

<Tabs>

<Tab heading="Import using ID">

In the following example, Terraform imports `example-bucket` into a resource at `aws_s3_bucket.this`:

```hcl
import {
Expand All @@ -214,13 +217,34 @@ import {
}

resource "aws_s3_bucket" "this" {
}
# …
}
```

Refer to the [AWS provider documentation](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/instance#import) in the Terraform registry for more information about importing AWS instances.

</Tab>

<Tab heading="Import using identity attributes">

In the following example, Terraform imports an S3 bucket using its `account_id`, `bucket`, and `region` attributes:

```hcl
import {
to = aws_s3_bucket.bucket
identity = {
account_id = "622801496880"
bucket = "hjarui4t89efuh"
region = "us-east-1"
}
}
```


</Tab>

</Tabs>

### Import multiple resources

In the following example, the `for_each` argument loops through the key-value pairs defined in the `buckets` map. For each pair, Terraform imports the S3 bucket into the `aws_s3_bucket.this` resource. The `[each.key]` index maps to the keys in `locals` block, such as `aws_s3_bucket.this["staging"]`.
Expand Down
56 changes: 40 additions & 16 deletions content/terraform/v1.13.x/docs/language/block/import.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,8 +14,8 @@ An `import` block supports the following configuration:

- [`import`](#import) &nbsp block
- [`to`](#to) &nbsp address | required
- [`id`](#id) &nbsp string
<!-- - [`identity`](#identity) &nbsp map | mutually exclusive with `id` -->
- [`id`](#id) &nbsp string | mutually exclusive with `identity`
- [`identity`](#identity) &nbsp map | mutually exclusive with `id`
- [`for_each`](#for_each) &nbsp map or set of strings
- [`provider`](#provider) &nbsp reference

Expand All @@ -26,11 +26,14 @@ The following `module` block includes all built-in arguments:
```hcl
import {
to = resource.type.address
id = "cloud-provider-id"
for_each = { # `for_each` accepts a map or a set of strings
id = "cloud-provider-id" # `id` is mutually exclusive with `identity`
identity = { # `identity` is mutually exclusive with `id`
<ATTRIBUTE> = <VALUE>
}
for_each = { # `for_each` accepts a map or a set of strings
<KEY> = <VALUE>
}
for_each = [ # `for_each` accepts a map or a set of strings
for_each = [ # `for_each` accepts a map or a set of strings
"<VALUE>",
"<VALUE>"
]
Expand Down Expand Up @@ -95,20 +98,18 @@ You must specify a string or an expression that evaluates to a string. The ID mu

The value of the `id` argument depends on the type of resource you are importing. You can only import resources that are supported by the provider. For information on how to import a resource, refer to the provider documentation.

<!--// HIDING INFO ABOUT IDENTITY FOR NOW //
You cannot use the `id` argument and [`identity` argument](#identity) in the same `import` block.
-->

#### Summary

- Data type: String
- Default: None
- Example: [Import a single resource](#import-a-single-resource)

<!-- leave out for now - providers are not using this yet

### `identity`

The `identity` argument specifies a resource identity object that uniquely identifies a resource.
The `identity` argument specifies a set of attributes that uniquely identifies a resource.

```hcl
import {
Expand All @@ -118,9 +119,7 @@ import {
}
```

The `identity` argument is an object of key-value pairs that uniquely identify a resource. The keys and values are specific to the resource type and provider.

The key-value pair for the `identity` object depends on the type of resource you are importing. You can only import resources that are supported by the provider. Refer to the provider documentation for information about how to retrieve the `identity`.
The keys of the `identity` argument are specific to the resource type and provider. You can only import resources that are supported by the provider. Refer to your provider documentation for details.

You cannot use the `identity` argument and [`id` argument](#id) in the same `import` block.

Expand All @@ -130,7 +129,6 @@ You cannot use the `identity` argument and [`id` argument](#id) in the same `imp
- Default: None
- Example: [Import a single resource](#import-a-single-resource)

-->

### `for_each`

Expand Down Expand Up @@ -204,8 +202,13 @@ The following examples show how to write configuration for common use cases.

### Import a single resource

In the following example, Terraform imports `example-bucket` into a resource at `aws_s3_bucket.this`:
You can import an individual resource by specifying its ID in `id` argument or by specifying the set of identifying attributes in the `identity` argument.

<Tabs>

<Tab heading="Import using ID">

In the following example, Terraform imports `example-bucket` into a resource at `aws_s3_bucket.this`:

```hcl
import {
Expand All @@ -214,13 +217,34 @@ import {
}

resource "aws_s3_bucket" "this" {
}
# …
}
```

Refer to the [AWS provider documentation](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/instance#import) in the Terraform registry for more information about importing AWS instances.

</Tab>

<Tab heading="Import using identity attributes">

In the following example, Terraform imports an S3 bucket using its `account_id`, `bucket`, and `region` attributes:

```hcl
import {
to = aws_s3_bucket.bucket
identity = {
account_id = "622801496880"
bucket = "hjarui4t89efuh"
region = "us-east-1"
}
}
```


</Tab>

</Tabs>

### Import multiple resources

In the following example, the `for_each` argument loops through the key-value pairs defined in the `buckets` map. For each pair, Terraform imports the S3 bucket into the `aws_s3_bucket.this` resource. The `[each.key]` index maps to the keys in `locals` block, such as `aws_s3_bucket.this["staging"]`.
Expand Down Expand Up @@ -302,4 +326,4 @@ import {

resource "aws_instance" "web" {
# ...
}
}
Loading