atmos aws cloudformation source

Use these commands to manage aws/cloudformation 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 aws cloudformation commands—just run atmos aws cloudformation 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 aws cloudformation source --help

Usage

atmos aws cloudformation source <subcommand> [options]

Subcommands

source delete

Remove vendored source directory

source describe

Show source configuration for a component

source list

List aws/cloudformation components with source configuration

source pull

Vendor component source from source configuration

Automatic Provisioning

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

# Source is automatically provisioned on first use
atmos aws cloudformation plan vpc --stack dev
# → Auto-provisioning source for component 'vpc'
# → Auto-provisioned source to components/cloudformation/vpc
# → CloudFormation operation runs

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

CLI Commands

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

• Force re-vendor the already-configured source (re-downloads the same source.uri/source.version; to pick up a newer revision, update source.version or the URI in stack configuration first)
• Describe source configuration
• Delete vendored sources
• List components with sources

How It Works

The source provisioner enables just-in-time vendoring of aws/cloudformation 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:
  "aws/cloudformation":
    vpc:
      source:
        uri: github.com/cloudposse/cloudformation-aws-components//modules/vpc
        version: 1.0.0
        included_paths:
          - "*.yaml"
          - "modules/**"
        excluded_paths:
          - "*.md"
          - "tests/**"
      stack_name: vpc-dev

When you run atmos aws cloudformation 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/cloudformation-aws-components//modules/vpc?ref=1.0.0"

Map Format (Full Control)

For more control, use a map with explicit fields:

source:
  uri: github.com/cloudposse/cloudformation-aws-components//modules/vpc
  version: 1.0.0
  included_paths:
    - "*.yaml"
    - "*.json"
    - "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."aws/cloudformation".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 aws cloudformation source pull vpc --stack dev

Output:

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

Force Re-vendor

Force re-download even if the component directory exists:

atmos aws cloudformation source pull vpc --stack dev --force

View Source Configuration

Display the source configuration for a component:

atmos aws cloudformation source describe vpc --stack dev

Output:

components:
  "aws/cloudformation":
    vpc:
      source:
        uri: github.com/cloudposse/cloudformation-aws-components//modules/vpc
        version: 1.0.0
        included_paths:
          - "*.yaml"
          - "modules/**"
        excluded_paths:
          - "*.md"
          - "tests/**"

List Components with Sources

List all components that have source configured:

atmos aws cloudformation source list --stack dev

Delete Vendored Source

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

atmos aws cloudformation 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 (pull only).

--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:
  "aws/cloudformation":
    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 aws cloudformation 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:
  "aws/cloudformation":
    vpc/defaults:
      source:
        uri: github.com/cloudposse/cloudformation-aws-components//modules/vpc
        version: 1.0.0

# stacks/dev.yaml
components:
  "aws/cloudformation":
    vpc:
      metadata:
        inherits: [vpc/defaults]
      # Inherits source configuration
      stack_name: vpc-dev

Version Override per Environment

Override the version per environment:

# stacks/dev.yaml
components:
  "aws/cloudformation":
    vpc:
      metadata:
        inherits: [vpc/defaults]
      source:
        version: 1.1.0  # Override version for dev

# stacks/prod.yaml
components:
  "aws/cloudformation":
    vpc:
      metadata:
        inherits: [vpc/defaults]
      source:
        version: 1.0.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/cloudformation-aws-components//modules/vpc
  version: 1.0.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

See Also

• Source-Based Version Pinning — Design pattern for per-environment version management
• Stack Configuration — Learn about Atmos stacks
• atmos aws cloudformation — Parent command overview
• Vendoring — Pre-vendor components for immutability and audit trails