Proxmox Packer Plugin

The proxmox-iso builder creates new Proxmox VE images by taking an ISO source, running provisioning steps on the launched image, and then creating a virtual machine template.

Note: The builder does not manage the lifecycle of the created templates; once the template is created, you are responsible for using or deleting it.

source "proxmox-iso" "example" {
  # Configuration goes here
}

The proxmox-clone builder creates new Proxmox Virtual Machine templates by cloning an existing cloud-init enabled virtual machine template. After cloning, Packer runs any specified provisioning steps on the new instance and then converts it into a template.

Key Behaviors:

• Disk Management: If you specify disks in your configuration, they will replace the disks present on the cloned VM template. To reuse the existing disks from the source template, omit the disks configuration.
• Template Lifecycle: The builder creates the template but does not manage its lifecycle; you are responsible for manually using or deleting the resulting template in Proxmox.

type = `proxmox-clone`
Artifact BuilderId = `proxmox.clone`

The Proxmox plugin provides two primary builder types depending on your source material:

• proxmox-clone: Used when you have an existing Cloud-Init enabled virtual machine template. The builder launches the template, runs provisioning, and then creates a new virtual machine template.
• proxmox-iso: Used when you have an ISO file as a source. The builder launches a VM from the ISO, runs provisioning, and then creates a virtual machine template.

To improve network throughput for high-traffic VMs (such as routers, reverse proxies, or busy HTTP servers), you can enable multiqueue support using the packet_queues setting.

Requirements and Best Practices:

• You must use the virtio network adapter model.
• For best performance, set packet_queues to the number of CPU cores available to the virtual machine.
• Be aware that activating this increases CPU load on both the host and guest systems as traffic increases.

model = "virtio"
packet_queues = 4 # Example for a 4-core VM

To build the plugin from the source code:

1. Clone the GitHub repository locally.
2. Run go build from the root directory.
3. The resulting packer-plugin-proxmox binary will be located in the root directory.
4. Install the binary following the official Packer plugin installation guide.

For Packer version 1.7 and later, you can automatically install the Proxmox plugin by declaring it in your Packer configuration file and running the packer init command. This is the recommended method for managing plugin dependencies.

packer {
  required_plugins {
    proxmox = {
      version = ">= 1.2.2"
      source  = "github.com/hashicorp/proxmox"
    }
  }
}

The top-level ISO configuration options in the Proxmox ISO builder are deprecated. Instead of using iso_file, iso_storage_pool, iso_download_pve, or unmount_iso directly in the builder configuration, you should define your boot ISO settings using a boot_iso block.

# Example of the new pattern (conceptual)

build {
  proxmox-iso {
    # Instead of iso_file = "..."
    boot_iso {
      # Use the new block configuration here
    }
  }
}

You can install the Proxmox plugin using two methods: adding it to your Packer configuration block or using the CLI.

Method 1: Packer Configuration (Recommended)

Add the following required_plugins block to your Packer HCL configuration and then run packer init.

Method 2: CLI Installation

Use the packer plugins install command to manually install the plugin from the GitHub source.

packer {
  required_plugins {
    name = {
      version = "~> 1"
      source  = "github.com/hashicorp/proxmox"
    }
  }
}

The Proxmox builder supports a variety of configuration parameters categorized into required and optional settings.

When configuring the builder, you can also specify a communicator. If no communicator is explicitly defined, the builder will automatically generate an SSH key to be used in the image's Cloud-Init settings for provisioning purposes.

If you cannot use packer init, you can install the plugin manually:

1. Download the latest pre-built binary release for your target OS from the GitHub releases page.
2. Uncompress the archive to retrieve the plugin binary.
3. Follow the standard Packer documentation for installing a plugin (typically placing the binary in your PATH or the Packer plugin directory).

Run the following command to install the Proxmox plugin directly using the Packer CLI:

packer plugins install github.com/hashicorp/proxmox

Use the tpm_config block to set the Trusted Platform Module (TPM) state storage options for your Proxmox virtual machine. This allows you to specify the storage pool where the TPM state is stored and the version of the TPM to be used.

tpm_config {
  tpm_storage_pool = "local"
  tpm_version      = "v1.2"
}