Package tfprotov6 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 tfprotov6 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 `tfprotov6/server.Serve` function.
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.
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.
This section is empty.
ApplyResourceChangeRequest is the request Terraform sends when it needs to apply a planned set of changes to a resource.
ApplyResourceChangeResponse is the response from the provider about what the state of a resource is after planned changes have been applied.
CallFunctionRequest is the request Terraform sends when it wants to execute the logic of function referenced in the configuration.
CallFunctionResponse is the response from the provider with the result of executing the logic of the function.
type CloseEphemeralResourceRequest struct {
TypeName string
Private []byte
}
CloseEphemeralResourceRequest is the request Terraform sends when it wants to close an ephemeral resource.
type CloseEphemeralResourceResponse struct {
Diagnostics []*Diagnostic
}
CloseEphemeralResourceResponse is the response from the provider about the closed ephemeral resource.
type ConfigureProviderClientCapabilities struct {
DeferralAllowed bool
}
ConfigureProviderClientCapabilities allows Terraform to publish information regarding optionally supported protocol features for the ConfigureProvider RPC, such as forward-compatible Terraform behavior changes.
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 struct {
Diagnostics []*Diagnostic
}
ConfigureProviderResponse represents a Terraform RPC response to the configuration block that Terraform supplied for the provider.
type DataSourceMetadata struct {
TypeName string
}
DataSourceMetadata describes metadata for a data resource in the GetMetadata RPC.
DataSourceServer is an interface containing the methods a data source implementation needs to fill.
Deferred is used to indicate to Terraform that a change needs to be deferred for a reason.
type DeferredReason int32
DeferredReason represents different reasons for deferring a change.
Diagnostic is used to convey information back the user running Terraform.
type DiagnosticSeverity int32
DiagnosticSeverity represents different classes of Diagnostic which affect how Terraform handles the Diagnostics.
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.
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.
IsNull returns true if the DynamicValue represents a null value based on the underlying JSON or MessagePack data.
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 struct {
TypeName string
}
EphemeralResourceMetadata describes metadata for an ephemeral resource in the GetMetadata RPC.
EphemeralResourceServer is an interface containing the methods an ephemeral resource implementation needs to fill.
Function describes the definition of a function. Result must be defined.
type FunctionError struct {
Text string
FunctionArgument *int64
}
FunctionError is used to convey information back to the user running Terraform.
type FunctionMetadata struct {
Name string
}
FunctionMetadata describes metadata for a function in the GetMetadata RPC.
FunctionParameter describes the definition of a function parameter. Type must be defined.
FunctionReturn describes the definition of a function result. Type must be defined.
FunctionServer is an interface containing the methods a function implementation needs to fill.
type GetFunctionsRequest struct{}
GetFunctionsRequest is the request Terraform sends when it wants to lookup which functions a provider supports when not calling GetProviderSchema.
GetFunctionsResponse is the response from the provider about the implemented functions.
type GetMetadataRequest struct{}
GetMetadataRequest represents a GetMetadata RPC request.
GetMetadataResponse represents a GetMetadata RPC response.
type GetProviderSchemaRequest struct{}
GetProviderSchemaRequest represents a Terraform RPC request for the provider's schemas.
GetProviderSchemaResponse represents a Terraform RPC response containing the provider's schemas.
type GetResourceIdentitySchemasRequest struct{}
GetResourceIdentitySchemasRequest represents a Terraform RPC request for the provider's resource identity schemas.
GetResourceIdentitySchemasResponse represents a Terraform RPC response containing the provider's resource identity schemas.
type ImportResourceStateClientCapabilities struct {
DeferralAllowed bool
}
ImportResourceStateClientCapabilities allows Terraform to publish information regarding optionally supported protocol features for the ImportResourceState RPC, such as forward-compatible Terraform behavior changes.
ImportResourceStateRequest is the request Terraform sends when it wants a provider to import one or more resources specified by an ID.
ImportResourceStateResponse is the response from the provider about the imported resources.
ImportedResource represents a single resource that a provider has successfully imported into state.
type MoveResourceStateRequest struct {
SourcePrivate []byte
SourceProviderAddress string
SourceSchemaVersion int64
SourceState *RawState
SourceTypeName string
TargetTypeName string
SourceIdentity *RawState
SourceIdentitySchemaVersion int64
}
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.
MoveResourceStateResponse is the response from the provider containing the moved state for the given resource.
type OpenEphemeralResourceClientCapabilities struct {
DeferralAllowed bool
}
OpenEphemeralResourceClientCapabilities allows Terraform to publish information regarding optionally supported protocol features for the OpenEphemeralResource RPC, such as forward-compatible Terraform behavior changes.
OpenEphemeralResourceRequest is the request Terraform sends when it wants to open an ephemeral resource.
OpenEphemeralResourceResponse is the response from the provider about the current state of the opened ephemeral resource.
type PlanResourceChangeClientCapabilities struct {
DeferralAllowed bool
}
PlanResourceChangeClientCapabilities allows Terraform to publish information regarding optionally supported protocol features for the PlanResourceChange RPC, such as forward-compatible Terraform behavior changes.
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.
PlanResourceChangeResponse is the response from the provider about what the planned state for a given resource should be.
type ProviderServer interface {
GetMetadata(context.Context, *GetMetadataRequest) (*GetMetadataResponse, error)
GetProviderSchema(context.Context, *GetProviderSchemaRequest) (*GetProviderSchemaResponse, error)
GetResourceIdentitySchemas(context.Context, *GetResourceIdentitySchemasRequest) (*GetResourceIdentitySchemasResponse, error)
ValidateProviderConfig(context.Context, *ValidateProviderConfigRequest) (*ValidateProviderConfigResponse, error)
ConfigureProvider(context.Context, *ConfigureProviderRequest) (*ConfigureProviderResponse, error)
StopProvider(context.Context, *StopProviderRequest) (*StopProviderResponse, error)
ResourceServer
DataSourceServer
FunctionServer
EphemeralResourceServer
}
ProviderServer is an interface that reflects that Terraform protocol. Providers must implement this interface.
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.
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.
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 struct {
DeferralAllowed bool
}
ReadDataSourceClientCapabilities allows Terraform to publish information regarding optionally supported protocol features for the ReadDataSource RPC, such as forward-compatible Terraform behavior changes.
ReadDataSourceRequest is the request Terraform sends when it wants to get the latest state for a data source.
ReadDataSourceResponse is the response from the provider about the current state of the requested data source.
type ReadResourceClientCapabilities struct {
DeferralAllowed bool
}
ReadResourceClientCapabilities allows Terraform to publish information regarding optionally supported protocol features for the ReadResource RPC, such as forward-compatible Terraform behavior changes.
ReadResourceRequest is the request Terraform sends when it wants to get the latest state for a resource.
ReadResourceResponse is the response from the provider about the current state of the requested resource.
type RenewEphemeralResourceRequest struct {
TypeName string
Private []byte
}
RenewEphemeralResourceRequest is the request Terraform sends when it wants to renew an ephemeral resource.
RenewEphemeralResourceResponse is the response from the provider after an ephemeral resource has been renewed.
type ResourceIdentityData struct {
IdentityData *DynamicValue
}
ResourceIdentityData contains the raw undecoded identity data for a resource.
ResourceIdentitySchema is the identity schema for a Resource.
ValueType returns the tftypes.Type for a ResourceIdentitySchema.
If ResourceIdentitySchema is missing, an empty Object is returned.
ResourceIdentitySchemaAttribute represents one value of data within resource identity. These are always used in resource identity comparisons.
ValueType returns the tftypes.Type for a ResourceIdentitySchemaAttribute.
If ResourceIdentitySchemaAttribute is missing, nil is returned.
type ResourceMetadata struct {
TypeName string
}
ResourceMetadata describes metadata for a managed resource in the GetMetadata RPC.
type ResourceServer interface {
ValidateResourceConfig(context.Context, *ValidateResourceConfigRequest) (*ValidateResourceConfigResponse, error)
UpgradeResourceState(context.Context, *UpgradeResourceStateRequest) (*UpgradeResourceStateResponse, error)
ReadResource(context.Context, *ReadResourceRequest) (*ReadResourceResponse, error)
PlanResourceChange(context.Context, *PlanResourceChangeRequest) (*PlanResourceChangeResponse, error)
ApplyResourceChange(context.Context, *ApplyResourceChangeRequest) (*ApplyResourceChangeResponse, error)
ImportResourceState(context.Context, *ImportResourceStateRequest) (*ImportResourceStateResponse, error)
MoveResourceState(context.Context, *MoveResourceStateRequest) (*MoveResourceStateResponse, error)
UpgradeResourceIdentity(context.Context, *UpgradeResourceIdentityRequest) (*UpgradeResourceIdentityResponse, error)
}
ResourceServer is an interface containing the methods a resource implementation needs to fill.
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.
ValueType returns the tftypes.Type for a Schema.
If Schema is missing, an empty Object is returned.
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.
ValueType returns the tftypes.Type for a SchemaAttribute.
If SchemaAttribute is missing, nil is returned.
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.
ValueType returns the tftypes.Type for a SchemaBlock.
If SchemaBlock is missing, an empty Object is returned.
SchemaNestedBlock is a nested block within another block. See SchemaBlock for more information on blocks.
ValueType returns the tftypes.Type for a SchemaNestedBlock.
If SchemaNestedBlock is missing or the Nesting mode is invalid, nil is returned.
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.
SchemaObject represents a nested-block-stype object in an Attribute.
ValueType returns the tftypes.Type for a SchemaObject.
If SchemaObject is missing or the Nesting mode is invalid, nil is returned.
type SchemaObjectNestingMode int32
SchemaObjectNestingMode indicates the nesting mode for SchemaNestedBlocks. The nesting mode determines the number of instances of the nested type allowed and the data structure used for the block in config and state values.
type ServerCapabilities struct {
GetProviderSchemaOptional bool
MoveResourceState bool
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 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 struct {
Error string
}
StopProviderResponse represents a Terraform RPC response surfacing an issues the provider encountered in terminating.
StringKind indicates a formatting or encoding scheme for a string.
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 UpgradeResourceIdentityRequest struct {
TypeName string
Version int64
RawIdentity *RawState
}
UpgradeResourceStateRequest is the request Terraform sends when it needs a provider to upgrade the state of a given resource.
UpgradeResourceStateResponse is the response from the provider containing the upgraded state for the given resource.
ValidateDataResourceConfigRequest is the request Terraform sends when it wants to validate a data source's configuration.
type ValidateDataResourceConfigResponse struct {
Diagnostics []*Diagnostic
}
ValidateDataResourceConfigResponse is the response from the provider about the validity of a data source's configuration.
type ValidateEphemeralResourceConfigRequest struct {
TypeName string
Config *DynamicValue
}
ValidateEphemeralResourceConfigRequest is the request Terraform sends when it wants to validate an ephemeral resource's configuration.
type ValidateEphemeralResourceConfigResponse struct {
Diagnostics []*Diagnostic
}
ValidateEphemeralResourceConfigResponse is the response from the provider about the validity of an ephemeral resource's configuration.
type ValidateProviderConfigRequest struct {
Config *DynamicValue
}
ValidateProviderConfigRequest represents a Terraform RPC request for the provider to modify the provider configuration in preparation for Terraform validating it.
ValidateProviderConfigResponse represents a Terraform RPC response containing a modified provider configuration that Terraform can now validate and use.
type ValidateResourceConfigClientCapabilities struct {
WriteOnlyAttributesAllowed bool
}
ValidateResourceConfigClientCapabilities allows Terraform to publish information regarding optionally supported protocol features for the ValidateResourceConfig RPC, such as forward-compatible Terraform behavior changes.
ValidateResourceConfigRequest is the request Terraform sends when it wants to validate a resource's configuration.
type ValidateResourceConfigResponse struct {
Diagnostics []*Diagnostic
}
ValidateResourceConfigResponse is the response from the provider about the validity of a resource's configuration.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4