Docs: Create Proxmox Account

Mon, 01 Jan 0001 00:00:00 +0000

Proxmox resource onboarding flow

When creating a Proxmox cloud account, the platform does not sync Proxmox bridges as Layer-2 networks / IP subnets. Instead it prepares local networks from IPs on node NICs (including bridges):
- If an existing local IDC (e.g. KVM) IP subnet already covers those host IPs, reuse it and do not create a new one;
- Otherwise automatically create a Layer-2 network and IP subnet (names like {account-name}-proxmox-host-network);
- When syncing host NICs later, attach by NIC IP to the matching local Layer-2 network and record the bridge name (e.g. vmbr0).
After the account is added, if the auto-created Layer-2 network and IP subnet do not match your topology (for example they only cover host IPs, not VM ranges, or one Layer-2 was split into multiple segments), merge wires and merge IP subnets to match the real Proxmox network. Merging wires is irreversible; if misconfigured, delete the cloud account and add it again.
When syncing existing VMs, NICs match local IP subnets by VM IP and are not tied to Proxmox remote network IDs. Running VM IPs are obtained via QEMU Guest Agent.

Notes

Version upgrade

Note: If Proxmox cloud accounts were onboarded before upgrading to 4.0.4, delete those accounts after the upgrade and re-import using this document. 4.0.4 changed the Proxmox network and resource sync model; old accounts leave dirty data and may cause abnormal network, host, or VM status. Deleting a cloud account only removes platform management; Proxmox-side resources are unaffected.

Account onboarding

Enter only IP or domain for the access address (e.g. 192.168.1.10 or pve.example.com); do not include https://, path, or port. Port is a separate field (default 8006).
If the access address is a domain, cloud management control nodes must resolve it, or connection tests and sync fail.
Auth method maps to Proxmox Realm:
- PAM: Linux system user auth (commonly root). Required when creating VMs from local Glance images because remote system-disk mount depends on PAM users.
- PVE: Proxmox VE local user auth. Only for API operations such as resource sync; cannot remote-mount system disks.
Enter only the username in the account field; the platform appends @pam or @pve by auth method. Do not add the suffix yourself.
Prefer a PAM account with admin rights (e.g. root). Insufficient permissions may allow a successful connection test but fail to sync hosts, storage, or VMs, or block create/change operations on the platform.
The platform calls the Proxmox API over HTTPS and skips certificate verification, so self-signed certificates work.

Sync scope

Syncs QEMU VMs only, not LXC containers.
Syncs nodes (hosts), block storage, and ISO images; VPC uses the platform local Default VPC.
Only storage whose Content includes images is enabled as block storage; ISO images come from storage whose Content includes iso.
Does not sync Proxmox bridges as platform IP subnets; VMs and hosts use local Layer-2 networks / IP subnets. Creating or modifying bridges on Proxmox from the platform is not supported.
Does not sync or manage security groups, EIPs, snapshots, object storage, or load balancers.

VM management

Two image methods are supported when creating VMs:

Local Glance image (recommended): Choose a public or custom image from platform system images. The platform caches the image to Proxmox storage, then esxi-agent remote-mounts the system disk and injects login and other info so the guest can boot into the OS.
ISO image: Mount an ISO as a CD-ROM and create an empty disk. After creation the VM is powered off; power on and install the OS via VNC. Place the ISO in Proxmox storage beforehand, or cache it to the storage from the platform.

Deploy with a local Glance image

Creating a VM from a public or custom image is similar to VMware and does not use cloud-init:

Upload and cache the Glance image to Proxmox storage (first use of an image takes longer; cached images can be reused).
Create the VM on Proxmox and attach that system disk.
esxi-agent remote-mounts the system disk; host-deployer injects admin password, SSH keys, and NIC config into the disk filesystem.

Notes for this method:

Auth must be PAM: Remote system-disk mount uses a Linux system user (e.g. root@pam) to access Proxmox nodes. PVE users cannot log in to hosts; deploy fails with PVE auth.
esxi-agent: esxi-agent must be deployed and running (same service as for VMware). The esxi-agent node must reach the Proxmox API and storage, or remote mount and deploy fail.
No cloud-init required on the image: Password, keys, and IP are written directly to disk by host-deployer, same as local KVM and VMware.
VM must be powered off: Remote system-disk mount for deploy requires the VM to be off.
NIC: Choose a local IP subnet Layer-2-reachable to the target node. At create time the NIC attaches to the bridge recorded on that Layer-2 network (e.g. vmbr0); if none is recorded, default is vmbr0. Ensure the target node has that bridge and Layer-2 connectivity to the chosen IP subnet.

Tip: Glance images suit bulk delivery of packaged OSes; ISO suits interactive install or custom partitioning.

Running VM IPs come from QEMU Guest Agent. Without Guest Agent installed/enabled, IPs may be missing after sync.
Reinstall OS, bind security group, bind EIP, create snapshot, and migrate are not supported.
Attach disks only when the VM is powered off; detach can be done powered on or off. Creating cloud disks alone from the disk menu is not supported; data disks are added with VM create or add-disk on the VM.
Disk resize capacity must be an integer multiple of 1 GB; the VM may be on or off.
Adjusting CPU and memory can be done powered on or off.

Tip: If no resources appear after importing the account, check account permissions and whether QEMU VMs exist on Proxmox (LXC containers are not synced).

Procedure

On the Cloud Accounts page, click “Create” above the list.
Select Proxmox, then click “Next: Configure cloud account”.
Configure:
- Name: Proxmox cloud account name.
- Remarks: optional remarks.
- Access address: Proxmox console IP or domain, without protocol, path, or port.
- Port: Proxmox console port (default 8006).
- Auth method: PAM (Linux system user) or PVE (Proxmox VE local user). Must be PAM when creating VMs from Glance images with remote system-disk mount.
- Account / Password: Proxmox console username and password; do not include @pam / @pve in the account.
- Common parameters: see Common configuration parameters.
Click “Connection test” to verify parameters.
After a successful test, click “Next: Configure sync regions” and configure related parameters.
Click “Next: Scheduled sync (optional)” to configure scheduled sync.
Click “OK” to create the Proxmox cloud account, related IP subnets, and sync resources on the account.

Cloudpods – Proxmox