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:
- Implement
ProviderWithActions— add anActions()method to the provider that returns[]func() action.Action. - Set
ActionDatainConfigure— the provider'sConfiguremethod must setresp.ActionData = valongside the existingResourceData,DataSourceData, andEphemeralResourceDataassignments. - Create
ActionWithConfigurebase type — if the provider uses embedded base types (e.g.ResourceWithConfigure), create an equivalentActionWithConfiguretype implementingaction.ConfigureRequest/action.ConfigureResponse. - Action-schema helper variants — if the provider injects common schema attributes (e.g.
namespace) via helper functions, action-schema variants are needed sinceaction/schematypes differ fromresource/schematypes.
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:
-
Type Mismatches
- Model structs use
types.String/types.Int64and schemas usetypes.StringTypefromgithub.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
- Model structs use
-
List/Map Element Types
// WRONG - missing ElementType "items": schema.ListAttribute{ Optional: true, } // CORRECT "items": schema.ListAttribute{ Optional: true, ElementType: types.StringType, } -
Computed vs Optional
- Attributes with defaults must be both
Optional: trueandComputed: true - Don't mark action inputs as
Computedunless they have defaults
- Attributes with defaults must be both
-
Validator Imports
// Ensure proper imports "github.com/hashicorp/terraform-plugin-framework-validators/int64validator" "github.com/hashicorp/terraform-plugin-framework-validators/stringvalidator" -
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
-
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 buildto 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