# 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.

## Usage

Execute the `terraform workspace` command like this:

```shell
atmos terraform workspace <component> -s <stack> [subcommand] [options]
```

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
:::

## Subcommands

## Configuration

Configure workspace behavior in your `atmos.yaml`:

```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:

```shell
export ATMOS_COMPONENTS_TERRAFORM_INIT_RUN_RECONFIGURE=true
export ATMOS_COMPONENTS_TERRAFORM_WORKSPACES_ENABLED=true
```

### Recommended: Stable Keys with metadata.name

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

```yaml
# 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](/design-patterns/version-management/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`:

```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

```shell
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.
  ```shell
  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.
  ```shell
  atmos terraform workspace <component> -s <stack> --process-templates=false
  ```
- **`--process-functions` (optional)**

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

  If the flag is not passed, YAML function processing is enabled by default.
  ```shell
  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.
  ```shell
  atmos terraform workspace <component> -s <stack> --skip=eval --skip=include
  atmos terraform workspace <component> -s <stack> --skip=terraform.output,include
  ```

## Related Commands

- [terraform init](/cli/commands/terraform/init) - Initialize a Terraform working directory
- [terraform plan](/cli/commands/terraform/plan) - Generate an execution plan
- [terraform shell](/cli/commands/terraform/shell) - Start a shell in the component's context