Forge Home


Allows simple and programatic control over the Proxmox Hypervisor.


1,261 latest version

5.0 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Version information

  • 0.1.3 (latest)
  • 0.1.2
  • 0.1.1
  • 0.1.0
released Aug 1st 2020
This version is compatible with:
  • ,

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'danmanners-proxmox_api', '0.1.3'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add danmanners-proxmox_api
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install danmanners-proxmox_api --version 0.1.3

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.



danmanners/proxmox_api — version 0.1.3 Aug 1st 2020


This proxmox_api module allows you to simply and programatically control the Proxmox Hypervisor.

Table of Contents

  1. Description
  2. Setup requirements
  3. Usage - Configuration options and additional functionality
  4. Limitations - OS compatibility, etc.


This proxmox_api module allows you to perform several functions. Currently, this includes:

  1. Create GenericCloud Cloud-Init enabled image by simply providing some values.
  2. Clone an existing template VM.


Examples for each of the commands are below:

Create new GenericCloud VM Template

    proxmox_api::qemu::create_genericcloud {'Ubuntu2004-Template':
      pmx_node          => 'pmx',
          # Proxmox Node to create the VM on
      vm_name           => 'Ubuntu2004-Template',
          # New VM Template Name
      ci_username       => 'ubuntu',
          # Set the Cloud-Init Username
      interface         => 'vmbr0',
          # Set the Proxmox Network adapter to connect the template to
      storage_id        => 'local',
          # Set the storage volume for the VM Template
      default_disk_size => '20G',
          # Defaults to an 8G size if left undefined, but can be set.
      vmid              =>  20001,
          # Set the ID for the new VM Template
      cloudimage_source => '',
          # URL of the GenericCloud image
      image_type        => 'img',
          # File type of the URL below

Cloning an existing VM Template

    proxmox_api::qemu::clone {'test':
      node             => 'pmx',
          # Proxmox Node to create the VM on
      vm_name          => 'TesterMcTesterson',
          # New VM Name
      clone_id         => 1001,
          # The ID of the VM template
      disk_size        => 20,
          # Size of the new disk in GB
      cpu_cores        => 2,
          # Number of CPU cores
      memory           => 4096,
          # Amount of RAM in MB
      ci_username      => 'root',
          # Set the Cloud-Init Username
      ci_password      => 'password',
          # Set the Cloud-Init Password
      protected        => true,
          # Enable the 'Protected' flag
      ipv4_static      => true,
          # [OPTIONAL] Use Static IP
      ipv4_static_cidr => '',
          # [OPTIONAL] Static IP and Subnet Mask
      ipv4_static_gw   => '',
          # [OPTIONAL] Gateway Address


I'd like to suggest using one of the following URLs for your Generic Cloud Images.


  • This is currently being developed and tested against a single Proxmox 6.2-4 node, and is not being actively tested against earlier versions. I cannot promise that things will work as expected if you are running earlier versions of Proxmox.
  • This will not (but absolutely could) non-template virtual machines. Reason being is that if you're cloning non-template VM's you're probably approaching your infrastructure wrong.


If there are features that this does not perform or if there are bugs you are encountering, please feel free to open an issue.

Known Issues

  • Currently, adding SSH keys doesn't work and should be done manually. Looks to be an issue with how Ruby processes urlencoded strings, but otherwise TBD.