Skip to main content

Using Packer

Atmos natively supports opinionated workflows for HashiCorp Packer. Packer automates the creation of machine images for multiple platforms, enabling you to build immutable infrastructure with consistent, versioned images.

For a complete list of supported commands, please see the Atmos packer documentation.

Why Use Packer with Atmos?​

Packer components in Atmos allow you to:

  • Build immutable infrastructure — Create golden AMIs and machine images that are versioned and reproducible
  • Patch images for security and compliance — Apply security patches and compliance requirements consistently across your image library
  • Manage images like any other component — Use the same inheritance, imports, and configuration patterns you use for Terraform

Stack Configuration​

The schema for configuring Packer components in Atmos stacks:

components:
  packer:
    # the slug of the component
    ubuntu-base:

      # configuration specific to atmos
      metadata:
        type: real
        component: ubuntu-base

      # Settings for integrations
      settings: {}

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

      # Environment variables
      env:
        PACKER_LOG: "1"

Attributes​

vars (optional)

Variables passed to Packer. These are deep-merged and made available to your Packer templates.

Example:

vars:
  ami_name: "ubuntu-base"
  instance_type: "t3.medium"
  region: "us-east-1"
metadata (optional)

The metadata section extends functionality of the component. See Common Component Attributes for details.

Example:

metadata:
  type: real
  component: ubuntu-base
  inherits:
    - base-image-defaults
settings (optional)

Free-form map for integration configuration.

env (optional)

Environment variables to set when running Packer commands.

Example:

env:
  PACKER_LOG: "1"
  AWS_PROFILE: "production"

Example: Build a Packer Component​

To build a Packer component using the atmos CLI, run the following commands:

atmos packer init ubuntu-base --stack=ue2-dev
atmos packer build ubuntu-base --stack=ue2-dev

where:

  • ubuntu-base is the Packer component to build (from the components/packer folder)
  • --stack=ue2-dev is the stack context for the build

Short versions of the command-line arguments can be used:

atmos packer init ubuntu-base -s ue2-dev
atmos packer build ubuntu-base -s ue2-dev

Example: Validate a Packer Template​

To validate a Packer template before building:

atmos packer validate ubuntu-base -s ue2-dev

Example: Inspect a Packer Template​

To inspect a Packer template and see its configuration:

atmos packer inspect ubuntu-base -s ue2-dev

Try It​

Explore a complete, working example that builds a local image with Packer's Docker builder — no cloud credentials required.

packer-dockerView full example
atmos Packer Docker build
00:00.0 / 00:00.0

Example: Packer Docker Image

Minimal Atmos setup demonstrating the Packer component type using Packer's Docker builder — no cloud credentials required.

What You'll See

  • Packer component configuration in an Atmos stack
  • Packer's docker builder pulling alpine:3.19, running a shell provisioner, and committing the result as a local image — no AMIs, no cloud credentials, and nothing pushed anywhere (there's no post-processor)
  • The Atmos toolchain installing Packer automatically, pinned as a component-level tool dependency

Prerequisites

  • Docker or Podman running locally (the docker builder talks to the local container runtime; atmos packer init only needs network access to download the plugin)

Try It

cd examples/packer-docker

# Download the Docker plugin (network access only — no daemon required)
atmos packer init alpine -s alpine

# Build the image (requires Docker or Podman running locally)
atmos packer build alpine -s alpine

Key Files

FilePurpose
atmos.yamlAtmos configuration: Packer component path + toolchain-managed Packer install
stacks/alpine.yamlSingle flat stack declaring the alpine Packer component
components/packer/alpine/image.pkr.hclPacker template using the Docker builder
Browse all files