Imported from hashi-demo-lab/terraform-provider-aap (.claude/skills/provider-resources/SKILL.md). Install upstream with npx skills add hashi-demo-lab/terraform-provider-aap --skill provider-resources. Copyright stays with the author.

Terraform Provider Resources Implementation Guide

Overview

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

References:

• Terraform Plugin Framework
• Resource Development
• Data Source Development

File Structure

Resources follow the standard service package structure:

internal/service/<service>/
├── <resource_name>.go           # Resource implementation
├── <resource_name>_test.go      # Acceptance tests
├── <resource_name>_data_source.go    # Data source (if applicable)
├── find.go                      # Finder functions
├── exports_test.go              # Test exports
└── service_package_gen.go       # Auto-generated registration

Documentation structure:

website/docs/r/
└── <service>_<resource_name>.html.markdown  # Resource documentation

website/docs/d/
└── <service>_<resource_name>.html.markdown  # Data source documentation

Resource Structure

Plugin Framework Resource Pattern

type resourceExample struct {
    framework.ResourceWithConfigure
}

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

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

Constructor & Service Registration

Every resource requires an exported constructor and service registration wiring:

// In <resource_name>.go — exported constructor per constitution §2.2
func NewResourceExample() resource.Resource {
    return &resourceExample{}
}

// In exports_test.go — re-exports the constructor for use in acceptance tests
// (e.g., CheckResourceDisappears needs the resource constructor)
package <service>_test

import <service> "github.com/<org>/<provider>/internal/service/<service>"

var (
    ResourceExample = <service>.NewResourceExample
)

// In service_package_gen.go — registers the resource with the provider.
// This file is typically auto-generated. Each resource gets one entry.
func (p *servicePackage) FrameworkResources(ctx context.Context) []*types.ServicePackageFrameworkResource {
    return []*types.ServicePackageFrameworkResource{
        {
            Factory: NewResourceExample,
        },
    }
}

CRUD Operations

Create Operation

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

    conn := r.Meta().ExampleClient(ctx)

    input := &example.CreateExampleInput{
        Name: data.Name.ValueStringPointer(),
    }

    output, err := conn.CreateExample(ctx, input)
    if err != nil {
        resp.Diagnostics.AddError(
            "Error creating Example",
            fmt.Sprintf("Could not create example %s: %s", data.Name.ValueString(), err),
        )
        return
    }

    data.ID = types.StringPointerValue(output.Id)
    data.ARN = types.StringPointerValue(output.Arn)

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

Read Operation

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

    conn := r.Meta().ExampleClient(ctx)

    output, err := findExampleByID(ctx, conn, data.ID.ValueString())
    if tfresource.NotFound(err) {
        resp.State.RemoveResource(ctx)
        return
    }
    if err != nil {
        resp.Diagnostics.AddError(
            "Error reading Example",
            fmt.Sprintf("Could not read example %s: %s", data.ID.ValueString(), err),
        )
        return
    }

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

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

Update Operation

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

    conn := r.Meta().ExampleClient(ctx)

    if !plan.Description.Equal(state.Description) {
        input := &example.UpdateExampleInput{
            Id:          plan.ID.ValueStringPointer(),
            Description: plan.Description.ValueStringPointer(),
        }

        _, err := conn.UpdateExample(ctx, input)
        if err != nil {
            resp.Diagnostics.AddError(
                "Error updating Example",
                fmt.Sprintf("Could not update example %s: %s", plan.ID.ValueString(), err),
            )
            return
        }
    }

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

Delete Operation

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

    conn := r.Meta().ExampleClient(ctx)

    _, err := conn.DeleteExample(ctx, &example.DeleteExampleInput{
        Id: data.ID.ValueStringPointer(),
    })

    if tfresource.NotFound(err) {
        return
    }

    if err != nil {
        resp.Diagnostics.AddError(
            "Error deleting Example",
            fmt.Sprintf("Could not delete example %s: %s", data.ID.ValueString(), err),
        )
        return
    }
}

Schema Design

Attribute Types

Plan Modifiers

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

