Research Help improve navigation and content organization by answering a short survey. Start Survey
Terraform
Custom Framework Providers

Implement Documentation Generation

  • 7min
  • |
  • Terraform

In this tutorial, you will add documentation generation capabilities to a provider that interacts with the API of a fictional coffee-shop application called HashiCups. To do this, you will:

  1. Add terraform-plugin-docs to the provider.
    This enables the provider to automatically generate data source and resource documentation.
  2. Add schema descriptions.
    This enhances the documentation to include a description for the provider itself, its data sources and resources, and each of their attributes.
  3. Add configuration examples.
    This enhances the documentation to include example Terraform configurations.
  4. Add resource import documentation.
    This enhances the resource documentation to include an example of how to import the resources that support it.
  5. Run documentation generation.
    This ensures that the documentation generation works as expected.

The terraform-plugin-docs Go module cmd/tfplugindocs command enables providers to implement documentation generation. The generation uses schema descriptions and conventionally placed files to produce provider documentation that is compatible with the Terraform Registry.

Prerequisites

To follow this tutorial, you need:

Navigate to your terraform-provider-hashicups-pf directory.

Your code should match the acceptance-tests branch from the example repository.

If you're stuck at any point during this tutorial, refer to the documentation-generation branch to see the changes implemented in this tutorial.

Add schema descriptions

The tfplugindocs tool will automatically include schema-based descriptions, if present in a data source, provider, or resource's schema. The schema.Schema type's Description field describes the data source, provider, or resource itself. Each attribute's or block's Description field describes that particular attribute or block. These descriptions should be tailored to practitioner usage and include any caveats or value expectations, such as special syntax.

Open the internal/provider/provider.go file.

Add documentation to your provider by replacing the entire Schema method with the following, which adds Description fields to the provider's schema and each of it's attributes.

internal/provider/provider.go
// Schema defines the provider-level schema for configuration data.
func (p *hashicupsProvider) Schema(_ context.Context, _ provider.SchemaRequest, resp *provider.SchemaResponse) {
    resp.Schema = schema.Schema{
        Description: "Interact with HashiCups.",
        Attributes: map[string]schema.Attribute{
            "host": schema.StringAttribute{
                Description: "URI for HashiCups API. May also be provided via HASHICUPS_HOST environment variable.",
                Optional:    true,
            },
            "username": schema.StringAttribute{
                Description: "Username for HashiCups API. May also be provided via HASHICUPS_USERNAME environment variable.",
                Optional:    true,
            },
            "password": schema.StringAttribute{
                Description: "Password for HashiCups API. May also be provided via HASHICUPS_PASSWORD environment variable.",
                Optional:    true,
                Sensitive:   true,
            },
        },
    }
}

Open the internal/provider/coffees_data_source.go file.

Add documentation to your data source by replacing the entire Schema method with the following.

internal/provider/coffees_data_source.go
// Schema defines the schema for the data source.
func (d *coffeesDataSource) Schema(_ context.Context, _ datasource.SchemaRequest, resp *datasource.SchemaResponse) {
    resp.Schema = schema.Schema{
        Description: "Fetches the list of coffees.",
        Attributes: map[string]schema.Attribute{
            "id": schema.StringAttribute{
                Description: "Placeholder identifier attribute.",
                Computed:    true,
            },
            "coffees": schema.ListNestedAttribute{
                Description: "List of coffees.",
                Computed:    true,
                NestedObject: schema.NestedAttributeObject{
                    Attributes: map[string]schema.Attribute{
                        "id": schema.Int64Attribute{
                            Description: "Numeric identifier of the coffee.",
                            Computed:    true,
                        },
                        "name": schema.StringAttribute{
                            Description: "Product name of the coffee.",
                            Computed:    true,
                        },
                        "teaser": schema.StringAttribute{
                            Description: "Fun tagline for the coffee.",
                            Computed:    true,
                        },
                        "description": schema.StringAttribute{
                            Description: "Product description of the coffee.",
                            Computed:    true,
                        },
                        "price": schema.Float64Attribute{
                            Description: "Suggested cost of the coffee.",
                            Computed:    true,
                        },
                        "image": schema.StringAttribute{
                            Description: "URI for an image of the coffee.",
                            Computed:    true,
                        },
                        "ingredients": schema.ListNestedAttribute{
                            Description: "List of ingredients in the coffee.",
                            Computed:    true,
                            NestedObject: schema.NestedAttributeObject{
                                Attributes: map[string]schema.Attribute{
                                    "id": schema.Int64Attribute{
                                        Description: "Numeric identifier of the coffee ingredient.",
                                        Computed:    true,
                                    },
                                },
                            },
                        },
                    },
                },
            },
        },
    }
}

Open the internal/provider/order_resource.go file.

Add documentation to your resource by replacing the entire Schema method with the following.

