# Provision Defaults

The `settings.provision` block sets global defaults for component provisioning. Today this controls the default workdir behavior — whether workdirs are created automatically, and how long unused workdirs persist before they become candidates for cleanup. Settings here apply to every component unless overridden at the toolchain or component level.

> **Key points**
>
> - Set `provision.workdir.enabled` once at the global level instead of per-component
> - Document the intended TTL for workdir cleanup (note: `atmos terraform workdir clean --expired` currently requires explicit `--ttl` flag)
> - Toolchain and component overrides still take precedence
> - For per-component configuration, see [Workdir Provisioning](/stacks/components/provision/workdir)

## Configuration

**File:** `atmos.yaml`

```yaml
settings:
  provision:
    workdir:
      # Enable workdir provisioning for every component by default.
      enabled: true
      # Default time-to-live for workdirs (e.g., "7d", "24h", "weekly").
      ttl: "7d"
```

## Configuration Reference

- **`settings.provision.workdir.enabled`**

  Global default for whether components run inside an isolated workdir under `.workdir/<componentType>/<stack>-<componentName>/`. When enabled, every component instance gets its own working directory, allowing concurrent runs without conflicts on `.terraform/`, lockfiles, or generated varfiles.

  Component-level and toolchain-level settings override this default; a component can opt out with `provision.workdir.enabled: false`.
  - **Type:** `boolean`
  - **Default:** `false`
- **`settings.provision.workdir.ttl`**

  Documents the intended time-to-live for workdirs. This setting expresses how long workdirs should persist before becoming candidates for cleanup. Currently, the `atmos terraform workdir clean --expired` command still requires an explicit `--ttl` flag to operate, regardless of whether this setting is configured.

  Usage example:
  ```bash
  # Even with settings.provision.workdir.ttl configured in atmos.yaml,
  # the CLI currently requires --ttl:
  atmos terraform workdir clean --expired --ttl 7d
  ```
  - **Type:** `string`
  - **Default:** (none — `atmos terraform workdir clean --expired` currently requires the `--ttl` flag)

## Precedence

Provisioning settings are deep-merged across three levels (lower overrides higher):

1. Global — `settings.provision` (this page)
2. Toolchain — `terraform.provision`, `helmfile.provision`, `packer.provision`, `ansible.provision`
3. Component — `components.<type>.<name>.provision`

> **Note**
>
> There is no global `settings.provision.backend` today. Backend provisioning is opted in per component (or per toolchain) because it has stronger side effects (creating cloud resources). See [Backend Provisioning](/stacks/components/provision/backend) for backend provisioning details.

## See Also

- [Workdir Provisioning](/stacks/components/provision/workdir) — Per-component workdir configuration and conceptual treatment
- [Backend Provisioning](/stacks/components/provision/backend) — Per-component backend provisioning and automatic state backend creation
- [`atmos terraform workdir`](/cli/commands/terraform/workdir) — CLI commands for managing workdirs
- [Settings](/cli/configuration/settings) — Overview of all settings