/provider-actions

name: provider-actions
description: Implement Terraform Provider actions using the Plugin Framework. Use when developing imperative operations that execute at lifecycle events (before/after create, update, destroy).
metadata:
  lifecycle-status: active
  copyright: Copyright IBM Corp. 2026
  version: "0.0.1"

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](https://developer.hashicorp.com/terraform/plugin/framework)
• [Terraform Plugin Framework Actions](https://developer.hashicorp.com/terraform/plugin/framework/actions)

First Action Setup

When adding the first action to a provider that has never had one, several one-time scaffolding steps are required:

1. **Implement `ProviderWithActions`** — add an `Actions()` method to the provider that returns `[]func() action.Action`. 2. **Set `ActionData` in `Configure`** — the provider's `Configure` method must set `resp.ActionData = v` alongside the existing `ResourceData`, `DataSourceData`, and `EphemeralResourceData` assignments. 3. **Create `ActionWithConfigure` base type** — if the provider uses embedded base types (e.g. `ResourceWithConfigure`), create an equivalent `ActionWithConfigure` type implementing `action.ConfigureRequest` / `action.ConfigureResponse`. 4. **Action-schema helper variants** — if the provider injects common schema attributes (e.g. `namespace`) via helper functions, action-schema variants are needed since `action/schema` types differ from `resource/schema` types.

File Structure

Most providers keep actions alongside resources in the provider package:

internal/provider/
├── <action_name>_action.go       # Action implementation
└── <action_name>_action_test.go  # Action tests

(Large multi-service providers use `internal/service/<service>/` packages instead — follow the target repository's layout.)

Documentation lives with the other generated docs:

docs/actions/
└── <action_name>.md              # User-facing documentation

(Some older, large providers hand-write `website/docs/actions/<name>.html.markdown` instead — match the repo.)

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:

1. **Type Mismatches**

• Model structs use `types.String`/`types.Int64` and schemas use

`types.StringType` from `github.com/hashicorp/terraform-plugin-framework/types` — don't mix in types from other packages

• Some large providers layer their own custom type package on top (e.g.

terraform-provider-aws's internal `fwtypes`); inside such a repo, follow its convention consistently instead of the plain types

2. **List/Map Element Types**

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

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

3. **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

4. **Validator Imports**

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

5. **Region/Provider Attribute** (multi-region providers, e.g. AWS)

• Use the provider's shared region handling when it has one
• Don't manually re-define provider-level configuration in an action schema

6. **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)...)
    if resp.Diagnostics.HasError() {
        return
    }

    // a.client was stored by Configure (from req.ProviderData), the same
    // pattern resources use.
    resp.SendProgress(action.InvokeProgressEvent{Message: "Starting operation..."})

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

    resp.SendProgress(action.InvokeProgressEvent{Message: "Operation completed"})
}

Key Implementation Requirements

1. Progress Reporting

• Use `resp.SendProgress(ac