<< Click to Display Table of Contents >> Navigation:  Nodes > Tasks > Flow Control > ProxmoxVM

 

Purpose

 

This node creates qemu tasks on Proxmox servers, by using the Proxmox REST API.

 

Example presets are provided for common management of qemu virtual machines (Get VM Info, Clone, Start, Shutdown, Stop, Remove, etc), for which this node is focused to. However there is also a Custom mode to send any other command supported by the Proxmox REST API. )

 

This node only covers a subset of the Proxmox API, as it is specialized in basic commands for VM management. But in principle you can also use it as an example to cover other areas of the Proxmox API. (In fact this is a Python node  and the source code is also provided to help on this flexibility).

 

Inputs

 

vmIn: Get VMs (their metadata) sent by a previous Proxmox node upstream. If you want to use this connector you also need to set the selectionMode property to FROM INPUT connector, so that the new commands will operate with the received VMs (rather than selecting their own VMs)

 

Outputs

 

vmOut:  If the command was successful (no proxmox task failed) then it will output the vm metadata via this connector, to be received by other ProxmoxVM nodes downstream.

 

Note: When selecting VM Clone as commandPreset then what is sent trough the vmOut connector is the new VM clone, not the original VM that was cloned by the node.

 

vmTaskFail:   If a proxmox task is successfully created in the proxmox server but it fails later during proxmox execution then the vm is sent via the vmTaskFailed connector rather than vmOut, which will be empty.  This gives you the opportunity to react to Proxmox task execution failures by executing alternative actions.

 

 

Standard properties

 

Object Name

Color

Bypass

Lock

 

Node specific properties

 

NOTE: Some properties mentioned here are only visible when they can be applied to the current VM selection mode and command preset.

 

Server Credentials

 

proxmoxServer: Proxmox host (hostname or ipaddress)

 

proxmoxPort: Proxmox server port, 8006 by default.

 

node: The proxmox node name. Typically it is the hostname, but you can select a different node in Proxmox clusters.

 

username, password: User credentials. By default the username is root@pam, which is the only user coming with Proxmox default installations.

 

