Proxmox VE

Onde no admin: Infrastructure › Cloud provider › Providers (/infra/providers), depois a página do provedor (/infra/providers/<id>) com as abas Overview, Clusters, VMs, Servers e Credentials. Os planos são definidos em Services › Virtual Machines › Plans & pricing (/vm/catalog).

O que faz

O NexCMP pode vender máquinas virtuais executadas em um ou mais clusters Proxmox VE, ao lado ou em vez do CloudStack. Uma VM é criada clonando um modelo de OS com clonagem completa, sendo configurada via cloud-init: tamanho, endereço IP de um pool definido por você, senha de root e chave SSH. Os clientes obtêm controle de energia, console, snapshots, reinstalação, redefinição de senha e métricas no portal. Eles nunca veem o cluster, o nó ou o nome da fonte.

Use quando você já opera o Proxmox VE, ou para oferecer um segundo pool de VMs com preços diferentes.

Requisitos

Item	Requisito
Proxmox VE	PVE 9.x. A integração foi verificada na versão 9.2. Requer o conteúdo de armazenamento import e a opção de disco import-from (PVE 8.2 ou mais recente).
Rede a partir do painel	HTTPS para a API do cluster, https://<host or IP>:8006. Sem caminho, nome de usuário ou consulta. O painel e o worker se conectam; o console do navegador é roteado via proxy pelo painel.
Conta	Um usuário dedicado do PVE com um token de API e uma função personalizada com os privilégios listados abaixo. Nunca use root@pam.
Armazenamento	Um armazenamento para discos de VM que suporte clones (por exemplo, local-lvm). Para o construtor de modelos integrado, o armazenamento chamado local com os tipos de conteúdo import e snippets.
Rede	Uma bridge do Linux (por exemplo, vmbr0) que alcance a rede onde os IPs dos clientes residem. Use uma bridge ciente de VLAN se você inserir uma tag de VLAN.
IPs	Um bloco IPv4 (/16 a /30) roteado para essa bridge, com um gateway. O NexCMP atribui os endereços por conta própria; o Proxmox não possui gerenciamento de IP.
Templates	Uma VM de modelo cloud-init por SO, em cada nó para o qual você implantar, com o agente de convidado QEMU.
Zone	Uma zona existente para anexar o cluster. Consulte Zones.
Depende de	Nothing.

Preparar a infraestrutura

Execute os comandos como root em qualquer nó do cluster.

1. Criar uma função, um usuário e um token de API com privilégios mínimos

1. Crie a função. A lista de privilégios é exatamente a utilizada pelo NexCMP; ela não contém nada que edite usuários, definições de armazenamento ou o 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 é obrigatório para o download de imagens em nuvem. O PVE 9 não possui o privilégio VM.Monitor; não o adicione.

2. Crie o usuário e um token. --privsep 1 significa que os direitos do token são a intersecção entre as permissões do usuário e as permissões do próprio token.

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

   O comando exibe o token secret apenas uma vez (um UUID). Copie-o agora. O ID do token é nexcmp@pve!api.

3. Conceda a função tanto ao usuário quanto ao token. Esta é a etapa que as pessoas esquecem: com a separação de privilégios, apenas o token recebe erros 403, como Datastore.Audit, se o usuário não tiver permissão.

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

4. Teste-o a partir do servidor do painel:

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

   Um documento JSON com version significa que o token funciona. (-k serve apenas para esta verificação rápida; o NexCMP fixa o certificado por conta própria, veja abaixo.)

2. Verifique a bridge e o armazenamento

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

• As VMs de clientes recebem virtio interfaces de rede na bridge informada no NexCMP. Se você definir uma VLAN, a bridge deve ter suporte a VLAN (VLAN-aware).
• Coloque as VMs de clientes em uma bridge ou VLAN separada do endereço de gerenciamento do nó. Se compartilharem uma rede, o conjunto automático de IPs de gerenciamento do firewall do Proxmox abre as portas 22, 8006, 3128, 5900-5999 e 60000-60050 do nó para todas as VMs nessa rede. Se não puder separá-las, adicione uma regra DROP explícita para a sub-rede da VM nessas portas, acima da regra ACCEPT de gerenciamento.

