# atmos terraform source

Use these commands to manage Terraform component sources with just-in-time (JIT) vendoring. This enables components to declare their source location inline using the top-level `source` field without requiring a separate `component.yaml` file. Sources are automatically provisioned when running terraform commands—just run `atmos terraform plan` and the source is downloaded on first use.

**Source-Based Version Pinning**

Learn how to use the source field for native per-environment version control directly in stack configuration.

Design Pattern[Read more](/design-patterns/version-management/source-based-versioning)

## Usage

```shell
atmos terraform source <subcommand> [options]
```

## Subcommands

## Automatic Provisioning

Sources are automatically provisioned when running any terraform command. If a component has `source` configured and the target directory doesn't exist, Atmos downloads the source before running terraform:

```shell
# Source is automatically provisioned on first use
atmos terraform plan vpc --stack dev
# → Auto-provisioning source for component 'vpc'
# → Auto-provisioned source to components/terraform/vpc
# → Terraform runs
```

This means you can simply configure your component's source and run terraform—no explicit vendor step needed.

## CLI Commands

The explicit CLI commands are useful for fine-grained control:

- Force re-vendor to get the latest version
- Describe source configuration
- Delete vendored sources
- List components with sources

### Explicit working directory

For source components with workdir provisioning enabled, `metadata.working_directory` takes precedence
over `settings.working_directory`, then the generated workdir path. Relative overrides resolve from
the Atmos base path, including commands invoked from a nested directory.

This behavior starts with edition `2026-10-28`; earlier edition pins retain the generated path. If the
previous workdir still contains files, Atmos stops before switching paths. Explicitly migrate the whole
workdir and its state, or retain the earlier edition pin. Advancing an edition never moves state automatically.

Dry-run Terraform commands resolve the intended directory without fetching source or creating a workdir.

## How It Works

The source provisioner enables just-in-time vendoring of Terraform components directly from stack configuration. Instead of pre-vendoring components or maintaining separate `component.yaml` files, you can declare the source inline:

```yaml
# stacks/dev.yaml
components:
  terraform:
    vpc:
      source:
        uri: github.com/cloudposse/terraform-aws-components//modules/vpc
        version: 1.450.0
        included_paths:
          - "*.tf"
          - "modules/**"
        excluded_paths:
          - "*.md"
          - "tests/**"
      vars:
        cidr_block: "10.0.0.0/16"
```

When you run `atmos terraform source pull vpc --stack dev`, Atmos:

1. **Reads Configuration** - Extracts `source` from the component's stack manifest.
2. **Resolves Source** - Parses the go-getter-compatible URI with optional version.
3. **Downloads Content** - Fetches the source using go-getter (supports git, s3, http, oci, etc.).
4. **Filters Files** - Applies `included_paths` and `excluded_paths` patterns.
5. **Copies to Target** - Places files in the component directory.

## Source Specification

The `source` field supports two formats:

### String Format (Simple)

For simple cases, use a go-getter URI string:

```yaml
source: "github.com/cloudposse/terraform-aws-components//modules/vpc?ref=1.450.0"
```

### Map Format (Full Control)

For more control, use a map with explicit fields:

```yaml
source:
  uri: github.com/cloudposse/terraform-aws-components//modules/vpc
  version: 1.450.0
  included_paths:
    - "*.tf"
    - "*.tfvars"
    - "modules/**"
  excluded_paths:
    - "*.md"
    - "tests/**"
    - "examples/**"
```

### Source Fields

- **`uri`** — Go-getter compatible source URI. Supports git, s3, http, gcs, oci, and other protocols.
- **`version`** — Version tag, branch, or commit. Appended as `?ref=<version>` for git sources. For non-git sources (S3, HTTP, OCI), the version should be embedded in the URI itself.
- **`included_paths`** — Glob patterns for files to include. If specified, only matching files are copied.
- **`excluded_paths`** — Glob patterns for files to exclude. Applied after included\_paths filtering.
- **`ttl`** — Cache duration for JIT-vendored sources. Controls how long a cached source is reused before re-pulling from the remote. When set, Atmos checks the source's last update time against this TTL. If expired, the source is re-pulled automatically on the next command invocation. If not set, cached sources are reused indefinitely (only re-pulled on version or URI changes).

  Examples: `"0s"` (always re-pull), `"1h"` (hourly), `"7d"` (weekly), `"daily"`.

  A global default can be set in `atmos.yaml` under `components.terraform.source.ttl` and overridden per-component.
- **`retry`** — Optional retry configuration for handling transient network errors during download. Useful for unreliable networks or when hitting rate limits.
  ```yaml
  retry:
    max_attempts: 5
    initial_delay: 2s
    max_delay: 60s
    backoff_strategy: exponential
  ```
  All fields are optional. Recommended: `max_attempts`, `initial_delay`, `max_delay`, `backoff_strategy` (`exponential`, `linear`, `constant`). Additional options: `multiplier`, `random_jitter`, `max_elapsed_time`.

  When `retry` is omitted, git downloads still retry transient transport failures — a DNS lookup that fails, a connection refused or reset, a timeout, or a TLS handshake error — up to 3 attempts in total, with exponential backoff (1s initial delay, 8s maximum, multiplier 2.0, 20% random jitter — each overridable through the matching `retry` field). Missing refs are never retried. Authentication failures fail fast, except when Atmos brokered the credential itself (for example a GitHub App installation token), where a short post-issue retry window applies. Set `max_attempts: 1` to disable retrying entirely.

## Examples

### Vendor a Component

Download and vendor a component source:

```shell
atmos terraform source pull vpc --stack dev
```

Output:

```
Vendoring component 'vpc' from source...
Downloading from github.com/cloudposse/terraform-aws-components//modules/vpc?ref=1.450.0
✓ Successfully vendored component to components/terraform/vpc
```

