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 DataSourceType
• type Provider
• type ProviderWithConfigValidators
• type ProviderWithMetaSchema
• type ProviderWithValidateConfig
• type ResourceType
• 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 {
	// Diagnostics report errors or warnings related to configuring the
	// provider. An empty slice indicates success, with no warnings or
	// errors generated.
	Diagnostics diag.Diagnostics
}

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 DataSourceType

type DataSourceType interface {
	// GetSchema returns the schema for this data source.
	GetSchema(context.Context) (tfsdk.Schema, diag.Diagnostics)

	// NewDataSource instantiates a new DataSource of this DataSourceType.
	NewDataSource(context.Context, Provider) (datasource.DataSource, diag.Diagnostics)
}

A DataSourceType is a type of data source. For each type of data source this provider supports, it should define a type implementing DataSourceType and return an instance of it in the map returned by Provider.GetDataSources.

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)

	// GetResources returns a mapping of resource names to type
	// implementations.
	//
	// Conventionally, resource names should each include a prefix of the
	// provider name and an underscore. For example, a provider named
	// "examplecloud" with resources "thing" and "widget" should use
	// "examplecloud_thing" and "examplecloud_widget" as resource names.
	GetResources(context.Context) (map[string]ResourceType, diag.Diagnostics)

	// GetDataSources returns a mapping of data source name to types
	// implementations.
	//
	// Conventionally, data source names should each include a prefix of the
	// provider name and an underscore. For example, a provider named
	// "examplecloud" with data sources "thing" and "widget" should use
	// "examplecloud_thing" and "examplecloud_widget" as data source names.
	GetDataSources(context.Context) (map[string]DataSourceType, diag.Diagnostics)
}

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

Providers can optionally implement these additional concepts:

• 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 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 ResourceType

type ResourceType interface {
	// GetSchema returns the schema for this resource.
	GetSchema(context.Context) (tfsdk.Schema, diag.Diagnostics)

	// NewResource instantiates a new Resource of this ResourceType.
	NewResource(context.Context, Provider) (resource.Resource, diag.Diagnostics)
}

A ResourceType is a type of resource. For each type of resource this provider supports, it should define a type implementing ResourceType and return an instance of it in the map returned by Provider.GetResources.

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.