3. Notas sobre armazenamento (LVM-thin)

• Deixe o zeroing (zeragem) do thin-pool no padrão. Desativá-lo (lvchange -Zn) pode deixar dados antigos em blocos recém-alocados e corromper as tabelas de partições ou sistemas de arquivos de VMs clonadas.
• Discos que reportam "write cache: disabled" podem clonar a apenas alguns MB/s. Verifique com hdparm -W /dev/sdX e ative o cache de escrita se o disco tiver proteção contra perda de energia.

4. Ative o conteúdo import (apenas para o construtor de templates integrado)

O construtor integrado baixa a imagem de nuvem no armazenamento chamado local e cria o template a partir dela. Adicione import (e snippets) à lista de conteúdos desse armazenamento. Mantenha os tipos que você já usa; --content substitui a lista inteira:

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

5. Construir um template de SO a partir de uma imagem de nuvem

Um template é uma VM cloud-init que o NexCMP clona. Cada um é registrado sob uma OS key curta como ubuntu-24.04 com o id da VM correspondente. Crie um template por SO em cada nó que receberá VMs, pois o clone é executado no nó escolhido.

Opção A, recomendada: construa você mesmo. As imagens de nuvem padrão de Ubuntu e Debian não contêm o guest agent e não permitem login como root, e o NexCMP define a senha de root por meio do cloud-init. Prepare a imagem primeiro:

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'

