Lesson 6 of 7 in Infrastructure as Code with Terraform and OpenTofu

Dev, staging and prod: environments and workspaces

Advanced10 min

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

CLI workspaces: one config, several states
CLI workspaces: one config, several statesOne configuration and one backend hold a separate state for each workspace, so dev and prod are separate copies that share credentials.select workspace devselect workspace prodOne configsame code and backendState: devworkspace devState: prodworkspace prod
  • Control
  • Data

One configuration and one backend hold a separate state for each workspace, so dev and prod are separate copies that share credentials.

  1. One config to State: dev: select workspace dev
  2. One config to State: prod: select workspace prod
Separate folders: full isolation per environment
Separate folders: full isolation per environmentEach environment folder has its own backend and its own credentials, so a run in dev cannot reach prod state or resources.reads and writesreads and writesenvs/devown credentialsdev stateown backendenvs/prodown credentialsprod stateown backend
  • Control
  • Data

Each environment folder has its own backend and its own credentials, so a run in dev cannot reach prod state or resources.

  1. envs/dev to dev state: reads and writes
  2. 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.

  1. 1
    A 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 show

    Every folder starts in the workspace named default.

  2. 2
    Create 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.txt and prod.txt. workspace new also switches to the new workspace.

  3. 3
    See 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.

  4. 4
    Clean 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 default first. 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 show before 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 -force only 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.

Lesson 68 of 92 in the DevOps path

Search

Search cheat sheets and projects