action

package
v1.16.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 17, 2025 License: MPL-2.0 Imports: 4 Imported by: 0

Documentation

Overview

Package action contains all interfaces, request types, and response types for an action implementation.

In Terraform, an action is a concept which enables provider developers to offer practitioners ad-hoc side-effects to be used in their configuration.

The main starting point for implementations in this package is the Action type which represents an instance of an action that has its own configuration, plan, and invoke logic. The Action implementations are referenced by the [provider.ProviderWithActions] type Actions method, which enables the action practitioner usage.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Action 

type Action interface {
	// Schema should return the schema for this action.
	Schema(context.Context, SchemaRequest, *SchemaResponse)

	// Metadata should return the full name of the action, such as examplecloud_do_thing.
	Metadata(context.Context, MetadataRequest, *MetadataResponse)

	// Invoke is called to run the logic of the action. Config values should be read from the InvokeRequest
	// and potential diagnostics set in InvokeResponse.
	//
	// The [InvokeResponse.SendProgress] function can be called in the Invoke method to immediately
	// report progress events related to the invocation of the action to Terraform.
	Invoke(context.Context, InvokeRequest, *InvokeResponse)
}

type ActionWithConfigValidators 

type ActionWithConfigValidators interface {
	Action

	// ConfigValidators returns a list of functions which will all be performed during validation.
	ConfigValidators(context.Context) []ConfigValidator
}

ActionWithConfigValidators is an interface type that extends Action to include declarative validations.

Declaring validation using this methodology simplifies implementation of reusable functionality. These also include descriptions, which can be used for automating documentation.

Validation will include ConfigValidators and ValidateConfig, if both are implemented, in addition to any Attribute or Type validation.

type ActionWithConfigure 

type ActionWithConfigure interface {
	Action

	// Configure enables provider-level data or clients to be set in the
	// provider-defined Action type.
	Configure(context.Context, ConfigureRequest, *ConfigureResponse)
}

ActionWithConfigure is an interface type that extends Action to include a method which the framework will automatically call so provider developers have the opportunity to setup any necessary provider-level data or clients in the Action type.

type ActionWithModifyPlan 

type ActionWithModifyPlan interface {
	Action

	// ModifyPlan is called when the provider has an opportunity to modify
	// the plan for an action: once during the plan phase, and once
	// during the apply phase with any unknown values from configuration
	// filled in with their final values.
	//
	// All action schema types can use the plan as an opportunity to raise early
	// diagnostics to practitioners, such as validation errors.
	ModifyPlan(context.Context, ModifyPlanRequest, *ModifyPlanResponse)
}

ActionWithModifyPlan represents an action with a ModifyPlan function.

type ActionWithValidateConfig 

type ActionWithValidateConfig interface {
	Action

	// ValidateConfig performs the validation.
	ValidateConfig(context.Context, ValidateConfigRequest, *ValidateConfigResponse)
}

ActionWithValidateConfig is an interface type that extends Action to include imperative validation.

Declaring validation using this methodology simplifies one-off functionality that typically applies to a single action. Any documentation of this functionality must be manually added into schema descriptions.

Validation will include ConfigValidators and ValidateConfig, if both are implemented, in addition to any Attribute or Type validation.

type ConfigValidator 

type ConfigValidator interface {
	// Description describes the validation in plain text formatting.
	//
	// This information may be automatically added to action plain text
	// descriptions by external tooling.
	Description(context.Context) string

	// MarkdownDescription describes the validation in Markdown formatting.
	//
	// This information may be automatically added to action Markdown
	// descriptions by external tooling.
	MarkdownDescription(context.Context) string

	// ValidateAction performs the validation.
	//
	// This method name is separate from ConfigValidators in resource and other packages in
	// order to allow generic validators.
	ValidateAction(context.Context, ValidateConfigRequest, *ValidateConfigResponse)
}

ConfigValidator describes reusable Action configuration validation functionality.

