website: document state environments

website/source/docs/state/environments.html.md

@@ -0,0 +1,99 @@
+---
+layout: "docs"
+page_title: "State: Environments"
+sidebar_current: "docs-state-env"
+description: |-
+  Terraform stores state which caches the known state of the world the last time Terraform ran.
+---
+
+# State Environments
+
+An environment is a state namespace, allowing a single folder of Terraform
+configurations to manage multiple distinct infrastructure resources.
+
+Terraform state determines what resources it manages based on what
+exists in the state. This is how `terraform plan` determines what isn't
+created, what needs to be updated, etc. The full details of state can be
+found on the [purpose page](/docs/state/purpose.html).
+
+Environments are a way to create multiple states that contain
+their own data so a single set of Terraform configurations can manage
+multiple distinct sets of resources.
+
+## Using Environments
+
+Terraform starts with a single environment named "default". This
+environment is special both because it is the default and also because
+it cannot ever be deleted. If you've never explicitly used environments, then
+you've only ever worked on the "default" environment.
+
+Environments are managed with the `terraform env` set of commands. To
+create a new environment and switch to it, you can use `terraform env new`,
+to switch environments you can use `terraform env switch`, etc.
+
+For example, creating an environment:
+
+```
+$ terraform env create bar
+Created and switched to environment "bar"!
+
+You're now on a new, empty environment. Environments isolate their state,
+so if you run "terraform plan" Terraform will not see any existing state
+for this configuration.
+```
+
+As the command says, if you run `terraform plan`, Terraform will not see
+any existing resources that existed on the default (or any other) environment.
+**These resources still physically exist,** but are managed by another
+Terraform environment.
+
+## Best Practices
+
+An environment alone **should not** be used to manage the difference between
+development, staging, and production. While it is technically possible, it is
+much more manageable and safe to use multiple independently managed Terraform
+modules linked together with
+[terraform_remote_state](/docs/providers/terraform/d/remote_state.html)
+data sources.
+
+The [terraform_remote_state](/docs/providers/terraform/d/remote_state.html)
+resource accepts an `environment` name to target. Therefore, you can link
+together multiple independently managed Terraform modules with the same
+environment easily. But, they can also have different environments.
+
+While environments are available to all,
+[Terraform Enterprise](https://www.hashicorp.com/products/terraform/)
+provides an interface and API for managing sets of configurations linked
+with `terraform_remote_state` and viewing them all as a single environment.
+
+Environments alone are useful for isolating a set of resources to test
+changes during development. For example, it is common to associate a
+branch in a VCS with an environment so new features can be developed
+without affecting the default environment.
+
+Future Terraform versions and environment enhancements will enable
+Terraform to track VCS branches with an environment to help verify only certain
+branches can make changes to a Terraform environment.
+
+## Environments Internals
+
+Environments are technically equivalent to renaming your state file. They
+aren't any more complex than that. Terraform wraps this simple notion with
+a set of protections and support for remote state.
+
+For local state, Terraform stores the state environments in a folder
+`terraform.state.d`. This folder should be committed to version control
+(just like local-only `terraform.tfstate`).
+
+For [remote state](/docs/state/remote.html), the environments are stored
+directly in the configured [backend](/docs/backends). For example, if you
+use [Consul](/docs/backends/types/consul.html), the environments are stored
+by suffixing the state path with the environment name.
+
+The important thing about environment internals is that environments are
+meant to be a shared resource. They aren't a private, local-only notion
+(unless you're using purely local state and not committing it).
+
+The "current environment" name is stored only locally in the ignored
+`.terraform` directory. This allows multiple team members to work on
+different environments concurrently.

website/source/layouts/docs.erb

@@ -169,6 +169,10 @@
 							<a href="/docs/state/locking.html">Locking</a>
 						</li>
 
+						<li<%= sidebar_current("docs-state-env") %>>
+							<a href="/docs/state/environments.html">Environments</a>
+						</li>
+
 						<li<%= sidebar_current("docs-state-remote") %>>
 							<a href="/docs/state/remote.html">Remote State</a>
 						</li>
@@ -233,7 +237,7 @@
 					<li<%= sidebar_current("docs-providers-do") %>>
 					<a href="/docs/providers/do/index.html">DigitalOcean</a>
 					</li>
-          
+
 					<li<%= sidebar_current("docs-providers-dns") %>>
 					<a href="/docs/providers/dns/index.html">DNS</a>
 					</li>
@@ -540,4 +544,4 @@
 	<% end %>
 
 	<%= yield %>
-<% end %>
+<% end %>