What Terraform CLI workspaces are, how state is stored per workspace, how to vary configuration with terraform.workspace, why HashiCorp warns against using them to separate production, and the alternatives.

A Terraform workspace is a separate state file for the same configuration. Running terraform workspace new staging gives the working directory a second, empty state, and every plan and apply after terraform workspace select staging reads and writes that state instead of the default one. One set of .tf files can then manage a staging copy and a production copy of the same infrastructure.
The command takes seconds to learn. The design questions start with what changes between workspaces and what happens when someone applies in the wrong one. HashiCorp's own workspace documentation is direct about whether one backend and one set of credentials should be able to touch both staging and production.
This guide covers the workspace commands and state layout, a worked configuration that varies by terraform.workspace, the directory-per-environment alternative, and how Encore provisions environments from application code.
Encore brings infrastructure from code. The databases, buckets, topics and cron jobs your services declare are provisioned per environment, so staging and production come from the same code without a state file per environment. Each environment has a type, a deploy trigger, an optional infrastructure approval step, and its own cloud account if you want it. Cron jobs are managed by the Encore platform and do not run locally or in preview environments.

Run in your terminal to get started locally.
The bucket below becomes a separate S3 or Cloud Storage bucket in every environment. Behavior that should differ, such as whether emails go to real customers, is configuration loaded by the service:
// Service billing sends invoices. Its infrastructure is declared here, once,
// and every environment gets its own copy.
package billing
import (
"context"
"encore.dev"
"encore.dev/config"
"encore.dev/storage/objects"
)
// The same declaration becomes a separate bucket in every environment.
var Invoices = objects.NewBucket("invoices", objects.BucketConfig{})
// Behavior that differs per environment lives in config, not in infrastructure code.
type Config struct {
SendRealEmails config.Bool
MaxBatchSize config.Int
}
var cfg = config.Load[*Config]()
type Settings struct {
Environment string `json:"environment"`
EnvType string `json:"env_type"`
SendRealEmails bool `json:"send_real_emails"`
MaxBatchSize int `json:"max_batch_size"`
}
//encore:api public method=GET path=/billing/settings
func GetSettings(ctx context.Context) (*Settings, error) {
env := encore.Meta().Environment
return &Settings{
Environment: env.Name,
EnvType: string(env.Type),
SendRealEmails: cfg.SendRealEmails(),
MaxBatchSize: cfg.MaxBatchSize(),
}, nil
}
The values come from a CUE file in the service directory. Defaults apply everywhere, and a condition on the environment type overrides them for production:
// billing/config.cue // Defaults for every environment, including local and preview environments. SendRealEmails: bool | *false MaxBatchSize: int | *50 // Production gets real emails and bigger batches. if #Meta.Environment.Type == "production" { SendRealEmails: true MaxBatchSize: 1000 }
We ran this app with encore run: the local environment reported type development, send_real_emails: false and a batch size of 50. Production environments get true and 1000 from the same files, and secrets are set per environment type with encore secret set.
There is no workspace to select, so there is no way to apply staging's plan to production. Infrastructure for an environment changes when that environment deploys, and an environment configured for infrastructure approval waits for someone to approve infrastructure changes before it deploys. A coding agent working on a branch gets a Preview Environment for its pull request rather than a new workspace in the production backend.
Best fit: Application infrastructure, such as databases, queues, buckets and cron jobs, where every environment should be a copy of what the code declares, with staging and production in your own AWS or GCP account.
Workspaces are managed with the terraform workspace commands. Every working directory starts in a workspace called default:
With the S3 backend, the default workspace's state lives at the configured key and every other workspace at env:/<workspace>/<key> in the same bucket. Inside the configuration, terraform.workspace returns the current name, which is how one configuration sizes staging and production differently:
terraform {
required_providers {
aws = {
source = "hashicorp/aws"
version = "~> 6.0"
}
}
backend "s3" {
bucket = "acme-terraform-state"
key = "billing-api/terraform.tfstate"
region = "eu-central-1"
use_lockfile = true
}
}
provider "aws" {
region = "eu-central-1"
}
locals {
env = terraform.workspace
# One entry per workspace. A workspace without an entry fails at plan time.
settings = {
staging = {
instance_class = "db.t4g.medium"
multi_az = false
min_tasks = 1
}
production = {
instance_class = "db.m7g.large"
multi_az = true
min_tasks = 3
}
}
cfg = local.settings[local.env]
}
resource "aws_db_instance" "main" {
identifier = "billing-${local.env}"
engine = "postgres"
engine_version = "17"
instance_class = local.cfg.instance_class
allocated_storage = 50
multi_az = local.cfg.multi_az
username = "billing_admin"
manage_master_user_password = true
storage_encrypted = true
deletion_protection = local.env == "production"
skip_final_snapshot = local.env != "production"
}
output "db_endpoint" {
value = aws_db_instance.main.address
}
This configuration passes terraform validate in the staging workspace. In default, even validate fails with Invalid index, since there is no default entry in settings, which is a cheap guard against applying from the workspace nobody meant to use. We also applied a provider-free version with a local backend: staging and production each got their own state file under terraform.tfstate.d/ and their own values.
The workspace is a CLI setting, so the target of an apply is whatever terraform workspace show says at that moment. Every workspace shares one backend, which means whoever can plan staging can also read and write production's state, and HashiCorp states that CLI workspaces are not a suitable isolation mechanism when deployments need different credentials and access controls. Differences between environments also accumulate as conditionals on terraform.workspace, which get harder to read as they grow.
The common alternative keeps the resources in a module and gives each environment its own root module, backend and role:
infra/ modules/ billing/ # resources, variables, outputs envs/ staging/ main.tf # module "billing" { source = "../../modules/billing" ... } backend.tf # its own state bucket or key, its own role production/ main.tf backend.tf
Workspaces stay useful for short-lived copies: a per-branch test stack, a load-test environment, or a developer's sandbox that shares production's shape but not its account.
Best fit: Workspaces for temporary parallel copies of a stack; directories with separate backends for staging and production.
Use CLI workspaces for disposable copies of the same stack, and guard the default workspace so nothing applies there by accident. Use a directory, backend and role per environment once production needs its own credentials and access controls. Pick Encore for the application layer when you want staging and production provisioned from the code your services already declare, in your own AWS or GCP account, and a preview for each pull request hosted by Encore.
A CLI workspace is a named state file for the same configuration and backend. terraform workspace new staging creates an empty state next to the default one, and every plan and apply then reads and writes that state, so one configuration can manage several copies of the same infrastructure.
No. Not when you need strong separation. HashiCorp's documentation advises against it in that case: CLI workspaces in a working directory share one backend, so they share its credentials and access controls. Separate configurations per environment, each with its own backend and role, are the usual pattern for production.
The default workspace uses the configured key. Other workspaces are stored under env:/<workspace>/<key> in the same bucket, and the env: prefix can be changed with workspace_key_prefix.
Staging and production are provisioned from the same application code in your own AWS or GCP account. Preview environments for pull requests are hosted by Encore and are also built from that code. Per-environment behavior goes in config files keyed on the environment type, and infrastructure changes can require manual approval per environment.
Deploy to your cloud on AWS and Google Cloud
without managing infrastructure
Encore lets developers and agents define application infrastructure directly in code, then automatically provisions it from local development to production in your AWS or GCP account.