# 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[Read more](/design-patterns/version-management/source-based-versioning)

## Usage

```shell
atmos aws cloudformation source <subcommand> [options]
```

## Subcommands

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

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

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

```yaml
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:

```yaml
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.
  ```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`.

## Examples

### Vendor a Component

Download and vendor a component source:

```shell
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:

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

### View Source Configuration

Display the source configuration for a component:

```shell
atmos aws cloudformation source describe vpc --stack dev
```

Output:

```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/**"
```

### List Components with Sources

List all components that have source configured:

```shell
atmos aws cloudformation source list --stack dev
```

### Delete Vendored Source

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

```shell
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:

```yaml
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:

```shell
atmos aws cloudformation 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:
  "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:

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

```yaml
source:
  uri: github.com/cloudposse/cloudformation-aws-components//modules/vpc
  version: 1.0.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
```

## 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
- [`atmos aws cloudformation`](/cli/commands/aws/cloudformation) — Parent command overview
- [Vendoring](/vendor) — Pre-vendor components for immutability and audit trails