tfprotov5

package
v0.25.0 Latest Latest
Warning

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

 Go to latest Published: Oct 30, 2024 License: MPL-2.0 Imports: 9 Imported by: 90

Documentation

Overview

Package tfprotov5 provides the interfaces and types needed to build a Terraform provider server.

All Terraform provider servers should be built on these types, to take advantage of the ecosystem and tooling built around them.

These types are small wrappers around the Terraform protocol. It is assumed that developers using tfprotov5 are familiar with the protocol, its requirements, and its semantics. Developers not comfortable working with the raw protocol should use the github.com/hashicorp/terraform-plugin-sdk/v2 Go module instead, which offers a less verbose, safer way to develop a Terraform provider, albeit with less flexibility and power.

Provider developers should start by defining a type that implements the `ProviderServer` interface. A struct is recommended, as it will allow you to store the configuration information attached to your provider for use in requests, but any type is technically possible.

`ProviderServer` implementations will need to implement the composed interfaces, `ResourceServer` and `DataSourceServer`. It is recommended, but not required, to use an embedded `ResourceRouter` and `DataSourceRouter` in your `ProviderServer` to achieve this, which will let you handle requests for each resource and data source in a resource-specific or data source-specific function.

To serve the `ProviderServer` implementation as a gRPC server that Terraform can connect to, use the `tfprotov5/server.Serve` function.

Index

Constants

This section is empty.

Variables

View Source 
var ErrUnknownDynamicValueType = errors.New("DynamicValue had no JSON or msgpack data set")

ErrUnknownDynamicValueType is returned when a DynamicValue has no MsgPack or JSON bytes set. This should never be returned during the normal operation of a provider, and indicates one of the following:

1. terraform-plugin-go is out of sync with the protocol and should be updated.

2. terrafrom-plugin-go has a bug.

3. The `DynamicValue` was generated or modified by something other than terraform-plugin-go and is no longer a valid value.

View Source 
var ErrUnknownRawStateType = errors.New("RawState had no JSON or flatmap data set")

ErrUnknownRawStateType is returned when a RawState has no Flatmap or JSON bytes set. This should never be returned during the normal operation of a provider, and indicates one of the following:

1. terraform-plugin-go is out of sync with the protocol and should be updated.

2. terrafrom-plugin-go has a bug.

3. The `RawState` was generated or modified by something other than terraform-plugin-go and is no longer a valid value.

Functions

This section is empty.

Types

type ApplyResourceChangeRequest 

type ApplyResourceChangeRequest struct {
	// TypeName is the type of resource Terraform wants to change.
	TypeName string

	// PriorState is the state of the resource before the changes are
	// applied, represented as a `DynamicValue`. See the documentation for
	// `DynamicValue` for information about safely accessing the state.
	//
	// The state is represented as a tftypes.Object, with each attribute
	// and nested block getting its own key and value.
	PriorState *DynamicValue

	// PlannedState is Terraform's plan for what the state should look like
	// after the changes are applied, represented as a `DynamicValue`. See
	// the documentation for `DynamicValue` for information about safely
	// accessing the state.
	//
	// This is the PlannedState returned during PlanResourceChange.
	//
	// The state is represented as a tftypes.Object, with each attribute
	// and nested block getting its own key and value.
	PlannedState *DynamicValue

	// Config is the configuration the user supplied for the resource. See
	// the documentation on `DynamicValue` for more information about
	// safely accessing the configuration.
	//
	// The configuration is represented as a tftypes.Object, with each
	// attribute and nested block getting its own key and value.
	//
	// This configuration may contain unknown values.
	Config *DynamicValue

	// PlannedPrivate is any provider-defined private state stored with the
	// resource. It is used for keeping state with the resource that is not
	// meant to be included when calculating diffs.
	//
	// This private state data is sourced from the PlanResourceChange RPC, in
	// relation to the types in this package, the PlanResourceChangeResponse
	// type PlannedPrivate field.
	//
	// To ensure private state data is preserved, copy any necessary data to
	// the ApplyResourceChangeResponse type Private field.
	PlannedPrivate []byte

	// ProviderMeta supplies the provider metadata configuration for the
	// module this resource is in. Module-specific provider metadata is an
	// advanced feature and usage of it should be coordinated with the
	// Terraform Core team by raising an issue at
	// https://github.com/hashicorp/terraform/issues/new/choose. See the
	// documentation on `DynamicValue` for information about safely
	// accessing the configuration.
	//
	// The configuration is represented as a tftypes.Object, with each
	// attribute and nested block getting its own key and value.
	//
	// This configuration will have known values for all fields.
	ProviderMeta *DynamicValue
}

ApplyResourceChangeRequest is the request Terraform sends when it needs to apply a planned set of changes to a resource.

type ApplyResourceChangeResponse 

type ApplyResourceChangeResponse struct {
	// NewState is the provider's understanding of what the resource's
	// state is after changes are applied, represented as a `DynamicValue`.
	// See the documentation for `DynamicValue` for information about
	// safely creating the `DynamicValue`.
	//
	// Any attribute, whether computed or not, that has a known value in
	// the PlannedState in the ApplyResourceChangeRequest must be preserved
	// exactly as it was in NewState.
	//
	// Any attribute in the PlannedState in the ApplyResourceChangeRequest
	// that is unknown must take on a known value at this time. No unknown
	// values are allowed in the NewState.
	//
	// The state should be represented as a tftypes.Object, with each
	// attribute and nested block getting its own key and value.
	NewState *DynamicValue

	// Private should be set to any state that the provider would like sent
	// with requests for this resource. This state will be associated with
	// the resource, but will not be considered when calculating diffs.
	Private []byte

	// Diagnostics report errors or warnings related to applying changes to
	// the requested resource. Returning an empty slice indicates a
	// successful validation with no warnings or errors generated.
	Diagnostics []*Diagnostic

	// UnsafeToUseLegacyTypeSystem should only be set by
	// hashicorp/terraform-plugin-sdk. It modifies Terraform's behavior to
	// work with the legacy expectations of that SDK.
	//
	// Nobody else should use this. Ever. For any reason. Just don't do it.
	//
	// We have to expose it here for terraform-plugin-sdk to be muxable, or
	// we wouldn't even be including it in this type. Don't use it. It may
	// go away or change behavior on you with no warning. It is
	// explicitly unsupported and not part of our SemVer guarantees.
	//
	// Deprecated: Really, just don't use this, you don't need it.
	UnsafeToUseLegacyTypeSystem bool
}

ApplyResourceChangeResponse is the response from the provider about what the state of a resource is after planned changes have been applied.

type CallFunctionRequest added in v0.20.0 

type CallFunctionRequest struct {
	// Name is the function name being called.
	Name string

	// Arguments is the configuration value of each argument the practitioner
	// supplied for the function call. The ordering and value of each element
	// matches the function parameters and their associated type.  If the
	// function definition includes a final variadic parameter, its value is an
	// ordered list of the variadic parameter type.
	Arguments []*DynamicValue
}

CallFunctionRequest is the request Terraform sends when it wants to execute the logic of function referenced in the configuration.

type CallFunctionResponse added in v0.20.0 

type CallFunctionResponse struct {
	// Error reports errors related to the execution of the
	// function logic. Returning a nil error indicates a successful response
	// with no errors presented to practitioners.
	Error *FunctionError

	// Result is the return value from the called function, matching the result
	// type in the function definition.
	Result *DynamicValue
}

CallFunctionResponse is the response from the provider with the result of executing the logic of the function.

type CloseEphemeralResourceRequest added in v0.25.0 

type CloseEphemeralResourceRequest struct {
	// TypeName is the type of resource Terraform is closing.
	TypeName string

	// Private is any provider-defined private data stored with the
	// ephemeral resource from the most recent Open or Renew call.
	Private []byte
}

CloseEphemeralResourceRequest is the request Terraform sends when it wants to close an ephemeral resource.

type CloseEphemeralResourceResponse added in v0.25.0 

type CloseEphemeralResourceResponse struct {
	// Diagnostics report errors or warnings related to closing the
	// requested ephemeral resource. Returning an empty slice
	// indicates a successful creation with no warnings or errors
	// generated.
	Diagnostics []*Diagnostic
}

CloseEphemeralResourceResponse is the response from the provider about the closed ephemeral resource.

type ConfigureProviderClientCapabilities added in v0.23.0 

type ConfigureProviderClientCapabilities struct {
	// DeferralAllowed signals that the request from Terraform is able to
	// handle deferred responses from the provider.
	DeferralAllowed bool
}

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

type ConfigureProviderRequest 

