Atmos Packer

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