Atmos Packer Orchestration

Atmos wraps the Packer CLI to provide stack-aware orchestration of machine image builds. Instead of manually managing variable files, template paths, and environment configuration for each Packer component, Atmos resolves the full configuration from stack manifests and handles all of these concerns automatically.

How Atmos Orchestrates Packer

When you run any atmos packer command, Atmos performs the following sequence:

1. Resolves stack configuration -- Reads and deep-merges all stack manifests to produce the fully resolved configuration for the target component in the target stack.
2. Generates variable file -- Writes a variable file containing all vars defined for the component in the stack, making them available to the Packer template.
3. Auto-provisions source (if configured) -- If the component has a source field and the target directory does not exist, Atmos downloads the component via JIT vendoring before proceeding.
4. Resolves template path -- Determines the Packer template to use from the --template flag, settings.packer.template in the stack manifest, or defaults to . (all *.pkr.hcl files).
5. Sets environment variables -- Applies any env values defined in the stack configuration.
6. Executes the requested command -- Runs packer init, build, validate, inspect, etc. with the generated variable file and any additional flags.

This means a single command like atmos packer build ubuntu-base -s ue2-dev replaces what would normally require manually writing variable files, configuring paths, and running packer directly.

Stack Configuration

Packer components are configured under the components.packer section of stack manifests:

components:
  packer:
    ubuntu-base:
      metadata:
        type: real
        component: ubuntu-base

      settings: {}

      vars:
        ami_name: "ubuntu-base"
        instance_type: "t3.medium"
        source_ami_filter_name: "ubuntu/images/hvm-ssd/ubuntu-jammy-22.04-amd64-server-*"

      env:
        PACKER_LOG: "1"

Configuration Attributes

• vars -- Variables passed to Packer. These are deep-merged across the stack hierarchy and made available to Packer templates. This is the primary way to parameterize builds per stack.

• metadata -- Extends component functionality. Supports type (real/abstract), component (physical component path), and inherits (list of parent components for configuration inheritance).

• settings -- Free-form map for integration configuration. The settings.packer.template field controls which template file or directory Packer uses.

• env -- Environment variables set when running Packer commands. Common examples include PACKER_LOG, AWS_PROFILE, and AWS_REGION.

Core Commands

init

Initializes Packer and installs plugins according to an HCL template configuration.

atmos packer init <component> -s <stack>

# Basic init
atmos packer init aws/bastion --stack nonprod

# Init with a specific template file
atmos packer init aws/bastion -s prod --template main.pkr.hcl

# Init with shorthand flags
atmos packer init aws/bastion -s nonprod -t main.nonprod.pkr.hcl

build

Processes a Packer template and builds it to generate a set of artifacts. Builds within a template execute in parallel by default. A Packer manifest (if configured) is updated with the build results.

atmos packer build <component> -s <stack>

# Directory mode (default) -- loads all *.pkr.hcl files from the component directory
atmos packer build aws/bastion --stack nonprod

# Explicit directory mode
atmos packer build aws/bastion --stack prod --template .

# Single file mode
atmos packer build aws/bastion -s prod --template main.pkr.hcl
atmos packer build aws/bastion -s nonprod -t main.nonprod.pkr.hcl

validate

Validates the syntax and configuration of a Packer template before building.

atmos packer validate <component> -s <stack>

atmos packer validate aws/bastion --stack prod
atmos packer validate aws/bastion -s prod --template main.pkr.hcl
atmos packer validate aws/bastion -s nonprod -t main.nonprod.pkr.hcl

inspect

Inspects the components of a Packer template, showing variables it accepts, builders it defines, provisioners and their execution order, and post-processors.

atmos packer inspect <component> -s <stack>

atmos packer inspect aws/bastion --stack nonprod
atmos packer inspect aws/bastion -s prod --template main.pkr.hcl

output

Retrieves output from a Packer manifest. Manifests are generated by Packer during build commands when configured with a manifest post-processor. Supports YQ expressions for extracting specific sections or attributes.

atmos packer output <component> -s <stack> [--query <yq-expression>]

This command is specific to Atmos -- Packer itself does not have an output command.

# Get full manifest output
atmos packer output aws/bastion -s prod

# Get a specific attribute using YQ expression
atmos packer output aws/bastion -s prod --query '.builds[0].artifact_id'

# Extract just the AMI ID from the artifact
atmos packer output aws/bastion -s prod -q '.builds[0].artifact_id | split(":")[1]'

version

Displays the currently installed Packer version.

atmos packer version

Template Management

Atmos supports two modes for specifying which Packer template files to use:

Directory Mode (Default)

When no --template flag is specified, Packer loads all *.pkr.hcl files from the component directory. This is the recommended approach for components with multiple HCL files.

Single File Mode

Use --template (or -t) to point to a specific template file. This is useful when a component directory contains multiple template variants (e.g., main.pkr.hcl and main.nonprod.pkr.hcl).

Template Configuration in Stack Manifests

The template can be set in the stack manifest under settings.packer.template. The command-line --template flag takes precedence over the stack manifest setting.

components:
  packer:
    aws/bastion:
      settings:
        packer:
          template: main.pkr.hcl

Source Management and JIT Vendoring

Atmos supports just-in-time (JIT) vendoring of Packer components using the source field. Instead of pre-vendoring components or maintaining separate vendoring configuration, you declare the source inline in your stack manifest.

Source Configuration

The source field supports two formats:

String format (simple):

source: "github.com/cloudposse/packer-templates//ami-builder?ref=1.0.0"

Map format (full control):

