2015-05-26 15:35:19 +02:00
---
2020-08-15 03:51:06 +02:00
layout: "language"
2020-12-17 21:54:01 +01:00
page_title: "The terraform_remote_state Data Source"
2016-05-02 01:05:54 +02:00
sidebar_current: "docs-terraform-datasource-remote-state"
2015-05-26 15:35:19 +02:00
description: |-
website: Document alternatives to terraform_remote_state
For some time now we've been recommending explicitly passing data between
configurations using separate resource types and data sources, rather than
always using terraform_remote_state, for reasons including reducing
coupling between subsystems and allowing a configuration's state snapshots
to be under restrictive access controls.
However, those recommendations have so far not appeared directly in the
documentation for terraform_remote_state, and have instead just been
alluded to elsewhere in the documentation when discussing ways to pass
data between configurations.
This change, then, is an attempt to be clear and explicit about the
recommendation and to give a variety of specific examples of how to
implement it. The terraform_remote_state data source page is admittedly
not the most obvious place in the information architecture to put a set
of alternatives to it, but it does appear that this documentation page is
where people most commonly end up when researching options in this area
and so I've put this here in an attempt to "meet people where they are".
Possibly in a future documentation reorganization we might have an
separate page specifically about sharing data between configurations, but
we don't currently have time to do that bigger reorganization. If we do so
later, the content on this page could potentially be replaced with a
summary of the recommendation and a link to another place for the details,
but the goal here is to make this information visible in the existing
location people look for it, rather than blocking until there's a better
place for it to live.
This also includes a small amount of editing of some existing content on
the page to use terminology and style more similar to how our main
configuration language documentation is written,.
2020-11-17 00:54:51 +01:00
Retrieves the root module output values from a Terraform state snapshot stored in a remote backend.
2015-05-26 15:35:19 +02:00
---
2020-12-17 21:54:01 +01:00
# The `terraform_remote_state` Data Source
2015-05-26 15:35:19 +02:00
2018-11-07 23:01:58 +01:00
[backends]: /docs/backends/index.html
2020-12-17 21:54:01 +01:00
The `terraform_remote_state` data source retrieves the root module output values
from some other Terraform configuration, using the latest state snapshot from
the remote backend.
This data source is built into Terraform, and is always available; you do not
need to require or configure a provider in order to use it.
-> **Note:** This data source is implemented by a built-in provider, whose
2021-01-15 23:13:53 +01:00
[source address ](/docs/language/providers/requirements.html#source-addresses )
2020-12-17 21:54:01 +01:00
is `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.
website: Document alternatives to terraform_remote_state
For some time now we've been recommending explicitly passing data between
configurations using separate resource types and data sources, rather than
always using terraform_remote_state, for reasons including reducing
coupling between subsystems and allowing a configuration's state snapshots
to be under restrictive access controls.
However, those recommendations have so far not appeared directly in the
documentation for terraform_remote_state, and have instead just been
alluded to elsewhere in the documentation when discussing ways to pass
data between configurations.
This change, then, is an attempt to be clear and explicit about the
recommendation and to give a variety of specific examples of how to
implement it. The terraform_remote_state data source page is admittedly
not the most obvious place in the information architecture to put a set
of alternatives to it, but it does appear that this documentation page is
where people most commonly end up when researching options in this area
and so I've put this here in an attempt to "meet people where they are".
Possibly in a future documentation reorganization we might have an
separate page specifically about sharing data between configurations, but
we don't currently have time to do that bigger reorganization. If we do so
later, the content on this page could potentially be replaced with a
summary of the recommendation and a link to another place for the details,
but the goal here is to make this information visible in the existing
location people look for it, rather than blocking until there's a better
place for it to live.
This also includes a small amount of editing of some existing content on
the page to use terminology and style more similar to how our main
configuration language documentation is written,.
2020-11-17 00:54:51 +01:00
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< br >< small > (for IP addresses and hostnames)</ small > | [`alicloud_alidns_record` resource type ](https://registry.terraform.io/providers/aliyun/alicloud/latest/docs/resources/alidns_record ) | Normal DNS lookups, or [the `dns` provider ](https://registry.terraform.io/providers/hashicorp/dns/latest/docs ) |
| Amazon Route53< br >< small > (for IP addresses and hostnames)</ small > | [`aws_route53_record` resource type ](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/route53_record ) | Normal DNS lookups, or [the `dns` provider ](https://registry.terraform.io/providers/hashicorp/dns/latest/docs ) |
| Amazon S3 | [`aws_s3_bucket_object` resource type ](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/s3_bucket_object ) | [`aws_s3_bucket_object` data source ](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/s3_bucket_object ) |
| Amazon SSM Parameter Store | [`aws_ssm_parameter` resource type ](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ssm_parameter ) | [`aws_ssm_parameter` data source ](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/ssm_parameter ) |
| Azure Automation | [`azurerm_automation_variable_string` resource type ](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/automation_variable_string ) | [`azurerm_automation_variable_string` data source ](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/data-sources/automation_variable_string ) |
| Azure DNS< br >< small > (for IP addresses and hostnames)</ small > | [`azurerm_dns_a_record` resource type ](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/dns_a_record ), etc | Normal DNS lookups, or [the `dns` provider ](https://registry.terraform.io/providers/hashicorp/dns/latest/docs ) |
| Google Cloud DNS< br >< small > (for IP addresses and hostnames)</ small > | [`google_dns_record_set` resource type ](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/dns_record_set ) | Normal DNS lookups, or [the `dns` provider ](https://registry.terraform.io/providers/hashicorp/dns/latest/docs ) |
| Google Cloud Storage | [`google_storage_bucket_object` resource type ](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/storage_bucket_object ) | [`google_storage_bucket_object` data source ](https://registry.terraform.io/providers/hashicorp/google/latest/docs/data-sources/storage_bucket_object ) and [`http` data source ](https://registry.terraform.io/providers/hashicorp/http/latest/docs/data-sources/http ) |
| HashiCorp Consul | [`consul_key_prefix` resource type ](https://registry.terraform.io/providers/hashicorp/consul/latest/docs/resources/key_prefix ) | [`consul_key_prefix` data source ](https://registry.terraform.io/providers/hashicorp/consul/latest/docs/data-sources/key_prefix ) |
| Kubernetes | [`kubernetes_config_map` resource type ](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs/resources/config_map ) | [`kubernetes_config_map` data source ](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs/data-sources/config_map ) |
| OCI Object Storage | [`oci_objectstorage_bucket` resource type ](https://registry.terraform.io/providers/hashicorp/oci/latest/docs/resources/objectstorage_object ) | [`oci_objectstorage_bucket` data source ](https://registry.terraform.io/providers/hashicorp/oci/latest/docs/data-sources/objectstorage_object ) |
-> These are some common options from the Official Terraform providers, but
there are too many configuration storage options for us to list them all
here, including some in partner and community providers.
Any pair of managed resource type and corresponding data source can potentially
be used to share data between Terraform configurations. See individual provider
documentation to find other possibilities.
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:
* If you wish to share IP addresses and hostnames, you could publish them as
normal DNS `A` , `AAAA` , `CNAME` , and `SRV` records in a private DNS zone and
then configure your other infrastructure to refer to that zone so you can
find infrastructure objects via your system's built-in DNS resolver.
* If you use HashiCorp Consul then publishing data to the Consul key/value
store or Consul service catalog can make that data also accessible via
[Consul Template ](https://github.com/hashicorp/consul-template )
or the
[HashiCorp Nomad ](https://www.nomadproject.io/docs/job-specification/template )
`template` stanza.
* If you use Kubernetes then you can
[make Config Maps available to your Pods ](https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/ ).
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
2021-01-15 23:13:53 +01:00
[the `jsonencode` function ](https://www.terraform.io/docs/language/functions/jsonencode.html )
website: Document alternatives to terraform_remote_state
For some time now we've been recommending explicitly passing data between
configurations using separate resource types and data sources, rather than
always using terraform_remote_state, for reasons including reducing
coupling between subsystems and allowing a configuration's state snapshots
to be under restrictive access controls.
However, those recommendations have so far not appeared directly in the
documentation for terraform_remote_state, and have instead just been
alluded to elsewhere in the documentation when discussing ways to pass
data between configurations.
This change, then, is an attempt to be clear and explicit about the
recommendation and to give a variety of specific examples of how to
implement it. The terraform_remote_state data source page is admittedly
not the most obvious place in the information architecture to put a set
of alternatives to it, but it does appear that this documentation page is
where people most commonly end up when researching options in this area
and so I've put this here in an attempt to "meet people where they are".
Possibly in a future documentation reorganization we might have an
separate page specifically about sharing data between configurations, but
we don't currently have time to do that bigger reorganization. If we do so
later, the content on this page could potentially be replaced with a
summary of the recommendation and a link to another place for the details,
but the goal here is to make this information visible in the existing
location people look for it, rather than blocking until there's a better
place for it to live.
This also includes a small amount of editing of some existing content on
the page to use terminology and style more similar to how our main
configuration language documentation is written,.
2020-11-17 00:54:51 +01:00
and
2021-01-15 23:13:53 +01:00
[the `jsondecode` function ](https://www.terraform.io/docs/language/functions/jsondecode.html ) respectively
website: Document alternatives to terraform_remote_state
For some time now we've been recommending explicitly passing data between
configurations using separate resource types and data sources, rather than
always using terraform_remote_state, for reasons including reducing
coupling between subsystems and allowing a configuration's state snapshots
to be under restrictive access controls.
However, those recommendations have so far not appeared directly in the
documentation for terraform_remote_state, and have instead just been
alluded to elsewhere in the documentation when discussing ways to pass
data between configurations.
This change, then, is an attempt to be clear and explicit about the
recommendation and to give a variety of specific examples of how to
implement it. The terraform_remote_state data source page is admittedly
not the most obvious place in the information architecture to put a set
of alternatives to it, but it does appear that this documentation page is
where people most commonly end up when researching options in this area
and so I've put this here in an attempt to "meet people where they are".
Possibly in a future documentation reorganization we might have an
separate page specifically about sharing data between configurations, but
we don't currently have time to do that bigger reorganization. If we do so
later, the content on this page could potentially be replaced with a
summary of the recommendation and a link to another place for the details,
but the goal here is to make this information visible in the existing
location people look for it, rather than blocking until there's a better
place for it to live.
This also includes a small amount of editing of some existing content on
the page to use terminology and style more similar to how our main
configuration language documentation is written,.
2020-11-17 00:54:51 +01:00
to store and retrieve structured data.
You can encapsulate the implementation details of retrieving your published
configuration data by writing a
2021-01-15 23:13:53 +01:00
[data-only module ](/docs/language/modules/develop/composition.html#data-only-modules )
website: Document alternatives to terraform_remote_state
For some time now we've been recommending explicitly passing data between
configurations using separate resource types and data sources, rather than
always using terraform_remote_state, for reasons including reducing
coupling between subsystems and allowing a configuration's state snapshots
to be under restrictive access controls.
However, those recommendations have so far not appeared directly in the
documentation for terraform_remote_state, and have instead just been
alluded to elsewhere in the documentation when discussing ways to pass
data between configurations.
This change, then, is an attempt to be clear and explicit about the
recommendation and to give a variety of specific examples of how to
implement it. The terraform_remote_state data source page is admittedly
not the most obvious place in the information architecture to put a set
of alternatives to it, but it does appear that this documentation page is
where people most commonly end up when researching options in this area
and so I've put this here in an attempt to "meet people where they are".
Possibly in a future documentation reorganization we might have an
separate page specifically about sharing data between configurations, but
we don't currently have time to do that bigger reorganization. If we do so
later, the content on this page could potentially be replaced with a
summary of the recommendation and a link to another place for the details,
but the goal here is to make this information visible in the existing
location people look for it, rather than blocking until there's a better
place for it to live.
This also includes a small amount of editing of some existing content on
the page to use terminology and style more similar to how our main
configuration language documentation is written,.
2020-11-17 00:54:51 +01:00
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.
2015-05-26 15:35:19 +02:00
2020-05-21 23:54:30 +02:00
## Example Usage (`remote` Backend)
2015-05-26 15:35:19 +02:00
2017-04-07 17:36:49 +02:00
```hcl
2016-05-02 01:05:54 +02:00
data "terraform_remote_state" "vpc" {
2019-07-25 20:33:41 +02:00
backend = "remote"
2019-08-29 04:59:39 +02:00
2019-06-19 01:25:36 +02:00
config = {
2019-08-29 04:59:39 +02:00
organization = "hashicorp"
workspaces = {
name = "vpc-prod"
}
2017-04-07 17:36:49 +02:00
}
2015-05-26 15:35:19 +02:00
}
2019-03-08 08:45:33 +01:00
# Terraform >= 0.12
2015-05-26 15:35:19 +02:00
resource "aws_instance" "foo" {
2017-04-07 17:36:49 +02:00
# ...
2019-06-10 15:47:11 +02:00
subnet_id = data.terraform_remote_state.vpc.outputs.subnet_id
2015-05-26 15:35:19 +02:00
}
2019-03-08 08:45:33 +01:00
2019-09-17 20:19:54 +02:00
# Terraform <= 0.11
resource "aws_instance" "foo" {
# ...
subnet_id = "${data.terraform_remote_state.vpc.subnet_id}"
}
```
2020-05-21 23:54:40 +02:00
## Example Usage (`local` Backend)
2019-09-17 20:19:54 +02:00
```hcl
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
}
2019-03-08 08:45:33 +01:00
# Terraform <= 0.11
resource "aws_instance" "foo" {
# ...
subnet_id = "${data.terraform_remote_state.vpc.subnet_id}"
}
2015-05-26 15:35:19 +02:00
```
## Argument Reference
The following arguments are supported:
* `backend` - (Required) The remote backend to use.
2018-11-07 23:01:58 +01:00
* `workspace` - (Optional) The Terraform workspace to use, if the backend
supports workspaces.
2019-08-29 04:59:39 +02:00
* `config` - (Optional; object) The configuration of the remote backend.
Although this argument is listed as optional, most backends require
some configuration.
The `config` object can use any arguments that would be valid in the
equivalent `terraform { backend "<TYPE>" { ... } }` block. See
2021-01-16 00:41:43 +01:00
[the documentation of your chosen backend ](/docs/language/settings/backends/index.html )
2019-08-29 04:59:39 +02:00
for details.
-> **Note:** If the backend configuration requires a nested block, specify
it here as a normal attribute with an object value. (For example,
`workspaces = { ... }` instead of `workspaces { ... }` .)
* `defaults` - (Optional; object) Default values for outputs, in case the state
2018-11-07 23:01:58 +01:00
file is empty or lacks a required output.
2015-05-26 15:35:19 +02:00
## Attributes Reference
2019-02-06 13:53:51 +01:00
In addition to the above, the following attributes are exported:
2015-05-26 15:35:19 +02:00
2019-08-29 04:59:39 +02:00
* (v0.12+) `outputs` - An object containing every root-level
2021-01-15 23:13:53 +01:00
[output ](/docs/language/values/outputs.html ) in the remote state.
* (< = v0.11) `<OUTPUT NAME>` - Each root-level [output ](/docs/language/values/outputs.html )
2018-11-07 23:01:58 +01:00
in the remote state appears as a top level attribute on the data source.
2016-10-24 23:14:49 +02:00
## Root Outputs Only
website: Document alternatives to terraform_remote_state
For some time now we've been recommending explicitly passing data between
configurations using separate resource types and data sources, rather than
always using terraform_remote_state, for reasons including reducing
coupling between subsystems and allowing a configuration's state snapshots
to be under restrictive access controls.
However, those recommendations have so far not appeared directly in the
documentation for terraform_remote_state, and have instead just been
alluded to elsewhere in the documentation when discussing ways to pass
data between configurations.
This change, then, is an attempt to be clear and explicit about the
recommendation and to give a variety of specific examples of how to
implement it. The terraform_remote_state data source page is admittedly
not the most obvious place in the information architecture to put a set
of alternatives to it, but it does appear that this documentation page is
where people most commonly end up when researching options in this area
and so I've put this here in an attempt to "meet people where they are".
Possibly in a future documentation reorganization we might have an
separate page specifically about sharing data between configurations, but
we don't currently have time to do that bigger reorganization. If we do so
later, the content on this page could potentially be replaced with a
summary of the recommendation and a link to another place for the details,
but the goal here is to make this information visible in the existing
location people look for it, rather than blocking until there's a better
place for it to live.
This also includes a small amount of editing of some existing content on
the page to use terminology and style more similar to how our main
configuration language documentation is written,.
2020-11-17 00:54:51 +01:00
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:
2016-10-24 23:14:49 +02:00
2018-11-07 23:01:58 +01:00
For example:
2016-10-24 23:14:49 +02:00
2017-04-07 17:36:49 +02:00
```hcl
2016-10-24 23:14:49 +02:00
module "app" {
source = "..."
}
output "app_value" {
website: Document alternatives to terraform_remote_state
For some time now we've been recommending explicitly passing data between
configurations using separate resource types and data sources, rather than
always using terraform_remote_state, for reasons including reducing
coupling between subsystems and allowing a configuration's state snapshots
to be under restrictive access controls.
However, those recommendations have so far not appeared directly in the
documentation for terraform_remote_state, and have instead just been
alluded to elsewhere in the documentation when discussing ways to pass
data between configurations.
This change, then, is an attempt to be clear and explicit about the
recommendation and to give a variety of specific examples of how to
implement it. The terraform_remote_state data source page is admittedly
not the most obvious place in the information architecture to put a set
of alternatives to it, but it does appear that this documentation page is
where people most commonly end up when researching options in this area
and so I've put this here in an attempt to "meet people where they are".
Possibly in a future documentation reorganization we might have an
separate page specifically about sharing data between configurations, but
we don't currently have time to do that bigger reorganization. If we do so
later, the content on this page could potentially be replaced with a
summary of the recommendation and a link to another place for the details,
but the goal here is to make this information visible in the existing
location people look for it, rather than blocking until there's a better
place for it to live.
This also includes a small amount of editing of some existing content on
the page to use terminology and style more similar to how our main
configuration language documentation is written,.
2020-11-17 00:54:51 +01:00
# This syntax is for Terraform 0.12 or later.
value = module.app.example
2016-10-24 23:14:49 +02:00
}
```
website: Document alternatives to terraform_remote_state
For some time now we've been recommending explicitly passing data between
configurations using separate resource types and data sources, rather than
always using terraform_remote_state, for reasons including reducing
coupling between subsystems and allowing a configuration's state snapshots
to be under restrictive access controls.
However, those recommendations have so far not appeared directly in the
documentation for terraform_remote_state, and have instead just been
alluded to elsewhere in the documentation when discussing ways to pass
data between configurations.
This change, then, is an attempt to be clear and explicit about the
recommendation and to give a variety of specific examples of how to
implement it. The terraform_remote_state data source page is admittedly
not the most obvious place in the information architecture to put a set
of alternatives to it, but it does appear that this documentation page is
where people most commonly end up when researching options in this area
and so I've put this here in an attempt to "meet people where they are".
Possibly in a future documentation reorganization we might have an
separate page specifically about sharing data between configurations, but
we don't currently have time to do that bigger reorganization. If we do so
later, the content on this page could potentially be replaced with a
summary of the recommendation and a link to another place for the details,
but the goal here is to make this information visible in the existing
location people look for it, rather than blocking until there's a better
place for it to live.
This also includes a small amount of editing of some existing content on
the page to use terminology and style more similar to how our main
configuration language documentation is written,.
2020-11-17 00:54:51 +01:00
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` .
~> **Warning:** Although `terraform_remote_state` doesn't expose any other
state snapshot information for use in configuration, the state snapshot data
is a single object and so any user or server which has enough access to read
the root module output values will also always have access to the full state
snapshot data by direct network requests. Don't use `terraform_remote_state`
if any of the resources in your configuration work with data that you consider
sensitive.
