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.

Experimental

Source-Based Version Pinning

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

Design Pattern

atmos terraform source --help

Usage

atmos terraform source <subcommand> [options]

Subcommands

📄️ source delete

Remove vendored source directory

📄️ source describe

Show source configuration for a component

📄️ source list

List Terraform components with source configuration

📄️ source pull

Vendor component source from source configuration

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:

# 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

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:

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

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:

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.

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.

Examples

Vendor a Component

Download and vendor a component source:

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:

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

View Source Configuration

Display the source configuration for a component:

atmos terraform source describe vpc --stack dev

Output:

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:

atmos terraform source list --stack dev

Delete Vendored Source

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

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:

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:

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

For more details on configuring authentication identities, see the Authentication Guide.

Configuration Patterns

Inheritance with source

Use stack inheritance to share source configurations:

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

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

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

Explicit HTTPS:

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

Explicit SSH:

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

S3 Sources

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

HTTP/HTTPS Sources

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

OCI Registry Sources

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

See Also

• Source-Based Version Pinning — Design pattern for per-environment version management
• Stack Configuration — Learn about Atmos stacks
• Vendoring — Pre-vendor components for immutability and audit trails
• Vendoring Design Pattern — When explicit vendoring makes sense
• atmos vendor pull — Traditional component vendoring