github.com/kjmkznr/terraform@v0.5.2-0.20180216194316-1d0f5fdac99e/website/docs/state/workspaces.html.md (about) 1 --- 2 layout: "docs" 3 page_title: "State: Workspaces" 4 sidebar_current: "docs-state-workspaces" 5 description: |- 6 Workspaces allow the use of multiple states with a single configuration directory. 7 --- 8 9 # Workspaces 10 11 A _workspace_ is a named container for Terraform state. With multiple 12 workspaces, a single directory of Terraform configuration can be used to 13 manage multiple distinct sets of infrastructure resources. 14 15 Terraform state determines what resources it manages based on what 16 exists in the state. This is how `terraform plan` determines what isn't 17 created, what needs to be updated, etc. The full details of state can be 18 found on [the _purpose_ page](/docs/state/purpose.html). 19 20 Multiple workspaces are currently supported by the following backends: 21 22 * [AzureRM](/docs/backends/types/azurerm.html) 23 * [Consul](/docs/backends/types/consul.html) 24 * [GCS](/docs/backends/types/gcs.html) 25 * [Local](/docs/backends/types/local.html) 26 * [Manta](/docs/backends/types/manta.html) 27 * [S3](/docs/backends/types/s3.html) 28 29 In the 0.9 line of Terraform releases, this concept was known as "environment". 30 It was renamed in 0.10 based on feedback about confusion caused by the 31 overloading of the word "environment" both within Terraform itself and within 32 organizations that use Terraform. 33 34 ## Using Workspaces 35 36 Terraform starts with a single workspace named "default". This 37 workspace is special both because it is the default and also because 38 it cannot ever be deleted. If you've never explicitly used workspaces, then 39 you've only ever worked on the "default" workspace. 40 41 Workspaces are managed with the `terraform workspace` set of commands. To 42 create a new workspace and switch to it, you can use `terraform workspace new`; 43 to switch environments you can use `terraform workspace select`; etc. 44 45 For example, creating a new workspace: 46 47 ```text 48 $ terraform workspace new bar 49 Created and switched to workspace "bar"! 50 51 You're now on a new, empty workspace. Workspaces isolate their state, 52 so if you run "terraform plan" Terraform will not see any existing state 53 for this configuration. 54 ``` 55 56 As the command says, if you run `terraform plan`, Terraform will not see 57 any existing resources that existed on the default (or any other) workspace. 58 **These resources still physically exist,** but are managed in another 59 Terraform workspace. 60 61 ## Current Workspace Interpolation 62 63 Within your Terraform configuration, you may include the name of the current 64 workspace using the `${terraform.workspace}` interpolation sequence. This can 65 be used anywhere interpolations are allowed. 66 67 Referencing the current workspace is useful for changing behavior based 68 on the workspace. For example, for non-default workspaces, it may be useful 69 to spin up smaller cluster sizes. For example: 70 71 ```hcl 72 resource "aws_instance" "example" { 73 count = "${terraform.workspace == "default" ? 5 : 1}" 74 75 # ... other arguments 76 } 77 ``` 78 79 Another popular use case is using the workspace name as part of naming or 80 tagging behavior: 81 82 ```hcl 83 resource "aws_instance" "example" { 84 tags { 85 Name = "web - ${terraform.workspace}" 86 } 87 88 # ... other arguments 89 } 90 ``` 91 92 ## Best Practices 93 94 Workspaces can be used to manage small differences between development, 95 staging, and production, but they **should not** be treated as the only 96 isolation mechanism. As Terraform configurations get larger, it's much more 97 manageable and safer to split one large configuration into many 98 smaller ones linked together with the `terraform_remote_state` data source. 99 This allows teams to delegate ownership and reduce the potential impact of 100 changes. For *each* smaller configuration, you can use workspaces to model 101 the differences between development, staging, and production. However, if you 102 have one large Terraform configuration, it is riskier and not recommended to 103 use workspaces to handle those differences. 104 105 [The `terraform_remote_state` data source](/docs/providers/terraform/d/remote_state.html) 106 accepts a `workspace` name to target. Therefore, you can link 107 together multiple independently managed Terraform configurations with the same 108 environment easily, with each configuration itself having multiple workspaces. 109 110 While workspaces are available to all, 111 [Terraform Enterprise](https://www.hashicorp.com/products/terraform/) 112 provides an interface and API for managing sets of configurations linked 113 with `terraform_remote_state` and viewing them all as a single environment. 114 115 Workspaces alone are useful for isolating a set of resources to test 116 changes during development. For example, it is common to associate a 117 branch in a VCS with a temporary workspace so new features can be developed 118 without affecting the default workspace. 119 120 Future Terraform versions and workspace enhancements will enable 121 Terraform to track VCS branches with a workspace to help verify only certain 122 branches can make changes to a Terraform workspace. 123 124 ## Workspace Internals 125 126 Workspaces are technically equivalent to renaming your state file. They 127 aren't any more complex than that. Terraform wraps this simple notion with 128 a set of protections and support for remote state. 129 130 For local state, Terraform stores the workspace states in a directory called 131 `terraform.tfstate.d`. This directory should be be treated similarly to 132 local-only `terraform.tfstate`); some teams commit these files to version 133 control, although using a remote backend instead is recommended when there are 134 multiple collaborators. 135 136 For [remote state](/docs/state/remote.html), the workspaces are stored 137 directly in the configured [backend](/docs/backends). For example, if you 138 use [Consul](/docs/backends/types/consul.html), the workspaces are stored 139 by appending the environment name to the state path. To ensure that 140 workspace names are stored correctly and safely in all backends, the name 141 must be valid to use in a URL path segment without escaping. 142 143 The important thing about workspace internals is that workspaces are 144 meant to be a shared resource. They aren't a private, local-only notion 145 (unless you're using purely local state and not committing it). 146 147 The "current workspace" name is stored only locally in the ignored 148 `.terraform` directory. This allows multiple team members to work on 149 different workspaces concurrently.