resource

Documentation

Overview

Package resource contains all interfaces, request types, and response types for a managed resource implementation.

In Terraform, a managed resource is a concept which enables provider developers to offer practitioners full lifecycle management (create, read, update, and delete) of a infrastructure component. Managed resources can also stand in for one-time infrastructure operations that require tracking, by implementing create logic, while omitting update and delete logic.

Resources are saved into the Terraform state and can be referenced by other parts of a configuration. Resources are defined by a resource type/name, such as "examplecloud_thing", a schema representing the structure and data types of configuration, plan, and state, and lifecycle logic.

The main starting point for implementations in this package is the Resource type which represents an instance of a resource type that has its own configuration, plan, state, and lifecycle logic. The resource.Resource implementations are referenced by the [provider.Provider] type Resources method, which enables the resource practitioner and testing usage.

Index

• func ImportStatePassthroughID(ctx context.Context, attrPath path.Path, req ImportStateRequest, ...)
• type ConfigValidator
• type ConfigureRequest
• type ConfigureResponse
• type CreateRequest
• type CreateResponse
• type Deferred
• type DeferredReason
  • func (d DeferredReason) String() string
• type DeleteRequest
• type DeleteResponse
• type ImportStateClientCapabilities
• type ImportStateRequest
• type ImportStateResponse
• type MetadataRequest
• type MetadataResponse
• type ModifyPlanClientCapabilities
• type ModifyPlanRequest
• type ModifyPlanResponse
• type MoveStateRequest
• type MoveStateResponse
• type ProviderDeferredBehavior
• type ReadClientCapabilities
• type ReadRequest
• type ReadResponse
• type Resource
• type ResourceBehavior
• type ResourceWithConfigValidators
• type ResourceWithConfigure
• type ResourceWithImportState
• type ResourceWithModifyPlan
• type ResourceWithMoveState
• type ResourceWithUpgradeState
• type ResourceWithValidateConfig
• type SchemaRequest
• type SchemaResponse
• type StateMover
• type StateUpgrader
• type UpdateRequest
• type UpdateResponse
• type UpgradeStateRequest
• type UpgradeStateResponse
• type ValidateConfigRequest
• type ValidateConfigResponse

Functions

func ImportStatePassthroughID

func ImportStatePassthroughID(ctx context.Context, attrPath path.Path, req ImportStateRequest, resp *ImportStateResponse)

ImportStatePassthroughID is a helper function to set the import identifier to a given state attribute path. The attribute must accept a string value.

Types

type ConfigValidator

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

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

	// ValidateResource performs the validation.
	//
	// This method name is separate from the datasource.ConfigValidator
	// interface ValidateDataSource method name and provider.ConfigValidator
	// interface ValidateProvider method name to allow generic validators.
	ValidateResource(context.Context, ValidateConfigRequest, *ValidateConfigResponse)
}

ConfigValidator describes reusable Resource configuration validation functionality.

type ConfigureRequest

