# atmos packer

Use these subcommands to interact with [HashiCorp Packer](https://developer.hashicorp.com/packer)
to build automated machine images.

## Usage

```shell
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](https://developer.hashicorp.com/packer/docs/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:

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

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

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

Instead, you must use the unique component names:

```bash
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](https://mikefarah.gitbook.io/yq/) expression to get sections and attributes from a [Packer manifest](https://developer.hashicorp.com/packer/docs/post-processors/manifest).
  Used in the `atmos packer output` command.

## Examples

### Component Name Examples

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

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

**Troubleshooting**

Common issues and solutions when using Atmos with Packer.

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

## Subcommands