The terraform_remote_state Data Source

The terraform_remote_state data source uses the latest state snapshot from a specified state backend to retrieve the root module output values from some other Terraform configuration.

You can use the terraform_remote_state data source without requiring or configuring a provider. It is always available through a built-in provider with the source address terraform.io/builtin/terraform. That provider does not include any other resources or data sources.

Alternative Ways to Share Data Between Configurations

Sharing data with root module outputs is convenient, but it has drawbacks. Although terraform_remote_state only exposes output values, its user must have access to the entire state snapshot, which often includes some sensitive information.

When possible, we recommend explicitly publishing data for external consumption to a separate location instead of accessing it via remote state. This lets you apply different access controls for shared information and state snapshots.

To share data explicitly between configurations, you can use pairs of managed resource types and data sources in various providers, including (but not limited to) the following:

System Publish with... Read with...
Alibaba Cloud DNS
(for IP addresses and hostnames)
alicloud_alidns_record resource type Normal DNS lookups, or the dns provider
Amazon Route53
(for IP addresses and hostnames)
aws_route53_record resource type Normal DNS lookups, or the dns provider
Amazon S3 aws_s3_object resource type aws_s3_object data source
Amazon SSM Parameter Store aws_ssm_parameter resource type aws_ssm_parameter data source
Azure Automation azurerm_automation_variable_string resource type azurerm_automation_variable_string data source
Azure DNS
(for IP addresses and hostnames)
azurerm_dns_a_record resource type, etc Normal DNS lookups, or the dns provider
Google Cloud DNS
(for IP addresses and hostnames)
google_dns_record_set resource type Normal DNS lookups, or the dns provider
Google Cloud Storage google_storage_bucket_object resource type google_storage_bucket_object data source and http data source
HashiCorp Consul consul_key_prefix resource type consul_key_prefix data source
HashiCorp HCP Terraform Normal outputs terraform block tfe_outputs data source
Kubernetes kubernetes_config_map resource type kubernetes_config_map data source
OCI Object Storage oci_objectstorage_bucket resource type oci_objectstorage_bucket data source

A key advantage of using a separate explicit configuration store instead of terraform_remote_state is that the data can potentially also be read by systems other than Terraform, such as configuration management or scheduler systems within your compute instances. For that reason, we recommend selecting a configuration store that your other infrastructure could potentially make use of. For example:

Some of the data stores listed above are specifically designed for storing small configuration values, while others are generic blob storage systems. For those generic systems, you can use the jsonencode function and the jsondecode function respectively to store and retrieve structured data.

You can encapsulate the implementation details of retrieving your published configuration data by writing a data-only module containing the necessary data source configuration and any necessary post-processing such as JSON decoding. You can then change that module later if you switch to a different strategy for sharing data between multiple Terraform configurations.

Example Usage (remote Backend)

data "terraform_remote_state" "vpc" {
  backend = "remote"

  config = {
    organization = "hashicorp"
    workspaces = {
      name = "vpc-prod"
    }
  }
}

# Terraform >= 0.12
resource "aws_instance" "foo" {
  # ...
  subnet_id = data.terraform_remote_state.vpc.outputs.subnet_id
}

# Terraform <= 0.11
resource "aws_instance" "foo" {
  # ...
  subnet_id = "${data.terraform_remote_state.vpc.subnet_id}"
}

Example Usage (local Backend)

data "terraform_remote_state" "vpc" {
  backend = "local"

  config = {
    path = "..."
  }
}

# Terraform >= 0.12
resource "aws_instance" "foo" {
  # ...
  subnet_id = data.terraform_remote_state.vpc.outputs.subnet_id
}

# Terraform <= 0.11
resource "aws_instance" "foo" {
  # ...
  subnet_id = "${data.terraform_remote_state.vpc.subnet_id}"
}

Argument Reference

The following arguments are supported:

Attributes Reference

In addition to the above, the following attributes are exported:

Root Outputs Only

Only the root-level output values from the remote state snapshot are exposed for use elsewhere in your module. Resource data and output values from nested modules are not accessible.

If you wish to make a nested module output value accessible as a root module output value, you must explicitly configure a passthrough in the root module. For example:

For example:

module "app" {
  source = "..."
}

output "app_value" {
  # This syntax is for Terraform 0.12 or later.
  value = module.app.example
}

In this example, the output value named example from the "app" module is available as the app_value root module output value. If this configuration didn't include the output "app_value" block then the data would not be accessible via terraform_remote_state.