datasource

Documentation

Overview

Package datasource contains all interfaces, request types, and response types for a data source implementation.

In Terraform, a data source is a concept which enables provider developers to offer practitioners a read-only source of information, which is saved into the Terraform state and can be referenced by other parts of a configuration. Data sources are defined by a data source type/name, such as "examplecloud_thing", a schema representing the structure and data types of configuration and state, and read logic.

The main starting point for implementations in this package is the DataSource type which represents an instance of a data source type that has its own configuration, read logic, and state. The DataSource implementations are referenced by a [provider.Provider] type DataSources method, which enables the data source for practitioner and testing usage.

Index

• type ConfigValidator
• type ConfigureRequest
• type ConfigureResponse
• type DataSource
• type DataSourceWithConfigValidators
• type DataSourceWithConfigure
• type DataSourceWithValidateConfig
• type Deferred
• type DeferredReason
  • func (d DeferredReason) String() string
• type MetadataRequest
• type MetadataResponse
• type ReadClientCapabilities
• type ReadRequest
• type ReadResponse
• 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 data source plain text
	// descriptions by external tooling.
	Description(context.Context) string

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

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

ConfigValidator describes reusable data source configuration validation functionality.

type ConfigureRequest

type ConfigureRequest struct {
	// ProviderData is the data set in the
	// [provider.ConfigureResponse.DataSourceData] field. This data is
	// provider-specifc and therefore can contain any necessary remote system
	// clients, custom provider data, or anything else pertinent to the
	// functionality of the DataSource.
	//
	// This data is only set after the ConfigureProvider RPC has been called
	// by Terraform.
	ProviderData any
}

ConfigureRequest represents a request for the provider to configure a data source, i.e., set provider-level data or clients. An instance of this request struct is supplied as an argument to the DataSource type Configure method.

type ConfigureResponse

type ConfigureResponse struct {
	// Diagnostics report errors or warnings related to configuring of the
	// Datasource. An empty slice indicates a successful operation 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 DataSource type Configure method.

type DataSource

type DataSource interface {
	// Metadata should return the full name of the data source, such as
	// examplecloud_thing.
	Metadata(context.Context, MetadataRequest, *MetadataResponse)

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

	// Read is called when the provider must read data source values in
	// order to update state. Config values should be read from the
	// ReadRequest and new state values set on the ReadResponse.
	Read(context.Context, ReadRequest, *ReadResponse)
}

DataSource represents an instance of a data source type. This is the core interface that all data sources must implement.

Data sources can optionally implement these additional concepts:

• Configure: Include provider-level data or clients.
• Validation: Schema-based or entire configuration via DataSourceWithConfigValidators or DataSourceWithValidateConfig.

type DataSourceWithConfigValidators

type DataSourceWithConfigValidators interface {
	DataSource

	// ConfigValidators returns a list of ConfigValidators. Each ConfigValidator's Validate method will be called when validating the data source.
	ConfigValidators(context.Context) []ConfigValidator
}

DataSourceWithConfigValidators is an interface type that extends DataSource to include declarative validations.

Declaring validation using this methodology simplifies implmentation 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 DataSourceWithConfigure

type DataSourceWithConfigure interface {
	DataSource

	// Configure enables provider-level data or clients to be set in the
	// provider-defined DataSource type. It is separately executed for each
	// ReadDataSource RPC.
	Configure(context.Context, ConfigureRequest, *ConfigureResponse)
}

DataSourceWithConfigure is an interface type that extends DataSource to include a method which the framework will automatically call so provider developers have the opportunity to setup any necessary provider-level data or clients in the DataSource type.

This method is intended to replace the provider.DataSourceType type NewDataSource method in a future release.

type DataSourceWithValidateConfig

type DataSourceWithValidateConfig interface {
	DataSource

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

DataSourceWithValidateConfig is an interface type that extends DataSource to include imperative validation.

Declaring validation using this methodology simplifies one-off functionality that typically applies to a single data source. 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 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

	// DeferredReasonDataSourceConfigUnknown is used to indicate that the resource configuration
	// is partially unknown and the real values need to be known before the change can be planned.
	DeferredReasonDataSourceConfigUnknown DeferredReason = 1

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

	// DeferredReasonAbsentPrereq is used to indicate that a hard dependency has not been satisfied.
	DeferredReasonAbsentPrereq DeferredReason = 3
)

func (DeferredReason) String

func (d DeferredReason) String() string

type MetadataRequest

type MetadataRequest struct {
	// ProviderTypeName is the string returned from
	// [provider.MetadataResponse.TypeName], if the Provider type implements
	// the Metadata method. This string should prefix the DataSource type name
	// with an underscore in the response.
	ProviderTypeName string
}

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

type MetadataResponse

type MetadataResponse struct {
	// TypeName should be the full data source type, including the provider
	// type prefix and an underscore. For example, examplecloud_thing.
	TypeName string
}

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

type ReadClientCapabilities

type ReadClientCapabilities 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
}

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

type ReadRequest

type ReadRequest struct {
	// Config is the configuration the user supplied for the data source.
	//
	// 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

	// ProviderMeta is metadata from the provider_meta block of the module.
	ProviderMeta tfsdk.Config

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

ReadRequest represents a request for the provider to read a data source, i.e., update values in state according to the real state of the data source. An instance of this request struct is supplied as an argument to the data source's Read function.

type ReadResponse

type ReadResponse struct {
	// State is the state of the data source following the Read operation.
	// This field should be set during the resource's Read operation.
	State tfsdk.State

	// Diagnostics report errors or warnings related to reading the data
	// source. An empty slice indicates a successful operation with no
	// warnings or errors generated.
	Diagnostics diag.Diagnostics

	// Deferred indicates that Terraform should defer reading this
	// data source until a followup apply operation.
	//
	// This field can only be set if
	// `(datasource.ReadRequest).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
}

ReadResponse represents a response to a ReadRequest. An instance of this response struct is supplied as an argument to the data source's Read function, in which the provider should set values on the ReadResponse as appropriate.

type SchemaRequest

type SchemaRequest struct{}

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

type SchemaResponse

type SchemaResponse struct {
	// Schema is the schema of the data source.
	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 DataSource type Schema method.

type ValidateConfigRequest

type ValidateConfigRequest struct {
	// Config is the configuration the user supplied for the data source.
	//
	// 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 data source. An instance of this request struct is supplied as an argument to the DataSource ValidateConfig receiver method or automatically passed through to each ConfigValidator.

type ValidateConfigResponse

type ValidateConfigResponse struct {
	// 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
}

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