Allows simple and programatic control over the Proxmox Hypervisor.

Dan Manners



808 latest version

5.0 quality score

Version information

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

Start using this module


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.