Skip to main content

atmos terraform workspace

Use this command to calculate the terraform workspace for an Atmos component (from the context variables and stack config). It will run terraform init -reconfigure and then select the workspace by executing the terraform workspace select command.

atmos terraform workspace --help

Usage​

Execute the terraform workspace command like this:

atmos terraform workspace <component> -s <stack>

This command calculates the terraform workspace for an Atmos component (from the context variables and stack config), then runs terraform init -reconfigure, then selects the workspace by executing the terraform workspace select command.

If the workspace does not exist, the command creates it by executing the terraform workspace new command.

tip

Run atmos terraform workspace --help to see all the available options

Configuration​

Configure workspace behavior in your atmos.yaml:

components:
  terraform:
    # Run 'terraform init -reconfigure' when selecting workspace
    init_run_reconfigure: true

    # Enable workspace management
    workspaces_enabled: true

These settings can also be controlled via environment variables:

export ATMOS_COMPONENTS_TERRAFORM_INIT_RUN_RECONFIGURE=true
export ATMOS_COMPONENTS_TERRAFORM_WORKSPACES_ENABLED=true

The recommended way to ensure stable workspace keys is using metadata.name for logical component identity:

# stacks/catalog/vpc.yaml
components:
  terraform:
    vpc/defaults:
      metadata:
        type: abstract
        name: vpc              # Convention: top-level folder
        component: vpc/v2      # Version can change

# stacks/prod/us-east-1.yaml
import:
  - catalog/vpc

components:
  terraform:
    vpc:
      metadata:
        inherits: [vpc/defaults]
        # workspace_key_prefix auto-generates as "vpc" from inherited metadata.name
      vars:
        cidr_block: "10.0.0.0/16"

This keeps state paths stable when upgrading component versions. See folder-based versioning for details.

Advanced: Dynamic Workspace Naming​

For advanced use cases requiring dynamic workspace keys, workspace_key_prefix supports Go templates. This is configured at the stack level, not in atmos.yaml:

components:
  terraform:
    vpc:
      backend:
        # Use Go templates for dynamic workspace key prefix
        workspace_key_prefix: "{{.vars.namespace}}-{{.vars.environment}}-{{.vars.stage}}"

This allows you to construct workspace names dynamically based on stack variables, providing flexible workspace organization strategies.

Examples​

atmos terraform workspace top-level-component1 -s tenant1-ue2-dev
atmos terraform workspace infra/vpc -s tenant1-ue2-staging
atmos terraform workspace test/test-component -s tenant1-ue2-dev
atmos terraform workspace test/test-component-override-2 -s tenant2-ue2-prod
atmos terraform workspace test/test-component-override-3 -s tenant1-ue2-dev

Arguments​

component (required)

Atmos terraform component.

Flags​

--stack (alias -s) (required)

Atmos stack.

--dry-run (optional)

Dry run.

atmos terraform workspace <component> -s <stack> --dry-run=true
--process-templates (optional)

Enable/disable Go template processing in Atmos stack manifests when executing terraform commands.

If the flag is not passed, template processing is enabled by default.

atmos terraform workspace <component> -s <stack> --process-templates=false
--process-functions (optional)

Enable/disable YAML functions processing in Atmos stack manifests
when executing terraform commands.

If the flag is not passed, YAML function processing is enabled by default.

atmos terraform workspace <component> -s <stack> --process-functions=false
--skip (optional)

Skip processing a specific Atmos YAML function in Atmos stacks manifests when executing terraform commands.

To specify more than one function, use multiple --skip flags, or separate the functions with a comma.

atmos terraform workspace <component> -s <stack> --skip=eval --skip=include
atmos terraform workspace <component> -s <stack> --skip=terraform.output,include