Proxmox VE

Ubicación en el panel de administración: Infrastructure › Cloud provider › Providers (/infra/providers), luego la página del proveedor (/infra/providers/<id>) con las pestañas Overview, Clusters, VMs, Servers y Credentials. Los planes se configuran en Services › Virtual Machines › Plans & pricing (/vm/catalog).

Qué hace

NexCMP puede vender máquinas virtuales que se ejecutan en uno o varios clústeres de Proxmox VE, junto a CloudStack o en su lugar. Una VM se crea clonando una plantilla de SO mediante full clone y luego se configura a través de cloud-init: tamaño, dirección IP de un pool que usted defina, contraseña de root y clave SSH. Los clientes obtienen control de energía, consola, snapshots, reinstalación, restablecimiento de contraseña y métricas en el portal. Nunca ven el nombre del clúster, del nodo ni del origen.

Utilícelo si ya opera con Proxmox VE o para ofrecer un segundo pool de VM con precios diferenciados.

Requisitos

Elemento	Requisito
Proxmox VE	PVE 9.x. La integración se verificó en 9.2. Requiere el contenido de storage import y la opción de disco import-from (PVE 8.2 o posterior).
Red desde el panel	HTTPS hacia la API del clúster, https://<host or IP>:8006. Sin ruta, nombre de usuario ni consulta. Tanto el panel como el worker se conectan; la consola del navegador se redirige a través del panel.
Cuenta	Un usuario dedicado de PVE con un token de API y un rol personalizado con los privilegios indicados a continuación. Nunca utilice root@pam.
Almacenamiento	Un storage para discos de VM compatible con clones (por ejemplo, local-lvm). Para el generador de plantillas integrado, el storage denominado local con los tipos de contenido import y snippets.
Red	Un bridge de Linux (por ejemplo, vmbr0) con acceso a la red donde residen las IP de los clientes. Utilice un bridge con soporte para VLAN si introduce una etiqueta VLAN.
IP	Un bloque IPv4 (/16 a /30) enrutado a dicho bridge, con puerta de enlace. NexCMP asigna las direcciones por sí mismo; Proxmox no dispone de gestión de IP.
Plantillas	Una VM de plantilla cloud-init por cada SO, en cada nodo en el que realice despliegues, con el agente de invitado QEMU.
Zona	Una zona existente a la que vincular el clúster. Consulte Zonas.
Depende de	Ninguno.

Preparar la infraestructura

Ejecute los comandos como root en cualquier nodo del clúster.

1) Crear un rol, usuario y token de API con privilegios mínimos

1. Cree el rol. La lista de privilegios es exactamente la que utiliza NexCMP; no contiene nada que permita editar usuarios, definiciones de storage ni el datacenter.

   pveum role add NexCMP -privs "VM.Allocate VM.Clone VM.Config.CDROM VM.Config.CPU VM.Config.Cloudinit VM.Config.Disk VM.Config.HWType VM.Config.Memory VM.Config.Network VM.Config.Options VM.PowerMgmt VM.Audit VM.Console VM.Snapshot VM.Snapshot.Rollback VM.Backup VM.GuestAgent.Audit VM.GuestAgent.Unrestricted Datastore.Audit Datastore.AllocateSpace Datastore.AllocateTemplate Sys.Audit Sys.AccessNetwork SDN.Use SDN.Audit Pool.Audit Mapping.Audit Mapping.Use"

   Sys.AccessNetwork es necesario para la descarga de cloud-image. PVE 9 no dispone del privilegio VM.Monitor; no lo añada.

2. Cree el usuario y un token. --privsep 1 significa que los permisos del token son la intersección de los permisos del usuario y los del propio token.

   pveum user add nexcmp@pve --comment "NexCMP"
   pveum user token add nexcmp@pve api --privsep 1

   El comando muestra el secreto del token una sola vez (un UUID). Cópielo ahora. El ID del token es nexcmp@pve!api.

