aRustyDev Terraform Provider Development
Build production-quality Terraform and OpenTofu providers using the Plugin Framework. This skill covers the complete provider development lifecycle from design through testing and release.
Purpose
Guide the development of custom Terraform providers following HashiCorp's best practices, with emphasis on Test-Driven Development (TDD), proper resource lifecycle management, and comprehensive acceptance testing.
When to Use
- Create new Terraform/OpenTofu providers for APIs or services
- Implement resources, data sources, and functions in providers
- Write acceptance tests using terraform-plugin-testing
- Debug provider behavior and state management issues
- Migrate existing SDKv2 providers to Plugin Framework
- Implement import functionality for resources
- Handle sensitive data and computed attributes properly
TDD Workflow
Follow the RED → GREEN → REFACTOR cycle for all provider development:
┌─────────────────────────────────────────────────────────────┐
│ RED: Write a failing test that defines expected behavior │
│ ↓ │
│ GREEN: Write minimal code to make the test pass │
│ ↓ │
│ REFACTOR: Improve code while keeping tests green │
│ ↓ │
│ REPEAT: Move to next requirement │
└─────────────────────────────────────────────────────────────┘
Never skip the RED phase. A test that never failed provides no confidence.
Provider Structure
terraform-provider-{name}/
├── main.go # Provider entry point
├── go.mod # Go module definition
├── internal/
│ └── provider/
│ ├── provider.go # Provider implementation
│ ├── provider_test.go # Provider tests
│ ├── {resource}_resource.go
│ ├── {resource}_resource_test.go
│ ├── {datasource}_data_source.go
│ └── {datasource}_data_source_test.go
├── examples/
│ ├── provider/
│ │ └── provider.tf
│ ├── resources/
│ │ └── {name}_{resource}/
│ │ └── resource.tf
│ └── data-sources/
│ └── {name}_{datasource}/
│ └── data-source.tf
├── docs/ # Generated documentation
├── templates/ # Doc templates (optional)
└── .goreleaser.yml # Release configuration
Provider Implementation
Basic Provider
package provider
import (
"context"
"github.com/hashicorp/terraform-plugin-framework/datasource"
"github.com/hashicorp/terraform-plugin-framework/provider"
"github.com/hashicorp/terraform-plugin-framework/provider/schema"
"github.com/hashicorp/terraform-plugin-framework/resource"
)
var _ provider.Provider = &ExampleProvider{}
type ExampleProvider struct {
version string
}
type ExampleProviderModel struct {
Endpoint types.String `tfsdk:"endpoint"`
APIKey types.String `tfsdk:"api_key"`
}
func New(version string) func() provider.Provider {
return func() provider.Provider {
return &ExampleProvider{
version: version,
}
}
}
func (p *ExampleProvider) Metadata(ctx context.Context, req provider.MetadataRequest, resp *provider.MetadataResponse) {
resp.TypeName = "example"
resp.Version = p.version
}
func (p *ExampleProvider) Schema(ctx context.Context, req provider.SchemaRequest, resp *provider.SchemaResponse) {
resp.Schema = schema.Schema{
Attributes: map[string]schema.Attribute{
"endpoint": schema.StringAttribute{
Optional: true,
Description: "API endpoint URL",
},
"api_key": schema.StringAttribute{
Optional: true,
Sensitive: true,
Description: "API key for authentication",
},
},
}
}
func (p *ExampleProvider) Configure(ctx context.Context, req provider.ConfigureRequest, resp *provider.ConfigureResponse) {
var config ExampleProviderModel
resp.Diagnostics.Append(req.Config.Get(ctx, &config)...)
if resp.Diagnostics.HasError() {
return
}
// Create API client and store in resp.DataSourceData and resp.ResourceData
client := NewAPIClient(config.Endpoint.ValueString(), config.APIKey.ValueString())
resp.DataSourceData = client
resp.ResourceData = client
}
func (p *ExampleProvider) Resources(ctx context.Context) []func() resource.Resource {
return []func() resource.Resource{
NewThingResource,
}
}
func (p *ExampleProvider) DataSources(ctx context.Context) []func() datasource.DataSource {
return []func() datasource.DataSource{
NewThingDataSource,
}
}
Resource Implementation
package provider
import (
"context"
"fmt"
"github.com/hashicorp/terraform-plugin-framework/path"
"github.com/hashicorp/terraform-plugin-framework/resource"
"github.com/hashicorp/terraform-plugin-framework/resource/schema"
"github.com/hashicorp/terraform-plugin-framework/resource/schema/planmodifier"
"github.com/hashicorp/terraform-plugin-framework/resource/schema/stringplanmodifier"
"github.com/hashicorp/terraform-plugin-framework/types"
)
var (
_ resource.Resource = &ThingResource{}
_ resource.ResourceWithImportState = &ThingResource{}
)
type ThingResource struct {
client *APIClient
}
type ThingResourceModel struct {
ID types.String `tfsdk:"id"`
Name types.String `tfsdk:"name"`
Description types.String `tfsdk:"description"`
Status types.String `tfsdk:"status"` // Computed
}
func NewThingResource() resource.Resource {
return &ThingResource{}
}
func (r *ThingResource) Metadata(ctx context.Context, req resource.MetadataRequest, resp *resource.MetadataResponse) {
resp.TypeName = req.ProviderTypeName + "_thing"
}
func (r *ThingResource) Schema(ctx context.Context, req resource.SchemaRequest, resp *resource.SchemaResponse) {
resp.Schema = schema.Schema{
Description: "Manages a Thing resource.",
Attributes: map[string]schema.Attribute{
"id": schema.StringAttribute{
Computed: true,
Description: "Unique identifier for the thing.",
PlanModifiers: []planmodifier.String{
stringplanmodifier.UseStateForUnknown(),
},
},
"name": schema.StringAttribute{
Required: true,
Description: "Name of the thing.",
},
"description": schema.StringAttribute{
Optional: true,
Description: "Description of the thing.",
},
"status": schema.StringAttribute{
Computed: true,
Description: "Current status of the thing.",
},
},
}
}
func (r *ThingResource) Configure(ctx context.Context, req resource.ConfigureRequest, resp *resource.ConfigureResponse) {
if req.ProviderData == nil {
return
}
client, ok := req.ProviderData.(*APIClient)
if !ok {
resp.Diagnostics.AddError(
"Unexpected Resource Configure Type",
fmt.Sprintf("Expected *APIClient, got: %T", req.ProviderData),
)
return
}
r.client = client
}
func (r *ThingResource) Create(ctx context.Context, req resource.CreateRequest, resp *resource.CreateResponse) {
var plan ThingResourceModel
resp.Diagnostics.Append(req.Plan.Get(ctx, &plan)...)
if resp.Diagnostics.HasError() {
return
}
// Create via API
thing, err := r.client.CreateThing(ctx, plan.Name.ValueString(), plan.Description.ValueString())
if err != nil {
resp.Diagnostics.AddError("Error creating thing", err.Error())
return
}
// Map response to state
plan.ID = types.StringValue(thing.ID)
plan.Status = types.StringValue(thing.Status)
resp.Diagnostics.Append(resp.State.Set(ctx, plan)...)
}
func (r *ThingResource) Read(ctx context.Context, req resource.ReadRequest, resp *resource.ReadResponse) {
var state ThingResourceModel
resp.Diagnostics.Append(req.State.Get(ctx, &state)...)
if resp.Diagnostics.HasError() {
return
}
// Read from API
thing, err := r.client.GetThing(ctx, state.ID.ValueString())
if err != nil {
resp.Diagnostics.AddError("Error reading thing", err.Error())
return
}
// Handle resource not found
if thing == nil {
resp.State.RemoveResource(ctx)
return
}
// Map response to state
state.Name = types.StringValue(thing.Name)
state.Description = types.StringValue(thing.Description)
state.Status = types.StringValue(thing.Status)
resp.Diagnostics.Append(resp.State.Set(ctx, state)...)
}
func (r *ThingResource) Update(ctx context.Context, req resource.UpdateRequest, resp *resource.UpdateResponse) {
var plan ThingResourceModel
resp.Diagnostics.Append(req.Plan.Get(ctx, &plan)...)
if resp.Diagnostics.HasError() {
return
}
var state ThingResourceModel
resp.Diagnostics.Append(req.State.Get(ctx, &state)...)
if resp.Diagnostics.HasError() {
return
}
// Update via API
thing, err := r.client.UpdateThing(ctx, state.ID.ValueString(), plan.Name.ValueString(), plan.Description.ValueString())
if err != nil {
resp.Diagnostics.AddError("Error updating thing", err.Error())
return
}
// Map response to state
plan.ID = state.ID
plan.Status = types.StringValue(thing.Status)
resp.Diagnostics.Append(resp.State.Set(ctx, plan)...)
}
func (r *ThingResource) Delete(ctx context.Context, req resource.DeleteRequest, resp *resource.DeleteResponse) {
var state ThingResourceModel
resp.Diagnostics.Append(req.State.Get(ctx, &state)...)
if resp.Diagnostics.HasError() {
return
}
// Delete via API
err := r.client.DeleteThing(ctx, state.ID.ValueString())
if err != nil {
resp.Diagnostics.AddError("Error deleting thing", err.Error())
return
}
}
func (r *ThingResource) ImportState(ctx context.Context, req resource.ImportStateRequest, resp *resource.ImportStateResponse) {
resource.ImportStatePassthroughID(ctx, path.Root("id"), req, resp)
}
Acceptance Testing
Test Setup
package provider
import (
"os"
"testing"
"github.com/hashicorp/terraform-plugin-framework/providerserver"
"github.com/hashicorp/terraform-plugin-go/tfprotov6"
"github.com/hashicorp/terraform-plugin-testing/helper/resource"
)
var testAccProtoV6ProviderFactories = map[string]func() (tfprotov6.ProviderServer, error){
"example": providerserver.NewProtocol6WithError(New("test")()),
}
func testAccPreCheck(t *testing.T) {
if v := os.Getenv("EXAMPLE_API_KEY"); v == "" {
t.Fatal("EXAMPLE_API_KEY must be set for acceptance tests")
}
}
Resource Test with State Checks
func TestAccThingResource_basic(t *testing.T) {
resource.Test(t, resource.TestCase{
PreCheck: func() { testAccPreCheck(t) },
ProtoV6ProviderFactories: testAccProtoV6ProviderFactories,
Steps: []resource.TestStep{
// Create and Read
{
Config: testAccThingResourceConfig("test-thing"),
Check: resource.ComposeAggregateTestCheckFunc(
resource.TestCheckResourceAttr("example_thing.test", "name", "test-thing"),
resource.TestCheckResourceAttrSet("example_thing.test", "id"),
resource.TestCheckResourceAttrSet("example_thing.test", "status"),
),
},
// ImportState
{
ResourceName: "example_thing.test",
ImportState: true,
ImportStateVerify: true,
},
// Update
{
Config: testAccThingResourceConfig("updated-thing"),
Check: resource.ComposeAggregateTestCheckFunc(
resource.TestCheckResourceAttr("example_thing.test", "name", "updated-thing"),
),
},
},
})
}
func testAccThingResourceConfig(name string) string {
return fmt.Sprintf(`
resource "example_thing" "test" {
name = %[1]q
}
`, name)
}
Plan Checks (terraform-plugin-testing v1.13.3+)
import (
"github.com/hashicorp/terraform-plugin-testing/plancheck"
)
func TestAccThingResource_planChecks(t *testing.T) {
resource.Test(t, resource.TestCase{
PreCheck: func() { testAccPreCheck(t) },
ProtoV6ProviderFactories: testAccProtoV6ProviderFactories,
Steps: []resource.TestStep{
{
Config: testAccThingResourceConfig("test"),
ConfigPlanChecks: resource.ConfigPlanChecks{
PreApply: []plancheck.PlanCheck{
plancheck.ExpectResourceAction("example_thing.test", plancheck.ResourceActionCreate),
},
},
},
{
Config: testAccThingResourceConfig("updated"),
ConfigPlanChecks: resource.ConfigPlanChecks{
PreApply: []plancheck.PlanCheck{
plancheck.ExpectResourceAction("example_thing.test", plancheck.ResourceActionUpdate),
},
},
},
},
})
}
State Checks (Modern Assertion Framework)
import (
"github.com/hashicorp/terraform-plugin-testing/statecheck"
"github.com/hashicorp/terraform-plugin-testing/compare"
)
func TestAccThingResource_stateChecks(t *testing.T) {
resource.Test(t, resource.TestCase{
PreCheck: func() { testAccPreCheck(t) },
ProtoV6ProviderFactories: testAccProtoV6ProviderFactories,
Steps: []resource.TestStep{
{
Config: testAccThingResourceConfig("test"),
ConfigStateChecks: []statecheck.StateCheck{
statecheck.ExpectKnownValue(
"example_thing.test",
tfjsonpath.New("name"),
knownvalue.StringExact("test"),
),
statecheck.ExpectKnownValue(
"example_thing.test",
tfjsonpath.New("id"),
knownvalue.NotNull(),
),
},
},
},
})
}
Drift Detection
func TestAccThingResource_drift(t *testing.T) {
var thingID string
resource.Test(t, resource.TestCase{
PreCheck: func() { testAccPreCheck(t) },
ProtoV6ProviderFactories: testAccProtoV6ProviderFactories,
Steps: []resource.TestStep{
{
Config: testAccThingResourceConfig("original"),
Check: resource.ComposeAggregateTestCheckFunc(
resource.TestCheckResourceAttrWith("example_thing.test", "id", func(value string) error {
thingID = value
return nil
}),
),
},
{
PreConfig: func() {
// Simulate drift by modifying resource outside Terraform
client := getTestClient()
client.UpdateThing(context.Background(), thingID, "drifted", "")
},
Config: testAccThingResourceConfig("original"),
Check: resource.ComposeAggregateTestCheckFunc(
// Verify Terraform corrected the drift
resource.TestCheckResourceAttr("example_thing.test", "name", "original"),
),
},
},
})
}
Best Practices
1. Schema Design
// Use appropriate attribute types
schema.StringAttribute{
Required: true, // Must be provided
Optional: true, // Can be provided
Computed: true, // Set by provider
Sensitive: true, // Masked in output
Description: "Clear description", // Always document
}
// Use plan modifiers for computed values
PlanModifiers: []planmodifier.String{
stringplanmodifier.UseStateForUnknown(), // Preserve on update
stringplanmodifier.RequiresReplace(), // Force recreation
}
// Use validators for input validation
Validators: []validator.String{
stringvalidator.LengthBetween(1, 64),
stringvalidator.RegexMatches(regexp.MustCompile(`^[a-z]`), "must start with lowercase"),
}
2. Error Handling
// Always check for errors and add diagnostics
if err != nil {
resp.Diagnostics.AddError(
"Error Creating Resource",
fmt.Sprintf("Could not create thing: %s", err.Error()),
)
return
}
// Add warnings for non-fatal issues
resp.Diagnostics.AddWarning(
"Deprecation Notice",
"This attribute will be removed in the next major version.",
)
3. Null vs Unknown Handling
// Check for null before using value
if !plan.Description.IsNull() {
description = plan.Description.ValueString()
}
// Check for unknown during plan
if plan.Status.IsUnknown() {
// Value will be known after apply
}
4. Import Testing
// Always test import functionality
{
ResourceName: "example_thing.test",
ImportState: true,
ImportStateVerify: true,
ImportStateVerifyIgnore: []string{"password"}, // Skip sensitive fields
}
Running Tests
# Run all acceptance tests
TF_ACC=1 go test -v ./internal/provider/
# Run specific test
TF_ACC=1 go test -v ./internal/provider/ -run TestAccThingResource_basic
# Run with timeout
TF_ACC=1 go test -v -timeout 120m ./internal/provider/
# Run with parallel limit
TF_ACC=1 go test -v -parallel 4 ./internal/provider/
Documentation Generation
Use tfplugindocs to generate documentation:
# Install
go install github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs@latest
# Generate docs
tfplugindocs generate
# Validate docs
tfplugindocs validate
Reference Files
Development Patterns
references/plugin-framework.md- Plugin Framework patterns and migration from SDKv2references/testing-patterns.md- Comprehensive testing strategies and examplesreferences/schema-design.md- Schema design patterns and validators
CI/CD
references/release-workflow.md- GoReleaser and GitHub Actions for provider releases
Related Skills
iac-terraform-modules-eng- For Terraform module developmentiac-terraform-orchestration-ops- For orchestration with Terragrunt, Terramate, Atmos