provider

Documentation

Overview

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

In Terraform, a provider is a concept which enables provider developers to offer practitioners data sources and managed resources. Those concepts are described in more detail in their respective datasource and resource packages.

Providers generally store any infrastructure clients or shared data that is applicable across data sources and managed resources. Providers are generally configured early in Terraform operations, such as plan and apply, before data source and managed resource logic is called. However, this early provider configuration is not guaranteed in the case there are unknown Terraform configuration values, so additional logic checks may be required throughout an implementation to handle this case. Providers may contain a schema representing the structure and data types of Terraform-based configuration.

The main starting point for implementations in this package is the Provider type which represents an instance of a provider that has its own configuration.

Index

• type ConfigValidator
• type ConfigureProviderClientCapabilities
• type ConfigureRequest
• type ConfigureResponse
• type Deferred
• type DeferredReason
  • func (d DeferredReason) String() string
• type MetaSchemaRequest
• type MetaSchemaResponse
• type MetadataRequest
• type MetadataResponse
• type Provider
• type ProviderWithConfigValidators
• type ProviderWithEphemeralResources
• type ProviderWithFunctions
• type ProviderWithMetaSchema
• type ProviderWithValidateConfig
• type SchemaRequest
• type SchemaResponse
• type ValidateConfigRequest
• type ValidateConfigResponse

Types

type ConfigValidator

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

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

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

ConfigValidator describes reusable Provider configuration validation functionality.

type ConfigureProviderClientCapabilities

type ConfigureProviderClientCapabilities struct {
	// DeferralAllowed indicates whether the Terraform client initiating
	// the request allows a deferral response.
	//
	// NOTE: This functionality is related to deferred action support, which is currently experimental and is subject
	// to change or break without warning. It is not protected by version compatibility guarantees.
	DeferralAllowed bool
}

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

type ConfigureRequest

type ConfigureRequest 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.
	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 Provider interface, for use in later
	// resource CRUD operations.
	Config tfsdk.Config

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

ConfigureRequest represents a request containing the values the user specified for the provider configuration block, along with other runtime information from Terraform or the Plugin SDK. An instance of this request struct is supplied as an argument to the provider's Configure function.

type ConfigureResponse

type ConfigureResponse struct {
	// DataSourceData is provider-defined data, clients, etc. that is passed
	// to [datasource.ConfigureRequest.ProviderData] for each DataSource type
	// that implements the Configure method.
	DataSourceData any

	// Diagnostics report errors or warnings related to configuring the
	// provider. An empty slice indicates success, with no warnings or
	// errors generated.
	Diagnostics diag.Diagnostics

	// ResourceData is provider-defined data, clients, etc. that is passed
	// to [resource.ConfigureRequest.ProviderData] for each Resource type
	// that implements the Configure method.
	ResourceData any

	// EphemeralResourceData is provider-defined data, clients, etc. that is
	// passed to [ephemeral.ConfigureRequest.ProviderData] for each
	// EphemeralResource type that implements the Configure method.
	EphemeralResourceData any

	// Deferred indicates that Terraform should automatically defer
	// all resources and data sources for this provider.
	//
	// This field can only be set if
	// `(provider.ConfigureRequest).ClientCapabilities.DeferralAllowed` is true.
	//
	// NOTE: This functionality is related to deferred action support, which is currently experimental and is subject
	// to change or break without warning. It is not protected by version compatibility guarantees.
	Deferred *Deferred
}

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

type Deferred

type Deferred struct {
	// Reason is the reason for deferring the change.
	Reason DeferredReason
}

Deferred is used to indicate to Terraform that a change needs to be deferred for a reason.

NOTE: This functionality is related to deferred action support, which is currently experimental and is subject to change or break without warning. It is not protected by version compatibility guarantees.

type DeferredReason

type DeferredReason int32

DeferredReason represents different reasons for deferring a change.

NOTE: This functionality is related to deferred action support, which is currently experimental and is subject to change or break without warning. It is not protected by version compatibility guarantees.

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

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

MAINTAINER NOTE: The deferred reason at enum value 1 in the plugin-protocol is not relevant for provider-level automatic deferred responses. provider.DeferredReason is directly mapped to the plugin-protocol which is why enum value 1 is skipped here

func (DeferredReason) String

func (d DeferredReason) String() string

type MetaSchemaRequest

type MetaSchemaRequest struct{}

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

type MetaSchemaResponse

type MetaSchemaResponse struct {
	// Schema is the meta schema of the provider.
	Schema metaschema.Schema

	// Diagnostics report errors or warnings related to validating the data
	// source configuration. An empty slice indicates success, with no warnings
	// or errors generated.
	Diagnostics diag.Diagnostics
}

MetaSchemaResponse represents a response to a MetaSchemaRequest. An instance of this response struct is supplied as an argument to the Provider type Schema method.

type MetadataRequest

type MetadataRequest struct{}

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

type MetadataResponse

type MetadataResponse struct {
	// TypeName should be the provider type. For example, examplecloud, if
	// the intended resource or data source types are examplecloud_thing, etc.
	TypeName string

	// Version should be the provider version, such as 1.2.3.
	//
	// This is not connected to any framework functionality currently, but may
	// be in the future.
	Version string
}

MetadataResponse represents a response to a MetadataRequest. An instance of this response struct is supplied as an argument to the Provider type Metadata method.

type Provider

