providers

package
v1.2.0 Latest Latest
Warning

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

 Go to latest Published: Oct 18, 2019 License: MPL-2.0 Imports: 8 Imported by: 0

Documentation

Overview

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

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AddressedTypes 

func AddressedTypes(providerAddrs []addrs.ProviderConfig) []string

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

func AddressedTypesAbs 

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

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

func ProviderHasDataSource 

func ProviderHasDataSource(provider Interface, dataSourceName string) bool

ProviderHasDataSource is a helper that requests schema from the given provider and checks if it has a data source of the given name.

This function is more expensive than it may first appear since it must retrieve the entire schema from the underlying provider, and so it should be used sparingly and especially not in tight loops.

Since retrieving the provider may fail (e.g. if the provider is accessed over an RPC channel that has operational problems), this function will return false if the schema cannot be retrieved, under the assumption that a subsequent call to do anything with the data source would fail anyway.

func ProviderHasResource 

func ProviderHasResource(provider Interface, typeName string) bool

ProviderHasResource is a helper that requests schema from the given provider and checks if it has a resource type of the given name.

This function is more expensive than it may first appear since it must retrieve the entire schema from the underlying provider, and so it should be used sparingly and especially not in tight loops.

Since retrieving the provider may fail (e.g. if the provider is accessed over an RPC channel that has operational problems), this function will return false if the schema cannot be retrieved, under the assumption that a subsequent call to do anything with the resource type would fail anyway.

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
}

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 Terraform 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 ConfigureRequest 

type ConfigureRequest struct {
	// Terraform version is the version string from the running instance of
	// terraform. 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 ConfigureResponse 

type ConfigureResponse 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 GetSchemaResponse 

type GetSchemaResponse struct {
	// Provider is the schema for the provider itself.
	Provider 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
}

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 Terraform 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.
	GetSchema() GetSchemaResponse

	// PrepareProviderConfig allows the provider to validate the configuration
	// values, and set or override any values with defaults.
	PrepareProviderConfig(PrepareProviderConfigRequest) PrepareProviderConfigResponse

	// ValidateResourceTypeConfig allows the provider to validate the resource
	// configuration values.
	ValidateResourceTypeConfig(ValidateResourceTypeConfigRequest) ValidateResourceTypeConfigResponse

	// ValidateDataSource allows the provider to validate the data source
	// configuration values.
	ValidateDataSourceConfig(ValidateDataSourceConfigRequest) ValidateDataSourceConfigResponse

	// 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.
	Configure(ConfigureRequest) ConfigureResponse

	// 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. Terraform 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

	// 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
}

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 thee attributes that are requiring
	// resource replacement.
	RequiresReplace []cty.Path

	// PlannedPrivate is an opaque blob that is not interpreted by terraform
	// 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 Terraform 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 PrepareProviderConfigRequest 

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

type PrepareProviderConfigResponse 

type PrepareProviderConfigResponse struct {
	// PreparedConfig is the configuration as prepared by the provider.
	PreparedConfig cty.Value
	// Diagnostics contains any warnings or errors from the method call.
	Diagnostics tfdiags.Diagnostics
}

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
}

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
}

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 Resolver 

type Resolver interface {
	// Given a constraint map, return a Factory for each requested provider.
	// If some or all of the constraints cannot be satisfied, return a non-nil
	// slice of errors describing the problems.
	ResolveProviders(reqd discovery.PluginRequirements) (map[string]Factory, []error)
}

Resolver is an interface implemented by objects that are able to resolve a given set of resource provider version constraints into Factory callbacks.

func ResolverFixed 

func ResolverFixed(factories map[string]Factory) Resolver

ResolverFixed returns a Resolver that has a fixed set of provider factories provided by the caller. The returned resolver ignores version constraints entirely and just returns the given factory for each requested provider name.

This function is primarily used in tests, to provide mock providers or in-process providers under test.

type ResolverFunc 

type ResolverFunc func(reqd discovery.PluginRequirements) (map[string]Factory, []error)

ResolverFunc wraps a callback function and turns it into a Resolver implementation, for convenience in situations where a function and its associated closure are sufficient as a resolver implementation.

func (ResolverFunc) ResolveProviders 

func (f ResolverFunc) ResolveProviders(reqd discovery.PluginRequirements) (map[string]Factory, []error)

ResolveProviders implements Resolver by calling the wrapped function.

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.

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 ValidateDataSourceConfigRequest 

type ValidateDataSourceConfigRequest 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 ValidateDataSourceConfigResponse 

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

type ValidateResourceTypeConfigRequest 

type ValidateResourceTypeConfigRequest 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 ValidateResourceTypeConfigResponse 

type ValidateResourceTypeConfigResponse 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.