provider-resources

SKILL.md

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 Type
Framework Type
Use Case

string
schema.StringAttribute
Names, identifiers

number
schema.Int64Attribute, schema.Float64Attribute
Counts, sizes

bool
schema.BoolAttribute
Feature flags

list
schema.ListAttribute
Ordered collections

set
schema.SetAttribute
Unordered unique items

map
schema.MapAttribute
Key-value pairs

object
schema.SingleNestedAttribute
Complex 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

Terraform Plugin Framework

Resource Development

Data Source Development

HashiCorp Provider Design Principles