provider-actions

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 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.)