Resource Import Documentation Handling #160
Description
Module version
v0.4.0 (not yet released)
Use-cases
Provider developers will want to document whether a resource supports import and what type of import identifier(s) are supported. Tooling such as terraform-plugin-docs (or similar) should be able to determine the implementation and automatically generate import documentation.
For example, most simple resources follow this simple type of documentation pattern for "passthrough" import:
- https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/instance#import
- https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/rds_cluster#import
- https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/windows_virtual_machine#import
- https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/mssql_database#import
Some resources may need to document more complicated cases, such as "complex" identifiers that get split into multiple attributes:
- https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role_policy#import
- https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/lambda_provisioned_concurrency_config#import
The most advanced cases require documenting multiple example import identifiers (sometimes to make the process easier for practitioners, other times to workaround incomplete Read APIs):
- https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/route53_record#import
- https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/route53_zone_association#import
- https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/security_group_rule#import
- https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/cloudfunctions_function#import
- https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/compute_instance#import
Attempted Solutions
Version 0.4.0 of the framework supports resource import via a required ImportState method on the Resource type. This makes it difficult for tooling to determine if import is supported or not as it is reliant on specific implementation details, which may or may not be consistently implemented (such as the recommended ResourceImportStateNotImplemented() helper).
There is no current methodology for tooling to know import examples, except by describing it manually in resource descriptions.
Proposal
Consider migrating the ImportState method onto its own interface type, e.g.
type ResourceWithImportState interface {
Resource
ImportState(context.Context, ImportResourceStateRequest, *ImportStateResponse)
}This will effectively make import support optional, against the design goals described in https://github.com/hashicorp/terraform-plugin-framework/blob/main/docs/design/import.md, however this means the framework can fully own the non-existent support implementation and downstream tooling will be able to easily determine if the implementation exists.
To handle documentation for all cases, an additional declarative documentation method could be added to that interface as well, e.g.
type ResourceWithImportState interface {
Resource
ImportState(context.Context, ImportResourceStateRequest, *ImportStateResponse)
ImportExamples() []ImportExample
}
type ImportExample struct {
// optional
Description string
Identifier string
}Potentially with helpers to make this easier for provider developers. Theoretically then, tooling could loop through those examples to fully generate import documentation for each import example such as:
{DESCRIPTION}
```console
$ terraform import {RESOURCE_TYPE}.example {IDENTIFIER}
```