type Provider interface {
	// Metadata should return the metadata for the provider, such as
	// a type name and version data.
	//
	// Implementing the MetadataResponse.TypeName will populate the
	// datasource.MetadataRequest.ProviderTypeName and
	// resource.MetadataRequest.ProviderTypeName fields automatically.
	Metadata(context.Context, MetadataRequest, *MetadataResponse)

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

	// Configure is called at the beginning of the provider lifecycle, when
	// Terraform sends to the provider the values the user specified in the
	// provider configuration block. These are supplied in the
	// ConfigureProviderRequest argument.
	// Values from provider configuration are often used to initialise an
	// API client, which should be stored on the struct implementing the
	// Provider interface.
	Configure(context.Context, ConfigureRequest, *ConfigureResponse)

	// DataSources returns a slice of functions to instantiate each DataSource
	// implementation.
	//
	// The data source type name is determined by the DataSource implementing
	// the Metadata method. All data sources must have unique names.
	DataSources(context.Context) []func() datasource.DataSource

	// Resources returns a slice of functions to instantiate each Resource
	// implementation.
	//
	// The resource type name is determined by the Resource implementing
	// the Metadata method. All resources must have unique names.
	Resources(context.Context) []func() resource.Resource
}

Provider is the core interface that all Terraform providers must implement.

Providers can optionally implement these additional concepts:

• Validation: Schema-based or entire configuration via ProviderWithConfigValidators or ProviderWithValidateConfig.
• Functions: ProviderWithFunctions
• Meta Schema: ProviderWithMetaSchema

type ProviderWithConfigValidators

type ProviderWithConfigValidators interface {
	Provider

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

ProviderWithConfigValidators is an interface type that extends Provider to include declarative validations.

Declaring validation using this methodology simplifies implementation of reusable functionality. These also include descriptions, which can be used for automating documentation.

Validation will include ConfigValidators and ValidateConfig, if both are implemented, in addition to any Attribute or Type validation.

type ProviderWithEphemeralResources

type ProviderWithEphemeralResources interface {
	Provider

	// EphemeralResources returns a slice of functions to instantiate each EphemeralResource
	// implementation.
	//
	// The ephemeral resource type name is determined by the EphemeralResource implementing
	// the Metadata method. All ephemeral resources must have unique names.
	EphemeralResources(context.Context) []func() ephemeral.EphemeralResource
}

ProviderWithEphemeralResources is an interface type that extends Provider to include ephemeral resources for usage in practitioner configurations.

Ephemeral resources are supported in Terraform version 1.10 and later.

NOTE: Ephemeral resource support is experimental and exposed without compatibility promises until these notices are removed.

type ProviderWithFunctions

type ProviderWithFunctions interface {
	Provider

	// Functions returns a slice of functions to instantiate each Function
	// implementation.
	//
	// The function name is determined by the Function implementing its Metadata
	// method. All functions must have unique names.
	Functions(context.Context) []func() function.Function
}

ProviderWithFunctions is an interface type that extends Provider to include provider defined functions for usage in practitioner configurations.

Provider-defined functions are supported in Terraform version 1.8 and later.

type ProviderWithMetaSchema

type ProviderWithMetaSchema interface {
	Provider

	// MetaSchema should return the meta schema for this provider.
	//
	// This functionality is currently experimental and subject to change or
	// break without warning. It is not protected by version compatibility
	// guarantees.
	MetaSchema(context.Context, MetaSchemaRequest, *MetaSchemaResponse)
}

ProviderWithMetaSchema is a provider with a provider meta schema, which is configured by practitioners via the provider_meta configuration block and the configuration data is included with certain data source and resource operations. The intended use case is to enable Terraform module authors within the same organization of the provider to track module usage in requests. Other use cases are explicitly not supported. All provider instances (aliases) receive the same data.

This functionality is currently experimental and subject to change or break without warning. It is not protected by version compatibility guarantees.

type ProviderWithValidateConfig

type ProviderWithValidateConfig interface {
	Provider

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

ProviderWithValidateConfig is an interface type that extends Provider to include imperative validation.

Declaring validation using this methodology simplifies one-off functionality that typically applies to a single provider. Any documentation of this functionality must be manually added into schema descriptions.

Validation will include ConfigValidators and ValidateConfig, if both are implemented, in addition to any Attribute or Type validation.

type SchemaRequest

type SchemaRequest struct{}

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

type SchemaResponse

type SchemaResponse struct {
	// Schema is the schema of the provider.
	Schema schema.Schema

	// Diagnostics report errors or warnings related to validating the data
	// source configuration. An empty slice indicates success, with no warnings
	// or errors generated.
	Diagnostics diag.Diagnostics
}

SchemaResponse represents a response to a SchemaRequest. An instance of this response struct is supplied as an argument to the Provider type Schema method.

type ValidateConfigRequest

type ValidateConfigRequest struct {
	// Config is the configuration the user supplied for the provider.
	//
	// This configuration may contain unknown values if a user uses
	// interpolation or other functionality that would prevent Terraform
	// from knowing the value at request time.
	Config tfsdk.Config
}

ValidateConfigRequest represents a request to validate the configuration of a provider. An instance of this request struct is supplied as an argument to the Provider ValidateConfig receiver method or automatically passed through to each ConfigValidator.

type ValidateConfigResponse

type ValidateConfigResponse struct {
	// Diagnostics report errors or warnings related to validating the provider
	// configuration. An empty slice indicates success, with no warnings or
	// errors generated.
	Diagnostics diag.Diagnostics
}

ValidateConfigResponse represents a response to a ValidateConfigRequest. An instance of this response struct is supplied as an argument to the Provider ValidateConfig receiver method or automatically passed through to each ConfigValidator.