Em seguida, crie a VM de template (o ID 9000 é um exemplo; mantenha os IDs de template abaixo do valor vmid from, padrão 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

Opção B: o construtor integrado. O card Create OS template from cloud image na aba Clusters (veja abaixo) baixa uma imagem qcow2, cria o template e o registra. Ele cria a VM com o cloud-init e a flag do guest agent, mas não altera o conteúdo interno da imagem. Use-o apenas com uma imagem que já permita login como root e execute o guest agent, ou quando você também fornecer um trecho de vendor-data do cloud-init.

O guest agent é necessário para Reset password e para exibir o endereço IP da VM.

6. Conhecer a impressão digital do certificado (opcional)

O NexCMP confia no cluster fixando a impressão digital SHA-256 do seu certificado TLS, portanto, um certificado autoassinado é aceitável. Para ver o valor que o NexCMP vai fixar:

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

Conectar no NexCMP

1. Abra Infrastructure › Cloud provider › Providers e clique em Add cloud provider. Escolha Proxmox VE e preencha:

   Campo	Valor de exemplo
   Name	Proxmox cluster 1
   Endpoint	https://192.0.2.10:8006
   Token id	nexcmp@pve!api
   Token secret	XXXX (o UUID exibido na etapa 1)
   Slug	pve-1 (a-z, 0-9, hífen, 2-32 caracteres)
   Default node	pve1 (vazio: o nó online com mais RAM livre)
   Armazenamento	local-lvm
   Bridge	vmbr0

   

2. Clique em Save & open provider e informe um motivo quando solicitado. O token é criptografado antes de ser armazenado.

3. Na aba Overview, clique em Test connection. O primeiro teste bem-sucedido fixa a impressão digital TLS do cluster; a partir daí, qualquer certificado diferente será recusado.

4. Abra a aba Clusters. O card Node · storage · bridge lista o que a API enxerga; o card Cluster configuration contém as configurações:

   Campo	Significado
   Default node	Nó usado para novas VMs. Vazio significa o nó online com mais RAM livre.
   Storage, Bridge, VLAN	Armazenamento de disco, bridge de placa de rede e tag VLAN opcional (0 significa nenhuma).
   CPU type	host por padrão. Use x86-64-v2-AES quando os nós tiverem gerações de CPU diferentes.
   vmid from	Primeiro ID de VM atribuído às VMs de clientes (padrão 1000).
   Storage ISO, Storage backup	Deixe em branco, a menos que os utilize; vazio significa que os recursos de ISO e backup não são oferecidos.
   Template OS	Um por linha, os-key=vmid, por exemplo ubuntu-24.04=9000.
   Pinned TLS fingerprint (SHA-256)	Preenchido pelo primeiro teste. Limpe-o e teste novamente após substituir o certificado do cluster.

   

5. Opcional: se você usou a Opção B acima, preencha Create OS template from cloud image (OS key ubuntu-24.04, vmid 9000, nó pve1, a URL da imagem qcow2) e clique em Create template. O processo é executado em segundo plano por alguns minutos; o resultado fica no Audit log.

   

6. Clique em Add pool em Cluster IP pool e crie o pool de onde as VMs obterão endereços IP:

   Campo	Valor de exemplo
   Name	customers-1
   CIDR	198.51.100.0/24
   Gateway	198.51.100.1 (nunca atribuído a uma VM)
   DNS	1.1.1.1,8.8.8.8 (1 a 4 endereços IPv4)
   Bridge, VLAN	vmbr0, 0
   Already used IPs	um por linha, ip note, por exemplo 198.51.100.10 monitoring

   O NexCMP nunca atribui o endereço de rede, o endereço de broadcast, o gateway ou um endereço reservado. Pools do mesmo cluster não podem se sobrepor. Um pool só pode ser excluído quando nenhum de seus endereços estiver em uso.

   

7. Em Attach cluster to zone, escolha a zona e, opcionalmente, um nome de nó, depois clique em Attach to zone. O cluster ingressa na zona que já vende VMs, permitindo que uma zona tenha CloudStack e Proxmox juntos. A nova origem não é vendida por padrão e não altera o comportamento dos planos existentes.

   

8. Abra Services › Virtual Machines › Plans & pricing e clique em Add plan. Em Infrastructure source, escolha o cluster Proxmox e, em seguida, defina CPU, RAM, disco e preço. Um plano do Proxmox não precisa de uma offering do CloudStack. Para vender a mesma configuração a partir de ambas as origens, use Clone em um plano e escolha a outra origem. O disco do plano deve ser pelo menos tão grande quanto o disco do template; o Proxmox não pode reduzir um disco.

Importar uma VM já existente

Abra a aba Servers para listar as VMs no cluster. Import atribui uma VM existente a uma conta de cliente sem custo: nada é cobrado por horas, tempo desligado ou tráfego. O cliente pode iniciar, desligar, reiniciar e abrir o console, mas não pode excluí-la; apenas um administrador pode. O NexCMP apenas lê do cluster durante a importação.

• O cluster deve estar vinculado a uma zona com o nome do nó dessa VM (deixe o nó vazio e as importações relatarão que a região não está configurada).

• Para tornar uma VM protected (parar, reiniciar, reinstalar, restaurar snapshot, destruir e alterar plano são recusados), importe-a pela linha de comando com --protect:

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

O que é e o que não é suportado no Proxmox

Recurso	Proxmox VE
Criar, ligar/desligar/reiniciar, excluir	Sim
Redimensionar CPU e RAM, expandir o disco	Sim, mas a VM é desligada, alterada e iniciada novamente (sem redimensionamento em tempo de execução)
Snapshots	Sim, até 5 por VM: criar, listar, restaurar, excluir
Reinstalar	Sim: a VM é reconstruída a partir do template e mantém seu ID, IP e configurações, com uma nova senha
Redefinir senha	Sim, através do guest agent
Console	Sim, um console de navegador com proxy pelo painel
Métricas	Sim: CPU, memória, rede e disco
Montagem de ISO, backups, firewall, IPv6, encaminhamento de porta, alteração de IP, volumes extras, Auto Scaling, DDoS Shield, VPC, medição de largura de banda	Não disponível. A página da VM do cliente oculta o que uma fonte não pode fazer.

Verificar

1. Test connection exibe OK e o status do provedor está ativo.
2. Clusters lista seus nós como online, com o armazenamento e a bridge.
3. Cluster IP pool mostra as contagens de endereços livres, usados e reservados.
4. A chave do SO aparece sob os templates da zona em Services › Virtual Machines › Template após o cluster ser conectado.
5. Peça uma VM de teste de um plano que use o cluster. Ela deve obter um endereço do pool, uma senha de root e um console funcional; o pool mostra um endereço usado.

Limites e observações

Zonas de fontes mistas

Desde o NexCMP 1.4.0, a tabela de preços pública do Cloud Server também funciona quando o CloudStack e o Proxmox VE compartilham uma zona. Cada plano usa seu próprio Infrastructure source. Depois de anexar um cluster, confira a tabela de preços pública e faça um pedido de teste para cada fonte.

• Vários clusters Proxmox podem ser adicionados. Cada um é um provedor.
• Uma zona oferece uma fonte padrão; um plano com sua própria Infrastructure source é implantado exatamente nesse cluster, desde que o cluster esteja ativo e na zona do plano.
• Um cluster atrás da mesma zona que o CloudStack mantém seus planos legados no CloudStack. Teste um pedido de ponta a ponta antes do lançamento.
• O token de API só pode ser substituído, nunca visualizado. Substitua-o na aba Credentials: crie o novo token no Proxmox primeiro, insira-o, execute Test connection e, em seguida, revoque o token antigo.
• As ações Test, Sync e cluster-info são limitadas a seis chamadas por minuto por administrador.
• O NexCMP cobra de seus clientes; o custo de hardware e licença do cluster é seu.

Resolução de problemas

Sintoma	Causa	Correção
Test: "Key rejected (wrong access key / secret, or revoked)" ou HTTP 401/403	ID de token ou segredo incorreto, ou a ACL foi concedida apenas ao token	Execute novamente os dois comandos pveum acl modify (usuário e token) e verifique se o id do token é user@realm!tokenid.
Teste: "Could not connect to the provider" ou "Timed out"	Firewall, host ou porta incorretos	Verifique https://host:8006 a partir do servidor do painel.
Teste: "Invalid endpoint or not on the allowlist"	O endpoint possui um caminho, usuário, query ou não é HTTPS	Use exatamente https://host:8006.
"o certificado TLS do cluster NÃO corresponde à impressão digital fixada (pinned fingerprint)"	O certificado do cluster foi substituído	Limpe Pinned TLS fingerprint na aba Clusters, salve e execute Test connection novamente.
Slug rejeitado	Não é a-z, 0-9, hífen ou não tem entre 2 e 32 caracteres	Use algo como pve-1.
"Formato do ID do token: user@realm!tokenid e o secret são obrigatórios"	ID do token ou segredo ausente	Insira ambos; o segredo é o UUID exibido quando o token foi criado.
"Linha de template inválida: …"	Uma linha em Template OS não é key=vmid	Use letras, dígitos, ., _, - na chave e um vmid de pelo menos 100.
"Chave do SO: a-z 0-9 . _ - e vmid ≥ 100"	Chave ou ID inválido em Create template	Corrija a chave do SO e use um vmid disponível.
"vmid … already exists" ao criar um template	O vmid já está em uso	Escolha outro ID.
"a URL aponta para um endereço interno"	A URL da imagem é um IP interno	Use uma URL pública; os nomes são resolvidos pelo Proxmox.
A tarefa de template falha no download	O armazenamento local não possui conteúdo import	pvesm set local --content …,import,snippets, e tente novamente. Um nome de arquivo deve terminar em .qcow2, .raw, .vmdk, .ova ou .ovf.
"cluster has no online nodes" ou "node … is not online"	O nó padrão está offline ou com o nome incorreto	Corrija Default node ou deixe-o em branco.
"a imagem não pertence ao cluster"	O SO do plano não está em Template OS	Adicione a chave à lista e salve.
A implantação aguarda e depois falha na clonagem	A VM de template não está no nó escolhido	Crie o template nesse nó ou defina Default node como o nó que o possui.
O cliente não consegue fazer login como root	A imagem bloqueia o login como root	Recompile o template conforme a Opção A.
A redefinição de senha não faz nada	Sem guest agent no sistema convidado	Instale e habilite o qemu-guest-agent no template.
"Nome, CIDR e gateway são obrigatórios"	Campo de pool ausente	Preencha todos os três.
Pool create: "overlaps with pool …", "gateway must be within range (not network/broadcast address)" ou "cidr: network address must be …"	Pool sobreposto, gateway incorreto ou um CIDR que não está em um limite de rede	Use uma faixa livre, um gateway dentro dela e um CIDR escrito como o endereço de rede (por exemplo, 198.51.100.0/24).
Importação: "a região não está configurada"	O cluster está vinculado sem o nome do nó da VM	Vincule o cluster à zona com o nome do nó.