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 "example_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. A DataSource is instantiated from a provider.DataSourceType type NewDataSource method, which also defines the data source schema. The provider.DataSourceType types are referenced by a provider.Provider type GetDataSources method, which enables the data source for practitioner and testing usage.

Index

• type ConfigValidator
• type DataSource
• type DataSourceWithConfigValidators
• type DataSourceWithValidateConfig
• type ReadRequest
• type ReadResponse
• 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 DataSource

type DataSource interface {
	// 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:

• Validation: Schema-based via tfsdk.Attribute 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 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 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
}

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
}

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