Skip to main content

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.

atmos terraform source --help
 

Usage​

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:

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

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

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:

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​

Featuresourcecomponent.yaml
Configuration locationInline in stackSeparate file
Version per environmentYesSingle version
JIT downloadYesPre-vendored
Path filteringYesYes
Mixins supportNoYes

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

Try it out​

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

atmos init examples/source-provisioning
cd source-provisioning

Inspect the local and remote component sources without provisioning them.

atmos terraform source list

See Also​