provider-actions

SKILL.md

Terraform Provider Actions Implementation Guide

Overview

Terraform Actions enable imperative operations during the Terraform lifecycle. Actions are experimental features that allow performing provider operations at specific lifecycle events (before/after create, update, destroy).

References:

Terraform Plugin Framework

Terraform Actions RFC

File Structure

Actions follow the standard service package structure:
internal/service/<service>/
├── <action_name>_action.go       # Action implementation
├── <action_name>_action_test.go  # Action tests
└── service_package_gen.go        # Auto-generated service registration

Documentation structure:

website/docs/actions/
└── <service>_<action_name>.html.markdown  # User-facing documentation

Changelog entry:

.changelog/
└── <pr_number_or_description>.txt  # Release note entry

Action Schema Definition

Actions use the Terraform Plugin Framework with a standard schema pattern:

func (a *actionType) Schema(ctx context.Context, req action.SchemaRequest, resp *action.SchemaResponse) {
    resp.Schema = schema.Schema{
        Attributes: map[string]schema.Attribute{
            // Required configuration parameters
            "resource_id": schema.StringAttribute{
                Required:    true,
                Description: "ID of the resource to operate on",
            },
            // Optional parameters with defaults
            "timeout": schema.Int64Attribute{
                Optional:    true,
                Description: "Operation timeout in seconds",
                Default:     int64default.StaticInt64(1800),
                Computed:    true,
            },
        },
    }
}

Common Schema Issues

Pay special attention to the schema definition - common issues after a first draft:

Type Mismatches

Using types.String instead of fwtypes.String in model structs

Using types.StringType instead of fwtypes.StringType in schema

Mixing framework types with plugin-framework types

List/Map Element Types

// WRONG - missing ElementType
"items": schema.ListAttribute{
    Optional: true,
}

// CORRECT
"items": schema.ListAttribute{
    Optional:    true,
    ElementType: fwtypes.StringType,
}

Computed vs Optional

Attributes with defaults must be both Optional: true and Computed: true

Don't mark action inputs as Computed unless they have defaults

Validator Imports

// Ensure proper imports
"github.com/hashicorp/terraform-plugin-framework-validators/int64validator"
"github.com/hashicorp/terraform-plugin-framework-validators/stringvalidator"

Region/Provider Attribute

Use framework-provided region handling when available

Don't manually define provider-specific config in schema if framework handles it

Nested Attributes

Use appropriate nested object types for complex structures

Ensure nested types are properly defined

Schema Validation Checklist

Before submitting, verify:

 All attributes have descriptions

 List/Map attributes have ElementType defined

 Validators are imported and applied correctly

 Model struct uses correct framework types

 Optional attributes with defaults are marked Computed

 Code compiles without type errors

 Run go build to catch type mismatches

Action Invoke Method

The Invoke method contains the action logic:

func (a *actionType) Invoke(ctx context.Context, req action.InvokeRequest, resp *action.InvokeResponse) {
    var data actionModel
    resp.Diagnostics.Append(req.Config.Get(ctx, &data)...)

    // Create provider client
    conn := a.Meta().Client(ctx)

    // Progress updates for long-running operations
    resp.Progress.Set(ctx, "Starting operation...")

    // Implement action logic with error handling
    // Use context for timeout management
    // Poll for completion if async operation

    resp.Progress.Set(ctx, "Operation completed")
}

Key Implementation Requirements

1. Progress Reporting

Use resp.SendProgress(action.InvokeProgressEvent{...}) for real-time updates

Provide meaningful progress messages during long operations

Update progress at key milestones

Include elapsed time for long operations

2. Timeout Management

Always include configurable timeout parameter (default: 1800s)

Use context.WithTimeout() for API calls

Handle timeout errors gracefully

Validate timeout ranges (typically 60-7200 seconds)

3. Error Handling

Add diagnostics with resp.Diagnostics.AddError()

Provide clear error messages with context

Include API error details when relevant

Map provider error types to user-friendly messages

Document all possible error cases

Example error handling:

// Handle specific errors
var notFound *types.ResourceNotFoundException
if errors.As(err, &notFound) {
    resp.Diagnostics.AddError(
        "Resource Not Found",
        fmt.Sprintf("Resource %s was not found", resourceID),
    )
    return
}

// Generic error handling
resp.Diagnostics.AddError(
    "Operation Failed",
    fmt.Sprintf("Could not complete operation for %s: %s", resourceID, err),
)

4. Provider SDK Integration

Use provider SDK clients from a.Meta().<Service>Client(ctx)

Handle pagination for list operations

Implement retry logic for transient failures

Use appropriate error types

5. Parameter Validation

Use framework validators for input validation

Validate resource existence before operations

Check for conflicting parameters

Validate against provider naming requirements

6. Polling and Waiting

For operations that require waiting for completion:

result, err := wait.WaitForStatus(ctx,
    func(ctx context.Context) (wait.FetchResult[*ResourceType], error) {
        // Fetch current status
        resource, err := findResource(ctx, conn, id)
        if err != nil {
            return wait.FetchResult[*ResourceType]{}, err
        }
        return wait.FetchResult[*ResourceType]{
            Status: wait.Status(resource.Status),
            Value:  resource,
        }, nil
    },
    wait.Options[*ResourceType]{
        Timeout:            timeout,
        Interval:           wait.FixedInterval(5 * time.Second),
        SuccessStates:      []wait.Status{"AVAILABLE", "COMPLETED"},
        TransitionalStates: []wait.Status{"CREATING", "PENDING"},
        ProgressInterval:   30 * time.Second,
        ProgressSink: func(fr wait.FetchResult[any], meta wait.ProgressMeta) {
            resp.SendProgress(action.InvokeProgressEvent{
                Message: fmt.Sprintf("Status: %s, Elapsed: %v", fr.Status, meta.Elapsed.Round(time.Second)),
            })
        },
    },
)