type ConfigureProviderRequest struct {
	// TerraformVersion is the version of Terraform executing the request.
	// This is supplied for logging, analytics, and User-Agent purposes
	// *only*. Providers should not try to gate provider behavior on
	// Terraform versions. It will make you sad. We can't stop you from
	// doing it, but we really highly recommend you do not do it.
	TerraformVersion string

	// Config is the configuration the user supplied for the provider. This
	// information should usually be persisted to the underlying type
	// that's implementing the ProviderServer interface, for use in later
	// RPC requests. See the documentation on `DynamicValue` for more
	// information about safely accessing the configuration.
	//
	// The configuration is represented as a tftypes.Object, with each
	// attribute and nested block getting its own key and value.
	//
	// The ConfigureProvider RPC call will be called twice; once when
	// generating a plan, once when applying the plan. When called during
	// plan, Config can contain unknown values if fields with unknown
	// values are interpolated into it. At apply time, all fields will have
	// known values. Values that are not set in the configuration will be
	// null.
	Config *DynamicValue

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

ConfigureProviderRequest represents a Terraform RPC request to supply the provider with information about what the user entered in the provider's configuration block.

type ConfigureProviderResponse 

type ConfigureProviderResponse struct {
	// Diagnostics report errors or warnings related to the provider's
	// configuration. Returning an empty slice indicates success, with no
	// errors or warnings generated.
	Diagnostics []*Diagnostic
}

ConfigureProviderResponse represents a Terraform RPC response to the configuration block that Terraform supplied for the provider.

type DataSourceMetadata added in v0.19.0 

type DataSourceMetadata struct {
	// TypeName is the name of the data resource.
	TypeName string
}

DataSourceMetadata describes metadata for a data resource in the GetMetadata RPC.

type DataSourceServer 

type DataSourceServer interface {
	// ValidateDataSourceConfig is called when Terraform is checking that a
	// data source's configuration is valid. It is guaranteed to have types
	// conforming to your schema, but it is not guaranteed that all values
	// will be known. This is your opportunity to do custom or advanced
	// validation prior to a plan being generated.
	ValidateDataSourceConfig(context.Context, *ValidateDataSourceConfigRequest) (*ValidateDataSourceConfigResponse, error)

	// ReadDataSource is called when Terraform is refreshing a data
	// source's state.
	ReadDataSource(context.Context, *ReadDataSourceRequest) (*ReadDataSourceResponse, error)
}

DataSourceServer is an interface containing the methods a data source implementation needs to fill.

type Deferred added in v0.23.0 

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.

type DeferredReason added in v0.23.0 

type DeferredReason int32

DeferredReason represents different reasons for deferring a change. 

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 added in v0.23.0 

func (d DeferredReason) String() string

type Diagnostic 

type Diagnostic struct {
	// Severity indicates how Terraform should handle the Diagnostic.
	Severity DiagnosticSeverity

	// Summary is a brief description of the problem, roughly
	// sentence-sized, and should provide a concise description of what
	// went wrong. For example, a Summary could be as simple as "Invalid
	// value.".
	Summary string

	// Detail is a lengthier, more complete description of the problem.
	// Detail should provide enough information that a user can resolve the
	// problem entirely. For example, a Detail could be "Values must be
	// alphanumeric and lowercase only."
	Detail string

	// Attribute indicates which field, specifically, has the problem. Not
	// setting this will indicate the entire resource; setting it will
	// indicate that the problem is with a certain field in the resource,
	// which helps users find the source of the problem.
	Attribute *tftypes.AttributePath
}

Diagnostic is used to convey information back the user running Terraform.

type DiagnosticSeverity 

type DiagnosticSeverity int32

DiagnosticSeverity represents different classes of Diagnostic which affect how Terraform handles the Diagnostics. 

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

	// DiagnosticSeverityError is used to indicate that a `Diagnostic`
	// represents an error and should halt Terraform execution.
	DiagnosticSeverityError DiagnosticSeverity = 1

	// DiagnosticSeverityWarning is used to indicate that a `Diagnostic`
	// represents a warning and should not halt Terraform's execution, but
	// it should be surfaced to the user.
	DiagnosticSeverityWarning DiagnosticSeverity = 2
)

func (DiagnosticSeverity) String 

func (d DiagnosticSeverity) String() string

type DynamicValue 

type DynamicValue struct {
	MsgPack []byte
	JSON    []byte
}

DynamicValue represents a nested encoding value that came from the protocol. The only way providers should ever interact with it is by calling its `Unmarshal` method to retrieve a `tftypes.Value`. Although the type system allows for other interactions, they are explicitly not supported, and will not be considered when evaluating for breaking changes. Treat this type as an opaque value, and *only* call its `Unmarshal` method.

func NewDynamicValue 

func NewDynamicValue(t tftypes.Type, v tftypes.Value) (DynamicValue, error)

NewDynamicValue creates a DynamicValue from a tftypes.Value. You must specify the tftype.Type you want to send the value as, and it must be a type that is compatible with the Type of the Value. Usually it should just be the Type of the Value, but it can also be the DynamicPseudoType.

func (DynamicValue) IsNull added in v0.17.0 

func (d DynamicValue) IsNull() (bool, error)

IsNull returns true if the DynamicValue represents a null value based on the underlying JSON or MessagePack data.

func (DynamicValue) Unmarshal 

func (d DynamicValue) Unmarshal(typ tftypes.Type) (tftypes.Value, error)

Unmarshal returns a `tftypes.Value` that represents the information contained in the DynamicValue in an easy-to-interact-with way. It is the main purpose of the DynamicValue type, and is how provider developers should obtain config, state, and other values from the protocol.

Pass in the type you want the `Value` to be interpreted as. Terraform's type system encodes in a lossy manner, meaning the type information is not preserved losslessly when going over the wire. Sets, lists, and tuples all look the same, as do user-specified values when the provider has a DynamicPseudoType in its schema. Objects and maps all look the same, as well, as do DynamicPseudoType values sometimes. Fortunately, the provider should already know the type; it should be the type of the schema, or PseudoDynamicType if that's what's in the schema. `Unmarshal` will then parse the value as though it belongs to that type, if possible, and return a `tftypes.Value` with the appropriate information. If the data can't be interpreted as that type, an error will be returned saying so. In these cases, double check to make sure the schema is declaring the same type being passed into `Unmarshal`.

In the event an ErrUnknownDynamicValueType is returned, one of three things has happened:

1. terraform-plugin-go is out of date and out of sync with the protocol, and an issue should be opened on its repo to get it updated.

2. terraform-plugin-go has a bug somewhere, and an issue should be opened on its repo to get it fixed.

3. The provider or a dependency has modified the `DynamicValue` in an unsupported way, or has created one from scratch, and should treat it as opaque and not modify it, only calling `Unmarshal` on `DynamicValue`s received from RPC requests.

type EphemeralResourceMetadata added in v0.25.0 

type EphemeralResourceMetadata struct {
	// TypeName is the name of the ephemeral resource.
	TypeName string
}

EphemeralResourceMetadata describes metadata for an ephemeral resource in the GetMetadata RPC.

type EphemeralResourceServer added in v0.25.0 

type EphemeralResourceServer interface {
	// ValidateEphemeralResourceConfig is called when Terraform is checking that an
	// ephemeral resource configuration is valid. It is guaranteed to have types
	// conforming to your schema, but it is not guaranteed that all values
	// will be known. This is your opportunity to do custom or advanced
	// validation prior to an ephemeral resource being opened.
	ValidateEphemeralResourceConfig(context.Context, *ValidateEphemeralResourceConfigRequest) (*ValidateEphemeralResourceConfigResponse, error)

	// OpenEphemeralResource is called when Terraform wants to open the ephemeral resource,
	// usually during planning. If the config for the ephemeral resource contains unknown
	// values, Terraform will defer the OpenEphemeralResource call until apply.
	OpenEphemeralResource(context.Context, *OpenEphemeralResourceRequest) (*OpenEphemeralResourceResponse, error)

	// RenewEphemeralResource is called when Terraform detects that the previously specified
	// RenewAt timestamp has passed. The RenewAt timestamp is supplied either from the
	// OpenEphemeralResource call or a previous RenewEphemeralResource call.
	RenewEphemeralResource(context.Context, *RenewEphemeralResourceRequest) (*RenewEphemeralResourceResponse, error)

	// CloseEphemeralResource is called when Terraform is closing the ephemeral resource.
	CloseEphemeralResource(context.Context, *CloseEphemeralResourceRequest) (*CloseEphemeralResourceResponse, error)
}

EphemeralResourceServer is an interface containing the methods an ephemeral resource implementation needs to fill.

type Function added in v0.20.0 

