Lesson 6 of 7 in Infrastructure as Code with Terraform and OpenTofu
Dev, staging and prod: environments and workspaces
An environment is a separate copy of your infrastructure, such as dev, staging or prod. In Terraform/OpenTofu you separate them with CLI workspaces, which give one configuration several state files, or with separate folders and backends, which give each environment its own configuration and state.
Draft. This lesson is written and waiting for a person to run every command and review it. It is safe to learn from, but check the official documentation for anything you depend on.
Read these first: State, drift and locking, Modules: reusing configuration safely
The problem this solves
You want to test a change in dev before it reaches production. That means the same code must build more than one copy, and a mistake in dev must not be able to touch prod.
Two common answers exist, and each has costs. Neither is correct for every team, so you need to know what each one separates and what it leaves shared.
How it works
- Control
- Data
One configuration and one backend hold a separate state for each workspace, so dev and prod are separate copies that share credentials.
- One config to State: dev: select workspace dev
- One config to State: prod: select workspace prod
- Control
- Data
Each environment folder has its own backend and its own credentials, so a run in dev cannot reach prod state or resources.
- envs/dev to dev state: reads and writes
- envs/prod to prod state: reads and writes
A workspace is a named state inside the same backend. You switch with terraform workspace select, and the config can read terraform.workspace to vary names or sizes. It is quick, and it needs no code duplication.
The catch is that workspaces share the same backend and the same credentials. The Terraform documentation says they are not a suitable isolation mechanism when deployments need different credentials and access controls. It is also easy to forget which workspace is selected.
With separate folders, each environment has a small root configuration that calls shared modules and sets its own inputs. It repeats a little code. In return each environment can have its own backend, its own access rules and its own review process.
A reasonable rule: workspaces for temporary copies of the same thing, such as a short-lived test copy. Separate folders or backends for environments that need to be protected from each other, especially production.
Try it yourself
You will see workspaces with local files. Local state is stored under terraform.tfstate.d/. Nothing here touches any cloud.
- 1A config that uses the workspace name
mkdir -p ~/iac-lab/envs && cd ~/iac-lab/envs cat > main.tf <<"EOF" terraform { required_providers { local = { source = "hashicorp/local" } } } resource "local_file" "env" { filename = format("%s.txt", terraform.workspace) content = format("I belong to the %s workspace", terraform.workspace) } EOF terraform init terraform workspace showEvery folder starts in the workspace named
default. - 2Create and use two workspaces
terraform workspace new dev terraform apply -auto-approve terraform workspace new prod terraform apply -auto-approve ls *.txt
You should see
dev.txtandprod.txt.workspace newalso switches to the new workspace. - 3See the separate states
terraform workspace list ls terraform.tfstate.d
The star marks the selected workspace. Each workspace has its own folder holding its state.
- 4Clean up both
terraform destroy -auto-approve terraform workspace select dev terraform destroy -auto-approve terraform workspace select default terraform workspace delete dev terraform workspace delete prod
You cannot delete the workspace you are in, so select
defaultfirst. Deleting a workspace that still has resources in state is refused unless you force it, which is why destroy comes first.
What breaks, and where to look
You ran apply and changed prod when you meant dev.
- WHY IT HAPPENS
- The selected workspace was prod. Nothing in the command shows the workspace, and workspaces share credentials, so nothing stopped it.
- CHECK FIRST
- Run
terraform workspace showbefore every plan and apply. For protected environments use separate folders with separate credentials, so the wrong run is impossible.
Workspace "dev" is not empty. (shown when you delete a workspace that still has resources in state)
- WHY IT HAPPENS
- The workspace's state still lists resources, so deleting it would orphan real objects.
- CHECK FIRST
- Select that workspace, run
terraform state list, and destroy first. Use-forceonly when you accept losing track of the objects.
When not to use this
- Do not use workspaces to separate production from everything else if the environments need different accounts, credentials or approvers.
- Separate folders cost some duplication. Keep them small by moving the shared logic into modules and leaving only inputs and backend settings in each environment.
Check yourself
What does a CLI workspace separate and what does it share?
It separates the state. It shares the configuration, the backend and the credentials.
Why are separate folders safer for production?
Each folder can have its own backend and credentials, so a run in one environment cannot reach another.
How do you see which workspace is active?
terraform workspace show, and terraform workspace list marks it with a star.
Keep going
Lesson 68 of 92 in the DevOps path