github.com/danp/terraform@v0.9.5-0.20170426144147-39d740081351/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 Environments are currently supported by the following backends: 24 25 * [Consul](/docs/backends/types/consul.html) 26 * [S3](/docs/backends/types/s3.html) 27 28 ## Using Environments 29 30 Terraform starts with a single environment named "default". This 31 environment is special both because it is the default and also because 32 it cannot ever be deleted. If you've never explicitly used environments, then 33 you've only ever worked on the "default" environment. 34 35 Environments are managed with the `terraform env` set of commands. To 36 create a new environment and switch to it, you can use `terraform env new`, 37 to switch environments you can use `terraform env select`, etc. 38 39 For example, creating an environment: 40 41 ```text 42 $ terraform env new bar 43 Created and switched to environment "bar"! 44 45 You're now on a new, empty environment. Environments isolate their state, 46 so if you run "terraform plan" Terraform will not see any existing state 47 for this configuration. 48 ``` 49 50 As the command says, if you run `terraform plan`, Terraform will not see 51 any existing resources that existed on the default (or any other) environment. 52 **These resources still physically exist,** but are managed by another 53 Terraform environment. 54 55 ## Current Environment Interpolation 56 57 Within your Terraform configuration, you may reference the current environment 58 using the `${terraform.env}` interpolation variable. This can be used anywhere 59 interpolations are allowed. 60 61 Referencing the current environment is useful for changing behavior based 62 on the environment. For example, for non-default environments, it may be useful 63 to spin up smaller cluster sizes. You can do this: 64 65 ```hcl 66 resource "aws_instance" "example" { 67 count = "${terraform.env == "default" ? 5 : 1}" 68 69 # ... other fields 70 } 71 ``` 72 73 Another popular use case is using the environment as part of naming or 74 tagging behavior: 75 76 ```hcl 77 resource "aws_instance" "example" { 78 tags { Name = "web - ${terraform.env}" } 79 80 # ... other fields 81 } 82 ``` 83 84 ## Best Practices 85 86 An environment alone **should not** be used to manage the difference between 87 development, staging, and production. As Terraform configurations get larger, 88 it's much more manageable and safer to split one large configuration into many 89 smaller ones linked together with terraform_remote_state data sources. This 90 allows teams to delegate ownership and reduce the blast radius of changes. 91 For each smaller configuration, you can use environments to model the 92 differences between development, staging, and production. However, if you have 93 one large Terraform configuration, it is riskier and not recommended to use 94 environments to model those differences. 95 96 The [terraform_remote_state](/docs/providers/terraform/d/remote_state.html) 97 resource accepts an `environment` name to target. Therefore, you can link 98 together multiple independently managed Terraform configurations with the same 99 environment easily. But, they can also have different environments. 100 101 While environments are available to all, 102 [Terraform Enterprise](https://www.hashicorp.com/products/terraform/) 103 provides an interface and API for managing sets of configurations linked 104 with `terraform_remote_state` and viewing them all as a single environment. 105 106 Environments alone are useful for isolating a set of resources to test 107 changes during development. For example, it is common to associate a 108 branch in a VCS with an environment so new features can be developed 109 without affecting the default environment. 110 111 Future Terraform versions and environment enhancements will enable 112 Terraform to track VCS branches with an environment to help verify only certain 113 branches can make changes to a Terraform environment. 114 115 ## Environments Internals 116 117 Environments are technically equivalent to renaming your state file. They 118 aren't any more complex than that. Terraform wraps this simple notion with 119 a set of protections and support for remote state. 120 121 For local state, Terraform stores the state environments in a folder 122 `terraform.tfstate.d`. This folder should be committed to version control 123 (just like local-only `terraform.tfstate`). 124 125 For [remote state](/docs/state/remote.html), the environments are stored 126 directly in the configured [backend](/docs/backends). For example, if you 127 use [Consul](/docs/backends/types/consul.html), the environments are stored 128 by suffixing the state path with the environment name. To ensure that 129 environment names are stored correctly and safely in all backends, the name 130 must be valid to use in a URL path segment without escaping. 131 132 The important thing about environment internals is that environments are 133 meant to be a shared resource. They aren't a private, local-only notion 134 (unless you're using purely local state and not committing it). 135 136 The "current environment" name is stored only locally in the ignored 137 `.terraform` directory. This allows multiple team members to work on 138 different environments concurrently.