Resource Import Documentation Handling

[bflad]

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}
```

References

• Support Managed Resource Import #33

[bflad]

Just for completeness, there could be other import documentation for consideration, such as gotchas and notes. Please see the following for additional examples:

• https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/emr_cluster#import
• https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/organizations_account#import
• https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/transfer_server#import