Documentation

Proxmox VE

Proxmox is the hypervisor integration. It creates virtual machines by cloning a template, follows the task while it runs, and keeps the panel in step with what the cluster actually reports.

What you need

Proxmox does not use a password for automation. You create an API token, which is a three-part identifier plus a secret shown to you once.

Host: the full base URL of the API. It has to be HTTPS; port 8006 is filled in for you if you leave it out.
Token identifier: in the form user@realm!tokenname, exactly as Proxmox writes it.
Token secret: the value Proxmox shows once when the token is created.
TLS fingerprint: the certificate of the node itself, not of the authority that issued it.

shell

openssl s_client -connect pve.example.com:8006 </dev/null 2>/dev/null | \
  openssl x509 -noout -fingerprint -sha256

Commands and terminal output are in English everywhere, in the panel and in these pages. One text, one truth: what you read here is literally what your host will print back.

Turn privilege separation off on the token, or give the token its own permissions explicitly. With it on, the token starts with none of the rights of the user it belongs to and every call fails for a reason Proxmox does not spell out.

Settings

Four non-secret choices, on the settings tab. Without them the integration is connected but cannot create anything.

Node: which node in the cluster to build on. The panel offers the nodes your agent has actually seen; if it has seen none yet, you can type one.
Storage: where the disks of new machines go.
Bridge: optional. It is stored and used where the platform creates a machine from nothing, but a clone inherits the bridge of the template it was cloned from.
Machine ID range: the block of Proxmox VM IDs Provibr may allocate inside.

The range is the safety boundary

This is the most important setting on the page. Provibr allocates identifiers only inside the range you give it and never touches anything outside it. Keep your own production machines outside the range and they stay out of reach, whatever anyone clicks in the panel.

Identifiers are never reused, not even after a machine is deleted. A late status message from a machine that is gone can therefore never land on a machine that is new.

A template you link as an operating system must sit outside the range, and the panel refuses it otherwise: inside the range, the allocator would eventually hand out the template's own identifier and the next order would clone from itself.

How a machine is created

Creating a machine is one clone task followed by a small number of configuration calls. The panel follows the task and shows real progress where Proxmox reports it.

Clone the template you picked, onto the node from the settings.
Grow the boot disk to the size you ordered. A disk can only grow; if the template is already bigger, the machine keeps the template's size.
Apply cores, memory and the cloud-init settings (address, gateway, resolvers, user, SSH keys) in one configuration call.
Enable the firewall and start the machine.

After the start the machine reports as installing rather than running, and only becomes running once cloud-init has done its work inside the guest. That is why a freshly created machine does not go green immediately.

Linux containers

A Proxmox connection carries virtual machines and containers. The plan decides which of the two an order produces, and from that point on the kind travels with every command instead of being guessed. A container is not a smaller virtual machine: it shares the kernel of its host, which is why it is cheap and why a handful of things are simply not available on it.

The plan says virtual machine, container, or either. With either the customer picks during the order, and the image list follows that choice rather than quietly filling one in.
A container is not cloned but unpacked, from a container template on the connection. That is a different kind of source from the templates a virtual machine is cloned from, and an image that only has a container template does not show up in the virtual machine list.
Unprivileged is the default. The root inside the container is not root on the host, which is what you want unless something specifically needs otherwise.
Storage is a root volume plus mount points. The panel shows them as key, source and path inside the guest; the host path is deliberately not shown, because it says more about the host than about the machine.

Every command carries the kind, and a command that does not fit is refused before it becomes a job, with the reason on screen. Two of those reasons mean genuinely different things.

Never: booting from the network, an empty machine, and firmware or boot order. A container does not start from a network card and has no firmware to ask.
Not yet: disks, network cards and the hardware screen. A container does have storage and networking, in a different shape, and reusing the fields of a virtual machine for them would give the same words a second meaning.
Available: create, start, stop, shut down, status, delete, suspend, resume, reinstall, the firewall and its anti spoofing.
The console is a separate case, and it is a not yet with a reason: the console of a virtual machine is a screen, and a container has none. What it does have is a terminal, which is a different protocol and a different client.

Backups have one difference that is easy to get wrong, and it works the opposite way from a virtual machine. A mount point is in the backup only when it is marked for it; a disk on a virtual machine is in the backup unless it is marked out. So a container with a data volume that nobody marked has a backup that looks complete and holds the root volume only.

The panel says per mount point whether it is in the backup, and never calls unmeasured coverage complete. Bind mounts and passed through devices never come along at all: what is behind them belongs to the host and not to the machine.

Reinstalling a container is a replacement and not a clone over the top. The panel first shows you what happens to each mount point, and only then replaces the machine under one lock: the root volume is rebuilt, and what was listed as kept is put back. Nothing that was not in that list is restored.

Cloud-init

Provibr writes a fixed, small set of cloud-init keys and nothing else: the four network configurations, resolvers and search domain, the user, the configuration type, SSH keys, the password and whether to run a package upgrade on first boot. The list exists on both sides, so a field that happens to be called cloud-init can never rewrite an arbitrary machine setting.

The root password never appears in the audit trail. Only the name of the field is recorded; the value travels separately and is not stored.

The upgrade-on-first-boot option needs Proxmox 8.1 or newer. On an older node the call is retried without it rather than failing.

What you can do afterwards

Start, stop, shut down, pause, resume, refresh, reinstall and delete. A shutdown asks the guest politely first and falls back to a hard stop after a timeout.

Disks and network cards can be added, resized, attached and detached. A disk can only grow. The boot disk and the cloud-init disk cannot be detached, and neither can the first network card.

The firewall has an editable rule list and a log, both read from and written to the node itself.

Worth knowing

A clone inherits the network bridge of its template. The bridge on the plan and on the integration is stored and is used elsewhere, but it is not applied to a clone.
Disk usage inside a virtual machine is not something Proxmox can see, so that graph shows the allocated size and no usage line. The other measurements are real.
Templates are excluded from the poll and never count towards your licence.
Machines that exist on your cluster but not in Provibr are ignored on every poll. They cannot be imported from Proxmox either: there is no import for hypervisors today.

PreviousIntegrations NextVMware vSphere