3. Asigne el rol tanto al usuario como al token. Este es el paso que suele pasarse por alto: con la separación de privilegios, solo el token recibe errores 403 como Datastore.Audit si el usuario no tiene permisos.

   pveum acl modify / --roles NexCMP --users nexcmp@pve
   pveum acl modify / --roles NexCMP --tokens 'nexcmp@pve!api'

4. Pruébelo desde el servidor del panel:

   curl -sk -H 'Authorization: PVEAPIToken=nexcmp@pve!api=<secret>' https://192.0.2.10:8006/api2/json/version

   Un documento JSON con un version significa que el token funciona. (-k es solo para esta comprobación rápida; NexCMP fija el certificado por sí mismo, consulte más abajo).

2. Comprobar el bridge y el almacenamiento

pvesm status          # storages, type, content and free space
ip -br link show type bridge

• Las VM de los clientes reciben interfaces de red virtio en el bridge que introduzca en NexCMP. Si configura una VLAN, el bridge debe ser VLAN-aware.
• Ubique las VM de los clientes en un bridge o VLAN independiente de la dirección de administración del nodo. Si comparten red, el conjunto automático de IP de administración del firewall de Proxmox abre los puertos 22, 8006, 3128, 5900-5999 y 60000-60050 del nodo a cada VM de esa red. Si no puede separarlas, añada una regla DROP explícita para la subred de las VM hacia esos puertos por encima de la regla ACCEPT de administración.

3. Notas sobre el almacenamiento (LVM-thin)

• Mantenga el zeroing del thin-pool en su valor predeterminado. Desactivarlo (lvchange -Zn) puede dejar datos antiguos en los bloques recién asignados y dañar las tablas de particiones o los sistemas de archivos de las VM clonadas.
• Los discos que reportan "write cache: disabled" pueden clonar a solo unos pocos MB/s. Compruébelo con hdparm -W /dev/sdX y habilite la caché de escritura si el disco cuenta con protección contra pérdida de energía.

4. Habilitar el contenido import (solo para el generador de plantillas integrado)

El generador integrado descarga la imagen cloud en el almacenamiento llamado local y crea la plantilla a partir de ella. Añada import (y snippets) a la lista de contenido de ese almacenamiento. Conserve los tipos que ya utiliza; --content reemplaza la lista completa:

pvesm status --storage local     # note the current content
pvesm set local --content iso,vztmpl,backup,import,snippets

5. Crear una plantilla de SO a partir de una imagen cloud

Una plantilla es una VM con cloud-init que NexCMP clona. Cada una se registra bajo una OS key corta como ubuntu-24.04 con su ID de VM. Cree una plantilla por SO en cada nodo que vaya a recibir VM, ya que la clonación se ejecuta en el nodo elegido.

Opción A, recomendada: créela usted mismo. Las imágenes cloud estándar de Ubuntu y Debian no contienen el guest agent y no permiten el inicio de sesión como root, y NexCMP establece la contraseña de root a través de cloud-init. Prepare la imagen primero:

apt install -y libguestfs-tools
wget -O noble.qcow2 https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img
virt-customize -a noble.qcow2 --install qemu-guest-agent \
  --write /etc/cloud/cloud.cfg.d/99-nexcmp.cfg:$'ssh_pwauth: true\ndisable_root: false\n' \
  --write /etc/ssh/sshd_config.d/00-nexcmp.conf:$'PermitRootLogin yes\nPasswordAuthentication yes\n'

A continuación, cree la VM de plantilla (el ID 9000 es un ejemplo; mantenga los ID de plantilla por debajo del valor de vmid from, por defecto 1000):

qm create 9000 --name tpl-ubuntu-24-04 --memory 2048 --cores 2 --cpu host --ostype l26 \
  --scsihw virtio-scsi-single --net0 virtio,bridge=vmbr0 --agent 1 --serial0 socket --vga serial0
qm set 9000 --scsi0 local-lvm:0,import-from=$PWD/noble.qcow2,discard=on,iothread=1
qm set 9000 --ide2 local-lvm:cloudinit --boot order=scsi0
qm template 9000

