atmos packer

Build reusable machine images with Packer using configuration from your Atmos stacks. Share image definitions across environments while varying their build settings through stack configuration.

Usage

atmos packer <sub-command> <atmos-component> --stack <atmos-stack> [atmos-flags] -- [packer-options]

tip

For more details on the Packer commands and options, refer to Packer Commands.

Path-Based Component Resolution

Atmos supports using filesystem paths instead of component names for convenience. This allows you to navigate to a component directory and use . to reference it:

# Navigate to component directory
cd components/packer/aws/bastion

# Use . to reference current directory
atmos packer validate . -s prod
atmos packer build . -s prod

This automatically resolves the path to the component name configured in your stack, eliminating the need to remember exact component names.

Supported path formats:

. - Current directory
./component - Relative path from current directory
../other-component - Relative path to sibling directory
/absolute/path/to/component - Absolute path

Requirements:

Must be inside a component directory under the configured base path
Must specify --stack flag
Component must exist in the specified stack configuration
The component path must resolve to a unique component name - If multiple components in the stack reference the same component path, you must use the unique component name instead of the path

Path Resolution Limitation

Path-based resolution only works when the component path resolves to a single unique component in the stack.

For example, if both bastion/prod and bastion/dev reference components/packer/aws/bastion:

cd components/packer/aws/bastion
atmos packer build . --stack prod  # ❌ Error: ambiguous - which component?

Instead, you must use the unique component names:

atmos packer build bastion/prod --stack prod  # ✓ Explicit and unambiguous
atmos packer build bastion/dev --stack dev    # ✓ Explicit and unambiguous

Atmos Flags

--stack (alias -s)

Atmos stack.

--template (alias -t)(optional)

Packer template file or directory path. Defaults to . (component working directory), which tells Packer to load all *.pkr.hcl files from the component directory.

Omit or use . to load all HCL files (recommended for multi-file components)
Use a specific filename like main.pkr.hcl for single-file templates

Can also be specified via settings.packer.template in the stack manifest. The command line flag takes precedence.

--query (alias -q)(optional)

YQ expression to get sections and attributes from a Packer manifest. Used in the atmos packer output command.

Examples

Component Name Examples

atmos packer version

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

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

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

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

atmos packer output aws/bastion -s prod
atmos packer output aws/bastion -s prod --query '.builds[0].artifact_id'
atmos packer output aws/bastion -s prod -q '.builds[0].artifact_id | split(":")[1]'

Path-Based Examples

# 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 from components/packer directory
cd components/packer
atmos packer init ./aws/bastion -s prod

# Use from project root with relative path
atmos packer build components/packer/aws/bastion -s prod

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

Configure Packer

Learn how to configure Packer components in your atmos.yaml, including templates and component settings.

Learn More

Troubleshooting

Common issues and solutions when using Atmos with Packer.

Learn More

Arguments

atmos-component (required)

Atmos component name or filesystem path.

Supports both:

Component names: aws/bastion, gcp/web-server
Filesystem paths: . (current directory), ./aws/bastion, components/packer/aws/bastion

When using paths, Atmos automatically resolves the path to the component name based on your stack configuration. See Path-Based Component Resolution above.