github.com/sixgill/terraform@v0.9.0-beta2.0.20170316214032-033f6226ae50/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 new 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 ## Current Environment Interpolation 51 52 Within your Terraform configuration, you may reference the current environment 53 using the `${terraform.env}` interpolation variable. This can be used anywhere 54 interpolations are allowed. 55 56 Referencing the current environment is useful for changing behavior based 57 on the environment. For example, for non-default environments, it may be useful 58 to spin up smaller cluster sizes. You can do this: 59 60 ``` 61 resource "aws_instance" "example" { 62 count = "${terraform.env == "default" ? 5 : 1}" 63 64 # ... other fields 65 } 66 ``` 67 68 Another popular use case is using the environment as part of naming or 69 tagging behavior: 70 71 ``` 72 resource "aws_instance" "example" { 73 tags { Name = "web - ${terraform.env}" } 74 75 # ... other fields 76 } 77 ``` 78 79 ## Best Practices 80 81 An environment alone **should not** be used to manage the difference between 82 development, staging, and production. While it is technically possible, it is 83 much more manageable and safe to use multiple independently managed Terraform 84 configurations linked together with 85 [terraform_remote_state](/docs/providers/terraform/d/remote_state.html) 86 data sources. 87 88 The [terraform_remote_state](/docs/providers/terraform/d/remote_state.html) 89 resource accepts an `environment` name to target. Therefore, you can link 90 together multiple independently managed Terraform configurations with the same 91 environment easily. But, they can also have different environments. 92 93 While environments are available to all, 94 [Terraform Enterprise](https://www.hashicorp.com/products/terraform/) 95 provides an interface and API for managing sets of configurations linked 96 with `terraform_remote_state` and viewing them all as a single environment. 97 98 Environments alone are useful for isolating a set of resources to test 99 changes during development. For example, it is common to associate a 100 branch in a VCS with an environment so new features can be developed 101 without affecting the default environment. 102 103 Future Terraform versions and environment enhancements will enable 104 Terraform to track VCS branches with an environment to help verify only certain 105 branches can make changes to a Terraform environment. 106 107 ## Environments Internals 108 109 Environments are technically equivalent to renaming your state file. They 110 aren't any more complex than that. Terraform wraps this simple notion with 111 a set of protections and support for remote state. 112 113 For local state, Terraform stores the state environments in a folder 114 `terraform.state.d`. This folder should be committed to version control 115 (just like local-only `terraform.tfstate`). 116 117 For [remote state](/docs/state/remote.html), the environments are stored 118 directly in the configured [backend](/docs/backends). For example, if you 119 use [Consul](/docs/backends/types/consul.html), the environments are stored 120 by suffixing the state path with the environment name. 121 122 The important thing about environment internals is that environments are 123 meant to be a shared resource. They aren't a private, local-only notion 124 (unless you're using purely local state and not committing it). 125 126 The "current environment" name is stored only locally in the ignored 127 `.terraform` directory. This allows multiple team members to work on 128 different environments concurrently.