How is the `terraform.workspace` value typically used inside a Terraform configuration, and where does driving behaviour from it start to hurt?

## What the expression is `terraform.workspace` is one of the handful of values Terraform exposes about the run itself. It evaluates to the **name of the currently selected CLI workspace** as a plain string — `"default"` unless you selected another. It is known during plan, so it can appear in `count`, in resource arguments, in `locals`, and in module inputs. ## The two idioms you will actually see **Naming and tagging.** The most common use is disambiguating globally-unique names when several copies of one stack live in the same account: ```hcl resource "aws_s3_bucket" "artifacts" { bucket = "acme-artifacts-${terraform.workspace}" tags = { Environment = terraform.workspace } } ``` **Lookup tables.** Rather than sprinkling conditionals, the configuration keeps one map in `locals` and indexes it: ```hcl locals { sizes = { default = "t3.small" dev = "t3.micro" } instance_type = lookup(local.sizes, terraform.workspace, "t3.micro") } ``` Note the default argument. A bare `local.sizes[terraform.workspace]` fails the moment somebody creates a workspace nobody added to the map — an error that only appears in the new workspace, which is precisely the class of bug this expression invites. ## Where it hurts: derived immutable attributes When the workspace name feeds an attribute the provider cannot update in place — a bucket name, an RDS identifier — the resource's identity is now a function of *which state you selected*. Rename the workspace and the next plan is a destroy-and-create, not a rename. Copy the stack into another workspace and you get an entirely new set of resources, which may well be what you wanted, but the config no longer says so anywhere a reviewer can see. Prefer an explicit input: ```hcl variable "environment" { type = string } ``` and pass `-var-file=dev.tfvars`. Now the environment is a reviewable input rather than an implicit consequence of an untracked CLI selection. ## Where it hurts more: divergent code paths The deeper problem is what conditionals on the workspace do to your confidence. If the configuration contains `count = terraform.workspace == "prod" ? 3 : 1`, or worse a whole block that only exists in one workspace, then the code exercised in `dev` is *not* the code that will run in `prod`. A clean plan and apply in the cheap workspace stops being evidence about the expensive one, which is the main thing you were hoping to buy by using the same configuration for both. The same applies to policy checks and tests: a scanner or a `terraform test` run against one workspace's plan only sees the branch that workspace takes. ## What it cannot do `terraform.workspace` is an expression, so it is unavailable where Terraform forbids expressions — most importantly inside a `backend` block, which must be static and is resolved before any workspace exists. You cannot select a different bucket or a different account per workspace this way; that requires separate root configurations or partial backend configuration passed at `init`. This limit is what pushes teams toward directory-per-environment once environments genuinely differ. ## The pragmatic rule Use `terraform.workspace` for **cosmetics** — names, prefixes, tags — in stacks where workspaces hold ephemeral copies. Use **input variables** for anything that changes what gets built. If you find yourself writing more than one or two conditionals on the workspace name, the configuration is telling you these are different environments that deserve different root modules.