type ConfigureRequest 

type ConfigureRequest struct {
	// ProviderData is the data set in the
	// [provider.ConfigureResponse.ActionData] field. This data is
	// provider-specifc and therefore can contain any necessary remote system
	// clients, custom provider data, or anything else pertinent to the
	// functionality of the Action.
	//
	// This data is only set after the ConfigureProvider RPC has been called
	// by Terraform.
	ProviderData any
}

ConfigureRequest represents a request for the provider to configure an action, i.e., set provider-level data or clients. An instance of this request struct is supplied as an argument to the Action type Configure method.

type ConfigureResponse 

type ConfigureResponse struct {
	// Diagnostics report errors or warnings related to configuring of the
	// Datasource. An empty slice indicates a successful operation with no
	// warnings or errors generated.
	Diagnostics diag.Diagnostics
}

ConfigureResponse represents a response to a ConfigureRequest. An instance of this response struct is supplied as an argument to the Action type Configure method.

type Deferred 

type Deferred struct {
	// Reason is the reason for deferring the change.
	Reason DeferredReason
}

Deferred is used to indicate to Terraform that a change needs to be deferred for a reason.

NOTE: This functionality is related to deferred action support, which is currently experimental and is subject to change or break without warning. It is not protected by version compatibility guarantees.

type DeferredReason 

type DeferredReason int32

DeferredReason represents different reasons for deferring a change.

NOTE: This functionality is related to deferred action support, which is currently experimental and is subject to change or break without warning. It is not protected by version compatibility guarantees. 

const (
	// DeferredReasonUnknown is used to indicate an invalid `DeferredReason`.
	// Provider developers should not use it.
	DeferredReasonUnknown DeferredReason = 0

	// DeferredReasonActionConfigUnknown is used to indicate that the action configuration
	// is partially unknown and the real values need to be known before the change can be planned.
	DeferredReasonActionConfigUnknown DeferredReason = 1

	// DeferredReasonProviderConfigUnknown is used to indicate that the provider configuration
	// is partially unknown and the real values need to be known before the change can be planned.
	DeferredReasonProviderConfigUnknown DeferredReason = 2

	// DeferredReasonAbsentPrereq is used to indicate that a hard dependency has not been satisfied.
	DeferredReasonAbsentPrereq DeferredReason = 3
)

func (DeferredReason) String 

func (d DeferredReason) String() string

type InvokeProgressEvent 

type InvokeProgressEvent struct {
	// Message is the string that will be presented to the practitioner either via the console
	// or an external system like HCP Terraform.
	Message string
}

InvokeProgressEvent is the event returned to Terraform while an action is being invoked.

type InvokeRequest 

type InvokeRequest struct {
	// Config is the configuration the user supplied for the action.
	Config tfsdk.Config
}

InvokeRequest represents a request for the provider to invoke the action.

type InvokeResponse 

type InvokeResponse struct {
	// Diagnostics report errors or warnings related to invoking the action. Returning an empty slice
	// indicates a successful invocation with no warnings or errors
	// generated.
	Diagnostics diag.Diagnostics

	// SendProgress will immediately send a progress update to Terraform core during action invocation.
	// This function is provided by the framework and can be called multiple times while action logic is running.
	SendProgress func(event InvokeProgressEvent)
}

InvokeResponse represents a response to an InvokeRequest. An instance of this response struct is supplied as an argument to the action's Invoke function, in which the provider should set values on the InvokeResponse as appropriate.

type MetadataRequest 

type MetadataRequest struct {
	// ProviderTypeName is the string returned from
	// [provider.MetadataResponse.TypeName], if the Provider type implements
	// the Metadata method. This string should prefix the Action type name
	// with an underscore in the response.
	ProviderTypeName string
}

MetadataRequest represents a request for the Action to return metadata, such as its type name. An instance of this request struct is supplied as an argument to the Action type Metadata method.

type MetadataResponse 

