github.com/pulumi/terraform@v1.4.0/website/docs/language/state/remote-state-data.mdx (about) 1 --- 2 page_title: The terraform_remote_state Data Source 3 description: >- 4 Retrieves the root module output values from a Terraform state snapshot stored 5 in a remote backend. 6 --- 7 8 # The `terraform_remote_state` Data Source 9 10 [backends]: /language/settings/backends/configuration 11 12 The `terraform_remote_state` data source uses the latest state snapshot from a specified state backend to retrieve the root module output values 13 from some other Terraform configuration. 14 15 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](/language/providers/requirements#source-addresses) `terraform.io/builtin/terraform`. That provider does not include any other resources or data sources. 16 17 ~> **Important:** We recommend using the [`tfe_outputs` data source](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs/data-sources/outputs) in the [Terraform Cloud/Enterprise Provider](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs) to access remote state outputs in Terraform Cloud or Terraform Enterprise. The `tfe_outputs` data source is more secure because it does not require full access to workspace state to fetch outputs. 18 19 ## Alternative Ways to Share Data Between Configurations 20 21 Sharing data with root module outputs is convenient, but it has drawbacks. 22 Although `terraform_remote_state` only exposes output values, its user must have 23 access to the entire state snapshot, which often includes some sensitive 24 information. 25 26 When possible, we recommend explicitly publishing data for external consumption 27 to a separate location instead of accessing it via remote state. This lets you 28 apply different access controls for shared information and state snapshots. 29 30 To share data explicitly between configurations, you can use pairs of managed 31 resource types and data sources in various providers, including (but not 32 limited to) the following: 33 34 | System | Publish with... | Read with... | 35 | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 36 | 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) | 37 | 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) | 38 | Amazon S3 | [`aws_s3_object` resource type](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/s3_object) | [`aws_s3_object` data source](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/s3_object) | 39 | 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) | 40 | 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) | 41 | 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) | 42 | 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) | 43 | 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) | 44 | 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) | 45 | HashiCorp Terraform Cloud | Normal `outputs` terraform block | [`tfe_outputs` data source](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs/data-sources/outputs) | 46 | 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) | 47 | 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) | 48 49 -> These are some common options from the Official Terraform providers, but 50 there are too many configuration storage options for us to list them all 51 here, including some in partner and community providers. 52 Any pair of managed resource type and corresponding data source can potentially 53 be used to share data between Terraform configurations. See individual provider 54 documentation to find other possibilities. 55 56 A key advantage of using a separate explicit configuration store instead of 57 `terraform_remote_state` is that the data can potentially also be read by 58 systems other than Terraform, such as configuration management or scheduler 59 systems within your compute instances. For that reason, we recommend selecting 60 a configuration store that your other infrastructure could potentially make 61 use of. For example: 62 63 * If you wish to share IP addresses and hostnames, you could publish them as 64 normal DNS `A`, `AAAA`, `CNAME`, and `SRV` records in a private DNS zone and 65 then configure your other infrastructure to refer to that zone so you can 66 find infrastructure objects via your system's built-in DNS resolver. 67 * If you use HashiCorp Consul then publishing data to the Consul key/value 68 store or Consul service catalog can make that data also accessible via 69 [Consul Template](https://github.com/hashicorp/consul-template) 70 or the 71 [HashiCorp Nomad](https://developer.hashicorp.com/nomad/docs/job-specification/template) 72 `template` stanza. 73 * If you use Kubernetes then you can 74 [make Config Maps available to your Pods](https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/). 75 76 Some of the data stores listed above are specifically designed for storing 77 small configuration values, while others are generic blob storage systems. For 78 those generic systems, you can use 79 [the `jsonencode` function](/language/functions/jsonencode) 80 and 81 [the `jsondecode` function](/language/functions/jsondecode) respectively 82 to store and retrieve structured data. 83 84 You can encapsulate the implementation details of retrieving your published 85 configuration data by writing a 86 [data-only module](/language/modules/develop/composition#data-only-modules) 87 containing the necessary data source configuration and any necessary 88 post-processing such as JSON decoding. You can then change that module later 89 if you switch to a different strategy for sharing data between multiple 90 Terraform configurations. 91 92 ## Example Usage (`remote` Backend) 93 94 ```hcl 95 data "terraform_remote_state" "vpc" { 96 backend = "remote" 97 98 config = { 99 organization = "hashicorp" 100 workspaces = { 101 name = "vpc-prod" 102 } 103 } 104 } 105 106 # Terraform >= 0.12 107 resource "aws_instance" "foo" { 108 # ... 109 subnet_id = data.terraform_remote_state.vpc.outputs.subnet_id 110 } 111 112 # Terraform <= 0.11 113 resource "aws_instance" "foo" { 114 # ... 115 subnet_id = "${data.terraform_remote_state.vpc.subnet_id}" 116 } 117 ``` 118 119 ## Example Usage (`local` Backend) 120 121 ```hcl 122 data "terraform_remote_state" "vpc" { 123 backend = "local" 124 125 config = { 126 path = "..." 127 } 128 } 129 130 # Terraform >= 0.12 131 resource "aws_instance" "foo" { 132 # ... 133 subnet_id = data.terraform_remote_state.vpc.outputs.subnet_id 134 } 135 136 # Terraform <= 0.11 137 resource "aws_instance" "foo" { 138 # ... 139 subnet_id = "${data.terraform_remote_state.vpc.subnet_id}" 140 } 141 ``` 142 143 ## Argument Reference 144 145 The following arguments are supported: 146 147 * `backend` - (Required) The remote backend to use. 148 * `workspace` - (Optional) The Terraform workspace to use, if the backend 149 supports workspaces. 150 * `config` - (Optional; object) The configuration of the remote backend. 151 Although this argument is listed as optional, most backends require 152 some configuration. 153 154 The `config` object can use any arguments that would be valid in the 155 equivalent `terraform { backend "<TYPE>" { ... } }` block. See 156 [the documentation of your chosen backend](/language/settings/backends/configuration) 157 for details. 158 159 -> **Note:** If the backend configuration requires a nested block, specify 160 it here as a normal attribute with an object value. (For example, 161 `workspaces = { ... }` instead of `workspaces { ... }`.) 162 * `defaults` - (Optional; object) Default values for outputs, in case the state 163 file is empty or lacks a required output. 164 165 ## Attributes Reference 166 167 In addition to the above, the following attributes are exported: 168 169 * (v0.12+) `outputs` - An object containing every root-level 170 [output](/language/values/outputs) in the remote state. 171 * (<= v0.11) `<OUTPUT NAME>` - Each root-level [output](/language/values/outputs) 172 in the remote state appears as a top level attribute on the data source. 173 174 ## Root Outputs Only 175 176 Only the root-level output values from the remote state snapshot are exposed 177 for use elsewhere in your module. Resource data and output values from nested 178 modules are not accessible. 179 180 If you wish to make a nested module output value accessible as a root module 181 output value, you must explicitly configure a passthrough in the root module. 182 For example: 183 184 For example: 185 186 ```hcl 187 module "app" { 188 source = "..." 189 } 190 191 output "app_value" { 192 # This syntax is for Terraform 0.12 or later. 193 value = module.app.example 194 } 195 ``` 196 197 In this example, the output value named `example` from the "app" module is 198 available as the `app_value` root module output value. If this configuration 199 didn't include the `output "app_value"` block then the data would not be 200 accessible via `terraform_remote_state`. 201 202 ~> **Warning:** Although `terraform_remote_state` doesn't expose any other 203 state snapshot information for use in configuration, the state snapshot data 204 is a single object and so any user or server which has enough access to read 205 the root module output values will also always have access to the full state 206 snapshot data by direct network requests. Don't use `terraform_remote_state` 207 if any of the resources in your configuration work with data that you consider 208 sensitive.