github.com/vtorhonen/terraform@v0.9.0-beta2.0.20170307220345-5d894e4ffda7/website/source/docs/state/environments.html.md (about)

     1  ---
     2  layout: "docs"
     3  page_title: "State: Environments"
     4  sidebar_current: "docs-state-env"
     5  description: |-
     6    Terraform stores state which caches the known state of the world the last time Terraform ran.
     7  ---
     8  
     9  # State Environments
    10  
    11  An environment is a state namespace, allowing a single folder of Terraform
    12  configurations to manage multiple distinct infrastructure resources.
    13  
    14  Terraform state determines what resources it manages based on what
    15  exists in the state. This is how `terraform plan` determines what isn't
    16  created, what needs to be updated, etc. The full details of state can be
    17  found on the [purpose page](/docs/state/purpose.html).
    18  
    19  Environments are a way to create multiple states that contain
    20  their own data so a single set of Terraform configurations can manage
    21  multiple distinct sets of resources.
    22  
    23  ## Using Environments
    24  
    25  Terraform starts with a single environment named "default". This
    26  environment is special both because it is the default and also because
    27  it cannot ever be deleted. If you've never explicitly used environments, then
    28  you've only ever worked on the "default" environment.
    29  
    30  Environments are managed with the `terraform env` set of commands. To
    31  create a new environment and switch to it, you can use `terraform env new`,
    32  to switch environments you can use `terraform env select`, etc.
    33  
    34  For example, creating an environment:
    35  
    36  ```
    37  $ terraform env create bar
    38  Created and switched to environment "bar"!
    39  
    40  You're now on a new, empty environment. Environments isolate their state,
    41  so if you run "terraform plan" Terraform will not see any existing state
    42  for this configuration.
    43  ```
    44  
    45  As the command says, if you run `terraform plan`, Terraform will not see
    46  any existing resources that existed on the default (or any other) environment.
    47  **These resources still physically exist,** but are managed by another
    48  Terraform environment.
    49  
    50  ## Best Practices
    51  
    52  An environment alone **should not** be used to manage the difference between
    53  development, staging, and production. While it is technically possible, it is
    54  much more manageable and safe to use multiple independently managed Terraform
    55  configurations linked together with
    56  [terraform_remote_state](/docs/providers/terraform/d/remote_state.html)
    57  data sources.
    58  
    59  The [terraform_remote_state](/docs/providers/terraform/d/remote_state.html)
    60  resource accepts an `environment` name to target. Therefore, you can link
    61  together multiple independently managed Terraform configurations with the same
    62  environment easily. But, they can also have different environments.
    63  
    64  While environments are available to all,
    65  [Terraform Enterprise](https://www.hashicorp.com/products/terraform/)
    66  provides an interface and API for managing sets of configurations linked
    67  with `terraform_remote_state` and viewing them all as a single environment.
    68  
    69  Environments alone are useful for isolating a set of resources to test
    70  changes during development. For example, it is common to associate a
    71  branch in a VCS with an environment so new features can be developed
    72  without affecting the default environment.
    73  
    74  Future Terraform versions and environment enhancements will enable
    75  Terraform to track VCS branches with an environment to help verify only certain
    76  branches can make changes to a Terraform environment.
    77  
    78  ## Environments Internals
    79  
    80  Environments are technically equivalent to renaming your state file. They
    81  aren't any more complex than that. Terraform wraps this simple notion with
    82  a set of protections and support for remote state.
    83  
    84  For local state, Terraform stores the state environments in a folder
    85  `terraform.state.d`. This folder should be committed to version control
    86  (just like local-only `terraform.tfstate`).
    87  
    88  For [remote state](/docs/state/remote.html), the environments are stored
    89  directly in the configured [backend](/docs/backends). For example, if you
    90  use [Consul](/docs/backends/types/consul.html), the environments are stored
    91  by suffixing the state path with the environment name.
    92  
    93  The important thing about environment internals is that environments are
    94  meant to be a shared resource. They aren't a private, local-only notion
    95  (unless you're using purely local state and not committing it).
    96  
    97  The "current environment" name is stored only locally in the ignored
    98  `.terraform` directory. This allows multiple team members to work on
    99  different environments concurrently.