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

SDKv2 Resource Pattern

func ResourceExample() *schema.Resource { return &schema.Resource{ CreateWithoutTimeout: resourceExampleCreate, ReadWithoutTimeout: resourceExampleRead, UpdateWithoutTimeout: resourceExampleUpdate, DeleteWithoutTimeout: resourceExampleDelete,

    Importer: &#x26;schema.ResourceImporter{
        StateContext: schema.ImportStatePassthroughContext,
    },

    Schema: map[string]*schema.Schema{
        "name": {
            Type:         schema.TypeString,
            Required:     true,
            ForceNew:     true,
            ValidateFunc: validation.StringLenBetween(1, 255),
        },
        "arn": {
            Type:     schema.TypeString,
            Computed: true,
        },
        "tags":     tftags.TagsSchema(),
        "tags_all": tftags.TagsSchemaComputed(),
    },

    CustomizeDiff: verify.SetTagsDiff,
}

}

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(), }, }, }, } }

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 := &#x26;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, &#x26;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.Diagnostics.AddWarning(
        "Resource not found",
        fmt.Sprintf("Example %s not found, removing from state", data.ID.ValueString()),
    )
    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, &#x26;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 := &#x26;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, &#x26;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, &#x26;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

Terraform Type Framework Type Use Case

string

schema.StringAttribute

Names, ARNs, IDs

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

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, &#x26;notFound) {
        return nil, &#x26;retry.NotFoundError{
            LastError:   err,
            LastRequest: input,
        }
    }
    return nil, err
}

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 TestAccExampleResource_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 TestAccExampleResource_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
Terraform Plugin SDKv2
Acceptance Testing
terraform-plugin-framework GitHub

provider-resources

Safety Notice

Copy this and send it to your AI assistant to learn