Opción B: el generador integrado. La tarjeta Create OS template from cloud image en la pestaña Clusters (consulte más abajo) descarga una imagen qcow2, compila la plantilla y la registra. Crea la VM con cloud-init y el flag del guest agent, pero no modifica el contenido de la imagen. Utilícela solo con una imagen que ya permita el inicio de sesión de root y ejecute el guest agent, o cuando también proporcione un fragmento vendor-data de cloud-init.

El guest agent es necesario para Reset password y para mostrar la dirección IP de la VM.

6. Conocer la huella digital del certificado (opcional)

NexCMP confía en el clúster fijando la huella digital SHA-256 de su certificado TLS, por lo que un certificado autofirmado es válido. Para ver el valor que fijará NexCMP:

openssl x509 -in /etc/pve/local/pve-ssl.pem -noout -fingerprint -sha256

Conectar en NexCMP

1. Abra Infrastructure › Cloud provider › Providers y haga clic en Add cloud provider. Elija Proxmox VE y complete:

   Campo	Valor de ejemplo
   Nombre	Proxmox cluster 1
   Endpoint	https://192.0.2.10:8006
   ID del token	nexcmp@pve!api
   Secreto del token	XXXX (el UUID mostrado en el paso 1)
   Slug	pve-1 (a-z, 0-9, guion, 2-32 caracteres)
   Nodo predeterminado	pve1 (vacío: el nodo online con más RAM libre)
   Almacenamiento	local-lvm
   Bridge	vmbr0

   

2. Haga clic en Save & open provider e introduzca un motivo si se le solicita. El token se cifra antes de almacenarse.

3. En la pestaña Overview, haga clic en Test connection. La primera prueba correcta fija la huella digital TLS del clúster; a partir de ese momento se rechazará cualquier certificado diferente.

4. Abra la pestaña Clusters. La tarjeta Node · storage · bridge muestra lo que detecta la API; la tarjeta Cluster configuration contiene los ajustes:

   Campo	Significado
   Nodo predeterminado	Nodo utilizado para las nuevas VM. Si está vacío, se utilizará el nodo online con más RAM libre.
   Storage, Bridge, VLAN	Almacenamiento en disco, bridge de la NIC y etiqueta VLAN opcional (0 significa ninguna).
   CPU type	host de forma predeterminada. Utilice x86-64-v2-AES cuando los nodos tengan diferentes generaciones de CPU.
   vmid from	Primer ID de VM asignado a las VM de clientes (por defecto 1000).
   Storage ISO, Storage backup	Déjelo vacío salvo que los utilice; si está vacío, las funciones de ISO y backup no se ofrecerán.
   Template OS	Uno por línea, os-key=vmid, por ejemplo ubuntu-24.04=9000.
   Pinned TLS fingerprint (SHA-256)	Se completa con la primera prueba. Bórrelo y vuelva a probar después de sustituir el certificado del clúster.

   

5. Opcional: si utilizó la Opción B anterior, complete Create OS template from cloud image (clave de SO ubuntu-24.04, vmid 9000, nodo pve1, la URL de la imagen qcow2) y haga clic en Create template. Se ejecuta en segundo plano durante unos minutos; el resultado se encuentra en el Audit log.

   

6. Haga clic en Add pool dentro de Cluster IP pool y cree el pool del cual las VM obtendrán sus direcciones:

   Campo	Valor de ejemplo
   Nombre	customers-1
   CIDR	198.51.100.0/24
   Gateway	198.51.100.1 (nunca se asigna a una VM)
   DNS	1.1.1.1,8.8.8.8 (de 1 a 4 direcciones IPv4)
   Bridge, VLAN	vmbr0, 0
   Already used IPs	una por línea, ip note, por ejemplo 198.51.100.10 monitoring

   NexCMP nunca asigna la dirección de red, la dirección de broadcast, la gateway ni una dirección reservada. Los pools del mismo clúster no pueden solaparse. Solo se puede eliminar un pool cuando ninguna de sus direcciones esté en uso.

   