// Preserve unknown value during plan
stringplanmodifier.UseStateForUnknown()

// Custom plan modifier
stringplanmodifier.RequiresReplaceIf(
    func(ctx context.Context, req planmodifier.StringRequest, resp *stringplanmodifier.RequiresReplaceIfFuncResponse) {
        // Custom logic
    },
    "description",
    "markdown description",
)

Validators

// String validators
stringvalidator.LengthBetween(1, 255)
stringvalidator.RegexMatches(regexp.MustCompile(`^[a-z0-9-]+$`), "must be lowercase alphanumeric with hyphens")
stringvalidator.OneOf("option1", "option2", "option3")

// Int64 validators
int64validator.Between(1, 100)
int64validator.AtLeast(1)
int64validator.AtMost(1000)

// List validators
listvalidator.SizeAtLeast(1)
listvalidator.SizeAtMost(10)

Sensitive Attributes

"password": schema.StringAttribute{
    Required:  true,
    Sensitive: true,
    Validators: []validator.String{
        stringvalidator.LengthAtLeast(8),
    },
}

State Management

Handling Resource Not Found

func findExampleByID(ctx context.Context, conn *example.Client, id string) (*example.Example, error) {
    input := &example.GetExampleInput{
        Id: &id,
    }

    output, err := conn.GetExample(ctx, input)
    if err != nil {
        var notFound *types.ResourceNotFoundException
        if errors.As(err, &notFound) {
            return nil, &retry.NotFoundError{
                LastError:   err,
                LastRequest: input,
            }
        }
        return nil, err
    }

    // Guard against nil output — the API may return success with an empty body.
    // NewEmptyResultError returns a retry.NotFoundError variant, consistent
    // with the constitution §2.5 requirement that finders wrap NotFound using
    // retry.NotFoundError.
    if output == nil || output.Example == nil {
        return nil, tfresource.NewEmptyResultError(input)
    }

    return output.Example, nil
}

Waiting for Resource States

func waitExampleCreated(ctx context.Context, conn *example.Client, id string, timeout time.Duration) (*example.Example, error) {
    stateConf := &retry.StateChangeConf{
        Pending: []string{"CREATING", "PENDING"},
        Target:  []string{"ACTIVE", "AVAILABLE"},
        Refresh: statusExample(ctx, conn, id),
        Timeout: timeout,
    }

    outputRaw, err := stateConf.WaitForStateContext(ctx)
    if output, ok := outputRaw.(*example.Example); ok {
        return output, err
    }

    return nil, err
}

func statusExample(ctx context.Context, conn *example.Client, id string) retry.StateRefreshFunc {
    return func() (interface{}, string, error) {
        output, err := findExampleByID(ctx, conn, id)
        if tfresource.NotFound(err) {
            return nil, "", nil
        }
        if err != nil {
            return nil, "", err
        }
        return output, string(output.Status), nil
    }
}

Testing

Basic Acceptance Test

func TestAccExample_basic(t *testing.T) {
    ctx := acctest.Context(t)
    rName := sdkacctest.RandomWithPrefix(acctest.ResourcePrefix)
    resourceName := "provider_example.test"

    resource.ParallelTest(t, resource.TestCase{
        PreCheck:                 func() { acctest.PreCheck(ctx, t) },
        ProtoV5ProviderFactories: acctest.ProtoV5ProviderFactories,
        CheckDestroy:             testAccCheckExampleDestroy(ctx),
        Steps: []resource.TestStep{
            {
                Config: testAccExampleConfig_basic(rName),
                Check: resource.ComposeTestCheckFunc(
                    testAccCheckExampleExists(ctx, resourceName),
                    resource.TestCheckResourceAttr(resourceName, "name", rName),
                    resource.TestCheckResourceAttrSet(resourceName, "arn"),
                ),
            },
            {
                ResourceName:      resourceName,
                ImportState:       true,
                ImportStateVerify: true,
            },
        },
    })
}

Disappears Test

