Workdir Provisioning

provision.workdir creates an isolated working directory for each component instance under .workdir/<componentType>/<stack>-<componentName>/. The component source is staged into this directory and all toolchain commands execute there, enabling concurrent execution and just-in-time source provisioning without .terraform/, lockfile, or generated-varfile collisions.

Experimental

Schema

provision.workdir.enabled

Create an isolated working directory for each component instance.

• Type: boolean
• Default: false
• Applies to: Terraform, Helmfile, Packer, and Ansible components

Configuration

Enable workdir provisioning for any supported toolchain:

stacks/catalog/_defaults.yaml

components:
  terraform:
    vpc:
      provision:
        workdir:
          enabled: true
      vars:
        cidr_block: "10.0.0.0/16"

  helmfile:
    nginx:
      provision:
        workdir:
          enabled: true
      vars:
        replicas: 3

Directory Layout

When workdir provisioning is enabled, Atmos creates a per-component-instance directory under .workdir/ and runs all toolchain commands there. Each instance gets its own .terraform/, varfiles, and state cache.

.workdir/
├── terraform/
│   └── prod-ue1-vpc/        # <stack>-<componentName>
│       ├── .terraform/
│       ├── .atmos/metadata.json
│       └── ... (component source)
└── helmfile/
    └── prod-ue1-nginx/
        └── ...

NOTE:

The .workdir/ directory is created at runtime and should be added to .gitignore. It is not used by atmos describe affected for change detection — that command tracks the source files in components/<type>/<name>/, not the runtime workdir.

Toolchain-Level Defaults

Apply workdir provisioning to every component of a toolchain:

stacks/orgs/acme/plat/dev/_defaults.yaml

terraform:
  provision:
    workdir:
      enabled: true   # Every Terraform component in this stack gets an isolated workdir

helmfile:
  provision:
    workdir:
      enabled: true   # Every Helmfile component runs in its own workdir

Component-Level Overrides

Opt a single component out of a toolchain or global default by setting enabled: false:

stacks/orgs/acme/plat/dev/us-east-1.yaml

components:
  terraform:
    legacy-vpc:
      provision:
        workdir:
          enabled: false   # Run in the original component directory
      vars:
        # ...

Global Defaults

Set workdir defaults globally for every stack and component via the settings.provision block in atmos.yaml:

atmos.yaml

settings:
  provision:
    workdir:
      enabled: true       # Default for every component, every stack
      ttl: "7d"           # Auto-clean workdirs not accessed for 7 days

settings.provision.workdir.enabled

Global default for provision.workdir.enabled. Toolchain-level and component-level settings still override this.

settings.provision.workdir.ttl

Time-to-live for workdirs (e.g., "7d", "24h", "weekly"). Workdirs not accessed within this duration become candidates for cleanup by atmos terraform workdir clean --expired.

For the full reference of the global settings page, see Settings: Provision Defaults.

Managing Workdirs

Use the atmos terraform workdir commands to inspect and clean up workdirs:

Command	Purpose
atmos terraform workdir list	List all workdirs
atmos terraform workdir show <component> -s <stack>	Show details for a specific workdir
atmos terraform workdir clean --expired --ttl=7d	Remove workdirs not accessed within the TTL
atmos terraform workdir clean --all	Remove every workdir (forces re-provisioning on next run)

Related

• Backend Provisioning — The other half of the provision: block
• Settings: Provision Defaults — Global workdir defaults in atmos.yaml
• atmos terraform workdir — CLI commands for managing workdirs
• Terraform CLI Configuration — auto_provision_workdir_for_outputs and other global Terraform settings