7. En Attach cluster to zone, elija la zona y, opcionalmente, un nombre de nodo, y luego haga clic en Attach to zone. El clúster se une a la zona que ya vende VM, por lo que una misma zona puede combinar CloudStack y Proxmox. El nuevo origen no se vende por defecto y no modifica el comportamiento de los planes existentes.

   

8. Abra Services › Virtual Machines › Plans & pricing y haga clic en Add plan. En Infrastructure source, elija el clúster de Proxmox y configure CPU, RAM, disco y precio. Un plan de Proxmox no requiere un offering de CloudStack. Para vender la misma configuración desde ambos orígenes, use Clone en un plan y elija el otro origen. El disco del plan debe ser al menos tan grande como el de la plantilla; Proxmox no puede reducir el tamaño de un disco.

Importar una VM ya existente

Abra la pestaña Servers para listar las VM del cluster. Import asigna una VM existente a la cuenta de un cliente sin costo: no se factura nada por horas, tiempo de apagado ni tráfico. El cliente puede iniciar, detener, reiniciar y abrir la consola, pero no puede eliminarla; solo un administrador puede hacerlo. NexCMP únicamente lee del cluster durante la importación.

• El cluster debe estar asociado a una zona con el nombre del nodo de esa VM (si deja el nodo vacío, las importaciones informarán que la región no está configurada).

• Para hacer que una VM esté protegida (se rechazan las acciones de detener, reiniciar, reinstalar, restaurar snapshot, destruir y cambiar de plan), impórtela desde la línea de comandos con --protect:

  sudo -u nexcmp /opt/nexcmp/bin/nexcmp px-import --provider pve-1 --server-ref pve1/101 --account-id 12 --hostname web-1 --protect

Qué es compatible y qué no en Proxmox

Característica	Proxmox VE
Crear, encender/apagar/reiniciar, eliminar	Sí
Redimensionar CPU y RAM, ampliar el disco	Sí, pero la VM se detiene, se modifica y se inicia nuevamente (sin redimensionamiento en caliente)
Snapshots	Sí, hasta 5 por VM: crear, listar, restaurar, eliminar
Reinstalar	Sí: la VM se reconstruye a partir de la plantilla y conserva su ID, IP y configuración, con una nueva contraseña
Restablecer contraseña	Sí, a través del guest agent
Consola	Sí, una consola en el navegador con proxy a través del panel
Métricas	Sí: CPU, memoria, red y disco
Montaje de ISO, Backups, firewall, IPv6, reenvío de puertos, cambio de IP, volúmenes adicionales, Auto Scaling, DDoS Shield, VPC, medición de ancho de banda	No disponible. La página de la VM del cliente oculta lo que un origen no puede hacer.

Verificación

1. Test connection muestra OK y el estado del proveedor es activo.
2. Clusters lista sus nodos como en línea, con el almacenamiento y el bridge.
3. Cluster IP pool muestra las cantidades libres, en uso y retenidas.
4. La clave de SO aparece bajo las plantillas de la zona en Services › Virtual Machines › Template tras asociar el cluster.
5. Solicite una VM de prueba a partir de un plan que utilice el cluster. Debería recibir una dirección del pool, una contraseña de root y una consola funcional; el pool mostrará una dirección utilizada.

Límites y notas

Zonas de origen mixto

Desde NexCMP 1.4.0, la lista pública de precios de Cloud Server también funciona cuando CloudStack y Proxmox VE comparten una zona. Cada plan utiliza su propio Infrastructure source. Tras vincular un clúster, revise la lista de precios pública y realice un pedido de prueba para cada origen.

