providers

package
v1.7.1 Latest Latest
Warning

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

 Go to latest Published: May 8, 2024 License: MPL-2.0 Imports: 7 Imported by: 0

Documentation

Overview

Package providers contains the interface and primary types required to implement a OpenTofu resource provider.

Index

Constants

View Source 
const TextFormattingMarkdown = TextFormatting("Markdown")
View Source 
const TextFormattingPlain = TextFormatting("Plain")

Variables

View Source 
var SchemaCache = &schemaCache{
	m: make(map[addrs.Provider]ProviderSchema),
}

SchemaCache is a global cache of Schemas. This will be accessed by both core and the provider clients to ensure that large schemas are stored in a single location.

Functions

func AddressedTypesAbs 

func AddressedTypesAbs(providerAddrs []addrs.AbsProviderConfig) []addrs.Provider

AddressedTypesAbs is a helper that extracts all of the distinct provider types from the given list of absolute provider configuration addresses.

func NewMockSchemaCache 

func NewMockSchemaCache() *schemaCache

Types

type ApplyResourceChangeRequest 

type ApplyResourceChangeRequest struct {
	// TypeName is the name of the resource type being applied.
	TypeName string

	// PriorState is the current state of resource.
	PriorState cty.Value

	// Planned state is the state returned from PlanResourceChange, and should
	// represent the new state, minus any remaining computed attributes.
	PlannedState cty.Value

	// Config is the resource configuration, before being merged with the
	// PriorState. Any value not explicitly set in the configuration will be
	// null. Config is supplied for reference, but Provider implementations
	// should prefer the PlannedState in most circumstances.
	Config cty.Value

	// PlannedPrivate is the same value as returned by PlanResourceChange.
	PlannedPrivate []byte

	// ProviderMeta is the configuration for the provider_meta block for the
	// module and provider this resource belongs to. Its use is defined by
	// each provider, and it should not be used without coordination with
	// HashiCorp. It is considered experimental and subject to change.
	ProviderMeta cty.Value
}

type ApplyResourceChangeResponse 

type ApplyResourceChangeResponse struct {
	// NewState is the new complete state after applying the planned change.
	// In the event of an error, NewState should represent the most recent
	// known state of the resource, if it exists.
	NewState cty.Value

	// Private is an opaque blob that will be stored in state along with the
	// resource. It is intended only for interpretation by the provider itself.
	Private []byte

	// Diagnostics contains any warnings or errors from the method call.
	Diagnostics tfdiags.Diagnostics

	// LegacyTypeSystem is set only if the provider is using the legacy SDK
	// whose type system cannot be precisely mapped into the OpenTofu type
	// system. We use this to bypass certain consistency checks that would
	// otherwise fail due to this imprecise mapping. No other provider or SDK
	// implementation is permitted to set this.
	LegacyTypeSystem bool
}

type CallFunctionArgumentError added in v1.7.0 

type CallFunctionArgumentError struct {
	Text             string
	FunctionArgument int
}

func (*CallFunctionArgumentError) Error added in v1.7.0 

func (err *CallFunctionArgumentError) Error() string

type CallFunctionRequest added in v1.7.0 

type CallFunctionRequest struct {
	Name      string
	Arguments []cty.Value
}

type CallFunctionResponse added in v1.7.0 

type CallFunctionResponse struct {
	Result cty.Value
	Error  error
}

type ConfigureProviderRequest 

type ConfigureProviderRequest struct {
	// OpenTofu version is the version string from the running instance of
	// tofu. Providers can use TerraformVersion to verify compatibility,
	// and to store for informational purposes.
	TerraformVersion string

	// Config is the complete configuration value for the provider.
	Config cty.Value
}

type ConfigureProviderResponse 

type ConfigureProviderResponse struct {
	// Diagnostics contains any warnings or errors from the method call.
	Diagnostics tfdiags.Diagnostics
}

type Factory 

type Factory func() (Interface, error)

Factory is a function type that creates a new instance of a resource provider, or returns an error if that is impossible.

func FactoryFixed 

func FactoryFixed(p Interface) Factory

FactoryFixed is a helper that creates a Factory that just returns some given single provider.

Unlike usual factories, the exact same instance is returned for each call to the factory and so this must be used in only specialized situations where the caller can take care to either not mutate the given provider at all or to mutate it in ways that will not cause unexpected behavior for others holding the same reference.

type FunctionParameterSpec added in v1.7.0 

type FunctionParameterSpec struct {
	// Human-readable display name for the parameter
	Name string
	// Type constraint for the parameter
	Type cty.Type
	// Null values alowed for the parameter
	AllowNullValue bool
	// Unknown Values allowed for the parameter
	// Implies the Return type of the function is also Unknown
	AllowUnknownValues bool
	// Human-readable documentation for the parameter
	Description string
	// Formatting type of the Description field
	DescriptionFormat TextFormatting
}