type ConfigureRequest struct {
	// ProviderData is the data set in the
	// [provider.ConfigureResponse.ResourceData] 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 Resource.
	//
	// 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 a resource, i.e., set provider-level data or clients. An instance of this request struct is supplied as an argument to the Resource 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 Resource type Configure method.

type CreateRequest

type CreateRequest struct {
	// Config is the configuration the user supplied for the resource.
	//
	// 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

	// Plan is the planned state for the resource.
	Plan tfsdk.Plan

	// ProviderMeta is metadata from the provider_meta block of the module.
	ProviderMeta tfsdk.Config
}

CreateRequest represents a request for the provider to create a resource. An instance of this request struct is supplied as an argument to the resource's Create function.

type CreateResponse

type CreateResponse struct {
	// State is the state of the resource following the Create operation.
	// This field is pre-populated from CreateRequest.Plan and
	// should be set during the resource's Create operation.
	State tfsdk.State

	// Private is the private state resource data following the Create operation.
	// This field is not pre-populated as there is no pre-existing private state
	// data during the resource's Create operation.
	Private *privatestate.ProviderData

	// Diagnostics report errors or warnings related to creating the
	// resource. An empty slice indicates a successful operation with no
	// warnings or errors generated.
	Diagnostics diag.Diagnostics
}

CreateResponse represents a response to a CreateRequest. An instance of this response struct is supplied as an argument to the resource's Create function, in which the provider should set values on the CreateResponse as appropriate.

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

	// DeferredReasonResourceConfigUnknown is used to indicate that the resource configuration
	// is partially unknown and the real values need to be known before the change can be planned.
	DeferredReasonResourceConfigUnknown 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 DeleteRequest

type DeleteRequest struct {
	// State is the current state of the resource prior to the Delete
	// operation.
	State tfsdk.State

	// ProviderMeta is metadata from the provider_meta block of the module.
	ProviderMeta tfsdk.Config

	// Private is provider-defined resource private state data which was previously
	// stored with the resource state.
	//
	// Use the GetKey method to read data.
	Private *privatestate.ProviderData
}

DeleteRequest represents a request for the provider to delete a resource. An instance of this request struct is supplied as an argument to the resource's Delete function.

type DeleteResponse

type DeleteResponse struct {
	// State is the state of the resource following the Delete operation.
	// This field is pre-populated from UpdateResourceRequest.Plan and
	// should be set during the resource's Update operation.
	State tfsdk.State

	// Private is the private state resource data following the Delete
	// operation. This field is pre-populated from DeleteRequest.Private and
	// can be modified during the resource's Delete operation in cases where
	// an error diagnostic is being returned. Otherwise if no error diagnostic
	// is being returned, indicating that the resource was successfully deleted,
	// this data will be automatically cleared to prevent Terraform errors.
	Private *privatestate.ProviderData

	// Diagnostics report errors or warnings related to deleting the
	// resource. An empty slice indicates a successful operation with no
	// warnings or errors generated.
	Diagnostics diag.Diagnostics
}

DeleteResponse represents a response to a DeleteRequest. An instance of this response struct is supplied as an argument to the resource's Delete function, in which the provider should set values on the DeleteResponse as appropriate.

type ImportStateClientCapabilities

type ImportStateClientCapabilities 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
}

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

type ImportStateRequest

type ImportStateRequest struct {
	// ID represents the import identifier supplied by the practitioner when
	// calling the import command. In many cases, this may align with the
	// unique identifier for the resource, which can optionally be stored
	// as an Attribute. However, this identifier can also be treated as
	// its own type of value and parsed during import. This value
	// is not stored in the state unless the provider explicitly stores it.
	ID string

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

ImportStateRequest represents a request for the provider to import a resource. An instance of this request struct is supplied as an argument to the Resource's ImportState method.

type ImportStateResponse

type ImportStateResponse struct {
	// Diagnostics report errors or warnings related to importing the
	// resource. An empty slice indicates a successful operation with no
	// warnings or errors generated.
	Diagnostics diag.Diagnostics

	// State is the state of the resource following the import operation.
	// It must contain enough information so Terraform can successfully
	// refresh the resource, e.g. call the Resource Read method.
	State tfsdk.State

	// Private is the private state resource data following the Import operation.
	// This field is not pre-populated as there is no pre-existing private state
	// data during the resource's Import operation.
	Private *privatestate.ProviderData

	// Deferred indicates that Terraform should defer
	// importing this resource.
	//
	// This field can only be set if
	// `(resource.ImportStateRequest).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
}

ImportStateResponse represents a response to a ImportStateRequest. An instance of this response struct is supplied as an argument to the Resource's ImportState method, in which the provider should set values on the ImportStateResponse 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 Resource type name
	// with an underscore in the response.
	ProviderTypeName string
}

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

type MetadataResponse

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

	// ResourceBehavior is used to control framework-specific logic when
	// interacting with this resource.
	ResourceBehavior ResourceBehavior
}