If you create other users in Proxmox then you will need to give them permissions in the Proxmox GUI for the commands that you want to execute here (test their capabilities via normal login before trying to use them with this node...). Then set the username property in the form "username@pve" (or if you use linux users managed by the host OS then use "name@pam" syntax.

 

Note that only the root user has direct access to the underlying hardware of a Proxmox server.  For example, if you plan to clone VMs that will receive hardware elements in PCIe passtrough mode then your username needs to be root@pam,  otherwise  Proxmox will not have permission to complete the cloning operation.

 

 

VM Selection

 

selectionMode: Defines which VMs of the Proxmox server will be selected for the command operation.

 

VM names containing matching strings (vmNamePrefix, vmNameContains, and vmNameSufix): To only process VMs with names matching the naming rules (vmNamePrefix, vmNameContains, and vmNameSufix). If you leave any of these properties empty it will not count for string matching, but in this selection mode you need to fill at least one of them.

 

Note: If you prefer an OR matching operation rather than AND just use multiple instances of this node...

 

use VM ID number (vm_ID_number): Only process the VM identified by the vmid number entered in that property.

 

FROM INPUT Connector: This mode will process the VMs received trough the input connector, rather than selecting them in the node properties. For example you could use multiple ProxmoxVM nodes interconnected in order to clone a particular VM, then start that clone, then execute some other workflow nodes that will use the VM for their own purposes (using the rank connectors to establish priorities...), and finally stop the VM and delete it.

Nodes using this mode will get the VMs from the input connector, execute the selected command, and pass the VMs to the out connectors, so you can daisy-chain as many ProxmoxVM nodes as you need.

 

onlyProcessLastMatch: If the VM Selection finds multiple VMs and this setting is active, the node will only process the last of them (according to the alphanumeric order of their names).

 

 

Proxmox Command

 

commandPreset: It will fill the command property and other related properties, to define the command that will be sent to Proxmox,  for the VMs obtained by the VM Selection section above.

 

It provides these presets:

 

Get VM Info: Just interrogate the Proxmox server to get current metadata from the selected VMs (the ones found by the VM Selection section), but do not apply any action to them.  When building your workflow it is recommended to execute this mode before any other action, just to check that the VM Selection section is getting the VMs that you expect and not affecting others.

 

Clone VM (clonedNameSufix ): Clone selected VMs. When using this particular preset, the vmOut connector will send the new VM clones, not the original VMs that are cloned.  

 

clonedNameSufix: Cloned VMs will have the same name as the originals, plus this sufix added at the end.

 

clonedMinimumId: Cloned VMs are requested to have the first available vmid that is higher than this number.

 

Start VM, Stop, Shutdown: Start, Stop, or Shutdown the selected VMs.

 

Wait until VM is down: Given an vm, if it is running it will wait until it is shutdown, or until the Timeout time has passed (in which case it will send the vm trough the taskFail output connector).  

Note that this mode does not trigger an vm shutdown by itself, it just monitor the vm state continously, holding the workflow until the vm is not running anymore. A typical use case is to have a script running in the vm that will shutdown the vm when finished, and you want to wait until that happens before continuing the workflow.

 

Remove VM (Are_You_Sure): Delete the selected VMs. This is a dangerous action, if you plan to use this option always keep backups of your important VMs, because it is too easy to delete the wrong VMs by mistake.

 

Note: To prevent accidental selection of this mode, when selecting it you will need to activate an Are_You_Sure property that will appear.

 

Exec guest command (via qemu guest agent) (guestAgentCommand): This preset permits to execute a command line directly inside the vm. Some notes to take into account:

 

- Put the command line that you want to execute in the vm in the guestAgentCommand property. (not in the command property, which is for the Proxmox API).

 

- The vm needs to have the qemu guest agent installed.

 

- For OS commands you will need to start the command line with the CLI interpreter. Example for a Windows VM:

 

 cmd.exe /c echo test > c:\\test2.txt

 

- On Linux VMs, it is pretty common to have the qemu command execution blacklisted by default.  You can change it in this file of the vm (not in the host): /etc/sysconfig/qemu-ga  

 

For example, to permit command line executions and also all RPCS actions just create an empty list for the BLOCK_RPCS variable:

 

BLOCK_RPCS=

 

Then restart the qemu-guest agent service.

 

Change macaddr (macaddr): Change the mac address of the selected VMs (type the new one in the macaddr property that will appear).

 

This preset just provides a command syntax example for changing the primary net1 interface, then switch to Custom mode if you want to modify a different network interface or for changing other settings of the command (in fact, the main purpose of this preset is to illustrate the syntax for sending API commmands in general)

 

Custom: Type your own Proxmox REST API command to send to the Proxmox server for each selected VM. It uses pythonized (proxmoxer) syntax.  An easy way to create it is to select any other commmandPreset to get an example API command, then switch to Custom mode to be able to modify the command to suite your needs.

 

Note that the command property uses dot notation rather than the slash notation of the API documentation,  but the syntax is very similar. Also note that the node will detect cloning  operations even in Custom mode (any commands containing ".clone."). That means that if you have ".clone." in your syntax it will add the clone sufix to the cloned vm name and it will send the clones tp the vmOut connector rather than sending the original VMs (similar to what the Clone VM mode does).

 

command: The Proxmox API command to be executed for each selected VM, in dot notation.

 

Note: Some of the command presets use meta variables starting with "__" in the command syntax. Those variables are substituted by real values at execution time, after the node is able to interrogate the Proxmox server to find their values.

 

timeout: Most of the commands executed by this node will create a "Proxmox task" ( you will see them in the task panel of the Proxmox GUI...), and this node will wait for them to be executed by Proxmox. The timeout property sets the maximum  time that can pass while waiting for each task to complete. If it is not 0 (which means no timeout) then this node will wait that number of seconds and it will consider that the task has failed if it is not completed by then.

 

But please note that the command execution itself may take a few seconds to start the task before entering the timeout loop, so the total time can be significantly higher. In particular, the Start_VM task in Proxmox requires a long time to complete (until the guest OS is already running...), so expect around 20 sg for the task creation itself.  before your timeout value starts counting.

 

 

 

Developer reference (Python - ProxmoxVM.[Property ID], API Rest - node/ProxmoxVM/property/[Property ID])