website: document terraform.env

website/source/docs/configuration/interpolation.html.md

@@ -84,6 +84,12 @@ interpolate the path to the current module. `root` will interpolate the
 path of the root module.  In general, you probably want the
 `path.module` variable.
 
+#### Terraform meta information
+
+The syntax is `terraform.FIELD`. This variable type contains metadata about
+the currently executing Terraform run. FIELD can currently only be `env` to
+reference the currently active [state environment](/docs/state/environments.html).
+
 <a id="conditionals"></a>
 ## Conditionals
 

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

@@ -47,6 +47,35 @@ any existing resources that existed on the default (or any other) environment.
 **These resources still physically exist,** but are managed by another
 Terraform environment.
 
+## Current Environment Interpolation
+
+Within your Terraform configuration, you may reference the current environment
+using the `${terraform.env}` interpolation variable. This can be used anywhere
+interpolations are allowed.
+
+Referencing the current environment is useful for changing behavior based
+on the environment. For example, for non-default environments, it may be useful
+to spin up smaller cluster sizes. You can do this:
+
+```
+resource "aws_instance" "example" {
+  count = "${terraform.env == "default" ? 5 : 1}"
+
+  # ... other fields
+}
+```
+
+Another popular use case is using the environment as part of naming or
+tagging behavior:
+
+```
+resource "aws_instance" "example" {
+  tags { Name = "web - ${terraform.env}" }
+
+  # ... other fields
+}
+```
+
 ## Best Practices
 
 An environment alone **should not** be used to manage the difference between