Skip to main content

Proxmox VE Requirements

This page is the Proxmox VE onboarding checklist for StackConsole / CMP. Complete the common prerequisites and confirm hosting topology as well.

Bare minimum

Items marked as required to begin in the checklist must be ready before setup can start. Without those prerequisites, installation cannot proceed.

1. Access for StackConsole Team​

To access the Proxmox web UI, use one of:

Option A — VPN access (preferred)

NameEmail
Satish Londhesatish.londhe@stackconsole.io
Ganesh Kanadeganesh.kanade@stackconsole.io

Option B — IP whitelist

If VPN is not feasible, whitelist the StackConsole jump server:

14.192.19.227
info

Ensure the Proxmox web UI is accessible from the browser through VPN or from the whitelisted IP before contacting the StackConsole team.

2. Proxmox credentials for CMP​

CMP connects to Proxmox with a dedicated API user. That user must belong to a permissions group with the required roles (default group name: UserAdmin).

FieldValue
Proxmox URL(for example https://proxmox.example.com:8006)
Username(member of the CMP permissions group — for example UserAdmin)
Password
Required roles

A user without the PVEVMAdmin, PVEDatastoreAdmin, and PVESDNAdmin roles at path / is not sufficient. CMP needs those roles to manage VMs, storage, and SDN/networks.

How to create the group and assign roles:

👉 Configure Proxmox Permissions (on Connecting CMP to Proxmox)

For StackConsole onboarding access to the Proxmox UI, you may still share a temporary admin account in addition to the CMP API user — see Access for StackConsole Team.

After permissions and connectivity are ready, configure the cloud provider in CMP:

👉 Connecting CMP to Proxmox — Provider Setup wizard, zone, templates, storage, quota, and networks

3. CMP VM → Proxmox connectivity​

From all CMP VMs, the Proxmox API must be reachable. Private access is recommended for production.

Communication between the CMP VM and Proxmox must be allowed on the Proxmox API port (default 8006).

Use the checks below in order. Replace {PROXMOX_IP} with your Proxmox IP or hostname, and YOUR_PASSWORD with the CMP API user password from Proxmox credentials for CMP.

On the Proxmox host​

1. Check whether the API service is listening on proxmox server​

ss -lntp | grep 8006

Expected output (address and process details may differ):

LISTEN 0      4096         0.0.0.0:8006       0.0.0.0:*    users:(("pveproxy",pid=...,fd=...))

If nothing is returned, the Proxmox API service (pveproxy) is not listening — resolve that on the Proxmox node before continuing.

2. Check the API responds locally​

curl -k https://localhost:8006/api2/json/version

Expected response (version and release vary by installation):

{
  "data": {
    "version": "8.x",
    "release": "..."
  }
}

Test step-by-step (Proxmox host or CMP VM)​

Run these from the Proxmox host first, then repeat Step 1 from each CMP VM to confirm network path and firewall rules.

Step 1 — Test that the API is reachable​

curl -k "https://{PROXMOX_IP}:8006/api2/json/version"

A successful response returns the same JSON structure as the local check above.

Step 2 — Authenticate​

Use the CMP API username (for example cmp-user@pve or root@pam during testing):

curl -k -X POST "https://{PROXMOX_IP}:8006/api2/json/access/ticket" \
  --data-urlencode "username=root@pam" \
  --data-urlencode "password=YOUR_PASSWORD"

If successful, Proxmox returns JSON similar to:

{
  "data": {
    "ticket": "PVE:root@pam:...",
    "CSRFPreventionToken": "...",
    "username": "root@pam"
  }
}

Step 3 — Query nodes with the ticket​

Copy the ticket value from Step 2 and use it as YOUR_TICKET:

curl -k \
  -H "Cookie: PVEAuthCookie=YOUR_TICKET" \
  "https://{PROXMOX_IP}:8006/api2/json/nodes"

A successful response lists Proxmox cluster nodes. If Step 3 fails, check group permissions — see Configure Proxmox Permissions.

Authentication for Stack Console / CMP​

The step-by-step test uses Proxmox ticket-based authentication (username + password → ticket + cookie).

CMP connects with the dedicated API user (username and password) configured in Connecting CMP to Proxmox — Provider Setup. A successful Step 2 confirms those credentials work against the Proxmox API.

For general application-to-application integrations, a Proxmox API token is often preferable to password-based auth. CMP’s Provider Setup wizard uses username and password for the API user in the UserAdmin group — not a separate API token field.

warning

Ensure firewalls and security groups allow CMP VM → Proxmox:8006 (TCP). Private network routing is preferred over exposing the API on the public internet.

4. CMP VM configuration​

Shared install inputs:

5. Domain, SSL, SMTP, and app logos​

Shared install inputs:

6. Storage types​

Configure storage labels in Proxmox to match what you want displayed in the CMP portal (for example SSD, NVMe, HDD). Storage must be tagged correctly at the Proxmox level. CMP displays storage types as defined in Proxmox — no separate CMP-level storage-type mapping is required for display.

7. Templates and networks​

Templates​

Proxmox uses VM templates (cloned from existing VMs) for CMP provisioning. Templates must be cloud-init ready (password / SSH where offered, QEMU Guest Agent).

Full procedure: Preparing CMP-compatible templates.

Key points:

  • Support password reset
  • Support SSH key injection where offered
  • Be cloud-init compatible
  • Be accessible to the Proxmox node(s) CMP will manage
  • On multi-node clusters, templates and shared storage must be available on nodes that can receive VMs — Proxmox has no DRS; CMP picks the node at provision time using the Node Selection Algorithm

Networks​

Before CMP setup, ensure:

  • Public networks — for customer VMs that need internet access
  • Private networks — for isolated workloads
  • Linux bridges configured on Proxmox nodes (for example vmbr0) — VMs must use bridges, not physical NICs (eth0 / eno1). See Linux bridge vs physical NIC

8. Checklist​

Items needed to begin setup (without these, setup cannot proceed):

Access and Proxmox​

  • VPN access to StackConsole team provided or jump server IP whitelisted
  • Proxmox UI accessible from browser via VPN or whitelisted IP
  • UserAdmin group (or equivalent) created with PVEVMAdmin, PVEDatastoreAdmin, and PVESDNAdmin at path / — see Configure Proxmox Permissions
  • CMP API user added to that group
  • CMP API credentials provided (URL, username, password)
  • Proxmox API responds on port 8006 — ss, version curl, and ticket auth test (access/ticket + /nodes) from CMP VMs — see CMP VM → Proxmox connectivity

Staging VM​

  • Staging VM and credentials provided
  • Staging URL provided
  • Staging SSL certificates provided

Production VM​

  • Frontend VM and credentials provided
  • Backend VM and credentials provided
  • Database VM and credentials provided

Production URL and SSL​

  • Frontend URL provided
  • Backend URL provided
  • Frontend VM can reach backend API URL (curl / connectivity tested)
  • Production SSL certificates provided

Other​

  • SMTP details provided
  • App logos (light + dark) provided when branding is required

9. Proxmox setup checkpoints​

CheckNotes
OS templates available and workingSee Preparing CMP-compatible templates
VM creation works from the Proxmox UI
Public and private networks configured
VM console access works from the Proxmox UI
Proxmox API reachable from CMP VMsPort 8006 — curl version endpoint; see CMP VM → Proxmox connectivity
Group permissions at / include required rolesSee Configure Proxmox Permissions