HashiCorp Packer

Build identical machine images for AWS, GCP, Azure, Docker, and more from a single HCL2 template. Bake your application into immutable AMIs and ship faster, safer deployments with zero configuration drift.

Installing Packer

# macOS
brew tap hashicorp/tap
brew install hashicorp/tap/packer

# Linux
wget -O- https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list
sudo apt update && sudo apt install packer

# Verify
packer version

HCL2 Template Structure

A Packer HCL2 template has three top-level blocks: packer (required plugins), source (what to build and where), and build (what to do inside):

# aws-ami.pkr.hcl

# 1. Required plugins
packer {
  required_plugins {
    amazon = {
      version = ">= 1.3.0"
      source  = "github.com/hashicorp/amazon"
    }
  }
}

# 2. Variables
variable "aws_region" {
  type    = string
  default = "us-east-1"
}

variable "app_version" {
  type = string
}

# 3. Locals (computed values)
locals {
  timestamp = regex_replace(timestamp(), "[- TZ:]", "")
  ami_name  = "my-app-{{var.app_version}}-${local.timestamp}"
}

# 4. Source block (what to build)
source "amazon-ebs" "ubuntu" {
  ami_name      = local.ami_name
  instance_type = "t3.medium"
  region        = var.aws_region

  source_ami_filter {
    filters = {
      name                = "ubuntu/images/*ubuntu-jammy-22.04-amd64-server-*"
      root-device-type    = "ebs"
      virtualization-type = "hvm"
    }
    most_recent = true
    owners      = ["099720109477"]  # Canonical
  }

  ssh_username = "ubuntu"

  tags = {
    Name        = local.ami_name
    AppVersion  = var.app_version
    BuildDate   = local.timestamp
    ManagedBy   = "Packer"
  }
}

# 5. Build block (provisioners run inside the machine)
build {
  name    = "my-app-ami"
  sources = ["source.amazon-ebs.ubuntu"]

  # Provisioner 1: Shell scripts
  provisioner "shell" {
    inline = [
      "sudo apt-get update -y",
      "sudo apt-get install -y nginx nodejs npm",
      "sudo systemctl enable nginx",
    ]
  }

  # Provisioner 2: Copy application files
  provisioner "file" {
    source      = "app/"
    destination = "/home/ubuntu/app"
  }

  # Provisioner 3: Run setup script
  provisioner "shell" {
    script = "scripts/setup-app.sh"
    environment_vars = [
      "APP_VERSION=${var.app_version}",
    ]
  }
}

Using Ansible Provisioner

# packer {
#   required_plugins {
#     ansible = {
#       version = ">= 1.1.0"
#       source  = "github.com/hashicorp/ansible"
#     }
#   }
# }

build {
  sources = ["source.amazon-ebs.ubuntu"]

  # Packer connects via SSH and runs Ansible against the temporary instance
  # No Ansible agent required on the target machine
  provisioner "ansible" {
    playbook_file   = "ansible/site.yml"
    user            = "ubuntu"
    use_proxy       = false
    extra_arguments = [
      "--extra-vars", "app_version=${var.app_version} env=production",
      "--tags", "app,nginx",
    ]
    ansible_env_vars = [
      "ANSIBLE_HOST_KEY_CHECKING=False",
    ]
  }
}

Building and Running Packer

# Initialize (download required plugins)
packer init .

# Validate the template (syntax + variable checks)
packer validate -var "app_version=1.4.2" aws-ami.pkr.hcl

# Build the AMI (requires AWS credentials in env)
export AWS_ACCESS_KEY_ID="AKIA..."
export AWS_SECRET_ACCESS_KEY="..."
# or use an IAM instance profile if running in AWS

packer build -var "app_version=1.4.2" aws-ami.pkr.hcl

# Output:
# --> amazon-ebs.ubuntu: AMI: ami-0a1b2c3d4e5f67890
# Build 'amazon-ebs.ubuntu' finished after 8 minutes.

# Build multiple targets (parallel)
packer build -parallel-builds=2 .   # builds all .pkr.hcl files in directory

GitHub Actions CI for Image Builds

# .github/workflows/build-ami.yml
name: Build AMI

on:
  push:
    branches: [main]
    paths:
      - 'packer/**'
      - 'ansible/**'
      - 'scripts/**'

permissions:
  id-token: write   # for OIDC (keyless AWS auth)
  contents: read

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Configure AWS Credentials (OIDC)
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789:role/GitHubActionsPackerRole
          aws-region: us-east-1

      - uses: hashicorp/setup-packer@main
        with:
          version: "latest"

      - name: Packer Init
        run: packer init packer/

      - name: Packer Validate
        run: packer validate -var "app_version=${{ github.sha }}" packer/

      - name: Packer Build
        run: packer build -var "app_version=${{ github.sha }}" packer/

      - name: Store AMI ID in SSM
        run: |
          AMI_ID=$(cat packer-manifest.json | jq -r '.builds[0].artifact_id' | cut -d: -f2)
          aws ssm put-parameter --name /my-app/ami-id --value $AMI_ID --type String --overwrite

Packer vs Docker for Immutable Infrastructure