type MetadataResponse struct {
	// TypeName should be the full action type, including the provider
	// type prefix and an underscore. For example, examplecloud_thing.
	TypeName string
}

MetadataResponse represents a response to a MetadataRequest. An instance of this response struct is supplied as an argument to the Action type Metadata method.

type ModifyPlanClientCapabilities 

type ModifyPlanClientCapabilities struct {
	// DeferralAllowed indicates whether the Terraform client initiating
	// the request allows a deferral response.
	//
	// NOTE: This functionality is related to deferred action support, which is currently experimental and is subject
	// to change or break without warning. It is not protected by version compatibility guarantees.
	DeferralAllowed bool
}

ModifyPlanClientCapabilities allows Terraform to publish information regarding optionally supported protocol features for the PlanAction RPC, such as forward-compatible Terraform behavior changes.

type ModifyPlanRequest 

type ModifyPlanRequest struct {
	// Config is the configuration the user supplied for the action.
	//
	// This configuration may contain unknown values if a user uses
	// interpolation or other functionality that would prevent Terraform
	// from knowing the value at request time.
	Config tfsdk.Config

	// ClientCapabilities defines optionally supported protocol features for the
	// PlanAction RPC, such as forward-compatible Terraform behavior changes.
	ClientCapabilities ModifyPlanClientCapabilities
}

ModifyPlanRequest represents a request for the provider during planning. The plan can be used as an opportunity to raise early diagnostics to practitioners, such as validation errors.

type ModifyPlanResponse 

type ModifyPlanResponse struct {
	// Diagnostics report early errors or warnings related action.
	// Returning an empty slice indicates a successful plan modification
	// with no warnings or errors generated.
	Diagnostics diag.Diagnostics

	// Deferred indicates that Terraform should defer planning this
	// action until a follow-up apply operation.
	//
	// This field can only be set if
	// `(action.ModifyPlanRequest).ClientCapabilities.DeferralAllowed` is true.
	//
	// NOTE: This functionality is related to deferred action support, which is currently experimental and is subject
	// to change or break without warning. It is not protected by version compatibility guarantees.
	Deferred *Deferred
}

ModifyPlanResponse represents a response to a ModifyPlanRequest. An instance of this response struct is supplied as an argument to the action's ModifyPlan function.

type SchemaRequest 

type SchemaRequest struct{}

SchemaRequest represents a request for the Action to return its schema. An instance of this request struct is supplied as an argument to the Action type Schema method.

type SchemaResponse 

type SchemaResponse struct {

	// Schema is the schema of the action.
	Schema schema.Schema

	// Diagnostics report errors or warnings related to retrieving the action schema.
	// An empty slice indicates success, with no warnings or errors generated.
	Diagnostics diag.Diagnostics
}

SchemaResponse represents a response to a SchemaRequest. An instance of this response struct is supplied as an argument to the Action type Schema method.

type ValidateConfigRequest 

type ValidateConfigRequest struct {
	// Config is the configuration the user supplied for the action.
	//
	// This configuration may contain unknown values if a user uses
	// interpolation or other functionality that would prevent Terraform
	// from knowing the value at request time.
	Config tfsdk.Config
}

ValidateConfigRequest represents a request to validate the configuration of an action. An instance of this request struct is supplied as an argument to the Action ValidateConfig receiver method or automatically passed through to each ConfigValidator.

type ValidateConfigResponse 

type ValidateConfigResponse struct {
	// Diagnostics report errors or warnings related to validating the action
	// configuration. An empty slice indicates success, with no warnings or
	// errors generated.
	Diagnostics diag.Diagnostics
}

ValidateConfigResponse represents a response to a ValidateConfigRequest. An instance of this response struct is supplied as an argument to the Action ValidateConfig receiver method or automatically passed through to each ConfigValidator.

Source Files

View all Source files

Directories

Path Synopsis
Package schema contains all available schema functionality for actions.
 Package schema contains all available schema functionality for actions.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.