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 ConfigureRequest
• type ConfigureResponse
• type MetadataRequest
• type MetadataResponse
• type Provider
• type ProviderWithConfigValidators
• type ProviderWithMetaSchema
• type ProviderWithMetadata
• type ProviderWithValidateConfig
• 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 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
}

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
}

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 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 {
	// GetSchema returns the schema for this provider's configuration. If
	// this provider has no configuration, return an empty schema.Schema.
	GetSchema(context.Context) (tfsdk.Schema, diag.Diagnostics)

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

• Resources: ProviderWithResources or (deprecated) ProviderWithGetResources.
• Data Sources: ProviderWithDataSources or (deprecated) ProviderWithGetDataSources.
• Validation: Schema-based via tfsdk.Attribute or entire configuration via ProviderWithConfigValidators or ProviderWithValidateConfig.
• 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 ProviderWithMetaSchema

type ProviderWithMetaSchema interface {
	Provider

	// GetMetaSchema returns the provider meta schema.
	GetMetaSchema(context.Context) (tfsdk.Schema, diag.Diagnostics)
}

ProviderWithMetaSchema is a provider with a provider meta schema. This functionality is currently experimental and subject to change or break without warning; it should only be used by providers that are collaborating on its use with the Terraform team.

type ProviderWithMetadata

type ProviderWithMetadata interface {
	Provider

	// Metadata should return the metadata for the provider, such as
	// a type name and version data.
	Metadata(context.Context, MetadataRequest, *MetadataResponse)
}

ProviderWithMetadata is an interface type that extends Provider to return its type name, such as examplecloud, and other metadata, such as version.

Implementing this method will populate the datasource.MetadataRequest.ProviderTypeName and resource.MetadataRequest.ProviderTypeName fields automatically.

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