# Generate Terraform Backend

The `backend` section generates Terraform backend configuration files (`backend.tf.json`)
for your components. Define backend settings once in your stacks and Atmos generates
the appropriate files for each environment.

## How It Works

When you run any `atmos terraform` command, Atmos:

1. Reads your `backend` and `backend_type` configuration from the stack
2. Deep-merges settings from all inherited stack manifests
3. Generates a `backend.tf.json` file in the component directory
4. Terraform uses this file to configure state storage

This separation means your Terraform modules stay clean—no hardcoded backend
configuration in your source code.

:::tip Generated Files
Add `backend.tf.json` to your `.gitignore` since these files are generated automatically by Atmos and should not be committed to version control:

```gitignore
# Atmos generated files
backend.tf.json
```

Some automation systems may require the generated file to be committed—in those cases,
committing `backend.tf.json` is acceptable.
:::

## Use Cases

- **State Management:** Configure S3, Azure Blob, GCS, or other backends for remote state storage.
- **Environment Isolation:** Use different state storage per environment or account.
- **State Locking:** Configure native locking (`use_lockfile`) or DynamoDB for legacy setups.
- **Remote State Access:** Configure `remote_state_backend` for cross-component state references.

## Configuration Scopes

Backend settings can be defined at multiple levels, with more specific scopes
overriding broader ones:

| Scope | Example File | Effect |
|-------|-------------|--------|
| Organization | `stacks/orgs/acme/_defaults.yaml` | All components inherit |
| Account/Stage | `stacks/orgs/acme/plat/prod/_defaults.yaml` | Override for prod |
| Component-type | Under `terraform:` in any stack | All Terraform components |
| Component | Under `components.terraform.<name>:` | Single component |

### Component-Type Level

Backend settings defined under `terraform` apply to all Terraform components:

### Stack Configuration

```yaml title="stacks/orgs/acme/_defaults.yaml"
terraform:
  backend_type: s3
  backend:
    s3:
      bucket: acme-ue1-root-tfstate
      region: us-east-1
      encrypt: true
      use_lockfile: true
```

### Generated File

```json title="components/terraform/vpc/backend.tf.json"
{
  "terraform": {
    "backend": {
      "s3": {
        "bucket": "acme-ue1-root-tfstate",
        "region": "us-east-1",
        "encrypt": true,
        "use_lockfile": true,
        "key": "ue1/prod/vpc/terraform.tfstate"
      }
    }
  }
}
```

### Component Level

Backend settings within a component override the defaults:

### Stack Configuration

```yaml title="stacks/orgs/acme/plat/prod/us-east-1.yaml"
components:
  terraform:
    special-component:
      backend_type: s3
      backend:
        s3:
          bucket: acme-ue1-prod-special-tfstate
          key: "special/terraform.tfstate"
```

### Generated File

```json title="components/terraform/special-component/backend.tf.json"
{
  "terraform": {
    "backend": {
      "s3": {
        "bucket": "acme-ue1-prod-special-tfstate",
        "key": "special/terraform.tfstate"
      }
    }
  }
}
```

## Related

- [Terraform Backend Configuration](/stacks/components/terraform/backend) - Component-level backend defaults
- [Terraform Backends](/components/terraform/backends) - Conceptual overview and inheritance
- [Backend Provisioning](/stacks/components/provision/backend) - Automatic backend creation
- [Remote State](/stacks/remote-state) - Reading state from other components
- [Terraform Workspaces](/components/terraform/workspaces)