Packer Skill

Reference for building machine images with HashiCorp Packer, focusing on VM template creation for homelab environments.

Quick Reference

# Core workflow
packer init .               # Initialize, download plugins
packer validate .           # Syntax validation
packer fmt -recursive .     # Format HCL files
packer build .              # Build image(s)

# Debug
packer build -debug .                     # Step through build
PACKER_LOG=1 packer build . 2>debug.log   # Verbose logging

# Specific template
packer build ubuntu-22.04.pkr.hcl

Core Workflow

init → fmt → validate → build

1. init: Download required plugins (builders, provisioners)
2. fmt: Format HCL files for consistency
3. validate: Check syntax and configuration validity
4. build: Execute the build process

Reference Files

Load on-demand based on task:

Topic	File	When to Load
Troubleshooting	troubleshooting.md	Build failures, SSH issues
Proxmox Builder	proxmox/builder.md	proxmox-iso builder config
Cloud-Init	cloud-init.md	Cloud-init template setup
Provisioners	provisioners.md	Shell, Ansible, file provisioners

HCL2 Syntax

Packer uses HCL2 (same as Terraform). Key blocks:

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

# Variables
variable "proxmox_api_url" {
  type        = string
  description = "Proxmox API URL"
}

# Local values
locals {
  timestamp = formatdate("YYYYMMDD-hhmm", timestamp())
}

# Builder source
source "proxmox-iso" "ubuntu" {
  # ... builder config
}

# Build definition
build {
  sources = ["source.proxmox-iso.ubuntu"]

  provisioner "shell" {
    scripts = ["scripts/setup.sh"]
  }
}

Proxmox Builder Quick Start

source "proxmox-iso" "ubuntu-22-04" {
  # Connection
  proxmox_url              = var.proxmox_api_url
  username                 = var.proxmox_api_token_id
  token                    = var.proxmox_api_token_secret
  insecure_skip_tls_verify = true
  node                     = "pve"

  # VM Settings
  vm_id                    = 9000
  vm_name                  = "ubuntu-22.04-template"
  template_description     = "Ubuntu 22.04 Template - ${local.timestamp}"

  # ISO
  iso_file                 = "local:iso/ubuntu-22.04.3-live-server-amd64.iso"
  iso_storage_pool         = "local"
  unmount_iso              = true

  # System
  qemu_agent              = true
  scsi_controller         = "virtio-scsi-single"

  # Disk
  disks {
    type         = "scsi"
    disk_size    = "20G"
    storage_pool = "local-lvm"
  }

  # Network
  network_adapters {
    model    = "virtio"
    bridge   = "vmbr0"
    firewall = false
  }

  # CPU/Memory
  cores   = 2
  memory  = 2048

  # Cloud-init
  cloud_init              = true
  cloud_init_storage_pool = "local-lvm"

  # SSH
  ssh_username = "ubuntu"
  ssh_password = "packer"
  ssh_timeout  = "20m"

  # Boot
  boot_command = [
    # Autoinstall boot command
  ]
  boot_wait = "5s"
}

Validation Checklist

Before packer build:

• packer init completed successfully
• packer fmt applied
• packer validate passes
• ISO file accessible from Proxmox node
• API token has required permissions
• VM ID not in use
• Storage pools exist and have space
• Network bridge accessible
• Boot command tested (or cloud-init/autoinstall configured)
• SSH credentials match user-data

Common Build Patterns

Pattern 1: Ubuntu Autoinstall

Uses cloud-init autoinstall for unattended installation:

http_directory = "http"  # Serves user-data, meta-data

boot_command = [
  "<esc><wait>",
  "e<wait>",
  "<down><down><down><end>",
  " autoinstall ds=nocloud-net\\;s=http://{{ .HTTPIP }}:{{ .HTTPPort }}/",
  "<f10>"
]

Pattern 2: Multi-Stage Provisioning

build {
  sources = ["source.proxmox-iso.ubuntu"]

  # Stage 1: System updates
  provisioner "shell" {
    inline = ["apt-get update && apt-get upgrade -y"]
  }

  # Stage 2: Ansible configuration
  provisioner "ansible" {
    playbook_file = "ansible/configure.yml"
  }

  # Stage 3: Cleanup
  provisioner "shell" {
    script = "scripts/cleanup.sh"
  }
}

Pattern 3: Variables File

# variables.pkrvars.hcl
proxmox_api_url          = "https://pve.local:8006/api2/json"
proxmox_api_token_id     = "packer@pam!packer"
proxmox_api_token_secret = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

packer build -var-file="variables.pkrvars.hcl" .

Troubleshooting Quick Reference

Issue	Check
SSH timeout	boot_wait, boot_command, firewall, cloud-init
Permission denied	API token permissions, user-data
ISO not found	iso_file path, storage pool permissions
Build hangs	boot_command timing, VNC console
Cloud-init fails	user-data syntax, meta-data presence