AutoGineer
Generated banner for Provider Resources
Generated logo for Provider Resources

Provider Resources

HashiCorpOfficialPublished by HashiCorp

  • Skill
  • Tool integration
  • Cloud and DevOps
  • MPL-2.0
  • No issues found
Download ZIP

From the author

Implement Terraform Provider resources and data sources using the Plugin Framework: CRUD operations, schema design, plan modifiers and validators, not-found handling, waiters for eventually consistent APIs, import support, resource design principles, and required acceptance test coverage. Use when adding or changing a resource or data source, deciding whether an API concept should be a resource, wiring a resource to the provider's configured client, handling drift or resource-not-found, or reviewing a resource implementation before submission.
— the description by HashiCorp

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a comprehensive guide for developers building Terraform Providers using the HashiCorp Plugin Framework. It covers the end-to-end implementation of resources and data sources, including CRUD operations, schema design, state management, and acceptance testing. The guide emphasizes using the Plugin Framework for all new development, provides patterns for handling eventually consistent APIs through waiters, and outlines best practices for resource design and error handling.

What it does

  • Defines the structure for implementing CRUD operations in Terraform resources.
  • Provides patterns for schema design, including plan modifiers and attribute validators.
  • Details how to implement data sources for read-only infrastructure access.
  • Outlines strategies for handling eventually consistent APIs using status and wait functions.
  • Specifies requirements for acceptance test coverage, including basic, disappearance, and import tests.
  • Offers guidance on resource design principles and file organization for provider projects.

When to use it

  • When developing new Terraform Provider resources or data sources.
  • When migrating or updating existing provider resource implementations.
  • When determining if an API concept should be modeled as a resource or data source.
  • When implementing logic to handle API drift, resource-not-found scenarios, or asynchronous API operations.

Advantages

  • Promotes consistent resource implementation patterns across provider codebases.
  • Provides clear guidance on using the modern Plugin Framework over legacy SDKs.
  • Includes standardized approaches for handling common provider challenges like eventual consistency.
  • Ensures adherence to established resource design principles for better maintainability.

Usage examples

“How do I implement a Create operation for a new Terraform resource?”
The guide provides a code template demonstrating how to retrieve plan data, call the API client, handle errors, and set the resource state.
“What is the best way to handle an eventually consistent API in a resource?”
The guide explains how to use retry.StateChangeConf to poll for resource readiness, providing examples for status and wait functions.
“How should I structure my acceptance tests for a new resource?”
The guide outlines the required test cases, including basic creation, import verification, and out-of-band deletion handling.

Install

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/hashicorp/provider-resources/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip provider-resources.zip -d .agents/skills

Documentation by HashiCorp

Terraform Provider Resources Implementation Guide

Overview

This guide covers developing Terraform Provider resources and data sources. Resources represent infrastructure objects that Terraform manages through Create, Read, Update, and Delete (CRUD) operations.

Use the Plugin Framework for all net-new resources and data sources. Plugin SDKv2 is for maintaining resources that already exist on it; do not write new code against it. A provider can serve both during migration by muxing (terraform-plugin-mux), so adopting the Framework never requires a big-bang rewrite. To tell which mode an existing provider is in, check go.mod: terraform-plugin-mux present means it serves both SDKv2 and Framework code; only terraform-plugin-sdk/v2 means SDKv2-only; only terraform-plugin-framework means Framework-only. Be cautious about migrating existing SDKv2 resources: the Framework distinguishes null from zero values, so naive migrations change behavior for existing users (use the provider-framework-migration skill, if available).

References (load when needed):

  • references/design-principles.md — what should (and should not) become a resource; data source semantics; relationship and async-task modeling

  • references/retries-and-waiters.md — eventual consistency, retry patterns, and status/wait function structure

File Structure

Most providers keep every resource in a single package:

internal/provider/
├── provider.go                  # Provider schema + Configure
├── widget_resource.go           # Resource implementation
├── widget_resource_test.go      # Acceptance tests
├── widget_data_source.go        # Data source (if applicable)
└── widget_data_source_test.go

Large multi-service providers (e.g. terraform-provider-aws) split into internal/service/<service>/ packages instead, with an idiomatic file taxonomy worth adopting once a package grows: consts.go, find.go (finders), status.go (status functions), wait.go (waiters), sweep.go (test sweepers), exports_test.go.

Documentation lives in docs/ and is generated with tfplugindocs:

docs/
├── resources/<name>.md          # generated; optional <name>.md.tmpl template
└── data-sources/<name>.md