internal/provider/order_resource.go
// Schema defines the schema for the resource.
func (r *orderResource) Schema(_ context.Context, _ resource.SchemaRequest, resp *resource.SchemaResponse) {
    resp.Schema = schema.Schema{
        Description: "Manages an order.",
        Attributes: map[string]schema.Attribute{
            "id": schema.StringAttribute{
                Description: "Numeric identifier of the order.",
                Computed:    true,
                PlanModifiers: []planmodifier.String{
                    stringplanmodifier.UseStateForUnknown(),
                },
            },
            "last_updated": schema.StringAttribute{
                Description: "Timestamp of the last Terraform update of the order.",
                Computed:    true,
            },
            "items": schema.ListNestedAttribute{
                Description: "List of items in the order.",
                Required:    true,
                NestedObject: schema.NestedAttributeObject{
                    Attributes: map[string]schema.Attribute{
                        "quantity": schema.Int64Attribute{
                            Description: "Count of this item in the order.",
                            Required:    true,
                        },
                        "coffee": schema.SingleNestedAttribute{
                            Description: "Coffee item in the order.",
                            Required:    true,
                            Attributes: map[string]schema.Attribute{
                                "id": schema.Int64Attribute{
                                    Description: "Numeric identifier of the coffee.",
                                    Required:    true,
                                },
                                "name": schema.StringAttribute{
                                    Description: "Product name of the coffee.",
                                    Computed:    true,
                                },
                                "teaser": schema.StringAttribute{
                                    Description: "Fun tagline for the coffee.",
                                    Computed:    true,
                                },
                                "description": schema.StringAttribute{
                                    Description: "Product description of the coffee.",
                                    Computed:    true,
                                },
                                "price": schema.Float64Attribute{
                                    Description: "Suggested cost of the coffee.",
                                    Computed:    true,
                                },
                                "image": schema.StringAttribute{
                                    Description: "URI for an image of the coffee.",
                                    Computed:    true,
                                },
                            },
                        },
                    },
                },
            },
        },
    }
}

Add configuration examples

The tfplugindocs tool will automatically include Terraform configuration examples from files with the following naming conventions:

  • Provider: examples/provider/provider.tf
  • Resources: examples/resources/TYPE/resource.tf
  • Data Sources: examples/data-sources/TYPE/data-source.tf

Replace TYPE with the name of the resource or data source. For example: examples/resources/hashicups_order/resource.tf.

Open the examples/provider/provider.tf file and replace the existing code with the following.

examples/provider/provider.tf
# Configuration-based authentication
provider "hashicups" {
  username = "education"
  password = "test123"
  host     = "http://localhost:19090"
}

Create a examples/data-sources/hashicups_coffees directory.

$ mkdir -p examples/data-sources/hashicups_coffees

Create the examples/data-sources/hashicups_coffees/data-source.tf file with the following.

examples/data-sources/hashicups_coffees/data-source.tf
# List all coffees.
data "hashicups_coffees" "all" {}

Create the examples/resources/hashicups_order directory.

$ mkdir -p examples/resources/hashicups_order

Create the examples/resources/hashicups_order/resource.tf file with the following.

examples/resources/hashicups_order/resource.tf
# Manage example order.
resource "hashicups_order" "example" {
  items = [
    {
      coffee = {
        id = 3
      }
      quantity = 2
    },
  ]
}

Add resource import documentation

The tfplugindocs tool automatically will include Terraform import examples for resources with the file naming convention examples/resources/TYPE/import.sh.

Create a new examples/resources/hashicups_order/import.sh file with the following.

examples/resources/hashicups_order/import.sh
# Order can be imported by specifying the numeric identifier.
terraform import hashicups_order.example 123

Run documentation generation

Now that you have implemented the documentation generation functionality for your provider, run the go generate ./... command to generate the documentation.

$ go generate ./...
rendering website for provider "hashicups" (as "hashicups")
exporting schema from Terraform
compiling provider "hashicups"
using Terraform CLI binary from PATH if available, otherwise downloading latest Terraform CLI binary
running terraform init
getting provider schema
rendering missing docs
generating missing resource content
generating template for "hashicups_order"
generating missing data source content
generating template for "hashicups_coffees"
generating missing provider content
generating template for "hashicups"
rendering static website
cleaning rendered website dir
rendering templated website to static markdown
rendering "data-sources/coffees.md.tmpl"
rendering "index.md.tmpl"
rendering "resources/order.md.tmpl"

View the generated files in the docs directory to verify that the data source, provider, and resource documentation contains the expected descriptions, examples, and schema information.

Next steps

Congratulations! You have enhanced the provider with documentation generation capabilities.

If you were stuck during this tutorial, checkout the documentation-generation branch to see the changes implemented in this tutorial.

Previous
Next