type FunctionSpec added in v1.7.0 

type FunctionSpec struct {
	// List of parameters required to call the function
	Parameters []FunctionParameterSpec
	// Optional Spec for variadic parameters
	VariadicParameter *FunctionParameterSpec
	// Type which the function will return
	Return cty.Type
	// Human-readable shortened documentation for the function
	Summary string
	// Human-readable documentation for the function
	Description string
	// Formatting type of the Description field
	DescriptionFormat TextFormatting
	// Human-readable message present if the function is deprecated
	DeprecationMessage string
}

type GetFunctionsResponse added in v1.7.0 

type GetFunctionsResponse struct {
	Functions map[string]FunctionSpec

	Diagnostics tfdiags.Diagnostics
}

type GetProviderSchemaResponse 

type GetProviderSchemaResponse struct {
	// Provider is the schema for the provider itself.
	Provider Schema

	// ProviderMeta is the schema for the provider's meta info in a module
	ProviderMeta Schema

	// ResourceTypes map the resource type name to that type's schema.
	ResourceTypes map[string]Schema

	// DataSources maps the data source name to that data source's schema.
	DataSources map[string]Schema

	// Diagnostics contains any warnings or errors from the method call.
	Diagnostics tfdiags.Diagnostics

	// ServerCapabilities lists optional features supported by the provider.
	ServerCapabilities ServerCapabilities

	// Functions lists all functions supported by this provider.
	Functions map[string]FunctionSpec
}

GetProviderSchemaResponse is the return type for GetProviderSchema, and should only be used when handling a value for that method. The handling of of schemas in any other context should always use ProviderSchema, so that the in-memory representation can be more easily changed separately from the RCP protocol.

type ImportResourceStateRequest 

type ImportResourceStateRequest struct {
	// TypeName is the name of the resource type to be imported.
	TypeName string

	// ID is a string with which the provider can identify the resource to be
	// imported.
	ID string
}

type ImportResourceStateResponse 

type ImportResourceStateResponse struct {
	// ImportedResources contains one or more state values related to the
	// imported resource. It is not required that these be complete, only that
	// there is enough identifying information for the provider to successfully
	// update the states in ReadResource.
	ImportedResources []ImportedResource

	// Diagnostics contains any warnings or errors from the method call.
	Diagnostics tfdiags.Diagnostics
}

type ImportedResource 

type ImportedResource struct {
	// TypeName is the name of the resource type associated with the
	// returned state. It's possible for providers to import multiple related
	// types with a single import request.
	TypeName string

	// State is the state of the remote object being imported. This may not be
	// complete, but must contain enough information to uniquely identify the
	// resource.
	State cty.Value

	// Private is an opaque blob that will be stored in state along with the
	// resource. It is intended only for interpretation by the provider itself.
	Private []byte
}

ImportedResource represents an object being imported into OpenTofu with the help of a provider. An ImportedObject is a RemoteObject that has been read by the provider's import handler but hasn't yet been committed to state.

func (ImportedResource) AsInstanceObject 

func (ir ImportedResource) AsInstanceObject() *states.ResourceInstanceObject

AsInstanceObject converts the receiving ImportedObject into a ResourceInstanceObject that has status ObjectReady.

The returned object does not know its own resource type, so the caller must retain the ResourceType value from the source object if this information is needed.

The returned object also has no dependency addresses, but the caller may freely modify the direct fields of the returned object without affecting the receiver.

type Interface 