Common Action Patterns

Batch Operations

Process items in configurable batches

Report progress per batch

Handle partial failures gracefully

Support prefix/filter parameters

Command Execution

Submit command and get operation ID

Poll for completion status

Retrieve and report output

Handle timeout during polling

Validate resources exist before execution

Service Invocation

Invoke service with parameters

Wait for completion (if synchronous)

Return output/results

Handle service-specific errors

Resource State Changes

Validate current state

Apply state change

Poll for target state

Handle transitional states

Async Job Submission

Submit job with configuration

Get job ID

Optionally wait for completion

Report job status

Action Triggers

Actions are invoked via action_trigger lifecycle blocks in Terraform configurations:

action "provider_service_action" "name" {
  config {
    parameter = value
  }
}

resource "terraform_data" "trigger" {
  lifecycle {
    action_trigger {
      events  = [after_create]
      actions = [action.provider_service_action.name]
    }
  }
}

Available Trigger Events

Terraform 1.14.0 Supported Events:

before_create - Before resource creation

after_create - After resource creation

before_update - Before resource update

after_update - After resource update

Not Supported in Terraform 1.14.0:

before_destroy - Not available (will cause validation error)

after_destroy - Not available (will cause validation error)

Testing Actions

Acceptance Tests

Test action invocation with valid parameters

Test timeout scenarios

Test error conditions

Verify provider state changes

Test progress reporting

Test with custom parameters

Test trigger-based invocation

Test Pattern

func TestAccServiceAction_basic(t *testing.T) {
    ctx := acctest.Context(t)

    resource.ParallelTest(t, resource.TestCase{
        PreCheck:                 func() { acctest.PreCheck(ctx, t) },
        ProtoV5ProviderFactories: acctest.ProtoV5ProviderFactories,
        TerraformVersionChecks: []tfversion.TerraformVersionCheck{
            tfversion.SkipBelow(tfversion.Version1_14_0),
        },
        Steps: []resource.TestStep{
            {
                Config: testAccActionConfig_basic(),
                Check: resource.ComposeTestCheckFunc(
                    testAccCheckResourceExists(ctx, "provider_resource.test"),
                ),
            },
        },
    })
}

Test Cleanup with Sweep Functions

Add sweep functions to clean up test resources:

func sweepResources(region string) error {
    ctx := context.Background()
    client := /* get client for region */

    input := &service.ListInput{
        // Filter for test resources
    }

    var sweeperErrs *multierror.Error

    pages := service.NewListPaginator(client, input)
    for pages.HasMorePages() {
        page, err := pages.NextPage(ctx)
        if err != nil {
            sweeperErrs = multierror.Append(sweeperErrs, err)
            continue
        }

        for _, item := range page.Items {
            id := item.Id

            // Skip non-test resources
            if !strings.HasPrefix(id, "tf-acc-test") {
                continue
            }

            _, err := client.Delete(ctx, &service.DeleteInput{
                Id: id,
            })
            if err != nil {
                sweeperErrs = multierror.Append(sweeperErrs, err)
            }
        }
    }

    return sweeperErrs.ErrorOrNil()
}

Testing Best Practices

Service-Specific Prerequisites

Always check for service-specific prerequisites that must be met before actions can succeed

Document prerequisites in action documentation and test configurations

Error Pattern Matching

Terraform wraps action errors with additional context

Use flexible regex patterns: regexache.MustCompile(\(?s)Error Title.*key phrase`)`

Test Patterns Not Applicable to Actions

Actions trigger on lifecycle events, not config reapplication

Before/After Destroy Tests: Not supported in Terraform 1.14.0

Running Tests

Compile test to check for errors:

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

Run specific action tests:

TF_ACC=1 go test ./internal/service/<service> -run TestAccServiceAction_ -v

Run sweep to clean up test resources:

TF_ACC=1 go test ./internal/service/<service> -sweep=<region> -v

Documentation Standards

Each action documentation file must include:

Front Matter

---
subcategory: "Service Name"
layout: "provider"
page_title: "Provider: provider_service_action"
description: |-
  Brief description of what the action does.
---

Header with Warnings

Beta/Alpha notice about experimental status

Warning about potential unintended consequences

Link to provider documentation

Example Usage

Basic usage example

Advanced usage with all options

Trigger-based example with terraform_data

Real-world use case examples

Argument Reference

List all required and optional arguments

Include descriptions and defaults

Note any validation rules

Documentation Linting

Run terrafmt fmt before submission

Verify with terrafmt diff

Changelog Entry Format

Create a changelog entry in .changelog/ directory:

.changelog/<pr_number_or_description>.txt

Content format:

action/provider_service_action: Brief description of the action

Pre-Submission Checklist

Before submitting your action implementation:

 Code compiles: go build -o /dev/null .

 Tests compile: go test -c -o /dev/null ./internal/service/<service>

 Code formatted: make fmt

 Documentation formatted: terrafmt fmt website/docs/actions/<action>.html.markdown

 Changelog entry created

 Schema uses correct types

 All List/Map attributes have ElementType

 Progress updates implemented for long operations

 Error messages include context and resource identifiers

 Documentation includes multiple examples

 Documentation includes prerequisites and warnings

References

Terraform Plugin Framework Documentation

Terraform Provider Development

terraform-plugin-framework GitHub

terraform-plugin-testing