• Se pueden añadir varios clusters de Proxmox. Cada uno es un proveedor.
• Una zona ofrece un origen predeterminado; un plan con su propio Infrastructure source se despliega exactamente en ese cluster, siempre que el cluster esté activo y en la zona del plan.
• Un cluster detrás de la misma zona que CloudStack mantiene sus planes heredados en CloudStack. Pruebe un pedido de extremo a extremo antes del lanzamiento.
• El token de la API solo se puede reemplazar, nunca ver. Reemplácelo en la pestaña Credentials: cree primero el nuevo token en Proxmox, ingréselo, ejecute Test connection y luego revoque el token anterior.
• Las acciones Test, Sync y cluster-info están limitadas a seis llamadas por minuto por administrador.
• NexCMP factura a sus clientes; el costo de hardware y licencias del cluster corre por su cuenta.

Resolución de problemas

Síntoma	Causa	Solución
Test: "Key rejected (wrong access key / secret, or revoked)" o HTTP 401/403	ID de token o secret incorrectos, o la ACL se otorgó únicamente al token	Vuelva a ejecutar los dos comandos pveum acl modify (usuario y token) y verifique que el token id sea user@realm!tokenid.
Test: "Could not connect to the provider" o "Timed out"	Firewall, host o puerto incorrectos	Verifique https://host:8006 desde el servidor del panel.
Prueba: "Endpoint no válido o no está en la lista de permitidos"	El endpoint tiene una ruta, usuario o consulta, o no es HTTPS	Utilice exactamente https://host:8006.
"El certificado TLS del clúster NO coincide con la huella digital fijada"	Se reemplazó el certificado del clúster	Borre Pinned TLS fingerprint en la pestaña Clusters, guarde y vuelva a ejecutar Test connection.
Slug rechazado	No contiene a-z, 0-9, guiones, o no tiene entre 2 y 32 caracteres	Utilice algo como pve-1.
"Formato del ID de token: user@realm!tokenid y el secret es obligatorio"	Falta el token id o el secret	Introduzca ambos; el secret es el UUID que se mostró al crear el token.
"Línea de plantilla no válida: …"	Una línea en Template OS no es key=vmid	Utilice letras, dígitos, ., _, - en la clave y un vmid de al menos 100.
"Clave de SO: a-z 0-9 . _ - y vmid ≥ 100"	Clave o id no válidos en Create template	Corrija la clave de OS y use un vmid libre.
"vmid … already exists" al crear una plantilla	El vmid ya está en uso	Elija otro id.
"la URL apunta a una dirección interna"	La URL de la imagen es una IP interna	Utilice una URL pública; Proxmox se encarga de resolver los nombres.
La tarea de plantilla falla durante la descarga	El almacenamiento local no admite contenido import	pvesm set local --content …,import,snippets y vuelva a intentarlo. El nombre de archivo debe terminar en .qcow2, .raw, .vmdk, .ova o .ovf.
"cluster has no online nodes" o "node … is not online"	El nodo predeterminado está inactivo o mal escrito	Corrija Default node o déjelo en blanco.
"la imagen no pertenece al clúster""	El OS del plan no está en Template OS	Añada la clave a la lista y guarde.
El despliegue espera y luego falla al clonar	La VM de plantilla no está en el nodo seleccionado	Cree la plantilla en ese nodo o configure Default node con el nodo que la contiene.
El cliente no puede iniciar sesión como root	La imagen bloquea el inicio de sesión de root	Vuelva a generar la plantilla como en la Opción A.
Restablecer contraseña no produce ningún efecto	No hay guest agent en el huésped	Instale y habilite qemu-guest-agent en la plantilla.
"El nombre, el CIDR y la puerta de enlace son obligatorios"	Falta un campo del pool	Complete los tres.
Creación del pool: "overlaps with pool …", "gateway must be within range (not network/broadcast address)" o "cidr: network address must be …"	Pool superpuesto, gateway incorrecta o un CIDR que no está en el límite de la red	Utilice un rango libre, una gateway dentro de él y un CIDR expresado como la dirección de red (por ejemplo 198.51.100.0/24).
Importación: "region is not set up"	El clúster está vinculado sin el nombre de nodo de la VM	Vincule el clúster a la zona con el nombre de nodo.