• Overview
    • Enforce Policy as Code
    • Infrastructure as Code
    • Inject Secrets into Terraform
    • Integrate with Existing Workflows
    • Manage Kubernetes
    • Manage Virtual Machine Images
    • Multi-Cloud Deployment
    • Network Infrastructure Automation
    • Terraform CLI
    • Terraform Cloud
    • Terraform Enterprise
  • Registry
  • Tutorials
    • About the Docs
    • Intro to Terraform
    • Configuration Language
    • Terraform CLI
    • Terraform Cloud
    • Terraform Enterprise
    • Provider Use
    • Plugin Development
    • Registry Publishing
    • Integration Program
    • Terraform Tools
    • CDK for Terraform
    • Glossary
  • Community
GitHubTerraform Cloud
Download

    Framework

  • Overview
  • Tutorial: Implement Create and Read
  • Provider Servers
  • Providers
    • Overview
    • Import
    • Plan Modification
    • State Upgrade
  • Data Sources
  • Schemas
  • Attribute Types
  • Accessing State, Config, and Plan
  • Writing State
  • Returning Errors and Warnings
  • Validation
  • Acceptance Tests
  • Debugging
  • Other Plugin Docs

  • Plugin Development
  • SDKv2
  • Logging
  • Combining and Translating
Type '/' to Search

»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 tfsdk.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 tfsdk.DataSource implementation that expects to operate on data with the structure defined in GetSchema.

The NewDataSource method is passed a tfsdk.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 tfsdk.Provider) (tfsdk.DataSource, diag.Diagnostics) {
    return computeImageDataSource{
        client: p.(*provider).client,
    }, nil
}
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 tfsdk.Provider) (tfsdk.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 tfsdk.ReadDataSourceRequest. 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]tfsdk.DataSourceType,
    diag.Diagnostics) {
    return map[string]tfsdk.DataSourceType{
        "example_compute_image": computeImageDataSourceType{},
    }, nil
}
func (p *provider) GetDataSources(_ context.Context) (map[string]tfsdk.DataSourceType,
    diag.Diagnostics) {
    return map[string]tfsdk.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.
github logoEdit this page
  • Overview
  • Docs
  • Extend
  • Privacy
  • Security
  • Press Kit
  • Consent Manager