Skip to content

Commit 3b9b212

Browse files
austinvalleaustinvalle
authored
generate: Add support for import configuration examples with the id attribute (#495)
* quick impl * add ID prefix * template update * add changelog * add import shell test * update acceptance tests and add some import config files * update naming * update changelog
1 parent 31cddc7 commit 3b9b212

13 files changed

+204
-49
lines changed

‎.changes/unreleased/FEATURES-20250616-181322.yaml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
kind: FEATURES
2+
body: 'generate: Added support for defining import example file (`import-by-string-id.tf`) using Terraform configuration and the `id` attribute'
3+
time: 2025-06-16T18:13:22.627319-04:00
4+
custom:
5+
Issue: "472"

‎README.md‎

Lines changed: 32 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -223,15 +223,16 @@ For examples:
223223
> **NOTE:** In the following conventional paths for examples, `<data source name>` and `<resource name>` include the provider prefix as well, but the provider prefix is **NOT** included in`<function name>`.
224224
> For example, the data source [`caller_identity`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/caller_identity) in the `aws` provider would have an "example" conventional path of: `examples/data-sources/aws_caller_identity/data-source.tf`
225225
226-
| Path | Description |
227-
|---------------------------------------------------------------------------|-----------------------------------|
228-
| `examples/` | Root of examples |
229-
| `examples/provider/provider.tf` | Provider example config |
230-
| `examples/data-sources/<data source name>/data-source.tf` | Data source example config |
231-
| `examples/ephemeral-resources/<ephemeral resource>/ephemeral-resource.tf` | Ephemeral resource example config |
232-
| `examples/functions/<function name>/function.tf` | Function example config |
233-
| `examples/resources/<resource name>/resource.tf` | Resource example config |
234-
| `examples/resources/<resource name>/import.sh` | Resource example import command |
226+
| Path | Description |
227+
|---------------------------------------------------------------------------|--------------------------------------|
228+
| `examples/` | Root of examples |
229+
| `examples/provider/provider.tf` | Provider example config |
230+
| `examples/data-sources/<data source name>/data-source.tf` | Data source example config |
231+
| `examples/ephemeral-resources/<ephemeral resource>/ephemeral-resource.tf` | Ephemeral resource example config |
232+
| `examples/functions/<function name>/function.tf` | Function example config |
233+
| `examples/resources/<resource name>/resource.tf` | Resource example config |
234+
| `examples/resources/<resource name>/import.sh` | Resource example import command |
235+
| `examples/resources/<resource name>/import-by-string-id.tf` | Resource example import by id config |
235236
236237
#### Migration
237238
@@ -280,31 +281,33 @@ using the following data fields and functions:
280281
281282
##### Provider Fields
282283
283-
| Field | Type | Description |
284-
|------------------------:|:------:|-------------------------------------------------------------------------------------------|
285-
| `.Description` | string | Provider description |
286-
| `.HasExample` | bool | Is there an example file? |
287-
| `.ExampleFile` | string | Path to the file with the terraform configuration example |
288-
| `.ProviderName` | string | Canonical provider name (ex. `terraform-provider-random`) |
289-
| `.ProviderShortName` | string | Short version of the rendered provider name (ex. `random`) |
284+
| Field | Type | Description |
285+
|-------------------------|--------|-------------------------------------------------------------------------------------------|
286+
| `.Description` | string | Provider description |
287+
| `.HasExample` | bool | Is there an example file? |
288+
| `.ExampleFile` | string | Path to the file with the terraform configuration example |
289+
| `.ProviderName` | string | Canonical provider name (ex. `terraform-provider-random`) |
290+
| `.ProviderShortName` | string | Short version of the rendered provider name (ex. `random`) |
290291
| `.RenderedProviderName` | string | Value provided via argument `--rendered-provider-name`, otherwise same as `.ProviderName` |
291-
| `.SchemaMarkdown` | string | a Markdown formatted Provider Schema definition |
292+
| `.SchemaMarkdown` | string | a Markdown formatted Provider Schema definition |
292293
293294
##### Managed Resource / Ephemeral Resource / Data Source Fields
294295
295-
| Field | Type | Description |
296-
|------------------------:|:------:|-------------------------------------------------------------------------------------------|
297-
| `.Name` | string | Name of the resource/data-source (ex. `tls_certificate`) |
298-
| `.Type` | string | Either `Resource` or `Data Source` |
299-
| `.Description` | string | Resource / Data Source description |
300-
| `.HasExample` | bool | Is there an example file? |
301-
| `.ExampleFile` | string | Path to the file with the terraform configuration example |
302-
| `.HasImport` | bool | Is there an import file? |
303-
| `.ImportFile` | string | Path to the file with the command for importing the resource |
304-
| `.ProviderName` | string | Canonical provider name (ex. `terraform-provider-random`) |
305-
| `.ProviderShortName` | string | Short version of the rendered provider name (ex. `random`) |
296+
| Field | Type | Description |
297+
|-------------------------|--------|-------------------------------------------------------------------------------------------|
298+
| `.Name` | string | Name of the resource/data-source (ex. `tls_certificate`) |
299+
| `.Type` | string | Either `Resource` or `Data Source` |
300+
| `.Description` | string | Resource / Data Source description |
301+
| `.HasExample` | bool | Is there an example file? |
302+
| `.ExampleFile` | string | Path to the file with the terraform configuration example |
303+
| `.HasImport` | bool | Is there an import shell file? (`terraform import` shell example) |
304+
| `.ImportFile` | string | Path to the file with the command for importing the resource |
305+
| `.HasImportIDConfig` | bool | Is there an import terraform config file? (`import` block example with `id`) |
306+
| `.ImportIDConfigFile` | string | Path to the file with the Terraform configuration for importing the resource by `id` |
307+
| `.ProviderName` | string | Canonical provider name (ex. `terraform-provider-random`) |
308+
| `.ProviderShortName` | string | Short version of the rendered provider name (ex. `random`) |
306309
| `.RenderedProviderName` | string | Value provided via argument `--rendered-provider-name`, otherwise same as `.ProviderName` |
307-
| `.SchemaMarkdown` | string | a Markdown formatted Resource / Data Source Schema definition |
310+
| `.SchemaMarkdown` | string | a Markdown formatted Resource / Data Source Schema definition |
308311
309312
##### Provider-defined Function Fields
310313

‎cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_generic_templates.txtar‎

Lines changed: 16 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -144,6 +144,8 @@ HasExample: true
144144
ExampleFile: $WORK/examples/resources/scaffolding_example/resource.tf
145145
HasImport: true
146146
ImportFile: $WORK/examples/resources/scaffolding_example/import.sh
147+
HasImportIDConfig: true
148+
ImportIDConfigFile: $WORK/examples/resources/scaffolding_example/import-by-string-id.tf
147149
ProviderName: terraform-provider-scaffolding
148150
ProviderShortName: scaffolding
149151
RenderedProviderName: terraform-provider-scaffolding
@@ -191,7 +193,7 @@ codefile:
191193
Import is supported using the following syntax:
192194

193195
```shell
194-
terraform import scaffolding_example.example
196+
terraform import scaffolding_example.example "id-123"
195197
```
196198

197199
tffile:
@@ -305,6 +307,8 @@ HasExample: {{.HasExample}}
305307
ExampleFile: {{.ExampleFile}}
306308
HasImport: {{.HasImport}}
307309
ImportFile: {{.ImportFile}}
310+
HasImportIDConfig: {{.HasImportIDConfig}}
311+
ImportIDConfigFile: {{.ImportIDConfigFile}}
308312
ProviderName: {{.ProviderName}}
309313
ProviderShortName: {{.ProviderShortName}}
310314
RenderedProviderName: {{.RenderedProviderName}}
@@ -371,12 +375,21 @@ data "scaffolding_example" "example" {
371375
provider "scaffolding" {
372376
# example configuration here
373377
}
374-
-- examples/resources/scaffolding_example/resource.tf --
378+
-- examples/resources/scaffolding_example/import-by-string-id.tf --
379+
import {
380+
to = scaffolding_example.example
381+
id = "id-123"
382+
}
383+
375384
resource "scaffolding_example" "example" {
376385
configurable_attribute = "some-value"
377386
}
378387
-- examples/resources/scaffolding_example/import.sh --
379-
terraform import scaffolding_example.example
388+
terraform import scaffolding_example.example "id-123"
389+
-- examples/resources/scaffolding_example/resource.tf --
390+
resource "scaffolding_example" "example" {
391+
configurable_attribute = "some-value"
392+
}
380393
-- internal/provider/example_data_source.go --
381394
// Copyright (c) HashiCorp, Inc.
382395
// SPDX-License-Identifier: MPL-2.0

‎cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_named_templates.txtar‎

Lines changed: 16 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -144,6 +144,8 @@ HasExample: true
144144
ExampleFile: $WORK/examples/resources/scaffolding_example/resource.tf
145145
HasImport: true
146146
ImportFile: $WORK/examples/resources/scaffolding_example/import.sh
147+
HasImportIDConfig: true
148+
ImportIDConfigFile: $WORK/examples/resources/scaffolding_example/import-by-string-id.tf
147149
ProviderName: terraform-provider-scaffolding
148150
ProviderShortName: scaffolding
149151
RenderedProviderName: terraform-provider-scaffolding
@@ -191,7 +193,7 @@ codefile:
191193
Import is supported using the following syntax:
192194

193195
```shell
194-
terraform import scaffolding_example.example
196+
terraform import scaffolding_example.example "id-123"
195197
```
196198

197199
tffile:
@@ -305,6 +307,8 @@ HasExample: {{.HasExample}}
305307
ExampleFile: {{.ExampleFile}}
306308
HasImport: {{.HasImport}}
307309
ImportFile: {{.ImportFile}}
310+
HasImportIDConfig: {{.HasImportIDConfig}}
311+
ImportIDConfigFile: {{.ImportIDConfigFile}}
308312
ProviderName: {{.ProviderName}}
309313
ProviderShortName: {{.ProviderShortName}}
310314
RenderedProviderName: {{.RenderedProviderName}}
@@ -371,12 +375,21 @@ data "scaffolding_example" "example" {
371375
provider "scaffolding" {
372376
# example configuration here
373377
}
374-
-- examples/resources/scaffolding_example/resource.tf --
378+
-- examples/resources/scaffolding_example/import-by-string-id.tf --
379+
import {
380+
to = scaffolding_example.example
381+
id = "id-123"
382+
}
383+
375384
resource "scaffolding_example" "example" {
376385
configurable_attribute = "some-value"
377386
}
378387
-- examples/resources/scaffolding_example/import.sh --
379-
terraform import scaffolding_example.example
388+
terraform import scaffolding_example.example "id-123"
389+
-- examples/resources/scaffolding_example/resource.tf --
390+
resource "scaffolding_example" "example" {
391+
configurable_attribute = "some-value"
392+
}
380393
-- internal/provider/example_data_source.go --
381394
// Copyright (c) HashiCorp, Inc.
382395
// SPDX-License-Identifier: MPL-2.0

‎cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_no_templates.txtar‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -122,6 +122,29 @@ resource "scaffolding_example" "example" {
122122
### Read-Only
123123

124124
- `id` (String) Example identifier
125+
126+
## Import
127+
128+
Import is supported using the following syntax:
129+
130+
In Terraform v1.5.0 and later, the [`import` block](https://developer.hashicorp.com/terraform/language/import) can be used with the `id` attribute, for example:
131+
132+
```terraform
133+
import {
134+
to = scaffolding_example.example
135+
id = "id-123"
136+
}
137+
138+
resource "scaffolding_example" "example" {
139+
configurable_attribute = "some-value"
140+
}
141+
```
142+
143+
The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example:
144+
145+
```shell
146+
terraform import scaffolding_example.example "id-123"
147+
```
125148
-- examples/README.md --
126149
# Examples
127150

@@ -140,6 +163,17 @@ data "scaffolding_example" "example" {
140163
provider "scaffolding" {
141164
# example configuration here
142165
}
166+
-- examples/resources/scaffolding_example/import-by-string-id.tf --
167+
import {
168+
to = scaffolding_example.example
169+
id = "id-123"
170+
}
171+
172+
resource "scaffolding_example" "example" {
173+
configurable_attribute = "some-value"
174+
}
175+
-- examples/resources/scaffolding_example/import.sh --
176+
terraform import scaffolding_example.example "id-123"
143177
-- examples/resources/scaffolding_example/resource.tf --
144178
resource "scaffolding_example" "example" {
145179
configurable_attribute = "some-value"

‎cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_generic_templates.txtar‎

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -193,6 +193,8 @@ HasExample: true
193193
ExampleFile: $WORK/examples/resources/scaffolding_example/resource.tf
194194
HasImport: true
195195
ImportFile: $WORK/examples/resources/scaffolding_example/import.sh
196+
HasImportIDConfig: true
197+
ImportIDConfigFile: $WORK/examples/resources/scaffolding_example/import-by-string-id.tf
196198
ProviderName: terraform-provider-scaffolding
197199
ProviderShortName: scaffolding
198200
RenderedProviderName: terraform-provider-scaffolding
@@ -240,7 +242,7 @@ codefile:
240242
Import is supported using the following syntax:
241243

242244
```shell
243-
terraform import scaffolding_example.example
245+
terraform import scaffolding_example.example "id-123"
244246
```
245247

246248
tffile:
@@ -453,6 +455,8 @@ HasExample: {{.HasExample}}
453455
ExampleFile: {{.ExampleFile}}
454456
HasImport: {{.HasImport}}
455457
ImportFile: {{.ImportFile}}
458+
HasImportIDConfig: {{.HasImportIDConfig}}
459+
ImportIDConfigFile: {{.ImportIDConfigFile}}
456460
ProviderName: {{.ProviderName}}
457461
ProviderShortName: {{.ProviderShortName}}
458462
RenderedProviderName: {{.RenderedProviderName}}
@@ -581,11 +585,20 @@ provider "scaffolding" {
581585
# example configuration here
582586
}
583587
-- examples/resources/scaffolding_example/resource.tf --
588+
resource "scaffolding_example" "example" {
589+
configurable_attribute = "some-value"
590+
}
591+
-- examples/resources/scaffolding_example/import-by-string-id.tf --
592+
import {
593+
to = scaffolding_example.example
594+
id = "id-123"
595+
}
596+
584597
resource "scaffolding_example" "example" {
585598
configurable_attribute = "some-value"
586599
}
587600
-- examples/resources/scaffolding_example/import.sh --
588-
terraform import scaffolding_example.example
601+
terraform import scaffolding_example.example "id-123"
589602
-- examples/ephemeral-resources/scaffolding_example/ephemeral-resource.tf --
590603
resource "scaffolding_example" "example" {
591604
configurable_attribute = "some-value"

‎cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_legacy_docs.txtar‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -193,11 +193,20 @@ resource "scaffolding_example" "example" {
193193
configurable_attribute = "some-value"
194194
}
195195
-- examples/ephemeral-resources/scaffolding_example/ephemeral-resource.tf --
196+
resource "scaffolding_example" "example" {
197+
configurable_attribute = "some-value"
198+
}
199+
-- examples/resources/scaffolding_example/import-by-string-id.tf --
200+
import {
201+
to = scaffolding_example.example
202+
id = "id-123"
203+
}
204+
196205
resource "scaffolding_example" "example" {
197206
configurable_attribute = "some-value"
198207
}
199208
-- examples/resources/scaffolding_example/import.sh --
200-
terraform import scaffolding_example.example
209+
terraform import scaffolding_example.example "id-123"
201210
-- schema.json --
202211
{
203212
"format_version": "1.0",

‎cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_named_templates.txtar‎

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -192,6 +192,8 @@ HasExample: true
192192
ExampleFile: $WORK/examples/resources/scaffolding_example/resource.tf
193193
HasImport: true
194194
ImportFile: $WORK/examples/resources/scaffolding_example/import.sh
195+
HasImportIDConfig: true
196+
ImportIDConfigFile: $WORK/examples/resources/scaffolding_example/import-by-string-id.tf
195197
ProviderName: terraform-provider-scaffolding
196198
ProviderShortName: Scaffolding
197199
RenderedProviderName: Scaffolding
@@ -239,7 +241,7 @@ codefile:
239241
Import is supported using the following syntax:
240242

241243
```shell
242-
terraform import scaffolding_example.example
244+
terraform import scaffolding_example.example "id-123"
243245
```
244246

245247
tffile:
@@ -452,6 +454,8 @@ HasExample: {{.HasExample}}
452454
ExampleFile: {{.ExampleFile}}
453455
HasImport: {{.HasImport}}
454456
ImportFile: {{.ImportFile}}
457+
HasImportIDConfig: {{.HasImportIDConfig}}
458+
ImportIDConfigFile: {{.ImportIDConfigFile}}
455459
ProviderName: {{.ProviderName}}
456460
ProviderShortName: {{.ProviderShortName}}
457461
RenderedProviderName: {{.RenderedProviderName}}
@@ -584,11 +588,20 @@ resource "scaffolding_example" "example" {
584588
configurable_attribute = "some-value"
585589
}
586590
-- examples/ephemeral-resources/scaffolding_example/ephemeral-resource.tf --
591+
resource "scaffolding_example" "example" {
592+
configurable_attribute = "some-value"
593+
}
594+
-- examples/resources/scaffolding_example/import-by-string-id.tf --
595+
import {
596+
to = scaffolding_example.example
597+
id = "id-123"
598+
}
599+
587600
resource "scaffolding_example" "example" {
588601
configurable_attribute = "some-value"
589602
}
590603
-- examples/resources/scaffolding_example/import.sh --
591-
terraform import scaffolding_example.example
604+
terraform import scaffolding_example.example "id-123"
592605
-- schema.json --
593606
{
594607
"format_version": "1.0",

‎cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_no_templates.txtar‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -192,6 +192,23 @@ resource "scaffolding_example" "example" {
192192
### Read-Only
193193

194194
- `id` (String) Example identifier
195+
196+
## Import
197+
198+
Import is supported using the following syntax:
199+
200+
In Terraform v1.5.0 and later, the [`import` block](https://developer.hashicorp.com/terraform/language/import) can be used with the `id` attribute, for example:
201+
202+
```terraform
203+
import {
204+
to = scaffolding_example.example
205+
id = "id-123"
206+
}
207+
208+
resource "scaffolding_example" "example" {
209+
configurable_attribute = "some-value"
210+
}
211+
```
195212
-- expected-ephemeral-resource.md --
196213
---
197214
# generated by https://github.com/hashicorp/terraform-plugin-docs
@@ -250,6 +267,15 @@ output "test" {
250267
provider "scaffolding" {
251268
# example configuration here
252269
}
270+
-- examples/resources/scaffolding_example/import-by-string-id.tf --
271+
import {
272+
to = scaffolding_example.example
273+
id = "id-123"
274+
}
275+
276+
resource "scaffolding_example" "example" {
277+
configurable_attribute = "some-value"
278+
}
253279
-- examples/resources/scaffolding_example/resource.tf --
254280
resource "scaffolding_example" "example" {
255281
configurable_attribute = "some-value"

0 commit comments

Comments
 (0)