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