220 lines
14 KiB
Plaintext
220 lines
14 KiB
Plaintext
|
---
|
||
|
|
page_title: The terraform_remote_state Data Source
|
||
|
|
description: >-
|
||
|
|
Retrieves the root module output values from a Terraform state snapshot stored
|
||
|
|
in a remote backend.
|
||
|
|
---
|
||
|
|
|
||
|
|
# The `terraform_remote_state` Data Source
|
||
|
|
|
||
|
|
[backends]: /backends/
|
||
|
|
|
||
|
|
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
|
||
|
|
[source address](/language/providers/requirements#source-addresses)
|
||
|
|
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.
|
||
|
|
|
||
|
|
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) |
|
||
|
|
| HashiCorp Terraform Cloud | Normal `outputs` terraform block | [`tfe_outputs` data source](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs/data-sources/outputs) |
|
||
|
|
| 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
|
||
|
|
[the `jsonencode` function](/language/functions/jsonencode)
|
||
|
|
and
|
||
|
|
[the `jsondecode` function](/language/functions/jsondecode) 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](/language/modules/develop/composition#data-only-modules)
|
||
|
|
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.
|
||
|
|
|
||
|
|
## Usage with Terraform Cloud/Enterprise
|
||
|
|
|
||
|
|
When trying to access remote state outputs in Terraform Cloud/Enterprise, it is recommended to use the `tfe_outputs` data source in the [Terraform Cloud/Enterprise Provider](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs) instead of relying the `terraform_remote_state` data source.
|
||
|
|
|
||
|
|
See the [full documentation](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs/data-sources/outputs) for the `tfe_outputs` data source for more details.
|
||
|
|
|
||
|
|
## Example Usage (`remote` Backend)
|
||
|
|
|
||
|
|
```hcl
|
||
|
|
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)
|
||
|
|
|
||
|
|
```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
|
||
|
|
}
|
||
|
|
|
||
|
|
# Terraform <= 0.11
|
||
|
|
resource "aws_instance" "foo" {
|
||
|
|
# ...
|
||
|
|
subnet_id = "${data.terraform_remote_state.vpc.subnet_id}"
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
## Argument Reference
|
||
|
|
|
||
|
|
The following arguments are supported:
|
||
|
|
|
||
|
|
* `backend` - (Required) The remote backend to use.
|
||
|
|
* `workspace` - (Optional) The Terraform workspace to use, if the backend
|
||
|
|
supports workspaces.
|
||
|
|
* `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
|
||
|
|
[the documentation of your chosen backend](/language/settings/backends/)
|
||
|
|
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
|
||
|
|
file is empty or lacks a required output.
|
||
|
|
|
||
|
|
## Attributes Reference
|
||
|
|
|
||
|
|
In addition to the above, the following attributes are exported:
|
||
|
|
|
||
|
|
* (v0.12+) `outputs` - An object containing every root-level
|
||
|
|
[output](/language/values/outputs) in the remote state.
|
||
|
|
* (<= v0.11) `<OUTPUT NAME>` - Each root-level [output](/language/values/outputs)
|
||
|
|
in the remote state appears as a top level attribute on the data source.
|
||
|
|
|
||
|
|
## 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:
|
||
|
|
|
||
|
|
```hcl
|
||
|
|
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`.
|
||
|
|
|
||
|
|
~> **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.
|