Skip to content
Lightning VMBeta

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

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 --build

The 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_NETWORKS in .env.

The order we suggest

  1. Learn the panel's flows with the simulator.
  2. On the real platform, connect an empty test cluster or node, not the production cluster.
  3. Prepare a template and build one server end to end: order, first boot, SSH sign-in, reinstall, resize, snapshot, delete.
  4. 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.
  5. If you have existing VMs, try adopting one; an adopted VM keeps running.
  6. Take a backup of the panel and copy backup.key off 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).