Workspaces, Environments and Project Structure

Source: Terraform Docs — terraform workspace, Terraform Docs — workspace new, Terraform Docs — workspace select, Terraform Docs — workspace delete

The output above is abbreviated and illustrative. The commands change which state the following plan and apply read and write, and nothing else: they do not copy configuration, variables or credentials.

Source: Terraform Docs — CLI workspaces

Source: Terraform Docs — Workspaces

Inside the configuration, terraform.workspace is a string with the name of the selected workspace. It can be used wherever an expression is allowed, for example to select a settings object from a map or to build a name. OpenTofu keeps the same name.

Source: Terraform Docs — Workspaces

The lookup local.settings[terraform.workspace] is deliberate. An unknown key makes the plan fail, which is much safer than a conditional such as terraform.workspace == "prod" ? 4 : 1 that silently treats every other name (including a typo) as the small case. The documentation’s own examples use the same name in count expressions and in tags.

TF_WORKSPACE selects a workspace without running terraform workspace select. The documentation recommends it only for non-interactive use, because a forgotten export in a shell profile makes later commands apply to the wrong state. A pipeline that runs one job per environment can set it in the job definition.

Source: Terraform Docs — Environment variables

The official CLI workspaces page is explicit about the limits, and they are the reason this page spends most of its length on other mechanisms.

The conclusion in the official text is that workspaces let you switch quickly between multiple instances of a single configuration within its single backend, and that they are not designed to solve every problem. Good uses are short-lived copies of one stack: a per-branch review environment of a single service in the same account, a copy of a stack to test a migration, or a scratch environment created and destroyed within a day. For long-lived, differently-privileged environments the documentation points to a configuration (a directory) per deployment with its own backend, sharing modules, and to terraform_remote_state, tag-based data source lookups or DNS to share data between them.

Source: Terraform Docs — CLI workspaces

The documentation of the remote backend and of the cloud block adds one more subtlety: with the legacy remote backend in prefix mode terraform.workspace can mean different things for local and remote operations, which is one more reason to prefer the cloud block (see Backends and Remote State).

Workspace names must be unique within the organization and can contain letters, numbers, hyphens and underscores. The documentation recommends 90 characters or fewer, and suggests a consistent pattern that combines component, environment and region, for example networking-prod-us-east. A workspace created from a VCS workflow defaults to the repository name. Every workspace belongs to a project.

For Bookshelf the pattern is <component>-<environment>: network-dev, database-dev, services-dev, network-prod, database-prod and services-prod. This follows the style guide, which recommends a separate workspace per environment and, for large codebases, splitting resources by component (prod-compute, prod-database, prod-networking).

Source: HCP Terraform Docs — Create workspaces

A project is a folder that holds one or more workspaces, Stacks, or both. Projects organize resources and scope access: a team can be given a role on a project (this needs a paid edition that supports project permissions) instead of on each workspace. Creating projects needs a team with the Manage all projects permission. The documentation also lists these project-level settings:

Source: HCP Terraform Docs — Manage projects

A natural Bookshelf layout is two projects, bookshelf-dev and bookshelf-prod, each holding the three workspaces for that environment. The platform team gets admin on both, the application teams get write on bookshelf-dev and plan-only on bookshelf-prod, and the production credentials exist only as sensitive variables (or dynamic credentials) in the bookshelf-prod workspaces.

A configuration connects to HCP Terraform with the cloud block inside the terraform block (details in Backends and Remote State). Its workspaces argument selects either one workspace by name, or a set of workspaces by tags; the two cannot be combined. workspaces.project narrows the match to a project. If no workspace matches the tags during initialization, the CLI offers to create one with those tags.

Source: Terraform Docs — Connect to HCP Terraform

With tags, the same directory can serve several workspaces and terraform workspace select chooses between them; with name the directory is bound to one workspace. TF_CLOUD_ORGANIZATION, TF_CLOUD_PROJECT and TF_WORKSPACE can supply the values from the environment, so one directory can be reused by different pipelines without edits. HCP Terraform stores workspace tags as key-value pairs or key-only tags. Tags must have between one and 255 characters, using letters, numbers, colons, hyphens and underscores, and creating or updating them needs plan permission or higher on the workspace.

