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

Dynamic Workspace Naming

The workspace_key_prefix backend configuration supports Go templates for dynamic workspace naming. 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