ResiLien
/
terraform
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

website: Adopt `terraform_remote_state` into language docs 

...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.
This commit is contained in:
Nick Fagerlund 2020-12-17 12:54:01 -08:00 committed by Nick Fagerlund
parent e9748574b9
commit 5ceb8b2b98
4 changed files with 38 additions and 74 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

38
website/docs/providers/terraform/d/remote_state.html.md
View File

@ -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

44
website/docs/providers/terraform/index.html.markdown
View File

@ -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).

4
website/layouts/language.erb
View File

@ -920,6 +920,10 @@
<a href="/docs/state/purpose.html">Purpose</a>
</li>
<li>
<a href="/docs/providers/terraform/d/remote_state.html">The <code>terraform_remote_state</code> Data Source</a>
</li>
<li>
<a href="/docs/backends/state.html">Backends: State Storage & Locking</a>
</li>

26
website/layouts/terraform.erb
View File

@ -1,26 +0,0 @@
<% wrap_layout :inner do %>
<% content_for :sidebar do %>
<div class="docs-sidebar hidden-print affix-top" role="complementary">
<ul class="nav docs-sidenav">
<li<%= sidebar_current("docs-home") %>>
<a href="/docs/providers/index.html">All Providers</a>
</li>
<li<%= sidebar_current("docs-terraform-index") %>>
<a href="/docs/providers/terraform/index.html">Terraform Provider</a>
</li>
<li<%= sidebar_current("docs-terraform-datasource") %>>
<a href="#">Data Sources</a>
<ul class="nav nav-visible">
<li<%= sidebar_current("docs-terraform-datasource-remote-state") %>>
<a href="/docs/providers/terraform/d/remote_state.html">terraform_remote_state</a>
</li>
</ul>
</li>
</ul>
</div>
<% end %>
<%= yield %>
<% end %>