Data Sources

Data sources are an abstraction that allow Terraform to reference external data. Unlike with resources, Terraform does not manage data sources and makes no attempt to modify the API.

Providers have data sources that tell Terraform how to request external data and how to convert the response into a format that practitioners can interpolate. To create data sources for your provider, you need to define both the data source archetype and actions on specific data source instances.

Define Data Source Archetype

Implement the provider.DataSourceType interface for every type of data source you want to support, such as disk images, compute instance groups, access policies, etc. It allows you to describe the data source archetype, which is the functionality related to all instances of that data source type. DataSourceType has the following methods.

GetSchema

GetSchema returns a schema describing what fields are available in the data source's configuration and state.

NewDataSource

NewDataSource returns a new instance of that data source type. It needs to instantiate a new datasource.DataSource implementation that expects to operate on data with the structure defined in GetSchema.

The NewDataSource method is passed a provider.Provider implementation. This is the provider type after its Configure method was called. The NewDataSource method can type-assert on this and inject it into the DataSource, allowing the DataSource to have strongly-typed access to the configured API client or other provider configuration data.

Example

type computeImageDataSourceType struct{}

func (c computeImageDataSourceType) GetSchema(_ context.Context) (tfsdk.Schema,
    diag.Diagnostics) {
    return tfsdk.Schema{
        Attributes: map[string]tfsdk.Attribute{
            "name": {
                Type: types.StringType,
                Required: true,
            },
        },
    }, nil
}

func (c computeImageDataSourceType) NewDataSource(_ context.Context,
    p provider.Provider) (datasource.DataSource, diag.Diagnostics) {
    return computeImageDataSource{
        client: p.(*provider).client,
    }, nil
}

Define Data Source

Data sources are scoped to a single instance of the data source type. They modify that specific data source in the state, given that data source's config values. They do this through their Read method.

Read

Read updates Terraform's state to reflect the API data described in the configuration. There is no plan or state to work with in Read. Data sources should retrieve the data they need from the configuration included in the datasource.ReadRequest. They can then use the configured API client injected into the data source by the data source type's NewDataSource method, and write the results to the state.

Terraform does not manage data sources, so there is no plan to follow and the provider can set any value in state. "Drift" describes instances when the API's state has deviated from the source of truth defined in the configuration file. Drift doesn't apply to data sources because Terraform is not the source of truth for these values.

Add Data Source to Provider

To make new data sources available to practitioners, add them to the GetDataSources method on the provider. The key must be the name of the data source, including the provider prefix, and the value must be an instance of the data source type.

Example

func (p *provider) GetDataSources(_ context.Context) (map[string]provider.DataSourceType,
    diag.Diagnostics) {
    return map[string]provider.DataSourceType{
        "example_compute_image": computeImageDataSourceType{},
    }, nil
}

Further Data Source Capabilities

• Validation helps practitioners understand the required syntax, types, and acceptable values for your data source.