跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
部署与云服务

provider-actions

Implement Terraform Provider actions using the Plugin Framework. Use when developing imperative operations that execute at lifecycle events (before/after create, update, destroy).

hashicorp · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add hashicorp/agent-skills --skill 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:

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
阅读完整来源 ↗