MetadataResponse represents a response to a MetadataRequest. An instance of this response struct is supplied as an argument to the Resource 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 PlanResourceChange RPC, such as forward-compatible Terraform behavior changes.

type ModifyPlanRequest

type ModifyPlanRequest struct {
	// Config is the configuration the user supplied for the resource.
	//
	// 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

	// State is the current state of the resource.
	State tfsdk.State

	// Plan is the planned new state for the resource. Terraform 1.3 and later
	// supports resource destroy planning, in which this will contain a null
	// value.
	Plan tfsdk.Plan

	// ProviderMeta is metadata from the provider_meta block of the module.
	ProviderMeta tfsdk.Config

	// Private is provider-defined resource private state data which was previously
	// stored with the resource state. This data is opaque to Terraform and does
	// not affect plan output. Any existing data is copied to
	// ModifyPlanResponse.Private to prevent accidental private state data loss.
	//
	// Use the GetKey method to read data. Use the SetKey method on
	// ModifyPlanResponse.Private to update or remove a value.
	Private *privatestate.ProviderData

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

ModifyPlanRequest represents a request for the provider to modify the planned new state that Terraform has generated for the resource.

type ModifyPlanResponse

type ModifyPlanResponse struct {
	// Plan is the planned new state for the resource.
	Plan tfsdk.Plan

	// RequiresReplace is a list of attribute paths that require the
	// resource to be replaced. They should point to the specific field
	// that changed that requires the resource to be destroyed and
	// recreated.
	RequiresReplace path.Paths

	// Private is the private state resource data following the ModifyPlan operation.
	// This field is pre-populated from ModifyPlanRequest.Private and
	// can be modified during the resource's ModifyPlan operation.
	Private *privatestate.ProviderData

	// Diagnostics report errors or warnings related to determining the
	// planned state of the requested resource. Returning an empty slice
	// indicates a successful plan modification with no warnings or errors
	// generated.
	Diagnostics diag.Diagnostics

	// Deferred indicates that Terraform should defer importing this
	// resource until a followup apply operation.
	//
	// This field can only be set if
	// `(resource.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 resource's ModifyPlan function, in which the provider should modify the Plan and populate the RequiresReplace field as appropriate.

type MoveStateRequest

type MoveStateRequest struct {
	// SourcePrivate is the source resource private state data. If this source
	// data is important for the target resource, the implementation should set
	// the data via [MoveStateResponse.TargetPrivate] as it is intentionally not
	// copied automatically.
	SourcePrivate *privatestate.ProviderData

	// SourceProviderAddress is the address of the provider for the source
	// resource type. It is the full address in HOSTNAME/NAMESPACE/TYPE format.
	// For example, registry.terraform.io/hashicorp/random.
	//
	// Implementations should consider using this value to determine whether the
	// request should be handled by this particular implementation. It is
	// recommended to ignore the hostname unless necessary for disambiguation.
	SourceProviderAddress string

	// SourceRawState is the raw state of the source resource. This data is
	// always available, regardless whether the [StateMover.SourceSchema] field
	// was set. If SourceSchema is present, the [SourceState] field will be
	// populated and it is recommended to use that field instead.
	//
	// If this request matches the intended implementation, the implementation
	// logic must set [MoveStateResponse.State] as it is intentionally not
	// copied automatically.
	//
	// This is advanced functionality for providers wanting to skip the full
	// redeclaration of source schemas and instead use lower level handlers to
	// transform data. A typical implementation for working with this data will
	// call the Unmarshal() method.
	SourceRawState *tfprotov6.RawState

	// SourceSchemaVersion is the schema version of the source resource. It is
	// important for implementations to account for the schema version when
	// handling the source state data, since differing schema versions typically
	// have differing data structures and types.
	SourceSchemaVersion int64

	// SourceState is the source resource state if the [StateMover.SourceSchema]
	// was set. When available, this allows for easier data handling such as
	// calling Get() or GetAttribute().
	//
	// If this request matches the intended implementation, the implementation
	// logic must set [MoveStateResponse.TargetState] as it is intentionally not
	// copied automatically.
	//
	// State conversion errors based on [StateMover.SourceSchema] not matching
	// the source state are only intentionally logged at DEBUG level as there
	// may be multiple [StateMover] implementations on the same target resource
	// for differing source resources. The [StateMover] implementation will
	// still be called even with these errors, so it is important that
	// implementations verify the request via the SourceTypeName and other
	// fields before attempting to use this data.
	SourceState *tfsdk.State

	// SourceTypeName is the type name of the source resource. For example,
	// aws_vpc or random_string.
	//
	// Implementations should always use this value, in addition to potentially
	// other request fields, to determine whether the request should be handled
	// by this particular implementation.
	SourceTypeName string
}

MoveStateRequest represents a request for the provider to move a source resource state into the target resource state with any necessary data transformation logic. An instance of this request struct is supplied as an argument to each [StateMover.StateMover].

type MoveStateResponse

type MoveStateResponse struct {
	// Diagnostics report errors or warnings related to moving the resource.
	// An unset or empty value indicates a successful operation or skipped
	// implementation if [TargetState] is also not set.
	Diagnostics diag.Diagnostics

	// TargetState is the resource state following the move operation. This
	// value is intentionally not pre-populated by the framework. The provider
	// must set state values to indicate a successful move operation.
	//
	// If this value is unset and there are no diagnostics, the framework will
	// consider this implementation to have not matched the request and move on
	// to the next implementation, if any. If no implementation returns a state
	// then the framework will return an implementation not found error.
	TargetState tfsdk.State

	// TargetPrivate is the resource private state data following the move
	// operation. This field is not pre-populated as it is up to implementations
	// whether the source private data is relevant for the target resource.
	TargetPrivate *privatestate.ProviderData
}

MoveStateResponse represents a response to a MoveStateRequest. An instance of this response struct is supplied as an argument to StateMover implementations. The provider should set response values only within the implementation that aligns with a supported request, or put differently, a response that contains no error diagnostics nor state is considered as skipped by the framework. Any fulfilling response, whether via error diagnostics or state data, will cause the framework to not call other implementations and immediately return that response. The framework will return an implementation not found error if all implementations return responses without error diagnostics and state.

type ProviderDeferredBehavior

type ProviderDeferredBehavior struct {
	// When EnablePlanModification is true, framework will still execute
	// provider-defined resource plan modification logic if
	// provider.Configure defers. Framework will then automatically return a
	// deferred response along with the modified plan.
	EnablePlanModification bool
}

ProviderDeferredBehavior enables provider-defined logic to be executed in the case of a deferred response from provider configuration.

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 ReadClientCapabilities

type ReadClientCapabilities 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
}

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

type ReadRequest

type ReadRequest struct {
	// State is the current state of the resource prior to the Read
	// operation.
	State tfsdk.State

	// Private is provider-defined resource private state data which was previously
	// stored with the resource state. This data is opaque to Terraform and does
	// not affect plan output. Any existing data is copied to
	// ReadResourceResponse.Private to prevent accidental private state data loss.
	//
	// Use the GetKey method to read data. Use the SetKey method on
	// ReadResourceResponse.Private to update or remove a value.
	Private *privatestate.ProviderData

	// ProviderMeta is metadata from the provider_meta block of the module.
	ProviderMeta tfsdk.Config

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

ReadRequest represents a request for the provider to read a resource, i.e., update values in state according to the real state of the resource. An instance of this request struct is supplied as an argument to the resource's Read function.

type ReadResponse

type ReadResponse struct {
	// State is the state of the resource following the Read operation.
	// This field is pre-populated from ReadRequest.State and
	// should be set during the resource's Read operation.
	State tfsdk.State

	// Private is the private state resource data following the Read operation.
	// This field is pre-populated from ReadResourceRequest.Private and
	// can be modified during the resource's Read operation.
	Private *privatestate.ProviderData

	// Diagnostics report errors or warnings related to reading the
	// resource. An empty slice indicates a successful operation with no
	// warnings or errors generated.
	Diagnostics diag.Diagnostics

	// Deferred indicates that Terraform should defer refreshing this
	// resource until a followup plan operation.
	//
	// This field can only be set if
	// `(resource.ReadRequest).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
}

ReadResponse represents a response to a ReadRequest. An instance of this response struct is supplied as an argument to the resource's Read function, in which the provider should set values on the ReadResponse as appropriate.

type Resource

type Resource interface {
	// Metadata should return the full name of the resource, such as
	// examplecloud_thing.
	Metadata(context.Context, MetadataRequest, *MetadataResponse)

	// Schema should return the schema for this resource.
	Schema(context.Context, SchemaRequest, *SchemaResponse)

	// Create is called when the provider must create a new resource. Config
	// and planned state values should be read from the
	// CreateRequest and new state values set on the CreateResponse.
	Create(context.Context, CreateRequest, *CreateResponse)

	// Read is called when the provider must read resource values in order
	// to update state. Planned state values should be read from the
	// ReadRequest and new state values set on the ReadResponse.
	Read(context.Context, ReadRequest, *ReadResponse)

	// Update is called to update the state of the resource. Config, planned
	// state, and prior state values should be read from the
	// UpdateRequest and new state values set on the UpdateResponse.
	Update(context.Context, UpdateRequest, *UpdateResponse)

	// Delete is called when the provider must delete the resource. Config
	// values may be read from the DeleteRequest.
	//
	// If execution completes without error, the framework will automatically
	// call DeleteResponse.State.RemoveResource(), so it can be omitted
	// from provider logic.
	Delete(context.Context, DeleteRequest, *DeleteResponse)
}

Resource represents an instance of a managed resource type. This is the core interface that all resources must implement.

Resources can optionally implement these additional concepts:

• Configure: Include provider-level data or clients.
• Import: ResourceWithImportState
• Validation: Schema-based or entire configuration via ResourceWithConfigValidators or ResourceWithValidateConfig.
• Plan Modification: Schema-based or entire plan via ResourceWithModifyPlan.
• State Upgrades: ResourceWithUpgradeState

Although not required, it is conventional for resources to implement the ResourceWithImportState interface.

type ResourceBehavior

type ResourceBehavior struct {
	// ProviderDeferred enables provider-defined logic to be executed
	// in the case of an automatic deferred response from provider configure.
	//
	// 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.
	ProviderDeferred ProviderDeferredBehavior
}

ResourceBehavior controls framework-specific logic when interacting with a resource.

type ResourceWithConfigValidators

type ResourceWithConfigValidators interface {
	Resource

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

ResourceWithConfigValidators is an interface type that extends Resource to include declarative validations.

Declaring validation using this methodology simplifies implmentation 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 ResourceWithConfigure

type ResourceWithConfigure interface {
	Resource

	// Configure enables provider-level data or clients to be set in the
	// provider-defined Resource type. It is separately executed for each
	// ReadResource RPC.
	Configure(context.Context, ConfigureRequest, *ConfigureResponse)
}

ResourceWithConfigure is an interface type that extends Resource 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 Resource type.

This method is intended to replace the provider.ResourceType type NewResource method in a future release.

type ResourceWithImportState

type ResourceWithImportState interface {
	Resource

	// ImportState is called when the provider must import the state of a
	// resource instance. This method must return enough state so the Read
	// method can properly refresh the full resource.
	//
	// If setting an attribute with the import identifier, it is recommended
	// to use the ImportStatePassthroughID() call in this method.
	ImportState(context.Context, ImportStateRequest, *ImportStateResponse)
}

Optional interface on top of Resource that enables provider control over the ImportResourceState RPC. This RPC is called by Terraform when the `terraform import` command is executed. Afterwards, the ReadResource RPC is executed to allow providers to fully populate the resource state.

type ResourceWithModifyPlan

type ResourceWithModifyPlan interface {
	Resource

	// ModifyPlan is called when the provider has an opportunity to modify
	// the plan: once during the plan phase when Terraform is determining
	// the diff that should be shown to the user for approval, and once
	// during the apply phase with any unknown values from configuration
	// filled in with their final values.
	//
	// The planned new state is represented by
	// ModifyPlanResponse.Plan. It must meet the following
	// constraints:
	// 1. Any non-Computed attribute set in config must preserve the exact
	// config value or return the corresponding attribute value from the
	// prior state (ModifyPlanRequest.State).
	// 2. Any attribute with a known value must not have its value changed
	// in subsequent calls to ModifyPlan or Create/Read/Update.
	// 3. Any attribute with an unknown value may either remain unknown
	// or take on any value of the expected type.
	//
	// Any errors will prevent further resource-level plan modifications.
	ModifyPlan(context.Context, ModifyPlanRequest, *ModifyPlanResponse)
}

ResourceWithModifyPlan represents a resource instance with a ModifyPlan function.

type ResourceWithMoveState

type ResourceWithMoveState interface {
	Resource

	// An ordered list of source resource to current schema version state move
	// implementations. Only the first [StateMover] implementation that returns
	// state data or error diagnostics will be used, otherwise the framework
	// considers the [StateMover] as skipped and will try the next [StateMover].
	// If all implementations return without state and error diagnostics, the
	// framework will return an implementation not found error.
	//
	// It is strongly recommended that implementations be overly cautious and
	// return no state data if the source provider address, resource type,
	// or schema version is not fully implemented.
	MoveState(context.Context) []StateMover
}

Optional interface on top of Resource that enables provider control over the MoveResourceState RPC. This RPC is called by Terraform when there is a `moved` configuration block that changes the resource type and where this Resource is the target resource type. Since state data operations can cause data loss for practitioners, this support is explicitly opt-in to ensure that all data transformation logic is explicitly defined by the provider.

If the Resource does not implement this interface and Terraform sends a MoveResourceState request, the framework will automatically return an error diagnostic notifying the practitioner that this resource does not support the requested operation.

This functionality is only supported in Terraform 1.8 and later.

type ResourceWithUpgradeState

type ResourceWithUpgradeState interface {
	Resource

	// A mapping of prior state version to current schema version state upgrade
	// implementations. Only the specified state upgrader for the prior state
	// version is called, rather than each version in between, so it must
	// encapsulate all logic to convert the prior state to the current schema
	// version.
	//
	// Version keys begin at 0, which is the default schema version when
	// undefined. The framework will return an error diagnostic should the
	// requested state version not be implemented.
	UpgradeState(context.Context) map[int64]StateUpgrader
}

Optional interface on top of Resource that enables provider control over the UpgradeResourceState RPC. This RPC is automatically called by Terraform when the current Schema type Version field is greater than the stored state. Terraform does not store previous Schema information, so any breaking changes to state data types must be handled by providers.

Terraform CLI can execute the UpgradeResourceState RPC even when the prior state version matches the current schema version. The framework will automatically intercept this request and attempt to respond with the existing state. In this situation the framework will not execute any provider defined logic, so declaring it for this version is extraneous.

type ResourceWithValidateConfig

type ResourceWithValidateConfig interface {
	Resource

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

ResourceWithValidateConfig is an interface type that extends Resource to include imperative validation.

Declaring validation using this methodology simplifies one-off functionality that typically applies to a single resource. 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 SchemaRequest

type SchemaRequest struct{}

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

type SchemaResponse

type SchemaResponse struct {
	// Schema is the schema of the data source.
	Schema schema.Schema

	// Diagnostics report errors or warnings related to validating the data
	// source configuration. 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 Resource type Schema method.

type StateMover

type StateMover struct {
	// SourceSchema is an optional schema for the intended source resource state
	// and schema version. While not required, setting this will populate
	// [MoveStateRequest.SourceState] when possible similar to other [Resource]
	// types.
	//
	// State conversion errors based on this schema are only logged at DEBUG
	// level as there may be multiple [StateMover] implementations on the same
	// target resource for differing source resources. The [StateMover]
	// implementation will still be called even with these errors, so it is
	// important that implementations verify the request via the
	// [MoveStateRequest.SourceTypeName] and other fields before attempting
	// to use [MoveStateRequest.SourceState].
	//
	// If not set, source state data is only available in
	// [MoveStateRequest.SourceRawState].
	SourceSchema *schema.Schema

	// StateMove defines the logic for determining whether the request source
	// resource information should match this implementation, and if so, the
	// data transformation of the source resource state to the current schema
	// version state of this [Resource].
	//
	// The [context.Context] parameter contains framework-defined loggers and
	// supports request cancellation.
	//
	// The [MoveStateRequest] parameter contains source resource information.
	// If [SourceSchema] was set, the [MoveStateRequest.SourceState] field will
	// be available. Otherwise, the [MoveStateRequest.SourceRawState] must be
	// used.
	//
	// The [MoveStateResponse] parameter can either remain unmodified to signal
	// to the framework that this implementation should be considered skipped or
	// must contain the transformed state data to signal a successful move. Any
	// returned error diagnostics will cause the framework to immediately
	// respond with those errors and without calling other [StateMover]
	// implementations.
	StateMover func(context.Context, MoveStateRequest, *MoveStateResponse)
}

Implementation handler for a state move operation. After determining the source resource is supported, this should encapsulate all data transformation logic from a source resource to the current schema version of this Resource. The Resource is connected to these implementations by implementing the ResourceWithMoveState interface.

This functionality is only available in Terraform 1.8 or later. It is invoked when a configuration contains a `moved` configuration block where the source resource type in the `from` argument differs from the target resource type in the `to` argument, causing Terraform to call this provider operation and the framework to route the request to this Resource as the target.

Each implementation is responsible for determining whether the request should be handled or skipped. The implementation is considered skipped by the framework when the response contains no error diagnostics or state. Otherwise, any error diagnostics or state data, will cause the framework to consider the request completed and not call other StateMover implementations. The framework will return an implementation not found error if all implementations return responses without error diagnostics or state.

type StateUpgrader

type StateUpgrader struct {
	// Schema information for the prior state version. While not required,
	// setting this will populate the UpgradeStateRequest type State
	// field similar to other Resource data types. This allows for easier data
	// handling such as calling Get() or GetAttribute().
	//
	// If not set, prior state data is available in the
	// UpgradeResourceStateRequest type RawState field.
	PriorSchema *schema.Schema

	// Provider defined logic for upgrading a resource state from the prior
	// state version to the current schema version.
	//
	// The context.Context parameter contains framework-defined loggers and
	// supports request cancellation.
	//
	// The UpgradeStateRequest parameter contains the prior state data.
	// If PriorSchema was set, the State field will be available. Otherwise,
	// the RawState must be used.
	//
	// The UpgradeStateResponse parameter should contain the upgraded
	// state data and can be used to signal any logic warnings or errors.
	StateUpgrader func(context.Context, UpgradeStateRequest, *UpgradeStateResponse)
}

Implementation handler for a UpgradeState operation.

This is used to encapsulate all upgrade logic from a prior state to the current schema version when a Resource implements the ResourceWithUpgradeState interface.

type UpdateRequest

type UpdateRequest struct {
	// Config is the configuration the user supplied for the resource.
	//
	// 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

	// Plan is the planned state for the resource.
	Plan tfsdk.Plan

	// State is the current state of the resource prior to the Update
	// operation.
	State tfsdk.State

	// ProviderMeta is metadata from the provider_meta block of the module.
	ProviderMeta tfsdk.Config

	// Private is provider-defined resource private state data which was previously
	// stored with the resource state. Any existing data is copied to
	// UpdateResponse.Private to prevent accidental private state data loss.
	//
	// Use the GetKey method to read data. Use the SetKey method on
	// UpdateResponse.Private to update or remove a value.
	Private *privatestate.ProviderData
}

UpdateRequest represents a request for the provider to update a resource. An instance of this request struct is supplied as an argument to the resource's Update function.

type UpdateResponse

type UpdateResponse struct {
	// State is the state of the resource following the Update operation.
	// This field is pre-populated from UpdateResourceRequest.Plan and
	// should be set during the resource's Update operation.
	State tfsdk.State

	// Private is the private state resource data following the Update operation.
	// This field is pre-populated from UpdateRequest.Private and
	// can be modified during the resource's Update operation.
	Private *privatestate.ProviderData

	// Diagnostics report errors or warnings related to updating the
	// resource. An empty slice indicates a successful operation with no
	// warnings or errors generated.
	Diagnostics diag.Diagnostics
}

UpdateResponse represents a response to an UpdateRequest. An instance of this response struct is supplied as an argument to the resource's Update function, in which the provider should set values on the UpdateResponse as appropriate.

type UpgradeStateRequest

type UpgradeStateRequest struct {
	// Previous state of the resource in JSON (Terraform CLI 0.12 and later)
	// or flatmap format, depending on which version of Terraform CLI last
	// wrote the resource state. This data is always available, regardless
	// whether the wrapping StateUpgrader type PriorSchema field was
	// present.
	//
	// This is advanced functionality for providers wanting to skip the full
	// redeclaration of older schemas and instead use lower level handlers to
	// transform data. A typical implementation for working with this data will
	// call the Unmarshal() method.
	//
	// TODO: Create framework defined type that is not protocol specific.
	// Reference: https://github.com/hashicorp/terraform-plugin-framework/issues/340
	RawState *tfprotov6.RawState

	// Previous state of the resource if the wrapping StateUpgrader
	// type PriorSchema field was present. When available, this allows for
	// easier data handling such as calling Get() or GetAttribute().
	State *tfsdk.State
}

Request information for the provider logic to update a resource state from a prior state version to the current schema version. An instance of this is supplied as a parameter to a StateUpgrader, which ultimately comes from a Resource's UpgradeState method.

type UpgradeStateResponse

type UpgradeStateResponse struct {
	// Diagnostics report errors or warnings related to upgrading the resource
	// state. An empty slice indicates a successful operation with no warnings
	// or errors generated.
	Diagnostics diag.Diagnostics

	// Upgraded state of the resource, which should match the current schema
	// version. If set, this will override State.
	//
	// This field is intended only for advanced provider functionality, such as
	// skipping the full redeclaration of older schemas or using lower level
	// handlers to transform data. Call tfprotov6.NewDynamicValue() to set this
	// value.
	//
	// All data must be populated to prevent data loss during the upgrade
	// operation. No prior state data is copied automatically.
	//
	// TODO: Remove in preference of requiring State, rather than using either
	// a new framework defined type or keeping this protocol specific type.
	// Reference: https://github.com/hashicorp/terraform-plugin-framework/issues/340
	DynamicValue *tfprotov6.DynamicValue

	// Upgraded state of the resource, which should match the current schema
	// version. If DynamicValue is set, it will override this value.
	//
	// This field allows for easier data handling such as calling Set() or
	// SetAttribute(). It is generally recommended over working with the lower
	// level types and functionality required for DynamicValue.
	//
	// All data must be populated to prevent data loss during the upgrade
	// operation. No prior state data is copied automatically.
	State tfsdk.State
}

Response information for the provider logic to update a resource state from a prior state version to the current schema version. An instance of this is supplied as a parameter to a StateUpgrader, which ultimately came from a Resource's UpgradeState method.

type ValidateConfigRequest

type ValidateConfigRequest struct {
	// Config is the configuration the user supplied for the resource.
	//
	// 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 a resource. An instance of this request struct is supplied as an argument to the Resource ValidateConfig receiver method or automatically passed through to each ConfigValidator.

type ValidateConfigResponse

type ValidateConfigResponse struct {
	// Diagnostics report errors or warnings related to validating the resource
	// 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 Resource ValidateConfig receiver method or automatically passed through to each ConfigValidator.