Skip to content

Commit 5db7d14

Browse files
trujillo-adamtrujillo-adam
authored
add details about identity arg in import ref (#924)
We commented out the `identity` argument when we rewrote the `import` block reference because it hadn't yet been adopted by provider developers, which was leading to confusion. This PR re-adds the argument and provides an example.
2 parents 0c182ca + f95e96c commit 5db7d14

File tree

2 files changed

+79
-31
lines changed

2 files changed

+79
-31
lines changed

‎content/terraform/v1.12.x/docs/language/block/import.mdx‎

Lines changed: 39 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -14,8 +14,8 @@ An `import` block supports the following configuration:
1414

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

@@ -26,11 +26,14 @@ The following `module` block includes all built-in arguments:
2626
```hcl
2727
import {
2828
to = resource.type.address
29-
id = "cloud-provider-id"
30-
for_each = { # `for_each` accepts a map or a set of strings
29+
id = "cloud-provider-id" # `id` is mutually exclusive with `identity`
30+
identity = { # `identity` is mutually exclusive with `id`
31+
<ATTRIBUTE> = <VALUE>
32+
}
33+
for_each = { # `for_each` accepts a map or a set of strings
3134
<KEY> = <VALUE>
3235
}
33-
for_each = [ # `for_each` accepts a map or a set of strings
36+
for_each = [ # `for_each` accepts a map or a set of strings
3437
"<VALUE>",
3538
"<VALUE>"
3639
]
@@ -95,20 +98,18 @@ You must specify a string or an expression that evaluates to a string. The ID mu
9598

9699
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.
97100

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

102103
#### Summary
103104

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

108-
<!-- leave out for now - providers are not using this yet
109+
109110
### `identity`
110111

111-
The `identity` argument specifies a resource identity object that uniquely identifies a resource.
112+
The `identity` argument specifies a set of attributes that uniquely identifies a resource.
112113

113114
```hcl
114115
import {
@@ -118,9 +119,7 @@ import {
118119
}
119120
```
120121

121-
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.
122-
123-
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`.
122+
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.
124123

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

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

133-
-->
134132

135133
### `for_each`
136134

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

205203
### Import a single resource
206204

207-
In the following example, Terraform imports `example-bucket` into a resource at `aws_s3_bucket.this`:
205+
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.
206+
207+
<Tabs>
208+
209+
<Tab heading="Import using ID">
208210

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

210213
```hcl
211214
import {
@@ -214,13 +217,34 @@ import {
214217
}
215218
216219
resource "aws_s3_bucket" "this" {
217-
}
218220
# …
219221
}
220222
```
221223

222224
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.
223225

226+
</Tab>
227+
228+
<Tab heading="Import using identity attributes">
229+
230+
In the following example, Terraform imports an S3 bucket using its `account_id`, `bucket`, and `region` attributes:
231+
232+
```hcl
233+
import {
234+
to = aws_s3_bucket.bucket
235+
identity = {
236+
account_id = "622801496880"
237+
bucket = "hjarui4t89efuh"
238+
region = "us-east-1"
239+
}
240+
}
241+
```
242+
243+
244+
</Tab>
245+
246+
</Tabs>
247+
224248
### Import multiple resources
225249

226250
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"]`.

‎content/terraform/v1.13.x/docs/language/block/import.mdx‎

Lines changed: 40 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -14,8 +14,8 @@ An `import` block supports the following configuration:
1414

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

@@ -26,11 +26,14 @@ The following `module` block includes all built-in arguments:
2626
```hcl
2727
import {
2828
to = resource.type.address
29-
id = "cloud-provider-id"
30-
for_each = { # `for_each` accepts a map or a set of strings
29+
id = "cloud-provider-id" # `id` is mutually exclusive with `identity`
30+
identity = { # `identity` is mutually exclusive with `id`
31+
<ATTRIBUTE> = <VALUE>
32+
}
33+
for_each = { # `for_each` accepts a map or a set of strings
3134
<KEY> = <VALUE>
3235
}
33-
for_each = [ # `for_each` accepts a map or a set of strings
36+
for_each = [ # `for_each` accepts a map or a set of strings
3437
"<VALUE>",
3538
"<VALUE>"
3639
]
@@ -95,20 +98,18 @@ You must specify a string or an expression that evaluates to a string. The ID mu
9598

9699
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.
97100

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

102103
#### Summary
103104

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

108-
<!-- leave out for now - providers are not using this yet
109+
109110
### `identity`
110111

111-
The `identity` argument specifies a resource identity object that uniquely identifies a resource.
112+
The `identity` argument specifies a set of attributes that uniquely identifies a resource.
112113

113114
```hcl
114115
import {
@@ -118,9 +119,7 @@ import {
118119
}
119120
```
120121

121-
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.
122-
123-
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`.
122+
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.
124123

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

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

133-
-->
134132

135133
### `for_each`
136134

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

205203
### Import a single resource
206204

207-
In the following example, Terraform imports `example-bucket` into a resource at `aws_s3_bucket.this`:
205+
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.
208206

207+
<Tabs>
208+
209+
<Tab heading="Import using ID">
210+
211+
In the following example, Terraform imports `example-bucket` into a resource at `aws_s3_bucket.this`:
209212

210213
```hcl
211214
import {
@@ -214,13 +217,34 @@ import {
214217
}
215218
216219
resource "aws_s3_bucket" "this" {
217-
}
218220
# …
219221
}
220222
```
221223

222224
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.
223225

226+
</Tab>
227+
228+
<Tab heading="Import using identity attributes">
229+
230+
In the following example, Terraform imports an S3 bucket using its `account_id`, `bucket`, and `region` attributes:
231+
232+
```hcl
233+
import {
234+
to = aws_s3_bucket.bucket
235+
identity = {
236+
account_id = "622801496880"
237+
bucket = "hjarui4t89efuh"
238+
region = "us-east-1"
239+
}
240+
}
241+
```
242+
243+
244+
</Tab>
245+
246+
</Tabs>
247+
224248
### Import multiple resources
225249

226250
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"]`.
@@ -302,4 +326,4 @@ import {
302326
303327
resource "aws_instance" "web" {
304328
# ...
305-
}
329+
}

0 commit comments

Comments
 (0)