### Force Re-vendor

Force re-download even if the component directory exists:

```shell
atmos terraform source pull vpc --stack dev --force
```

### View Source Configuration

Display the source configuration for a component:

```shell
atmos terraform source describe vpc --stack dev
```

Output:

```yaml
components:
  terraform:
    vpc:
      source:
        uri: github.com/cloudposse/terraform-aws-components//modules/vpc
        version: 1.450.0
        included_paths:
          - "*.tf"
          - "modules/**"
        excluded_paths:
          - "*.md"
          - "tests/**"
```

### List Components with Sources

List all components that have source configured:

```shell
atmos terraform source list --stack dev
```

### Delete Vendored Source

Remove the vendored component directory (requires --force for safety):

```shell
atmos terraform source delete vpc --stack dev --force
```

## Arguments

- **`component`** — The Atmos component name (required for pull, describe, delete)

## Flags

- **`--stack` / `-s`** — Atmos stack name (required). Can also be set via `ATMOS_STACK` environment variable.
- **`--identity` / `-i`** — Identity to use for authentication when downloading from protected sources.
- **`--force` / `-f`** — Force re-vendor even if component directory exists (pull command), or confirm deletion (delete command).

## Authentication

Source commands support authentication for accessing private repositories or cloud storage.

### Component-Level Identity

Components can specify an authentication identity:

```yaml
components:
  terraform:
    vpc:
      source:
        uri: github.com/my-org/private-components//modules/vpc
        version: v1.0.0
      auth:
        identities:
          github-deployer:
            default: true
            kind: github/app
            via:
              provider: github-app
```

### Identity Flag Override

Override the component's default identity:

```shell
atmos terraform source pull vpc --stack dev --identity admin
```

For more details on configuring authentication identities, see the [Authentication Guide](/stacks/auth).

## Configuration Patterns

### Inheritance with source

Use stack inheritance to share source configurations:

```yaml
# stacks/catalog/vpc/defaults.yaml
components:
  terraform:
    vpc/defaults:
      source:
        uri: github.com/cloudposse/terraform-aws-components//modules/vpc
        version: 1.450.0

# stacks/dev.yaml
components:
  terraform:
    vpc:
      metadata:
        inherits: [vpc/defaults]
      # Inherits source configuration
      vars:
        cidr_block: "10.0.0.0/16"
```

### Version Override per Environment

Override the version per environment:

```yaml
# stacks/dev.yaml
components:
  terraform:
    vpc:
      metadata:
        inherits: [vpc/defaults]
      source:
        version: 1.451.0  # Override version for dev

# stacks/prod.yaml
components:
  terraform:
    vpc:
      metadata:
        inherits: [vpc/defaults]
      source:
        version: 1.450.0  # Pin to stable version for prod
```

## Supported Source Types

The source provisioner uses go-getter and supports multiple protocols:

### Git Sources

Shortened GitHub syntax (recommended):

```yaml
source:
  uri: github.com/cloudposse/terraform-aws-components//modules/vpc
  version: 1.450.0
```

Explicit HTTPS:

```yaml
source:
  uri: git::https://github.com/org/repo.git//path
  version: main
```

Explicit SSH:

```yaml
source:
  uri: git::ssh://git@github.com/org/repo.git//path
  version: main
```

### S3 Sources

```yaml
source:
  uri: s3::https://s3-us-east-1.amazonaws.com/my-bucket/components/vpc.tar.gz
```

### HTTP/HTTPS Sources

```yaml
source:
  uri: https://releases.example.com/components/vpc-1.0.0.tar.gz
```

### OCI Registry Sources

```yaml
source:
  uri: oci://registry.example.com/components/vpc:v1.0.0
```

## Error Handling

### Missing source

```
Error: source not configured

Hint: Add source to the component configuration in your stack manifest

Example:
  components:
    terraform:
      vpc:
        source:
          uri: github.com/cloudposse/terraform-aws-components//modules/vpc
          version: 1.450.0
```

### Component Directory Exists

```
Error: component directory already exists

Hint: Use --force to overwrite the existing directory
```

### Download Failed

```
Error: failed to download source

Cause: failed to clone repository: authentication required

Hint: Check credentials or use --identity to specify authentication
```

## Comparison with Vendoring

| Feature | source | component.yaml |
|---------|--------|----------------|
| Configuration location | Inline in stack | Separate file |
| Version per environment | Yes | Single version |
| JIT download | Yes | Pre-vendored |
| Path filtering | Yes | Yes |
| Mixins support | No | Yes |

_Mixins allow combining multiple source configurations into a single component. See [Vendoring](/vendor) for details._

Use `source` when:

- You want version control per environment
- You prefer configuration colocation in stacks
- You need just-in-time vendoring

Use `component.yaml` when:

- You need mixin support
- You want pre-vendored components
- You have complex vendoring requirements

## Try it out

### source-provisioning

Copy the example into a new directory and make it your own:

```shell
atmos init examples/source-provisioning
cd source-provisioning
```

Inspect the local and remote component sources without provisioning them.

```shell
atmos terraform source list
```

- [Installation guide](/install)
- [Explore the example](/examples/source-provisioning)
- [Initialization and repository settings](/cli/commands/init#examples-and-source-directories)

## See Also

- [Source-Based Version Pinning](/design-patterns/version-management/source-based-versioning) — Design pattern for per-environment version management
- [Stack Configuration](/learn/stacks) — Learn about Atmos stacks
- [Vendoring](/vendor) — Pre-vendor components for immutability and audit trails
- [Vendoring Design Pattern](/design-patterns/version-management/vendoring-components) — When explicit vendoring makes sense
- [`atmos vendor pull`](/cli/commands/vendor/pull) — Traditional component vendoring