type Function struct {
	// Parameters is the ordered list of positional function parameters.
	Parameters []*FunctionParameter

	// VariadicParameter is an optional final parameter which accepts zero or
	// more argument values, in which Terraform will send an ordered list of the
	// parameter type.
	VariadicParameter *FunctionParameter

	// Return is the function result.
	Return *FunctionReturn

	// Summary is the shortened human-readable documentation for the function.
	Summary string

	// Description is the longer human-readable documentation for the function.
	Description string

	// DescriptionKind indicates the formatting and encoding that the
	// Description field is using.
	DescriptionKind StringKind

	// DeprecationMessage is the human-readable documentation if the function
	// is deprecated. This message should be practitioner oriented to explain
	// how their configuration should be updated.
	DeprecationMessage string
}

Function describes the definition of a function. Result must be defined.

type FunctionError added in v0.22.0 

type FunctionError struct {
	// Text is the description of the error.
	Text string

	// FunctionArgument is the positional function argument for aligning
	// configuration source.
	FunctionArgument *int64
}

FunctionError is used to convey information back to the user running Terraform.

type FunctionMetadata added in v0.20.0 

type FunctionMetadata struct {
	// Name is the name of the function.
	Name string
}

FunctionMetadata describes metadata for a function in the GetMetadata RPC.

type FunctionParameter added in v0.20.0 

type FunctionParameter struct {
	// AllowNullValue when enabled denotes that a null argument value can be
	// passed to the provider. When disabled, Terraform returns an error if the
	// argument value is null.
	AllowNullValue bool

	// AllowUnknownValues when enabled denotes that any unknown argument value
	// (recursively checked for collections) can be passed to the provider. When
	// disabled and an unknown value is present, Terraform skips the function
	// call entirely and returns an unknown value result from the function.
	AllowUnknownValues bool

	// Description is the human-readable documentation for the parameter.
	Description string

	// DescriptionKind indicates the formatting and encoding that the
	// Description field is using.
	DescriptionKind StringKind

	// Name is the human-readable display name for the parameter. Parameters
	// are by definition positional and this name is only used in documentation.
	Name string

	// Type indicates the type of data the parameter expects.
	Type tftypes.Type
}

FunctionParameter describes the definition of a function parameter. Type must be defined.

type FunctionReturn added in v0.20.0 

type FunctionReturn struct {
	// Type indicates the type of return data.
	Type tftypes.Type
}

FunctionReturn describes the definition of a function result. Type must be defined.

type FunctionServer added in v0.20.0 

type FunctionServer interface {
	// CallFunction is called when Terraform wants to execute the logic of a
	// function referenced in the configuration.
	CallFunction(context.Context, *CallFunctionRequest) (*CallFunctionResponse, error)

	// GetFunctions is called when Terraform wants to lookup which functions a
	// provider supports when not calling GetProviderSchema.
	GetFunctions(context.Context, *GetFunctionsRequest) (*GetFunctionsResponse, error)
}

FunctionServer is an interface containing the methods a function implementation needs to fill.

type GetFunctionsRequest added in v0.20.0 

type GetFunctionsRequest struct{}

GetFunctionsRequest is the request Terraform sends when it wants to lookup which functions a provider supports when not calling GetProviderSchema.

type GetFunctionsResponse added in v0.20.0 

type GetFunctionsResponse struct {
	// Diagnostics report errors or warnings related to the provider
	// implementation. Returning an empty slice indicates a successful response
	// with no warnings or errors presented to practitioners.
	Diagnostics []*Diagnostic

	// Functions is a map of function names to their definition.
	//
	// Unlike data resources and managed resources, the name should NOT be
	// prefixed with the provider name and an underscore. Configuration
	// references to functions use a separate namespacing syntax that already
	// includes the provider name.
	Functions map[string]*Function
}

GetFunctionsResponse is the response from the provider about the implemented functions.

type GetMetadataRequest added in v0.19.0 

type GetMetadataRequest struct{}

GetMetadataRequest represents a GetMetadata RPC request.

type GetMetadataResponse added in v0.19.0 

type GetMetadataResponse struct {
	// ServerCapabilities defines optionally supported protocol features,
	// such as forward-compatible Terraform behavior changes.
	ServerCapabilities *ServerCapabilities

	// Diagnostics report errors or warnings related to returning the
	// provider's schemas. Returning an empty slice indicates success, with
	// no errors or warnings generated.
	Diagnostics []*Diagnostic

	// DataSources returns metadata for all data resources.
	DataSources []DataSourceMetadata

	// Functions returns metadata for all functions.
	Functions []FunctionMetadata

	// Resources returns metadata for all managed resources.
	Resources []ResourceMetadata

	// EphemeralResources returns metadata for all ephemeral resources.
	EphemeralResources []EphemeralResourceMetadata
}

GetMetadataResponse represents a GetMetadata RPC response.

type GetProviderSchemaRequest 

type GetProviderSchemaRequest struct{}

GetProviderSchemaRequest represents a Terraform RPC request for the provider's schemas.

type GetProviderSchemaResponse 

type GetProviderSchemaResponse struct {
	// ServerCapabilities defines optionally supported protocol features,
	// such as forward-compatible Terraform behavior changes.
	ServerCapabilities *ServerCapabilities

	// Provider defines the schema for the provider configuration, which
	// will be specified in the provider block of the user's configuration.
	Provider *Schema

	// ProviderMeta defines the schema for the provider's metadata, which
	// will be specified in the provider_meta blocks of the terraform block
	// for a module. This is an advanced feature and its usage should be
	// coordinated with the Terraform Core team by opening an issue at
	// https://github.com/hashicorp/terraform/issues/new/choose.
	ProviderMeta *Schema

	// ResourceSchemas is a map of resource names to the schema for the
	// configuration specified in the resource. The name should be a
	// resource name, and should be prefixed with your provider's shortname
	// and an underscore. It should match the first label after `resource`
	// in a user's configuration.
	ResourceSchemas map[string]*Schema

	// DataSourceSchemas is a map of data source names to the schema for
	// the configuration specified in the data source. The name should be a
	// data source name, and should be prefixed with your provider's
	// shortname and an underscore. It should match the first label after
	// `data` in a user's configuration.
	DataSourceSchemas map[string]*Schema

	// Functions is a map of function names to their definition.
	//
	// Unlike data resources and managed resources, the name should NOT be
	// prefixed with the provider name and an underscore. Configuration
	// references to functions use a separate namespacing syntax that already
	// includes the provider name.
	Functions map[string]*Function

	// EphemeralResourceSchemas is a map of ephemeral resource names to the schema for
	// the configuration specified in the ephemeral resource. The name should be an
	// ephemeral resource name, and should be prefixed with your provider's
	// shortname and an underscore. It should match the first label after
	// `ephemeral` in a user's configuration.
	EphemeralResourceSchemas map[string]*Schema

	// Diagnostics report errors or warnings related to returning the
	// provider's schemas. Returning an empty slice indicates success, with
	// no errors or warnings generated.
	Diagnostics []*Diagnostic
}

GetProviderSchemaResponse represents a Terraform RPC response containing the provider's schemas.

type ImportResourceStateClientCapabilities added in v0.23.0 

type ImportResourceStateClientCapabilities struct {
	// DeferralAllowed signals that the request from Terraform is able to
	// handle deferred responses from the provider.
	DeferralAllowed bool
}

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

type ImportResourceStateRequest 

