Resource configuration

Resource documentation

Speakeasy automatically generates provider and resource documentation that is compliant with the public Terraform Registry requirements  via the HashiCorp-maintained terraform-plugin-docs tool. Speakeasy runs terraform-plugin-docs at the end of successful generations or manually run via go generate ./....

The public Terraform Registry and terraform-plugin-docs tool both follow specific file layout conventions.

For resources, the following file conventions are used:

The terraform-plugin-docs tool also supports its own advanced use case customization, such as custom templates. Refer to the terraform-plugin-docs documentation for more information about those capabilities.

Resource Description

The x-speakeasy-entity-description extension modifies the description of a Terraform data or managed resource. This is useful when augmenting the documentation for specific resources in an OpenAPI document. This documentation is expected to be in Markdown format. Use this extension alongside the x-speakeasy-entity extension.

In this example, an order managed resource will have Manage a coffee order. written as the description in the resource code for any consuming tools, including documentation written by terraform-plugin-docs into docs/resources/order.md:

Resource Example

Example resource configuration is based on the OpenAPI Specification for API operation request and response data schemas. Speakeasy only generates example configuration for configurable properties. Example configuration values use the property example field when available or, as a fallback, use a generated value of the expected type following any enum or validation fields.

Fully customize the example resource configuration by using Speakeasy code customization capabilities.

For example, to manually manage and update the example configuration for a managed resource:

• Edit root directory .genignore file with an entry for examples/resources/{type}/resource.tf
• Edit examples/resources/{type}/resource.tf as necessary
• Run go generate ./... or Speakeasy generation to update docs/resources/{name}.md

Resource version

The x-speakeasy-entity-version extension specifies the version of a given resource and should only be used if you need to write a state migrator, for instance, if you are changing the type of a field.

Terraform resource versions are zero-indexed and default to 0. For your first breaking change requiring a state migrator, set x-speakeasy-entity-version: 1. Each state migrator function must migrate from the previous version of the state.

If this is set, a boilerplate state upgrader will be written and hooked into internal/stateupgraders/your_resource_v1.go. Please refer to the Terraform documentation  for guidance on writing a state migrator.