type Interface interface {

	// GetSchema returns the complete schema for the provider.
	GetProviderSchema() GetProviderSchemaResponse

	// ValidateProviderConfig allows the provider to validate the configuration.
	// The ValidateProviderConfigResponse.PreparedConfig field is unused. The
	// final configuration is not stored in the state, and any modifications
	// that need to be made must be made during the Configure method call.
	ValidateProviderConfig(ValidateProviderConfigRequest) ValidateProviderConfigResponse

	// ValidateResourceConfig allows the provider to validate the resource
	// configuration values.
	ValidateResourceConfig(ValidateResourceConfigRequest) ValidateResourceConfigResponse

	// ValidateDataResourceConfig allows the provider to validate the data source
	// configuration values.
	ValidateDataResourceConfig(ValidateDataResourceConfigRequest) ValidateDataResourceConfigResponse

	// UpgradeResourceState is called when the state loader encounters an
	// instance state whose schema version is less than the one reported by the
	// currently-used version of the corresponding provider, and the upgraded
	// result is used for any further processing.
	UpgradeResourceState(UpgradeResourceStateRequest) UpgradeResourceStateResponse

	// Configure configures and initialized the provider.
	ConfigureProvider(ConfigureProviderRequest) ConfigureProviderResponse

	// Stop is called when the provider should halt any in-flight actions.
	//
	// Stop should not block waiting for in-flight actions to complete. It
	// should take any action it wants and return immediately acknowledging it
	// has received the stop request. OpenTofu will not make any further API
	// calls to the provider after Stop is called.
	//
	// The error returned, if non-nil, is assumed to mean that signaling the
	// stop somehow failed and that the user should expect potentially waiting
	// a longer period of time.
	Stop() error

	// ReadResource refreshes a resource and returns its current state.
	ReadResource(ReadResourceRequest) ReadResourceResponse

	// PlanResourceChange takes the current state and proposed state of a
	// resource, and returns the planned final state.
	PlanResourceChange(PlanResourceChangeRequest) PlanResourceChangeResponse

	// ApplyResourceChange takes the planned state for a resource, which may
	// yet contain unknown computed values, and applies the changes returning
	// the final state.
	ApplyResourceChange(ApplyResourceChangeRequest) ApplyResourceChangeResponse

	// ImportResourceState requests that the given resource be imported.
	ImportResourceState(ImportResourceStateRequest) ImportResourceStateResponse

	// ReadDataSource returns the data source's current state.
	ReadDataSource(ReadDataSourceRequest) ReadDataSourceResponse

	// GetFunctions returns a full list of functions defined in this provider.  It should be a super
	// set of the functions returned in GetProviderSchema()
	GetFunctions() GetFunctionsResponse

	// CallFunction requests that the given function is called and response returned.
	CallFunction(CallFunctionRequest) CallFunctionResponse

	// Close shuts down the plugin process if applicable.
	Close() error
}

Interface represents the set of methods required for a complete resource provider plugin.

type PlanResourceChangeRequest 

type PlanResourceChangeRequest struct {
	// TypeName is the name of the resource type to plan.
	TypeName string

	// PriorState is the previously saved state value for this resource.
	PriorState cty.Value

	// ProposedNewState is the expected state after the new configuration is
	// applied. This is created by directly applying the configuration to the
	// PriorState. The provider is then responsible for applying any further
	// changes required to create the proposed final state.
	ProposedNewState cty.Value

	// Config is the resource configuration, before being merged with the
	// PriorState. Any value not explicitly set in the configuration will be
	// null. Config is supplied for reference, but Provider implementations
	// should prefer the ProposedNewState in most circumstances.
	Config cty.Value

	// PriorPrivate is the previously saved private data returned from the
	// provider during the last apply.
	PriorPrivate []byte

	// ProviderMeta is the configuration for the provider_meta block for the
	// module and provider this resource belongs to. Its use is defined by
	// each provider, and it should not be used without coordination with
	// HashiCorp. It is considered experimental and subject to change.
	ProviderMeta cty.Value
}

type PlanResourceChangeResponse 

type PlanResourceChangeResponse struct {
	// PlannedState is the expected state of the resource once the current
	// configuration is applied.
	PlannedState cty.Value

	// RequiresReplace is the list of the attributes that are requiring
	// resource replacement.
	RequiresReplace []cty.Path

	// PlannedPrivate is an opaque blob that is not interpreted by tofu
	// core. This will be saved and relayed back to the provider during
	// ApplyResourceChange.
	PlannedPrivate []byte

	// Diagnostics contains any warnings or errors from the method call.
	Diagnostics tfdiags.Diagnostics

	// LegacyTypeSystem is set only if the provider is using the legacy SDK
	// whose type system cannot be precisely mapped into the OpenTofu type
	// system. We use this to bypass certain consistency checks that would
	// otherwise fail due to this imprecise mapping. No other provider or SDK
	// implementation is permitted to set this.
	LegacyTypeSystem bool
}

type ProviderSchema 

type ProviderSchema = GetProviderSchemaResponse

ProviderSchema is an overall container for all of the schemas for all configurable objects defined within a particular provider. All storage of provider schemas should use this type.

func (ProviderSchema) SchemaForResourceAddr 

func (ss ProviderSchema) SchemaForResourceAddr(addr addrs.Resource) (schema *configschema.Block, version uint64)

SchemaForResourceAddr attempts to find a schema for the mode and type from the given resource address. Returns nil if no such schema is available.

func (ProviderSchema) SchemaForResourceType 

func (ss ProviderSchema) SchemaForResourceType(mode addrs.ResourceMode, typeName string) (schema *configschema.Block, version uint64)

SchemaForResourceType attempts to find a schema for the given mode and type. Returns nil if no such schema is available.

type ReadDataSourceRequest 

type ReadDataSourceRequest struct {
	// TypeName is the name of the data source type to Read.
	TypeName string

	// Config is the complete configuration for the requested data source.
	Config cty.Value

	// ProviderMeta is the configuration for the provider_meta block for the
	// module and provider this resource belongs to. Its use is defined by
	// each provider, and it should not be used without coordination with
	// HashiCorp. It is considered experimental and subject to change.
	ProviderMeta cty.Value
}