Source: HCP Terraform Docs — Workspace tags

Per-environment values and credentials in HCP Terraform live in the workspace, or in variable sets: reusable groups of variables that can be applied to every workspace of the organization, to selected projects or Stacks, or to selected workspaces (a set owned by a project can be applied to the whole project or to some of its workspaces). The documented precedence is:

Files named terraform.tfvars or ending in .auto.tfvars in the configuration are loaded on each run but are not saved to the workspace and do not show in the UI. Sensitive variables are write-only: their value cannot be read through the UI or the API, only replaced. Variable sets are not evaluated for workspaces that use local execution mode.

Source: HCP Terraform Docs — Manage variables and variable sets

The organization’s own structure should itself be code. The hashicorp/tfe provider has resources for projects and workspaces. The example creates the bookshelf-prod project and one workspace in it; the organization name is a placeholder and the token comes from terraform login or the TFE_TOKEN environment variable, never from the file.

Source: Terraform Registry — tfe_project resource, Terraform Registry — tfe_workspace resource

The registry page for tfe_workspace documents that setting the execution mode and agent pool directly on the workspace is deprecated in favour of the separate tfe_workspace_settings and tfe_organization_default_settings resources, and that the same property must not be managed in both tfe_workspace and tfe_workspace_settings, because it causes permanent drift. terraform_version accepts an exact version or a constraint; with a constraint the workspace always uses the newest release that satisfies it. working_directory is the relative path in which Terraform runs and defaults to the repository root, which is how one repository with envs/dev and envs/prod directories is mapped onto several workspaces.

Each environment is one root module (the layout above, envs/dev and envs/prod). It is easy to understand and cheap to operate for a small system, because one apply converges one whole environment. The cost is a large blast radius and a long plan: a typo in the reviews-api service change is planned and applied together with the network and the database, and a refresh touches every resource.

Each component or layer is a root module with its own state, and each environment is an instance of that root module:

State becomes small and the blast radius shrinks: a change to the services layer cannot recreate the database. The layers are joined by outputs. The services root reads values published by network and data through terraform_remote_state (covered in Backends and Remote State), through a data source that looks the objects up by tag or name, or through a shared parameter store. The official CLI workspaces page itself lists these alternatives (key/value stores, tag-based lookups and DNS) next to terraform_remote_state, which needs read access to the whole state of the producer.

Source: Terraform Docs — The terraform_remote_state data source

The trade-offs are an ordering requirement (network before data before services, which Terraform cannot infer across states, so a pipeline or Terragrunt or a Stack must encode it), more directories and more pipeline jobs, and the need to keep the published outputs a stable contract. Terraform Stacks (Terraform Stacks) exist to describe exactly this arrangement of components and deployments in one place.

A pragmatic path is to start with environment-as-root and split a layer out when it has a different change cadence, a different owner or a noticeably higher risk. The database is usually the first candidate, because a mistake there is the most expensive.

Terraform loads variable values from several sources and applies a fixed precedence (it is described in detail, with a diagram, in Variables, Outputs and Locals). For environments the relevant part is: terraform.tfvars, terraform.tfvars.json and any *.auto.tfvars or *.auto.tfvars.json file in the working directory are loaded automatically, later sources win, and -var-file and -var on the command line override them, with TF_VAR_name environment variables ranking just below those. A file such as prod.tfvars is not loaded automatically, so the pipeline must pass -var-file=prod.tfvars explicitly, which is the point: the choice of environment is visible in the command.

Source: Terraform Docs — Input variables

Defaults in variables.tf should be the safe, cheap value (one replica, no multi-AZ) so that forgetting a value in dev costs little. A variable that must be decided for each environment (such as environment or vpc_cidr) has no default, so that omitting it is an error instead of a silent choice. Secrets never go into a .tfvars file that is committed: pass them with TF_VAR_ environment variables from the pipeline’s secret store or, better, read them at run time from a secrets manager and use ephemeral or write-only values where the provider supports them (see Sensitive Data, Ephemeral and Write-only Values).