func TestAccExample_disappears(t *testing.T) {
    ctx := acctest.Context(t)
    rName := sdkacctest.RandomWithPrefix(acctest.ResourcePrefix)
    resourceName := "provider_example.test"

    resource.ParallelTest(t, resource.TestCase{
        PreCheck:                 func() { acctest.PreCheck(ctx, t) },
        ProtoV5ProviderFactories: acctest.ProtoV5ProviderFactories,
        CheckDestroy:             testAccCheckExampleDestroy(ctx),
        Steps: []resource.TestStep{
            {
                Config: testAccExampleConfig_basic(rName),
                Check: resource.ComposeTestCheckFunc(
                    testAccCheckExampleExists(ctx, resourceName),
                    acctest.CheckResourceDisappears(ctx, acctest.Provider, ResourceExample(), resourceName),
                ),
                ExpectNonEmptyPlan: true,
            },
        },
    })
}

Test Helper Functions

func testAccCheckExampleExists(ctx context.Context, name string) resource.TestCheckFunc {
    return func(s *terraform.State) error {
        rs, ok := s.RootModule().Resources[name]
        if !ok {
            return fmt.Errorf("Not found: %s", name)
        }

        conn := acctest.Provider.Meta().(*conns.Client).ExampleClient(ctx)
        _, err := findExampleByID(ctx, conn, rs.Primary.ID)

        return err
    }
}

func testAccCheckExampleDestroy(ctx context.Context) resource.TestCheckFunc {
    return func(s *terraform.State) error {
        conn := acctest.Provider.Meta().(*conns.Client).ExampleClient(ctx)

        for _, rs := range s.RootModule().Resources {
            if rs.Type != "provider_example" {
                continue
            }

            _, err := findExampleByID(ctx, conn, rs.Primary.ID)
            if tfresource.NotFound(err) {
                continue
            }
            if err != nil {
                return err
            }

            return fmt.Errorf("Example %s still exists", rs.Primary.ID)
        }

        return nil
    }
}

Running Tests

# Compile tests
go test -c -o /dev/null ./internal/service/<service>

# Run acceptance tests
TF_ACC=1 go test ./internal/service/<service> -run TestAccExample -v -timeout 60m

# Run with specific provider version
TF_ACC=1 go test ./internal/service/<service> -run TestAccExample -v

# Run sweeper to clean up
TF_ACC=1 go test ./internal/service/<service> -sweep=<region> -v

Error Handling

Common Error Patterns

// Handle specific API errors
var notFound *types.ResourceNotFoundException
if errors.As(err, &notFound) {
    // Resource doesn't exist
}

var conflict *types.ConflictException
if errors.As(err, &conflict) {
    // Resource state conflict
}

var throttle *types.ThrottlingException
if errors.As(err, &throttle) {
    // Rate limited - SDK handles retry
}

Diagnostics

// Add error
resp.Diagnostics.AddError(
    "Error creating resource",
    fmt.Sprintf("Could not create resource: %s", err),
)

// Add warning
resp.Diagnostics.AddWarning(
    "Resource modified outside Terraform",
    "Resource was modified outside of Terraform, state may be inconsistent",
)

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

Documentation Standards

Resource Documentation

---
subcategory: "Service Name"
layout: "provider"
page_title: "Provider: provider_example"
description: |-
  Manages an Example resource.
---

# Resource: provider_example

Manages an Example resource.

## Example Usage

### Basic Usage

\```hcl
resource "provider_example" "example" {
  name = "my-example"
}
\```

## Argument Reference

* `name` - (Required) Name of the example.
* `description` - (Optional) Description of the example.

## Attribute Reference

* `id` - ID of the example.
* `arn` - ARN of the example.

## Import

Example can be imported using the ID:

\```
$ terraform import provider_example.example example-id-12345
\```

Pre-Submission Checklist

• Code compiles without errors
• All tests pass locally
• Resource has all CRUD operations implemented
• Import is implemented and tested
• Disappears test is included
• Documentation is complete with examples
• Error messages are clear and actionable
• Sensitive attributes are marked
• Plan modifiers are appropriate
• Validators cover edge cases

References

• Terraform Plugin Framework
• Acceptance Testing
• terraform-plugin-framework GitHub