(Hand-written website/docs/r/*.html.markdown trees exist in some older, large providers — follow the target repo's convention when editing one.)

Resource Structure

A Framework resource is a struct holding the API client, with interface assertions making the implemented behaviors explicit:

var (
    _ resource.Resource                = &widgetResource{}
    _ resource.ResourceWithConfigure   = &widgetResource{}
    _ resource.ResourceWithImportState = &widgetResource{}
)

func NewWidgetResource() resource.Resource {
    return &widgetResource{}
}

type widgetResource struct {
    client *examplecloud.Client
}

func (r *widgetResource) Metadata(_ context.Context, req resource.MetadataRequest, resp *resource.MetadataResponse) {
    resp.TypeName = req.ProviderTypeName + "_widget"
}

// Configure receives the client the provider built in its own Configure.
func (r *widgetResource) Configure(_ context.Context, req resource.ConfigureRequest, resp *resource.ConfigureResponse) {
    if req.ProviderData == nil {
        return // provider not yet configured (e.g. validation phase)
    }
    client, ok := req.ProviderData.(*examplecloud.Client)
    if !ok {
        resp.Diagnostics.AddError(
            "Unexpected Resource Configure Type",
            fmt.Sprintf("Expected *examplecloud.Client, got: %T.", req.ProviderData),
        )
        return
    }
    r.client = client
}

func (r *widgetResource) Schema(ctx context.Context, req resource.SchemaRequest, resp *resource.SchemaResponse) {
    resp.Schema = schema.Schema{
        Attributes: map[string]schema.Attribute{
            "name": schema.StringAttribute{
                Required: true,
                PlanModifiers: []planmodifier.String{
                    stringplanmodifier.RequiresReplace(),
                },
                Validators: []validator.String{
                    stringvalidator.LengthBetween(1, 255),
                },
            },
            "id": schema.StringAttribute{
                Computed: true,
                PlanModifiers: []planmodifier.String{
                    stringplanmodifier.UseStateForUnknown(),
                },
            },
        },
    }
}

How the provider's Configure produces that client — schema, credential resolution, validation — is covered by the provider-configuration skill (if available).

On id: SDKv2 required a magic id attribute; the Framework does not. If the API has its own identifier, expose it under its real meaning and do not add a second, redundant id. Only keep id when it is the API's identifier (as above).

CRUD Operations

Create
func (r *widgetResource) Create(ctx context.Context, req resource.CreateRequest, resp *resource.CreateResponse) {
    var data widgetResourceModel
    resp.Diagnostics.Append(req.Plan.Get(ctx, &data)...)
    if resp.Diagnostics.HasError() {
        return
    }

    input := &examplecloud.CreateWidgetInput{
        Name: data.Name.ValueStringPointer(),
    }

    output, err := r.client.CreateWidget(ctx, input)
    if err != nil {
        resp.Diagnostics.AddError(
            "Error creating Widget",
            fmt.Sprintf("creating Widget (%s): %s", data.Name.ValueString(), err),
        )
        return
    }

    data.ID = types.StringPointerValue(output.ID)

    // For eventually consistent APIs, wait for the resource to be usable
    // before returning — see references/retries-and-waiters.md.

    resp.Diagnostics.Append(resp.State.Set(ctx, &data)...)
}
Read

Read must handle out-of-band deletion by removing the resource from state so the next plan recreates it, rather than erroring forever:

func (r *widgetResource) Read(ctx context.Context, req resource.ReadRequest, resp *resource.ReadResponse) {
    var data widgetResourceModel
    resp.Diagnostics.Append(req.State.Get(ctx, &data)...)
    if resp.Diagnostics.HasError() {
        return
    }

    output, err := findWidgetByID(ctx, r.client, data.ID.ValueString())
    if isNotFound(err) {
        tflog.Warn(ctx, "Widget not found, removing from state", map[string]any{"id": data.ID.ValueString()})
        resp.State.RemoveResource(ctx)
        return
    }
    if err != nil {
        resp.Diagnostics.AddError(
            "Error reading Widget",
            fmt.Sprintf("reading Widget (%s): %s", data.ID.ValueString(), err),
        )
        return
    }

    data.Name = types.StringPointerValue(output.Name)

    resp.Diagnostics.Append(resp.State.Set(ctx, &data)...)
}
Update

Only call the API for attributes that actually changed; compare plan against state:

func (r *widgetResource) Update(ctx context.Context, req resource.UpdateRequest, resp *resource.UpdateResponse) {
    var plan, state widgetResourceModel
    resp.Diagnostics.Append(req.Plan.Get(ctx, &plan)...)
    resp.Diagnostics.Append(req.State.Get(ctx, &state)...)
    if resp.Diagnostics.HasError() {
        return
    }

    if !plan.Description.Equal(state.Description) {
        input := &examplecloud.UpdateWidgetInput{
            ID:          plan.ID.ValueStringPointer(),
            Description: plan.Description.ValueStringPointer(),
        }
        if _, err := r.client.UpdateWidget(ctx, input); err != nil {
            resp.Diagnostics.AddError(
                "Error updating Widget",
                fmt.Sprintf("updating Widget (%s): %s", plan.ID.ValueString(), err),
            )
            return
        }
    }

    resp.Diagnostics.Append(resp.State.Set(ctx, &plan)...)
}
Delete

Treat "already gone" as success — the desired end state is reached:

func (r *widgetResource) Delete(ctx context.Context, req resource.DeleteRequest, resp *resource.DeleteResponse) {
    var data widgetResourceModel
    resp.Diagnostics.Append(req.State.Get(ctx, &data)...)
    if resp.Diagnostics.HasError() {
        return
    }

    _, err := r.client.DeleteWidget(ctx, &examplecloud.DeleteWidgetInput{
        ID: data.ID.ValueStringPointer(),
    })
    if isNotFound(err) {
        return
    }
    if err != nil {
        resp.Diagnostics.AddError(
            "Error deleting Widget",
            fmt.Sprintf("deleting Widget (%s): %s", data.ID.ValueString(), err),
        )
        return
    }
}
Import

With ResourceWithImportState asserted, passthrough of the identifier is one line:

func (r *widgetResource) ImportState(ctx context.Context, req resource.ImportStateRequest, resp *resource.ImportStateResponse) {
    resource.ImportStatePassthroughID(ctx, path.Root("id"), req, resp)
}

For multi-part identifiers, parse a delimited import ID (commonly comma-separated) and set each attribute explicitly.

Resource Design Principles

Before implementing, check the shape of the thing being modeled (full treatment in references/design-principles.md):

  • A resource is the smallest useful building block; if the API offers CRUD for it, it likely deserves its own resource.

  • A resource should talk to one API/service only — cross-service resources break permissions, auditing, and endpoint configuration.

  • Data sources are read-only and side-effect free. A singular data source errors on zero or multiple matches; a plural data source (plural noun name) returns zero-or-more as a collection and errors on neither.

  • Attached policies/rules, long-running task invocations, and versioned artifacts usually deserve their own resources rather than attributes on the parent.

  • Start/stop or enable/disable state belongs as an attribute in the resource, not as a separate resource.

Schema Design

Attribute Types
Terraform TypeFramework TypeUse Case
stringschema.StringAttributeNames, identifiers
numberschema.Int64Attribute, schema.Float64AttributeCounts, sizes
boolschema.BoolAttributeFeature flags
listschema.ListAttributeOrdered collections
setschema.SetAttributeUnordered unique items
mapschema.MapAttributeKey-value pairs
objectschema.SingleNestedAttributeComplex nested config

Give every attribute a MarkdownDescription — tfplugindocs publishes it, and it is the primary user-facing documentation.

Plan Modifiers
// Force replacement when value changes
stringplanmodifier.RequiresReplace()

// Keep a known value during plan instead of (known after apply)
stringplanmodifier.UseStateForUnknown()
Validators
stringvalidator.LengthBetween(1, 255)
stringvalidator.RegexMatches(regexp.MustCompile(`^[a-z0-9-]+$`), "must be lowercase alphanumeric with hyphens")
stringvalidator.OneOf("small", "medium", "large")
int64validator.Between(1, 100)
listvalidator.SizeAtLeast(1)
Sensitive Attributes
"password": schema.StringAttribute{
    Required:  true,
    Sensitive: true,
},

State Management

Finders

Centralize "get one thing or a typed not-found" in a finder so Read, Delete, waiters, and tests all share identical not-found semantics:

func findWidgetByID(ctx context.Context, client *examplecloud.Client, id string) (*examplecloud.Widget, error) {
    output, err := client.GetWidget(ctx, &examplecloud.GetWidgetInput{ID: &id})
    if err != nil {
        var apiErr *examplecloud.NotFoundError
        if errors.As(err, &apiErr) {
            return nil, &retry.NotFoundError{LastError: err}
        }
        return nil, fmt.Errorf("getting Widget (%s): %w", id, err)
    }
    if output == nil || output.Widget == nil {
        return nil, &retry.NotFoundError{Message: "empty result"}
    }
    return output.Widget, nil
}

func isNotFound(err error) bool {
    var nfe *retry.NotFoundError
    return errors.As(err, &nfe)
}
Waiting for Resource States

Many APIs return from Create/Delete before the resource is usable/gone. Use retry.StateChangeConf (from github.com/hashicorp/terraform-plugin-sdk/v2/helper/retry — usable from Framework providers), with a status function built on the finder and timeouts in named constants:

stateConf := &retry.StateChangeConf{
    Pending: []string{"CREATING", "PENDING"},
    Target:  []string{"ACTIVE"},
    Refresh: statusWidget(ctx, r.client, id), // one poll of the finder: (obj, status, err)
    Timeout: widgetCreatedTimeout,
}
outputRaw, err := stateConf.WaitForStateContext(ctx)

The full status/wait function pairs (create and delete waiters, failure-state handling, post-create not-found retries, eventual-consistency patterns) are in references/retries-and-waiters.md — read it whenever the API is asynchronous or eventually consistent.

Testing

Every resource ships with, at minimum:

  • _basic — create with minimal config, assert attributes, then an import step (ImportState: true, ImportStateVerify: true)

  • _disappears — delete the object out-of-band mid-test; the next plan must propose recreation, not error

  • Per-attribute tests — exercise updates for each non-trivial argument

Naming grammar: tests TestAcc{Resource}_{group?}_{description}, helpers testAccCheck{Resource}Exists / testAccCheck{Resource}Destroy, config functions testAcc{Resource}Config_{description}. Keep configs self-contained, randomize real resource names, and never hardcode environment-specific values (account IDs, zones, versions).

func TestAccWidget_basic(t *testing.T) {
    rName := acctest.RandStringFromCharSet(10, acctest.CharSetAlphaNum)
    resourceName := "examplecloud_widget.test"

    resource.ParallelTest(t, resource.TestCase{
        PreCheck:                 func() { testAccPreCheck(t) },
        ProtoV6ProviderFactories: testAccProtoV6ProviderFactories,
        CheckDestroy:             testAccCheckWidgetDestroy,
        Steps: []resource.TestStep{
            {
                Config: testAccWidgetConfig_basic(rName),
                ConfigStateChecks: []statecheck.StateCheck{
                    statecheck.ExpectKnownValue(resourceName, tfjsonpath.New("name"), knownvalue.StringExact(rName)),
                    statecheck.ExpectKnownValue(resourceName, tfjsonpath.New("id"), knownvalue.NotNull()),
                },
            },
            {
                ResourceName:      resourceName,
                ImportState:       true,
                ImportStateVerify: true,
            },
        },
    })
}

func testAccWidgetConfig_basic(rName string) string {
    return fmt.Sprintf(`
resource "examplecloud_widget" "test" {
  name = %[1]q
}
`, rName)
}

Use the provider-test-patterns skill (if available) for the full testing treatment: config helper style (%[1]q indexed verbs), statecheck/plancheck, CompareValue, custom StateCheck implementations for exists/disappears helpers, sweepers, and ephemeral resource testing. Use the run-acceptance-tests skill for executing and debugging test runs.

Error Handling

Match API errors by type, not message text, and wrap with context:

var notFound *examplecloud.NotFoundError
if errors.As(err, &notFound) {
    // resource doesn't exist
}

// Wrapping inside helpers: preserve the cause with %w
return fmt.Errorf("creating Widget (%s): %w", name, err)

Diagnostics follow a consistent grammar — summary names the operation and type, detail carries identifier and cause:

resp.Diagnostics.AddError(
    "Error creating Widget",
    fmt.Sprintf("creating Widget (%s): %s", name, err),
)

resp.Diagnostics.AddAttributeError(
    path.Root("name"),
    "Invalid name",
    "Name must be lowercase alphanumeric",
)

Documentation

Write attribute MarkdownDescriptions first — they are the source of truth. Then generate Registry documentation with tfplugindocs (go generate ./... where wired up), adding docs/**/*.md.tmpl templates only for prose and examples the generator cannot derive. Use the provider-docs skill (if available) for the full documentation workflow and Registry publication rules.

Pre-Submission Checklist

  • [ ] Plugin Framework used (no new SDKv2 code)

  • [ ] Resource has all CRUD operations implemented

  • [ ] Read removes missing resources from state; Delete tolerates already-deleted

  • [ ] No redundant id attribute (real API identifier exposed instead)

  • [ ] Import implemented and covered by an ImportStateVerify step

  • [ ] _basic, _disappears, and per-attribute tests present

  • [ ] Waiters used where the API is eventually consistent

  • [ ] Error messages name the operation, type, and identifier

  • [ ] Sensitive attributes marked; every attribute has a description

  • [ ] Docs generated with tfplugindocs

  • [ ] Changelog entry added, if the repo tracks release notes (check CONTRIBUTING)

References

Files

references/design-principles.md

Resource and Data Source Design Principles

Distilled from HashiCorp's Provider Design Principles and the conventions of large production providers (notably terraform-provider-aws). Apply these before writing code — most painful provider mistakes are modeling mistakes.

Providers wrap a single API surface

A provider abstracts one platform's API/SDK into Terraform's lifecycle. Keep out of a provider:

  • Raw HTTP/protocol clients bolted onto an SDK-based provider

  • Functionality that requires extra binaries or agents on the host running Terraform

  • Data sources whose only purpose is exporting the provider's own credentials to other configuration (a credential-exfiltration hazard)

Resources: the smallest useful building block

Heuristic: if the API offers create/read/(update)/delete for a thing, that thing is a resource. Prefer many small resources over one large one — practitioners compose small blocks far more easily than they fight a mega-resource with intertwined attribute behaviors.

One resource, one API. A resource should call a single service's API. Cross-service resources look convenient but:

  • force users to grant permissions for services they may not know are involved,

  • scatter audit trails across services,

  • break per-service endpoint/partition configuration, and

  • silently break one service's users when the other service changes.

If two services must cooperate, model each side as its own resource and let configuration connect them.

Relationship and lifecycle modeling

API conceptModel as
Attached policy / rule documentSeparate resource referencing the parent, not a blob attribute on the parent
One-to-many attachment (e.g. member of group)Separate "attachment/membership" resource
Start/stop/enable/disable running stateAn attribute in the resource — a separate "power state" resource fights the parent's lifecycle
Long-running task / job / operation the API exposesSeparate resource representing the task; Create starts it, Read polls it
Invitation / handshake / approval flowsResource on the accepting side: Create = accept, Read = status, Delete = reject/leave
Versioned artifact (function version, template version)Usually a separate <thing>_version resource so versions can pin and iterate independently

When a single API object has two defensible modelings (one resource with nested attributes vs. parent + child resources), prefer the one whose update semantics match the API: if children can be added/removed independently server-side, separate resources avoid the classic "whole-list replacement" diff problem — but never ship both patterns for the same underlying collection without conflict warnings in both.

Data sources

Data sources are read-only views. They must not create, modify, or delete anything, ever — a data source with side effects breaks terraform plan's promise of being safe to run.

Singular data sources (examplecloud_widget) fetch exactly one object:

  • zero matches → error ("no Widget matched; adjust the filters")

  • more than one match → error ("multiple Widgets matched; add filters until exactly one matches")

Returning an arbitrary element instead of erroring hides real environmental problems and produces non-deterministic plans.

Plural data sources (examplecloud_widgets) fetch a collection:

  • return zero-or-more as a list/set attribute

  • zero matches is a valid, empty result, not an error

  • name them with the plural noun; keep filters consistent with the singular form

Ship both for most resources. Users need the singular form for point lookups ("give me this widget by name") and the plural form for enumeration ("give me every widget matching these filters") — different configurations need different shapes of the same data, and adding the missing one later is a common feature request. Skip one only when the API genuinely cannot support it.

Naming

  • Resource type: <provider>_<service?>_<noun>, all lowercase snake_case, noun derived from the API's own CRUD operation names (CreateWidget → _widget) so users can map docs ↔ API.

  • Go: factory functions NewWidgetResource, correct initialisms in MixedCaps (VPCEndpoint, not VpcEndpoint).

  • Attribute names: snake_case translations of the API's field names; do not invent new vocabulary the API's docs won't explain.

When not to add a resource

  • The "resource" is really an RPC with no persistent object behind it — a provider action may fit better (see the provider-actions skill, if available).

  • The object is read-only in the API → data source.

  • The object is a singleton account-level setting that cannot be created or destroyed → resource with Create = adopt/configure and Delete = reset to defaults, documented as such; or omit it.

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by
HashiCorp
Publisher
HashiCorp (Official)
Source
hashicorp/agent-skills · plugins/terraform/skills/provider-resources · commit 5e30fa5
Licence
Mozilla Public License 2.0 (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by HashiCorp or HashiCorp.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download provider-resources.zip