The one place that cannot be made DRY with variables is the backend block. The documentation states that the backend block cannot refer to named values such as input variables, locals or data sources. The standard workaround is partial configuration: leave the environment-specific arguments out of the block and supply them with -backend-config= files or flags at init time.

Source: Terraform Docs — Backend configuration, Terraform Docs — terraform init

OpenTofu relaxed this restriction. Since OpenTofu 1.8 early evaluation allows input variables and locals in the backend block, module sources and encryption configuration, so an OpenTofu project can write key = "bookshelf/${var.environment}/terraform.tfstate" directly. The details and the version in which each part appeared are in Backends and Remote State and OpenTofu. A configuration that must run on both tools should keep to partial configuration.

Source: OpenTofu Docs — Backend configuration

Teams sometimes symlink variables.tf or providers.tf from a common directory into every environment. It works, but symlinks are fragile on Windows, invisible in some code-review tools and confusing for editors, and Terraform itself offers nothing to manage them. If you find yourself building that, it is a signal to look at Terragrunt (below), at Stacks, or at HCP Terraform with one repository and one workspace per environment.

Terragrunt is worth considering when the system has many environments, many components per environment, the same backend and provider boilerplate everywhere and a need to run several roots in dependency order. It adds a second configuration language layer, a second binary to version and install in CI, its own documentation and its own failure modes, and it can hide what Terraform actually executes. Two alternatives cover part of the same ground: HCP Terraform workspaces with run triggers and the tfe provider for the platform side, and Terraform Stacks, which describe components and deployments natively in the product (see Terraform Stacks). For a system the size of Bookshelf, plain directories and modules are enough; Terragrunt becomes attractive when the number of root modules reaches the dozens.

The syntax shown above follows the current Terragrunt documentation; its command line and conventions change between releases, so check the documentation for the version in use.

Resource names inside the cloud provider are the identity that humans and tools see. A consistent scheme such as <application>-<environment>-<component>[-<suffix>] (bookshelf-prod-covers, bookshelf-dev-catalog-api) makes ownership and environment obvious in consoles, bills and logs. Build the prefix once in a local value, so it cannot drift:

Source: Terraform Docs — Style guide

Globally unique names (object storage buckets, DNS zones, registry names) need a suffix that the environment alone does not provide, such as an account identifier or a short random value from the random provider (see Resources and Data Sources). Mind the length and character limits of each service; a prefix built from four variables is easy to push past a 63-character limit.

Tags (called labels in Google Cloud) carry the metadata that names cannot: owner, cost centre, environment, data classification and the fact that Terraform manages the object. A small mandatory set, enforced by policy or by a check, is better than a long optional one. For Bookshelf: Application, Environment, Owner, CostCentre and ManagedBy.

In the AWS provider the way to avoid repeating the set on every resource is the default_tags block in the provider configuration. The documentation states that the tags apply to all resources the provider manages that support tags (with an exception for aws_autoscaling_group), that a resource’s own tags are merged with them, that a resource can override a default by using the same key but cannot exclude one, and that the merged result is visible in the tags_all attribute while tags shows only the resource-level tags. Default tags can also be supplied through TF_AWS_DEFAULT_TAGS_<tag_key> environment variables, with the provider configuration winning on a conflict. The provider-level ignore_tags block hides tag keys or key prefixes that another system adds (a cost-allocation tool, for example), but a resource that still sets an ignored key shows a perpetual difference.

Source: Terraform Registry — AWS provider

Other providers may not offer an equivalent block, in which case a common_tags local value merged into each resource with merge() is the portable pattern; check each provider’s documentation for what it supports. See the cloud-specific pages Terraform on AWS, Terraform on Azure and Terraform on Google Cloud.

HCP Terraform has its own tagging layer: key-value tags on projects and workspaces (inherited from the project, up to the limits above) and on private registry modules, used to filter lists and, through the cloud block, to select workspaces.

Use the same words everywhere. If the environment is prod in the directory (envs/prod), in the state key (bookshelf/prod/terraform.tfstate), in the HCP Terraform workspace (database-prod), in the variable (the variable environment) and in the tag, then a person looking at any one of them can find the others. Mixing prod, production and prd is the most common naming defect and costs a surprising amount of debugging time.