type ReadDataSourceResponse 

type ReadDataSourceResponse struct {
	// State is the current state of the requested data source.
	State cty.Value

	// Diagnostics contains any warnings or errors from the method call.
	Diagnostics tfdiags.Diagnostics
}

type ReadResourceRequest 

type ReadResourceRequest struct {
	// TypeName is the name of the resource type being read.
	TypeName string

	// PriorState contains the previously saved state value for this resource.
	PriorState cty.Value

	// Private is an opaque blob that will be stored in state along with the
	// resource. It is intended only for interpretation by the provider itself.
	Private []byte

	// ProviderMeta is the configuration for the provider_meta block for the
	// module and provider this resource belongs to. Its use is defined by
	// each provider, and it should not be used without coordination with
	// HashiCorp. It is considered experimental and subject to change.
	ProviderMeta cty.Value
}

type ReadResourceResponse 

type ReadResourceResponse struct {
	// NewState contains the current state of the resource.
	NewState cty.Value

	// Diagnostics contains any warnings or errors from the method call.
	Diagnostics tfdiags.Diagnostics

	// Private is an opaque blob that will be stored in state along with the
	// resource. It is intended only for interpretation by the provider itself.
	Private []byte
}

type Schema 

type Schema struct {
	Version int64
	Block   *configschema.Block
}

Schema pairs a provider or resource schema with that schema's version. This is used to be able to upgrade the schema in UpgradeResourceState.

This describes the schema for a single object within a provider. Type "Schemas" (plural) instead represents the overall collection of schemas for everything within a particular provider.

type ServerCapabilities 

type ServerCapabilities struct {
	// PlanDestroy signals that this provider expects to receive a
	// PlanResourceChange call for resources that are to be destroyed.
	PlanDestroy bool

	// The GetProviderSchemaOptional capability indicates that this
	// provider does not require calling GetProviderSchema to operate
	// normally, and the caller can used a cached copy of the provider's
	// schema.
	// In other words, the providers for which GetProviderSchemaOptional is false
	// require their schema to be read after EVERY instantiation to function normally.
	GetProviderSchemaOptional bool
}

ServerCapabilities allows providers to communicate extra information regarding supported protocol features. This is used to indicate availability of certain forward-compatible changes which may be optional in a major protocol version, but cannot be tested for directly.

type TextFormatting added in v1.7.0 

type TextFormatting string

type UpgradeResourceStateRequest 

type UpgradeResourceStateRequest struct {
	// TypeName is the name of the resource type being upgraded
	TypeName string

	// Version is version of the schema that created the current state.
	Version int64

	// RawStateJSON and RawStateFlatmap contiain the state that needs to be
	// upgraded to match the current schema version. Because the schema is
	// unknown, this contains only the raw data as stored in the state.
	// RawStateJSON is the current json state encoding.
	// RawStateFlatmap is the legacy flatmap encoding.
	// Only on of these fields may be set for the upgrade request.
	RawStateJSON    []byte
	RawStateFlatmap map[string]string
}

type UpgradeResourceStateResponse 

type UpgradeResourceStateResponse struct {
	// UpgradedState is the newly upgraded resource state.
	UpgradedState cty.Value

	// Diagnostics contains any warnings or errors from the method call.
	Diagnostics tfdiags.Diagnostics
}

type ValidateDataResourceConfigRequest 

type ValidateDataResourceConfigRequest struct {
	// TypeName is the name of the data source type to validate.
	TypeName string

	// Config is the configuration value to validate, which may contain unknown
	// values.
	Config cty.Value
}

type ValidateDataResourceConfigResponse 

type ValidateDataResourceConfigResponse struct {
	// Diagnostics contains any warnings or errors from the method call.
	Diagnostics tfdiags.Diagnostics
}

type ValidateProviderConfigRequest 

type ValidateProviderConfigRequest struct {
	// Config is the raw configuration value for the provider.
	Config cty.Value
}

type ValidateProviderConfigResponse 

type ValidateProviderConfigResponse struct {
	// PreparedConfig is unused and will be removed with support for plugin protocol v5.
	PreparedConfig cty.Value
	// Diagnostics contains any warnings or errors from the method call.
	Diagnostics tfdiags.Diagnostics
}

type ValidateResourceConfigRequest 

type ValidateResourceConfigRequest struct {
	// TypeName is the name of the resource type to validate.
	TypeName string

	// Config is the configuration value to validate, which may contain unknown
	// values.
	Config cty.Value
}

type ValidateResourceConfigResponse 

type ValidateResourceConfigResponse struct {
	// Diagnostics contains any warnings or errors from the method call.
	Diagnostics tfdiags.Diagnostics
}

Source Files

View all Source files

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.