Skip to main content

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. Commands that load a component template can provision its source on first use; for example, run atmos aws cloudformation plan.

Experimental
Source-Based Version Pinning

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

atmos aws cloudformation source --help

Usage​

atmos aws cloudformation source <subcommand> [options]

Subcommands​

Automatic Provisioning​

The template-loading commands render, validate, diff/plan, apply/deploy, fmt, and changeset create provision a configured source when needed before loading the template. source pull explicitly downloads the source. source delete, source describe, and source list manage or inspect source state without downloading it. Dry runs do not provision sources.

For example, if a component has source configured and its target directory doesn't exist:

# 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 without prompting (--force skips confirmation; omit it to confirm interactively):

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

Omitting the component and stack requests interactive selection before deletion confirmation:

atmos aws cloudformation source delete

Selection requires interactive mode, terminal input, and available candidates, and is disabled in CI. For unattended deletion, use the explicit component, --stack, and --force invocation above; --force does not bypass missing-value validation.

Arguments​

component
The Atmos component name. For pull, describe, and delete, provide it explicitly or select it interactively when a candidate is available. For list, it is an optional filter; omit it to list all components with sources.

Flags​

--stack / -s
Atmos stack name, also settable via ATMOS_STACK. For pull, describe, and delete, an unset stack triggers interactive selection when available; non-interactive use requires a stack value. For list, the stack is an optional filter; omit it to list across stacks.
--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 skip deletion confirmation (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​