Articles
From the simulator to a real vCenter or Proxmox
Trying the panel with the simulator first, then connecting it to a real vCenter or Proxmox node: the order to do it in, what to watch for, and the risks the docs state openly.
About 3 min read · Last updated
In this article
Before you take the panel into production there are two separate things to try: the panel itself, and the way the panel talks to your hypervisor. The first can be done with the simulator. The second cannot.
Starting with the simulator
The repository has a Compose file that runs with the VMware simulator (govmomi's vcsim):
docker compose -f compose.yaml -f compose.simulator.yaml up -d --buildThe simulator runs the whole flow without a real vCenter: adding a connection, discovery, the catalog, ordering, server operations. It is enough to get to know the interface, billing and notifications.
There are things the simulator cannot show. The README says it openly: the VMware side was tested mostly with the simulator, and a real vCenter / ESXi may behave differently. The simulator cannot produce a timeout, for example, so some error paths are only ever seen in a real environment.
Connecting to a real vCenter
Under Administration → Connections you enter the vCenter's address, a user and a password. The panel discovers hosts, datastores, networks and VMs; the TLS certificate is verified by its thumbprint.
What to know before you connect:
- Creating servers needs vCenter. A standalone ESXi host offers only read and power operations. With the free ESXi licence the API is read-only.
- Version: on vCenter 7.0 U3 and later, guest customisation is done with the built-in cloud-init; the template needs VMware Tools 11.3+ and cloud-init 21.3+. Between 6.0 and 7.0 U2 the guestinfo method is used.
- vCenter 9: password sign-in is blocked for accounts that use identity federation; use a vsphere.local account or an LDAP/AD service account.
- Firewall, private networks and rate limiting need a distributed virtual switch. They do not work for a network card on a standard switch.
- The console needs the VMware HTML Console SDK, which you have to add yourself, and that path was never tried with the real SDK.
For a server to count as "ready", three things must be true together: it is powered on, VMware Tools is running in the guest, and the guest reports to VMware the IP address assigned through cloud-init. If your template does not provide these, the build waits in the state "operating system not ready".
Connecting to a real Proxmox
Support for Proxmox VE is a first version, and its documentation says so plainly: the adapter was tested against tests that imitate the Proxmox API and has not yet been tried on a real Proxmox VE server. So try it on a test node first.
- Create a separate user for the panel and an API token without privilege separation. The list of privileges it needs is in docs/proxmox.md (Turkish).
- If the certificate is self-signed, compare its fingerprint on the node:
openssl x509 -in /etc/pve/local/pve-ssl.pem -noout -fingerprint -sha256- The template must have the QEMU guest agent. Proxmox's own cloud-init carries only the network and the SSH keys; the root password, the hostname and app installation are applied through the guest agent. Without the agent they are not applied.
- On Proxmox VE 9, asking the guest agent needs the
VM.GuestAgent.*privileges; on 8 and earlier,VM.Monitor. - If Proxmox sits on a network that overlaps the panel's Docker networks, the adapter refuses the connection; you allow that network with
PROXMOX_ALLOW_NETWORKSin.env.
The order we suggest
- Learn the panel's flows with the simulator.
- On the real platform, connect an empty test cluster or node, not the production cluster.
- Prepare a template and build one server end to end: order, first boot, SSH sign-in, reinstall, resize, snapshot, delete.
- Try every feature you intend to use once on that platform. "yes" in the coverage table means the code exists, not that it works on your version.
- If you have existing VMs, try adopting one; an adopted VM keeps running.
- Take a backup of the panel and copy
backup.keyoff the server.
The "Known limits" section of the README says that these trials are yours to make: none of the fixes was verified on real hypervisors. You can report what you find as an issue on GitHub.
Sources: docs/vmware.md, docs/proxmox.md, docs/provisioning.md (Turkish).
