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
 
@@ -273,7 +279,7 @@ The supported built-in functions are:
 
   * `pathexpand(string)` - Returns a filepath string with `~` expanded to the home directory. Note:
     This will create a plan diff between two different hosts, unless the filepaths are the same.
-  
+
   * `replace(string, search, replace)` - Does a search and replace on the
       given string. All instances of `search` are replaced with the value
       of `replace`. If `search` is wrapped in forward slashes, it is treated

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