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

layout	page_title	sidebar_current	description
docs	State: Environments	docs-state-env	Terraform stores state which caches the known state of the world the last time Terraform ran.

State Environments

An environment is a state namespace, allowing a single folder of Terraform configurations to manage multiple distinct infrastructure resources.

Terraform state determines what resources it manages based on what exists in the state. This is how terraform plan determines what isn't created, what needs to be updated, etc. The full details of state can be found on the purpose page.

Environments are a way to create multiple states that contain their own data so a single set of Terraform configurations can manage multiple distinct sets of resources.

Using Environments

Terraform starts with a single environment named "default". This environment is special both because it is the default and also because it cannot ever be deleted. If you've never explicitly used environments, then you've only ever worked on the "default" environment.

Environments are managed with the terraform env set of commands. To create a new environment and switch to it, you can use terraform env new, to switch environments you can use terraform env select, etc.

For example, creating an environment:

$ terraform env create bar
Created and switched to environment "bar"!

You're now on a new, empty environment. Environments isolate their state,
so if you run "terraform plan" Terraform will not see any existing state
for this configuration.

As the command says, if you run terraform plan, Terraform will not see any existing resources that existed on the default (or any other) environment. These resources still physically exist, but are managed by another Terraform environment.

Best Practices

An environment alone should not be used to manage the difference between development, staging, and production. While it is technically possible, it is much more manageable and safe to use multiple independently managed Terraform configurations linked together with terraform_remote_state data sources.

The terraform_remote_state resource accepts an environment name to target. Therefore, you can link together multiple independently managed Terraform configurations with the same environment easily. But, they can also have different environments.

While environments are available to all, Terraform Enterprise provides an interface and API for managing sets of configurations linked with terraform_remote_state and viewing them all as a single environment.

Environments alone are useful for isolating a set of resources to test changes during development. For example, it is common to associate a branch in a VCS with an environment so new features can be developed without affecting the default environment.

Future Terraform versions and environment enhancements will enable Terraform to track VCS branches with an environment to help verify only certain branches can make changes to a Terraform environment.

Environments Internals

Environments are technically equivalent to renaming your state file. They aren't any more complex than that. Terraform wraps this simple notion with a set of protections and support for remote state.

For local state, Terraform stores the state environments in a folder terraform.state.d. This folder should be committed to version control (just like local-only terraform.tfstate).

For remote state, the environments are stored directly in the configured backend. For example, if you use Consul, the environments are stored by suffixing the state path with the environment name.

The important thing about environment internals is that environments are meant to be a shared resource. They aren't a private, local-only notion (unless you're using purely local state and not committing it).

The "current environment" name is stored only locally in the ignored .terraform directory. This allows multiple team members to work on different environments concurrently.