source:
  uri: github.com/cloudposse/packer-templates//ami-builder
  version: 1.0.0
  included_paths:
    - "*.pkr.hcl"
    - "*.pkr.json"
    - "scripts/**"
  excluded_paths:
    - "*.md"
    - "tests/**"

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.
• 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.
• retry -- Optional retry configuration with max_attempts, initial_delay, max_delay, and backoff_strategy (exponential, linear, constant).

Automatic Provisioning

Sources are automatically provisioned when running any packer command. If a component has source configured and the target directory does not exist, Atmos downloads the source before running packer:

# Source is automatically provisioned on first use
atmos packer build ami-builder --stack dev
# -> Auto-provisioning source for component 'ami-builder'
# -> Auto-provisioned source to components/packer/ami-builder
# -> Packer runs

When using source, prefer enabling provision.workdir so each component-stack instance runs from an isolated staged directory:

components:
  packer:
    ami-builder:
      source: "github.com/cloudposse/packer-templates//ami-builder?ref=1.0.0"
      provision:
        workdir:
          enabled: true

Source Commands

For fine-grained control over source management:

# Download and vendor a component source
atmos packer source pull ami-builder --stack dev

# Force re-vendor (overwrites existing)
atmos packer source pull ami-builder --stack dev --force

# View source configuration
atmos packer source describe ami-builder --stack dev

# List all components with source configured
atmos packer source list --stack dev

# List sources across all stacks
atmos packer source list

# Delete vendored source (requires --force for safety)
atmos packer source delete ami-builder --stack dev --force

Version Pinning per Environment

Use stack inheritance to share base source configuration and override versions per environment:

# stacks/catalog/ami-builder/defaults.yaml
components:
  packer:
    ami-builder/defaults:
      source:
        uri: github.com/cloudposse/packer-templates//ami-builder
        version: 1.0.0

# stacks/dev.yaml
components:
  packer:
    ami-builder:
      metadata:
        inherits: [ami-builder/defaults]
      source:
        version: 1.1.0  # Override version for dev

# stacks/prod.yaml
components:
  packer:
    ami-builder:
      metadata:
        inherits: [ami-builder/defaults]
      source:
        version: 1.0.0  # Pin to stable version for prod

Supported Source Protocols

• Git -- github.com/org/repo//path, git::https://..., git::ssh://...
• S3 -- s3::https://s3-us-east-1.amazonaws.com/bucket/path.tar.gz
• HTTP/HTTPS -- https://releases.example.com/templates/component.tar.gz
• OCI -- oci::registry.example.com/templates/component:v1.0.0

Authentication for Sources

Components can specify authentication identity for accessing private sources:

components:
  packer:
    ami-builder:
      source:
        uri: github.com/my-org/private-templates//ami-builder
        version: v1.0.0
      auth:
        identities:
          github-deployer:
            default: true
            kind: github/app
            via:
              provider: github-app

Override identity at the command line:

atmos packer source pull ami-builder --stack dev --identity admin

Path-Based Component Resolution

Atmos supports using filesystem paths instead of component names:

# Navigate to component directory and use current directory
cd components/packer/aws/bastion
atmos packer validate . -s prod
atmos packer build . -s prod

# Use relative path
cd components/packer
atmos packer init ./aws/bastion -s prod

# Combine with other flags
cd components/packer/aws/bastion
atmos packer build . -s prod -t main.nonprod.pkr.hcl
atmos packer output . -s prod --query '.builds[0].artifact_id'

Supported path formats: ., ./component, ../sibling, /absolute/path.

Path-based resolution requires that the path resolves to a single unique component in the stack. If multiple components reference the same component path, use the explicit component name instead.

Common Flags

Flag	Short	Description
--stack	-s	Target Atmos stack (required)
--template	-t	Packer template file or directory path
--query	-q	YQ expression for manifest parsing (output command)

Use -- to pass flags directly to Packer: atmos packer build aws/bastion -s dev -- -color=false.

Manifest Parsing with YQ

The atmos packer output command supports YQ expressions for querying Packer manifests:

# Get entire manifest
atmos packer output aws/bastion -s prod

# Get artifact ID from the first build
atmos packer output aws/bastion -s prod --query '.builds[0].artifact_id'

# Extract just the AMI ID (second part after colon)
atmos packer output aws/bastion -s prod -q '.builds[0].artifact_id | split(":")[1]'

Debugging

Describe Component

Use atmos describe component to see the fully resolved configuration for a Packer component:

atmos describe component ubuntu-base -s ue2-dev

This shows all merged vars, metadata, settings, and environment variables.

Enable Packer Debug Logging

components:
  packer:
    ubuntu-base:
      env:
        PACKER_LOG: "1"

Or set it at runtime:

PACKER_LOG=1 atmos packer build ubuntu-base -s ue2-dev

Best Practices

1. Use directory mode for multi-file components. Omit --template to let Packer load all *.pkr.hcl files from the component directory.

2. Validate before building. Run atmos packer validate before atmos packer build to catch syntax and configuration errors early.

3. Use stack inheritance for shared defaults. Define base image configuration in catalog manifests and override per environment.

4. Configure manifests for build tracking. Use Packer's manifest post-processor to track build artifacts, then query them with atmos packer output.

5. Use JIT vendoring for version control per environment. The source field enables different template versions for dev, staging, and production stacks.

6. Pin production versions. Keep production stacks on stable, tested versions while allowing development stacks to use newer template versions.

7. Use atmos describe component to debug configuration resolution issues. It shows the fully merged result of all stack manifest inheritance.

Additional Resources

• For the complete command reference, see references/commands-reference.md