Terraform Plugin Best Practices

A key feature of Terraform is its plugin system, which separates the details of specific vendor APIs from the shared logic for managing state, managing configuration, and providing a safe plan and apply lifecycle. Plugins are responsible for the implementation of functionality for provisioning resources for a specific cloud provider, allowing each provider to fully support its unique resources and lifecycles and not settling for the lowest common denominator across all provider resources of that type (virtual machines, networks, configuration management systems, et. al). While each provider is unique, over the years, we accumulated recommended patterns that help ensure a consistent user experience when using Terraform for any given provider. This page describes best practices that generally apply to most Providers, with a brief description of each, and link to read more.

Interacting with Providers

Terraform's providers are a substantial amount of code, and occasionally it makes sense to depend on their functionality. Interacting with Providers describes different ways to interface with Terraform's providers outside of the context of the Terraform CLI.

Provider Design Principles

Over time, the Terraform development community has gained large amounts of experience across a wide breadth of Application Programming Interfaces (APIs) supported by Terraform and its Software Development Kits (SDKs). The Provider Design Principles highlight the most prolific patterns when designing Terraform providers and associated resources and functions, which guide HashiCorp design decisions.

Provider Code

In Provider Code, we describe the supported programming languages and HashiCorp libraries that can be used to develop Terraform Providers.

Naming

Naming resources, data sources, functions, and attributes in plugins is how plugin authors expose their functionality to operators and using patterns common to other plugins lays the foundation for a good user experience.

Versioning and Changelog

Terraform development serves two distinct audiences: those writing plugin code and those implementing them. By clearly and consistently allowing operators to easily understand changes in plugin implementation via version numbering and documenting those changes, a trust is formed between the two audiences. In Versioning and Changelog we cover some guidelines when deciding release versions and how to relay changes through documentation.

Handling Sensitive Data

In Handling Sensitive Data, we discuss the recommended approaches for managing sensitive state in Terraform.