From 5ceb8b2b9865b94159d7497b254a7c2784286dd6 Mon Sep 17 00:00:00 2001 From: Nick Fagerlund Date: Thu, 17 Dec 2020 12:54:01 -0800 Subject: [PATCH] website: Adopt `terraform_remote_state` into language docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ...and also shrink the explanation for alternate sharing approaches, a bit. Actually, it looks like I already half-adopted it by accident. 😬 But this commit adds it to the sidebar under "State", so users can browse to it. I'm leaving the URL alone, because it's not urgent and we'll need to adjust a large swath of URLs at some point anyway. This change effectively stops presenting `terraform` as a provider in the normal sense, and reduces /docs/providers/terraform/index.html to a ghost page in the language section (to avoid breaking links for the time being). The message a reader should get is that Terraform has one special built-in data source where you don't need to think about the provider or its version. --- .../terraform/d/remote_state.html.md | 38 +++++++++------- .../providers/terraform/index.html.markdown | 44 +++++-------------- website/layouts/language.erb | 4 ++ website/layouts/terraform.erb | 26 ----------- 4 files changed, 38 insertions(+), 74 deletions(-) delete mode 100644 website/layouts/terraform.erb diff --git a/website/docs/providers/terraform/d/remote_state.html.md b/website/docs/providers/terraform/d/remote_state.html.md index 6d0fb8d48..cba263823 100644 --- a/website/docs/providers/terraform/d/remote_state.html.md +++ b/website/docs/providers/terraform/d/remote_state.html.md @@ -1,31 +1,37 @@ --- layout: "language" -page_title: "Terraform: terraform_remote_state" +page_title: "The terraform_remote_state Data Source" sidebar_current: "docs-terraform-datasource-remote-state" description: |- Retrieves the root module output values from a Terraform state snapshot stored in a remote backend. --- -# terraform_remote_state +# The `terraform_remote_state` Data Source [backends]: /docs/backends/index.html -The `terraform_remote_state` data source retrieves the root module output -values saved as part of the latest state snapshot from the remote backend for -some other Terraform configuration. +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 can be a convenient way to make use of data already generated by another -Terraform configuration without publishing it explicitly elsewhere, but it's -important to note that output values are only a small part of a Terraform -state snapshot. Although `terraform_remote_state` only exposes the output -values, any user of this data source must have full access to the other aspects -of the state snapshot, which may be considered sensitive information. +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. -Rather than directly sharing state snapshots between your configurations, we -recommend explicitly publishing data for external consumption to a separate -location than to the producing configuration's remote state backend. -The shared information will then be separated from the internal details in the -state snapshots, and so you can apply different access controls to each. +-> **Note:** This data source is implemented by a built-in provider, whose +[source address](/docs/configuration/provider-requirements.html#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 diff --git a/website/docs/providers/terraform/index.html.markdown b/website/docs/providers/terraform/index.html.markdown index e6da618db..99a3e561e 100644 --- a/website/docs/providers/terraform/index.html.markdown +++ b/website/docs/providers/terraform/index.html.markdown @@ -3,40 +3,20 @@ layout: "language" page_title: "Provider: Terraform" sidebar_current: "docs-terraform-index" description: |- - The Terraform provider is used to access meta data from shared infrastructure. + The special `terraform_remote_state` data source is used to access outputs from shared infrastructure. --- -# Terraform Provider +# The Built-In `terraform` Provider -The terraform provider provides access to outputs from the Terraform state -of shared infrastructure. +Terraform includes one built-in data source: +[`terraform_remote_state`](/docs/providers/terraform/d/remote_state.html), which +provides access to root module outputs from some other Terraform configuration. -Use the navigation to the left to read about the available data sources. +This data source is implemented by a built-in provider, whose +[source address](/docs/configuration/provider-requirements.html#source-addresses) +is `terraform.io/builtin/terraform`. You do not need to require or configure +this provider in order to use the `terraform_remote_state` data source; it is +always available. -## Example Usage - -```hcl -# Shared infrastructure state stored in Atlas -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}" -} -``` +The `terraform_remote_state` data source is +[documented in the Terraform Language docs](/docs/providers/terraform/d/remote_state.html). diff --git a/website/layouts/language.erb b/website/layouts/language.erb index 11ec5a409..27e37e5c1 100644 --- a/website/layouts/language.erb +++ b/website/layouts/language.erb @@ -920,6 +920,10 @@ Purpose +
  • + The terraform_remote_state Data Source +
    • +
  • Backends: State Storage & Locking
    • diff --git a/website/layouts/terraform.erb b/website/layouts/terraform.erb deleted file mode 100644 index 015a6be3f..000000000 --- a/website/layouts/terraform.erb +++ /dev/null @@ -1,26 +0,0 @@ -<% wrap_layout :inner do %> - <% content_for :sidebar do %> - - <% end %> - - <%= yield %> -<% end %>