type ImportResourceStateRequest struct {
	// TypeName is the type of resource Terraform wants to import.
	TypeName string

	// ID is the user-supplied identifying information about the resource
	// or resources. Providers decide and communicate to users the format
	// for the ID, and use it to determine what resource or resources to
	// import.
	ID string

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

ImportResourceStateRequest is the request Terraform sends when it wants a provider to import one or more resources specified by an ID.

type ImportResourceStateResponse 

type ImportResourceStateResponse struct {
	// ImportedResources are the resources the provider found and was able
	// to import.
	ImportedResources []*ImportedResource

	// Diagnostics report errors or warnings related to importing the
	// requested resource or resources. Returning an empty slice indicates
	// a successful validation with no warnings or errors generated.
	Diagnostics []*Diagnostic

	// Deferred is used to indicate to Terraform that the ImportResourceState operation
	// needs to be deferred for a reason.
	Deferred *Deferred
}

ImportResourceStateResponse is the response from the provider about the imported resources.

type ImportedResource 

type ImportedResource struct {
	// TypeName is the type of resource that was imported.
	TypeName string

	// State is the provider's understanding of the imported resource's
	// state, represented as a `DynamicValue`. See the documentation for
	// `DynamicValue` for information about safely creating the
	// `DynamicValue`.
	//
	// The state should be represented as a tftypes.Object, with each
	// attribute and nested block getting its own key and value.
	State *DynamicValue

	// Private should be set to any state that the provider would like sent
	// with requests for this resource. This state will be associated with
	// the resource, but will not be considered when calculating diffs.
	Private []byte
}

ImportedResource represents a single resource that a provider has successfully imported into state.

type MoveResourceStateRequest added in v0.21.0 

type MoveResourceStateRequest struct {
	// SourcePrivate is the private state of the source resource.
	SourcePrivate []byte

	// SourceProviderAddress is the address of the provider for the source
	// resource type.
	SourceProviderAddress string

	// SourceSchemaVersion is the version of the source resource state.
	SourceSchemaVersion int64

	// SourceState is the raw state of the source resource.
	//
	// Only the underlying JSON field is populated.
	SourceState *RawState

	// SourceTypeName is the source resource type for the move request.
	SourceTypeName string

	// TargetTypeName is the target resource type for the move request.
	TargetTypeName string
}

MoveResourceStateRequest is the request Terraform sends when it requests a provider to move the state of a source resource into the target resource. Target resource types generally must opt into accepting each source resource type since any transformation logic requires knowledge of the source state.

This functionality is only supported in Terraform 1.8 and later. The provider must have enabled the MoveResourceState server capability to enable these requests.

type MoveResourceStateResponse added in v0.21.0 

type MoveResourceStateResponse struct {
	// TargetPrivate is the target resource private state after the move.
	TargetPrivate []byte

	// TargetState is the target resource state after the move.
	TargetState *DynamicValue

	// Diagnostics report any warnings or errors related to moving the state.
	Diagnostics []*Diagnostic
}

MoveResourceStateResponse is the response from the provider containing the moved state for the given resource.

type OpenEphemeralResourceClientCapabilities added in v0.25.0 

type OpenEphemeralResourceClientCapabilities struct {
	// DeferralAllowed signals that the request from Terraform is able to
	// handle deferred responses from the provider.
	DeferralAllowed bool
}

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

type OpenEphemeralResourceRequest added in v0.25.0 

type OpenEphemeralResourceRequest struct {
	// TypeName is the type of resource Terraform is opening.
	TypeName string

	// Config is the configuration the user supplied for that ephemeral resource. See
	// the documentation on `DynamicValue` for more information about
	// safely accessing the configuration.
	//
	// The configuration is represented as a tftypes.Object, with each
	// attribute and nested block getting its own key and value.
	//
	// This configuration will always be fully known. If Config contains unknown values,
	// Terraform will defer the OpenEphemeralResource RPC until apply.
	Config *DynamicValue

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

OpenEphemeralResourceRequest is the request Terraform sends when it wants to open an ephemeral resource.

type OpenEphemeralResourceResponse added in v0.25.0 

type OpenEphemeralResourceResponse struct {
	// Result is the provider's understanding of what the ephemeral resource's
	// data is after it has been opened, represented as a `DynamicValue`.
	// See the documentation for `DynamicValue` for information about
	// safely creating the `DynamicValue`.
	//
	// Any attribute, whether computed or not, that has a known value in
	// the Config in the OpenEphemeralResourceRequest must be preserved
	// exactly as it was in Result.
	//
	// Any attribute in the Config in the OpenEphemeralResourceRequest
	// that is unknown must take on a known value at this time. No unknown
	// values are allowed in the Result.
	//
	// The result should be represented as a tftypes.Object, with each
	// attribute and nested block getting its own key and value.
	Result *DynamicValue

	// Diagnostics report errors or warnings related to opening the
	// requested ephemeral resource. Returning an empty slice
	// indicates a successful creation with no warnings or errors
	// generated.
	Diagnostics []*Diagnostic

	// Private should be set to any private data that the provider would like to be
	// sent to the next Renew or Close call.
	Private []byte

	// RenewAt indicates to Terraform that the ephemeral resource
	// needs to be renewed at the specified time. Terraform will
	// call the RenewEphemeralResource RPC when the specified time has passed.
	RenewAt time.Time

	// Deferred is used to indicate to Terraform that the OpenEphemeralResource operation
	// needs to be deferred for a reason.
	Deferred *Deferred
}

OpenEphemeralResourceResponse is the response from the provider about the current state of the opened ephemeral resource.

type PlanResourceChangeClientCapabilities added in v0.23.0 

type PlanResourceChangeClientCapabilities struct {
	// DeferralAllowed signals that the request from Terraform is able to
	// handle deferred responses from the provider.
	DeferralAllowed bool
}

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

type PlanResourceChangeRequest 

type PlanResourceChangeRequest struct {
	// TypeName is the type of resource Terraform is generating a plan for.
	TypeName string

	// PriorState is the state of the resource before the plan is applied,
	// represented as a `DynamicValue`. See the documentation for
	// `DynamicValue` for information about safely accessing the state.
	//
	// The state is represented as a tftypes.Object, with each attribute
	// and nested block getting its own key and value.
	PriorState *DynamicValue

	// ProposedNewState is the state that Terraform is proposing for the
	// resource, with the changes in the configuration applied, represented
	// as a `DynamicValue`. See the documentation for `DynamicValue` for
	// information about safely accessing the state.
	//
	// The ProposedNewState merges any non-null values in the configuration
	// with any computed attributes in PriorState as a utility to help
	// providers avoid needing to implement such merging functionality
	// themselves.
	//
	// The state is represented as a tftypes.Object, with each attribute
	// and nested block getting its own key and value.
	//
	// The ProposedNewState will be null when planning a delete operation.
	ProposedNewState *DynamicValue

	// Config is the configuration the user supplied for the resource. See
	// the documentation on `DynamicValue` for more information about
	// safely accessing the configuration.
	//
	// The configuration is represented as a tftypes.Object, with each
	// attribute and nested block getting its own key and value.
	//
	// 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 *DynamicValue

	// PriorPrivate is any provider-defined private state stored with the
	// resource. It is used for keeping state with the resource that is not
	// meant to be included when calculating diffs.
	//
	// To ensure private state data is preserved, copy any necessary data to
	// the PlanResourceChangeResponse type PlannedPrivate field.
	PriorPrivate []byte

	// ProviderMeta supplies the provider metadata configuration for the
	// module this resource is in. Module-specific provider metadata is an
	// advanced feature and usage of it should be coordinated with the
	// Terraform Core team by raising an issue at
	// https://github.com/hashicorp/terraform/issues/new/choose. See the
	// documentation on `DynamicValue` for information about safely
	// accessing the configuration.
	//
	// The configuration is represented as a tftypes.Object, with each
	// attribute and nested block getting its own key and value.
	//
	// This configuration will have known values for all fields.
	ProviderMeta *DynamicValue

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

PlanResourceChangeRequest is the request Terraform sends when it is generating a plan for a resource and wants the provider's input on what the planned state should be.

type PlanResourceChangeResponse 

type PlanResourceChangeResponse struct {
	// PlannedState is the provider's indication of what the state for the
	// resource should be after apply, represented as a `DynamicValue`. See
	// the documentation for `DynamicValue` for information about safely
	// creating the `DynamicValue`.
	//
	// This is usually derived from the ProposedNewState passed in the
	// PlanResourceChangeRequest, with default values substituted for any
	// null values and overriding any computed values that are expected to
	// change as a result of the apply operation. This may contain unknown
	// values if the value could change but its new value won't be known
	// until apply time.
	//
	// Any value that was non-null in the configuration must either
	// preserve the exact configuration value or return the corresponding
	// value from the prior state. The value from the prior state should be
	// returned when the configuration value is semantically equivalent to
	// the state value.
	//
	// Any value that is marked as computed in the schema and is null in
	// the configuration may be set by the provider to any value of the
	// expected type.
	//
	// PlanResourceChange will actually be called twice; once when
	// generating the plan for the user to approve, once during the apply.
	// During the apply, additional values from the configuration--upstream
	// values interpolated in that were computed at apply time--will be
	// populated. During this second call, any attribute that had a known
	// value in the first PlannedState must have an identical value in the
	// second PlannedState. Any unknown values may remain unknown or may
	// take on any value of the appropriate type. This means the values
	// returned in PlannedState should be deterministic and unknown values
	// should be used if a field's value may change depending on what value
	// ends up filling an unknown value in the config.
	//
	// The state should be represented as a tftypes.Object, with each
	// attribute and nested block getting its own key and value.
	PlannedState *DynamicValue

	// RequiresReplace is a list of tftypes.AttributePaths 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 []*tftypes.AttributePath

	// PlannedPrivate should be set to any state that the provider would
	// like sent with requests for this resource. This state will be
	// associated with the resource, but will not be considered when
	// calculating diffs.
	//
	// This private state data will be sent in the ApplyResourceChange RPC, in
	// relation to the types of this package, the ApplyResourceChangeRequest
	// type PlannedPrivate field.
	PlannedPrivate []byte

	// Diagnostics report errors or warnings related to determining the
	// planned state of the requested resource. Returning an empty slice
	// indicates a successful validation with no warnings or errors
	// generated.
	Diagnostics []*Diagnostic

	// UnsafeToUseLegacyTypeSystem should only be set by
	// hashicorp/terraform-plugin-sdk. It modifies Terraform's behavior to
	// work with the legacy expectations of that SDK.
	//
	// Nobody else should use this. Ever. For any reason. Just don't do it.
	//
	// We have to expose it here for terraform-plugin-sdk to be muxable, or
	// we wouldn't even be including it in this type. Don't use it. It may
	// go away or change behavior on you with no warning. It is
	// explicitly unsupported and not part of our SemVer guarantees.
	//
	// Deprecated: Really, just don't use this, you don't need it.
	UnsafeToUseLegacyTypeSystem bool

	// Deferred is used to indicate to Terraform that the PlanResourceChange operation
	// needs to be deferred for a reason.
	Deferred *Deferred
}

PlanResourceChangeResponse is the response from the provider about what the planned state for a given resource should be.

type PrepareProviderConfigRequest 

type PrepareProviderConfigRequest struct {
	// Config is the configuration the user supplied for the provider. See
	// the documentation on `DynamicValue` for more information about
	// safely accessing the configuration.
	//
	// The configuration is represented as a tftypes.Object, with each
	// attribute and nested block getting its own key and value.
	//
	// The PrepareProviderConfig RPC call will be called twice; once when
	// generating a plan, once when applying the plan. When called during
	// plan, Config can contain unknown values if fields with unknown
	// values are interpolated into it. At apply time, all fields will have
	// known values. Values that are not set in the configuration will be
	// null.
	Config *DynamicValue
}

PrepareProviderConfigRequest represents a Terraform RPC request for the provider to modify the provider configuration in preparation for Terraform validating it.

type PrepareProviderConfigResponse 

type PrepareProviderConfigResponse struct {
	// PreparedConfig should be set to the modified configuration. See the
	// documentation on `DynamicValue` for information about safely
	// creating the `DynamicValue`.
	//
	// This RPC call exists because early versions of the Terraform Plugin
	// SDK allowed providers to set defaults for provider configurations in
	// such a way that Terraform couldn't validate the provider config
	// without retrieving the default values first. As providers using
	// terraform-plugin-go directly and new frameworks built on top of it
	// have no such requirement, it is safe and recommended to simply set
	// PreparedConfig to the value of the PrepareProviderConfigRequest's
	// Config property, indicating that no changes are needed to the
	// configuration.
	//
	// The configuration should be represented as a tftypes.Object, with
	// each attribute and nested block getting its own key and value.
	//
	// TODO: should we provide an implementation that does that that
	// provider developers can just embed and not need to implement the
	// method themselves, then?
	PreparedConfig *DynamicValue

	// Diagnostics report errors or warnings related to preparing the
	// provider's configuration. Returning an empty slice indicates
	// success, with no errors or warnings generated.
	Diagnostics []*Diagnostic
}

PrepareProviderConfigResponse represents a Terraform RPC response containing a modified provider configuration that Terraform can now validate and use.

type ProviderServer 

type ProviderServer interface {
	// GetMetadata returns upfront information about server capabilities and
	// supported resource types without requiring the server to instantiate all
	// schema information, which may be memory intensive. This RPC is optional,
	// where clients may receive an unimplemented RPC error. Clients should
	// ignore the error and call the GetProviderSchema RPC as a fallback.
	GetMetadata(context.Context, *GetMetadataRequest) (*GetMetadataResponse, error)

	// GetProviderSchema is called when Terraform needs to know what the
	// provider's schema is, along with the schemas of all its resources
	// and data sources.
	GetProviderSchema(context.Context, *GetProviderSchemaRequest) (*GetProviderSchemaResponse, error)

	// PrepareProviderConfig is called to give a provider a chance to
	// modify the configuration the user specified before validation.
	PrepareProviderConfig(context.Context, *PrepareProviderConfigRequest) (*PrepareProviderConfigResponse, error)

	// ConfigureProvider is called to pass the user-specified provider
	// configuration to the provider.
	ConfigureProvider(context.Context, *ConfigureProviderRequest) (*ConfigureProviderResponse, error)

	// StopProvider is called when Terraform would like providers to shut
	// down as quickly as possible, and usually represents an interrupt.
	StopProvider(context.Context, *StopProviderRequest) (*StopProviderResponse, error)

	// ResourceServer is an interface encapsulating all the
	// resource-related RPC requests. ProviderServer implementations must
	// implement them, but they are a handy interface for defining what a
	// resource is to terraform-plugin-go, so they're their own interface
	// that is composed into ProviderServer.
	ResourceServer

	// DataSourceServer is an interface encapsulating all the data
	// source-related RPC requests. ProviderServer implementations must
	// implement them, but they are a handy interface for defining what a
	// data source is to terraform-plugin-go, so they're their own
	// interface that is composed into ProviderServer.
	DataSourceServer

	// FunctionServer is an interface encapsulating all the function-related RPC
	// requests. ProviderServer implementations must implement them, but they
	// are a handy interface for defining what a function is to
	// terraform-plugin-go, so they are their own interface that is composed
	// into ProviderServer.
	FunctionServer
}

ProviderServer is an interface that reflects that Terraform protocol. Providers must implement this interface.

type ProviderServerWithEphemeralResources deprecated added in v0.25.0 

type ProviderServerWithEphemeralResources interface {
	ProviderServer

	// EphemeralResourceServer is an interface encapsulating all the ephemeral
	// resource-related RPC requests.
	EphemeralResourceServer
}

ProviderServerWithEphemeralResources is a temporary interface for servers to implement Ephemeral Resource RPC handling with:

- ValidateEphemeralResourceConfig - OpenEphemeralResource - RenewEphemeralResource - CloseEphemeralResource

Deprecated: The EphemeralResourceServer methods will be moved into the ProviderServer interface and this interface will be removed in a future version.

type RawState 

type RawState struct {
	JSON    []byte
	Flatmap map[string]string
}

RawState is the raw, undecoded state for providers to upgrade. It is undecoded as Terraform, for whatever reason, doesn't have the previous schema available to it, and so cannot decode the state itself and pushes that responsibility off onto providers.

It is safe to assume that Flatmap can be ignored for any state written by Terraform 0.12.0 or higher, but it is not safe to assume that all states written by 0.12.0 or higher will be in JSON format; future versions may switch to an alternate encoding for states.

func (RawState) Unmarshal added in v0.2.0 

func (s RawState) Unmarshal(typ tftypes.Type) (tftypes.Value, error)

Unmarshal returns a `tftypes.Value` that represents the information contained in the RawState in an easy-to-interact-with way. It is the main purpose of the RawState type, and is how provider developers should obtain state values from the UpgradeResourceState RPC call.

Pass in the type you want the `Value` to be interpreted as. Terraform's type system encodes in a lossy manner, meaning the type information is not preserved losslessly when going over the wire. Sets, lists, and tuples all look the same. Objects and maps all look the same, as well, as do user-specified values when DynamicPseudoType is used in the schema. Fortunately, the provider should already know the type; it should be the type of the schema, or DynamicPseudoType if that's what's in the schema. `Unmarshal` will then parse the value as though it belongs to that type, if possible, and return a `tftypes.Value` with the appropriate information. If the data can't be interpreted as that type, an error will be returned saying so. In these cases, double check to make sure the schema is declaring the same type being passed into `Unmarshal`.

In the event an ErrUnknownRawStateType is returned, one of three things has happened:

1. terraform-plugin-go is out of date and out of sync with the protocol, and an issue should be opened on its repo to get it updated.

2. terraform-plugin-go has a bug somewhere, and an issue should be opened on its repo to get it fixed.

3. The provider or a dependency has modified the `RawState` in an unsupported way, or has created one from scratch, and should treat it as opaque and not modify it, only calling `Unmarshal` on `RawState`s received from RPC requests.

State files written before Terraform 0.12 that haven't been upgraded yet cannot be unmarshaled, and must have their Flatmap property read directly.

func (RawState) UnmarshalWithOpts added in v0.13.0 

func (s RawState) UnmarshalWithOpts(typ tftypes.Type, opts UnmarshalOpts) (tftypes.Value, error)

UnmarshalWithOpts is identical to Unmarshal but also accepts a tftypes.UnmarshalOpts which contains options that can be used to modify the behaviour when unmarshalling JSON or Flatmap.

type ReadDataSourceClientCapabilities added in v0.23.0 

type ReadDataSourceClientCapabilities struct {
	// DeferralAllowed signals that the request from Terraform is able to
	// handle deferred responses from the provider.
	DeferralAllowed bool
}

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

type ReadDataSourceRequest 

type ReadDataSourceRequest struct {
	// TypeName is the type of data source Terraform is requesting an
	// updated state for.
	TypeName string

	// Config is the configuration the user supplied for that data source.
	// See the documentation on `DynamicValue` for information about safely
	// accessing the configuration.
	//
	// The configuration is represented as a tftypes.Object, with each
	// attribute and nested block getting its own key and value.
	//
	// This configuration may have unknown values.
	Config *DynamicValue

	// ProviderMeta supplies the provider metadata configuration for the
	// module this data source is in. Module-specific provider metadata is
	// an advanced feature and usage of it should be coordinated with the
	// Terraform Core team by raising an issue at
	// https://github.com/hashicorp/terraform/issues/new/choose. See the
	// documentation on `DynamicValue` for information about safely
	// accessing the configuration.
	//
	// The configuration is represented as a tftypes.Object, with each
	// attribute and nested block getting its own key and value.
	//
	// This configuration will have known values for all fields.
	ProviderMeta *DynamicValue

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

ReadDataSourceRequest is the request Terraform sends when it wants to get the latest state for a data source.

type ReadDataSourceResponse 

type ReadDataSourceResponse struct {
	// State is the current state of the data source, represented as a
	// `DynamicValue`. See the documentation on `DynamicValue` for
	// information about safely creating the `DynamicValue`.
	//
	// The state should be represented as a tftypes.Object, with each
	// attribute and nested block getting its own key and value.
	State *DynamicValue

	// Diagnostics report errors or warnings related to retrieving the
	// current state of the requested data source. Returning an empty slice
	// indicates a successful validation with no warnings or errors
	// generated.
	Diagnostics []*Diagnostic

	// Deferred is used to indicate to Terraform that the ReadDataSource operation
	// needs to be deferred for a reason.
	Deferred *Deferred
}

ReadDataSourceResponse is the response from the provider about the current state of the requested data source.

type ReadResourceClientCapabilities added in v0.23.0 

type ReadResourceClientCapabilities struct {
	// DeferralAllowed signals that the request from Terraform is able to
	// handle deferred responses from the provider.
	DeferralAllowed bool
}

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

type ReadResourceRequest 

type ReadResourceRequest struct {
	// TypeName is the type of resource Terraform is requesting an upated
	// state for.
	TypeName string

	// CurrentState is the current state of the resource as far as
	// Terraform knows, represented as a `DynamicValue`. See the
	// documentation for `DynamicValue` for information about safely
	// accessing the state.
	//
	// The state is represented as a tftypes.Object, with each attribute
	// and nested block getting its own key and value.
	CurrentState *DynamicValue

	// Private is any provider-defined private state stored with the
	// resource. It is used for keeping state with the resource that is not
	// meant to be included when calculating diffs.
	//
	// To ensure private state data is preserved, copy any necessary data to
	// the ReadResourceResponse type Private field.
	Private []byte

	// ProviderMeta supplies the provider metadata configuration for the
	// module this resource is in. Module-specific provider metadata is an
	// advanced feature and usage of it should be coordinated with the
	// Terraform Core team by raising an issue at
	// https://github.com/hashicorp/terraform/issues/new/choose. See the
	// documentation on `DynamicValue` for information about safely
	// accessing the configuration.
	//
	// The configuration is represented as a tftypes.Object, with each
	// attribute and nested block getting its own key and value.
	//
	// This configuration will have known values for all fields.
	ProviderMeta *DynamicValue

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

ReadResourceRequest is the request Terraform sends when it wants to get the latest state for a resource.

type ReadResourceResponse 

type ReadResourceResponse struct {
	// NewState is the current state of the resource according to the
	// provider, represented as a `DynamicValue`. See the documentation for
	// `DynamicValue` for information about safely creating the
	// `DynamicValue`.
	//
	// The state should be represented as a tftypes.Object, with each
	// attribute and nested block getting its own key and value.
	NewState *DynamicValue

	// Diagnostics report errors or warnings related to retrieving the
	// current state of the requested resource. Returning an empty slice
	// indicates a successful validation with no warnings or errors
	// generated.
	Diagnostics []*Diagnostic

	// Private should be set to any state that the provider would like sent
	// with requests for this resource. This state will be associated with
	// the resource, but will not be considered when calculating diffs.
	Private []byte

	// Deferred is used to indicate to Terraform that the ReadResource operation
	// needs to be deferred for a reason.
	Deferred *Deferred
}

ReadResourceResponse is the response from the provider about the current state of the requested resource.

type RenewEphemeralResourceRequest added in v0.25.0 

type RenewEphemeralResourceRequest struct {
	// TypeName is the type of resource Terraform is renewing.
	TypeName string

	// Private is any provider-defined private data stored with the
	// ephemeral resource from the most recent Open or Renew call.
	//
	// To ensure private data is preserved, copy any necessary data to
	// the RenewEphemeralResourceResponse type Private field.
	Private []byte
}

RenewEphemeralResourceRequest is the request Terraform sends when it wants to renew an ephemeral resource.

type RenewEphemeralResourceResponse added in v0.25.0 

type RenewEphemeralResourceResponse struct {
	// Diagnostics report errors or warnings related to renewing the
	// requested ephemeral resource. Returning an empty slice
	// indicates a successful creation with no warnings or errors
	// generated.
	Diagnostics []*Diagnostic

	// Private should be set to any private data that the provider would like to be
	// sent to the next Renew or Close call.
	Private []byte

	// RenewAt indicates to Terraform that the ephemeral resource
	// needs to be renewed at the specified time. Terraform will
	// call the RenewEphemeralResource RPC when the specified time has passed.
	RenewAt time.Time
}

RenewEphemeralResourceResponse is the response from the provider after an ephemeral resource has been renewed.

type ResourceMetadata added in v0.19.0 

type ResourceMetadata struct {
	// TypeName is the name of the managed resource.
	TypeName string
}

ResourceMetadata describes metadata for a managed resource in the GetMetadata RPC.

type ResourceServer 

type ResourceServer interface {
	// ValidateResourceTypeConfig is called when Terraform is checking that
	// a resource's configuration is valid. It is guaranteed to have types
	// conforming to your schema. This is your opportunity to do custom or
	// advanced validation prior to a plan being generated.
	ValidateResourceTypeConfig(context.Context, *ValidateResourceTypeConfigRequest) (*ValidateResourceTypeConfigResponse, error)

	// UpgradeResourceState is called when Terraform has encountered a
	// resource with a state in a schema that doesn't match the schema's
	// current version. It is the provider's responsibility to modify the
	// state to upgrade it to the latest state schema.
	UpgradeResourceState(context.Context, *UpgradeResourceStateRequest) (*UpgradeResourceStateResponse, error)

	// ReadResource is called when Terraform is refreshing a resource's
	// state.
	ReadResource(context.Context, *ReadResourceRequest) (*ReadResourceResponse, error)

	// PlanResourceChange is called when Terraform is attempting to
	// calculate a plan for a resource. Terraform will suggest a proposed
	// new state, which the provider can modify or return unmodified to
	// influence Terraform's plan.
	PlanResourceChange(context.Context, *PlanResourceChangeRequest) (*PlanResourceChangeResponse, error)

	// ApplyResourceChange is called when Terraform has detected a diff
	// between the resource's state and the user's config, and the user has
	// approved a planned change. The provider is to apply the changes
	// contained in the plan, and return the resulting state.
	ApplyResourceChange(context.Context, *ApplyResourceChangeRequest) (*ApplyResourceChangeResponse, error)

	// ImportResourceState is called when a user has requested Terraform
	// import a resource. The provider should fetch the information
	// specified by the passed ID and return it as one or more resource
	// states for Terraform to assume control of.
	ImportResourceState(context.Context, *ImportResourceStateRequest) (*ImportResourceStateResponse, error)

	// MoveResourceState is called when Terraform is asked to change a resource
	// type for an existing resource. The provider must accept the change as
	// valid by ensuring the source resource type, schema version, and provider
	// address are compatible to convert the source state into the target
	// resource type and latest state version.
	//
	// This functionality is only supported in Terraform 1.8 and later. The
	// provider must have enabled the MoveResourceState server capability to
	// enable these requests.
	MoveResourceState(context.Context, *MoveResourceStateRequest) (*MoveResourceStateResponse, error)
}

ResourceServer is an interface containing the methods a resource implementation needs to fill.

type Schema 

type Schema struct {
	// Version indicates which version of the schema this is. Versions
	// should be monotonically incrementing numbers. When Terraform
	// encounters a resource stored in state with a schema version lower
	// that the schema version the provider advertises for that resource,
	// Terraform requests the provider upgrade the resource's state.
	Version int64

	// Block is the root level of the schema, the collection of attributes
	// and blocks that make up a resource, data source, provider, or other
	// configuration block.
	Block *SchemaBlock
}

Schema is how Terraform defines the shape of data. It can be thought of as the type information for resources, data sources, provider configuration, and all the other data that Terraform sends to providers. It is how providers express their requirements for that data.

func (*Schema) ValueType added in v0.8.0 

func (s *Schema) ValueType() tftypes.Type

ValueType returns the tftypes.Type for a Schema.

If Schema is missing, an empty Object is returned.

type SchemaAttribute 

type SchemaAttribute struct {
	// Name is the name of the attribute. This is what the user will put
	// before the equals sign to assign a value to this attribute.
	Name string

	// Type indicates the type of data the attribute expects. See the
	// documentation for the tftypes package for information on what types
	// are supported and their behaviors.
	Type tftypes.Type

	// Description offers an end-user friendly description of what the
	// attribute is for. This will be surfaced to users through editor
	// integrations, documentation generation, and other settings.
	Description string

	// Required, when set to true, indicates that this attribute must have
	// a value assigned to it by the user or Terraform will throw an error.
	Required bool

	// Optional, when set to true, indicates that the user does not need to
	// supply a value for this attribute, but may.
	Optional bool

	// Computed, when set to true, indicates the the provider will supply a
	// value for this field. If Optional and Required are false and
	// Computed is true, the user will not be able to specify a value for
	// this field without Terraform throwing an error. If Optional is true
	// and Computed is true, the user can specify a value for this field,
	// but the provider may supply a value if the user does not. It is
	// always a violation of Terraform's protocol to substitute a value for
	// what the user entered, even if Computed is true.
	Computed bool

	// Sensitive, when set to true, indicates that the contents of this
	// attribute should be considered sensitive and not included in output.
	// This does not encrypt or otherwise protect these values in state, it
	// only offers protection from them showing up in plans or other
	// output.
	Sensitive bool

	// DescriptionKind indicates the formatting and encoding that the
	// Description field is using.
	DescriptionKind StringKind

	// Deprecated, when set to true, indicates that a attribute should no
	// longer be used and users should migrate away from it. At the moment
	// it is unused and will have no impact, but it will be used in future
	// tooling that is powered by provider schemas to enable richer user
	// experiences. Providers should set it when deprecating attributes in
	// preparation for these tools.
	Deprecated bool
}

SchemaAttribute represents a single attribute within a schema block. Attributes are the fields users can set in configuration using the equals sign, can assign to variables, can interpolate, and can use list comprehensions on.

func (*SchemaAttribute) ValueType added in v0.8.0 

func (s *SchemaAttribute) ValueType() tftypes.Type

ValueType returns the tftypes.Type for a SchemaAttribute.

If SchemaAttribute is missing, nil is returned.

type SchemaBlock 

type SchemaBlock struct {
	// TODO: why do we have version in the block, too?
	Version int64

	// Attributes are the attributes defined within the block. These are
	// the fields that users can set using the equals sign or reference in
	// interpolations.
	Attributes []*SchemaAttribute

	// BlockTypes are the nested blocks within the block. These are used to
	// have blocks within blocks.
	BlockTypes []*SchemaNestedBlock

	// Description offers an end-user friendly description of what the
	// block is for. This will be surfaced to users through editor
	// integrations, documentation generation, and other settings.
	Description string

	// DescriptionKind indicates the formatting and encoding that the
	// Description field is using.
	DescriptionKind StringKind

	// Deprecated, when set to true, indicates that a block should no
	// longer be used and users should migrate away from it. At the moment
	// it is unused and will have no impact, but it will be used in future
	// tooling that is powered by provider schemas to enable richer user
	// experiences. Providers should set it when deprecating blocks in
	// preparation for these tools.
	Deprecated bool
}

SchemaBlock represents a block in a schema. Blocks are how Terraform creates groupings of attributes. In configurations, they don't use the equals sign and use dynamic instead of list comprehensions.

Blocks will show up in state and config Values as a tftypes.Object, with the attributes and nested blocks defining the tftypes.Object's AttributeTypes.

func (*SchemaBlock) ValueType added in v0.8.0 

func (s *SchemaBlock) ValueType() tftypes.Type

ValueType returns the tftypes.Type for a SchemaBlock.

If SchemaBlock is missing, an empty Object is returned.

type SchemaNestedBlock 

type SchemaNestedBlock struct {
	// TypeName is the name of the block. It is what the user will specify
	// when using the block in configuration.
	TypeName string

	// Block is the block being nested inside another block. See the
	// SchemaBlock documentation for more information on blocks.
	Block *SchemaBlock

	// Nesting is the kind of nesting the block is using. Different nesting
	// modes have different behaviors and imply different kinds of data.
	Nesting SchemaNestedBlockNestingMode

	// MinItems is the minimum number of instances of this block that a
	// user must specify or Terraform will return an error.
	//
	// MinItems can only be set for SchemaNestedBlockNestingModeList and
	// SchemaNestedBlockNestingModeSet. SchemaNestedBlockNestingModeSingle
	// can also set MinItems and MaxItems both to 1 to indicate that the
	// block is required to be set. All other SchemaNestedBlockNestingModes
	// must leave MinItems set to 0.
	MinItems int64

	// MaxItems is the maximum number of instances of this block that a
	// user may specify before Terraform returns an error.
	//
	// MaxItems can only be set for SchemaNestedBlockNestingModeList and
	// SchemaNestedBlockNestingModeSet. SchemaNestedBlockNestingModeSingle
	// can also set MinItems and MaxItems both to 1 to indicate that the
	// block is required to be set. All other SchemaNestedBlockNestingModes
	// must leave MaxItems set to 0.
	MaxItems int64
}

SchemaNestedBlock is a nested block within another block. See SchemaBlock for more information on blocks.

func (*SchemaNestedBlock) ValueType added in v0.8.0 

func (s *SchemaNestedBlock) ValueType() tftypes.Type

ValueType returns the tftypes.Type for a SchemaNestedBlock.

If SchemaNestedBlock is missing or the Nesting mode is invalid, nil is returned.

type SchemaNestedBlockNestingMode 

type SchemaNestedBlockNestingMode int32

SchemaNestedBlockNestingMode indicates the nesting mode for SchemaNestedBlocks. The nesting mode determines the number of instances of the block allowed, how many labels the block expects, and the data structure used for the block in config and state values. 

const (
	// SchemaNestedBlockNestingModeInvalid indicates that the nesting mode
	// for a nested block in the schema is invalid. This generally
	// indicates a nested block that was created incorrectly.
	SchemaNestedBlockNestingModeInvalid SchemaNestedBlockNestingMode = 0

	// SchemaNestedBlockNestingModeSingle indicates that the nested block
	// should be treated as a single block with no labels, and there should
	// not be more than one of these blocks in the containing block. The
	// block will appear in config and state values as a tftypes.Object.
	SchemaNestedBlockNestingModeSingle SchemaNestedBlockNestingMode = 1

	// SchemaNestedBlockNestingModeList indicates that multiple instances
	// of the nested block should be permitted, with no labels, and that
	// the instances of the block should appear in config and state values
	// as a tftypes.List, with an ElementType of tftypes.Object.
	SchemaNestedBlockNestingModeList SchemaNestedBlockNestingMode = 2

	// SchemaNestedBlockNestingModeSet indicates that multiple instances
	// of the nested block should be permitted, with no labels, and that
	// the instances of the block should appear in config and state values
	// as a tftypes.Set, with an ElementType of tftypes.Object.
	SchemaNestedBlockNestingModeSet SchemaNestedBlockNestingMode = 3

	// SchemaNestedBlockNestingModeMap indicates that multiple instances of
	// the nested block should be permitted, each with a single label, and
	// that they should be represented in state and config values as a
	// tftypes.Map, with an ElementType of tftypes.Object. The labels on
	// the blocks will be used as the map keys. It is an error, therefore,
	// to use the same label value on multiple block instances.
	SchemaNestedBlockNestingModeMap SchemaNestedBlockNestingMode = 4

	// SchemaNestedBlockNestingModeGroup indicates that the nested block
	// should be treated as a single block with no labels, and there should
	// not be more than one of these blocks in the containing block. The
	// block will appear in config and state values as a tftypes.Object.
	//
	// SchemaNestedBlockNestingModeGroup is distinct from
	// SchemaNestedBlockNestingModeSingle in that it guarantees that the
	// block will never be null. If it is omitted from a config, the block
	// will still be set, but its attributes and nested blocks will all be
	// null. This is an exception to the rule that any block not set in the
	// configuration cannot be set in config by the provider; this ensures
	// the block is always considered "set" in the configuration, and is
	// therefore settable in state by the provider.
	SchemaNestedBlockNestingModeGroup SchemaNestedBlockNestingMode = 5
)

func (SchemaNestedBlockNestingMode) String 

func (s SchemaNestedBlockNestingMode) String() string

type ServerCapabilities added in v0.11.0 

type ServerCapabilities struct {
	// GetProviderSchemaOptional signals that this provider does not require
	// having the GetProviderSchema RPC called first to operate normally. This
	// means the caller can use a cached copy of the provider's schema instead.
	GetProviderSchemaOptional bool

	// MoveResourceState signals that a provider supports the MoveResourceState
	// RPC.
	MoveResourceState bool

	// PlanDestroy signals that a provider expects a call to
	// PlanResourceChange when a resource is going to be destroyed. This is
	// opt-in to prevent unexpected errors or panics since the
	// ProposedNewState in PlanResourceChangeRequest will be a null value.
	PlanDestroy bool
}

ServerCapabilities allows providers to communicate optionally supported protocol features, such as forward-compatible Terraform behavior changes.

This information is used in GetProviderSchemaResponse as capabilities are static features which must be known upfront in the provider server.

type StopProviderRequest 

type StopProviderRequest struct{}

StopProviderRequest represents a Terraform RPC request to interrupt a provider's work and terminate a provider's processes as soon as possible.

type StopProviderResponse 

type StopProviderResponse struct {
	// Error should be set to a string describing the error if the provider
	// cannot currently shut down for some reason. Because this always
	// represents a system error and not a user error, it is returned as a
	// string, not a Diagnostic.
	Error string
}

StopProviderResponse represents a Terraform RPC response surfacing an issues the provider encountered in terminating.

type StringKind 

type StringKind int32

StringKind indicates a formatting or encoding scheme for a string. 

const (
	// StringKindPlain indicates a string is plaintext, and should be
	// interpreted as having no formatting information.
	StringKindPlain StringKind = 0

	// StringKindMarkdown indicates a string is markdown-formatted, and
	// should be rendered using a Markdown renderer to correctly display
	// its formatting.
	StringKindMarkdown StringKind = 1
)

func (StringKind) String 

func (s StringKind) String() string

type UnmarshalOpts added in v0.13.0 

type UnmarshalOpts struct {
	ValueFromJSONOpts tftypes.ValueFromJSONOpts
}

UnmarshalOpts contains options that can be used to modify the behaviour when unmarshalling. Currently, this only contains a struct for opts for JSON but could have a field for Flatmap in the future.

type UpgradeResourceStateRequest 

type UpgradeResourceStateRequest struct {
	// TypeName is the type of resource that Terraform needs to upgrade the
	// state for.
	TypeName string

	// Version is the version of the state the resource currently has.
	Version int64

	// RawState is the state as Terraform sees it right now. See the
	// documentation for `RawState` for information on how to work with the
	// data it contains.
	RawState *RawState
}

UpgradeResourceStateRequest is the request Terraform sends when it needs a provider to upgrade the state of a given resource.

type UpgradeResourceStateResponse 

type UpgradeResourceStateResponse struct {
	// UpgradedState is the upgraded state for the resource, represented as
	// a `DynamicValue`. See the documentation on `DynamicValue` for
	// information about safely creating the `DynamicValue`.
	//
	// The state should be represented as a tftypes.Object, with each
	// attribute and nested block getting its own key and value.
	//
	// Terraform CLI 0.12 through 0.14 require the Msgpack field to be
	// populated or an EOF error will be returned.
	UpgradedState *DynamicValue

	// Diagnostics report errors or warnings related to upgrading the
	// state of the requested resource. Returning an empty slice indicates
	// a successful validation with no warnings or errors generated.
	Diagnostics []*Diagnostic
}

UpgradeResourceStateResponse is the response from the provider containing the upgraded state for the given resource.

type ValidateDataSourceConfigRequest 

type ValidateDataSourceConfigRequest struct {
	// TypeName is the type of data source Terraform is validating.
	TypeName string

	// Config is the configuration the user supplied for that data source.
	// See the documentation on `DynamicValue` for more information about
	// safely accessing the configuration.
	//
	// The configuration is represented as a tftypes.Object, with each
	// attribute and nested block getting its own key and value.
	//
	// 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 *DynamicValue
}

ValidateDataSourceConfigRequest is the request Terraform sends when it wants to validate a data source's configuration.

type ValidateDataSourceConfigResponse 

type ValidateDataSourceConfigResponse struct {
	// Diagnostics report errors or warnings related to the given
	// configuration. Returning an empty slice indicates a successful
	// validation with no warnings or errors generated.
	Diagnostics []*Diagnostic
}

ValidateDataSourceConfigResponse is the response from the provider about the validity of a data source's configuration.

type ValidateEphemeralResourceConfigRequest added in v0.25.0 

type ValidateEphemeralResourceConfigRequest struct {
	// TypeName is the type of resource Terraform is validating.
	TypeName string

	// Config is the configuration the user supplied for that ephemeral resource. See
	// the documentation on `DynamicValue` for more information about
	// safely accessing the configuration.
	//
	// The configuration is represented as a tftypes.Object, with each
	// attribute and nested block getting its own key and value.
	//
	// 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. Any attributes not directly
	// set in the configuration will be null.
	Config *DynamicValue
}

ValidateEphemeralResourceConfigRequest is the request Terraform sends when it wants to validate an ephemeral resource's configuration.

type ValidateEphemeralResourceConfigResponse added in v0.25.0 

type ValidateEphemeralResourceConfigResponse struct {
	// Diagnostics report errors or warnings related to the given
	// configuration. Returning an empty slice indicates a successful
	// validation with no warnings or errors generated.
	Diagnostics []*Diagnostic
}

ValidateEphemeralResourceConfigResponse is the response from the provider about the validity of an ephemeral resource's configuration.

type ValidateResourceTypeConfigRequest 

type ValidateResourceTypeConfigRequest struct {
	// TypeName is the type of resource Terraform is validating.
	TypeName string

	// Config is the configuration the user supplied for that resource. See
	// the documentation on `DynamicValue` for more information about
	// safely accessing the configuration.
	//
	// The configuration is represented as a tftypes.Object, with each
	// attribute and nested block getting its own key and value.
	//
	// 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. Any attributes not directly
	// set in the configuration will be null.
	Config *DynamicValue
}

ValidateResourceTypeConfigRequest is the request Terraform sends when it wants to validate a resource's configuration.

type ValidateResourceTypeConfigResponse 

type ValidateResourceTypeConfigResponse struct {
	// Diagnostics report errors or warnings related to the given
	// configuration. Returning an empty slice indicates a successful
	// validation with no warnings or errors generated.
	Diagnostics []*Diagnostic
}

ValidateResourceTypeConfigResponse is the response from the provider about the validity of a resource's configuration.

Source Files

View all Source files

Directories

Path Synopsis
internal
diag
Package diag contains diagnostics helpers.
 Package diag contains diagnostics helpers.
fromproto
Package fromproto converts Protocol Buffers generated tfplugin5 types into terraform-plugin-go tfprotov5 types.
 Package fromproto converts Protocol Buffers generated tfplugin5 types into terraform-plugin-go tfprotov5 types.
funcerr
Package funcerr contains function error helpers.
 Package funcerr contains function error helpers.
tf5serverlogging
Package tf5serverlogging contains logging functionality specific to tf5server and tfprotov5 types.
 Package tf5serverlogging contains logging functionality specific to tf5server and tfprotov5 types.
tfplugin5
toproto
Package toproto converts terraform-plugin-go tfprotov5 types to Protocol Buffers generated tfplugin5 types.
 Package toproto converts terraform-plugin-go tfprotov5 types to Protocol Buffers generated tfplugin5 types.
Package tf5server implements a server implementation to run tfprotov5.ProviderServers as gRPC servers.
 Package tf5server implements a server implementation to run tfprotov5.ProviderServers as gRPC servers.

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.