---
title: Proxmox VE
description: Adicione clusters Proxmox VE como origem de VM: token de API com menor privilégio, armazenamento, modelos cloud-image, pools de IP e fixação TLS.
url: https://nexcmp.com/pt/docs/infrastructure/proxmox/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# 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 {#what-it-does}

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 {#requirements}

| 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](https://nexcmp.com/pt/docs/infrastructure/zones/). |
| Depende de | Nothing. |

## Preparar a infraestrutura {#prepare-the-infrastructure}

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-create-a-least-privilege-role-user-and-api-token}

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.

   ```bash
   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.

   ```bash
   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.

   ```bash
   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:

   ```bash
   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 {#_2-check-the-bridge-and-the-storage}

```bash
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) {#_3-storage-notes-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) {#_4-enable-the-import-content-only-for-the-built-in-template-builder}

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:

```bash
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 {#_5-build-an-os-template-from-a-cloud-image}

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:

```bash
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):

```bash
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) {#_6-know-the-certificate-fingerprint-optional}

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:

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

## Conectar no NexCMP {#connect-in-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` |

      ![Add cloud provider dialog com o Proxmox VE selecionado e valores de exemplo de endpoint, token e armazenamento](https://nexcmp.com/pt/docs/images/infrastructure/proxmox-01-add-provider.webp)

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

      ![Aba Clusters, card Cluster configuration com exemplo de nó, armazenamento, bridge e lista de templates de SO](https://nexcmp.com/pt/docs/images/infrastructure/proxmox-03-cluster-config.webp)

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.

      ![Card Create OS template from cloud image com uma URL de exemplo de imagem do Ubuntu](https://nexcmp.com/pt/docs/images/infrastructure/proxmox-04-template-from-image.webp)

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.

      ![Diálogo de adição de pool de IP com um exemplo de /24 e gateway](https://nexcmp.com/pt/docs/images/infrastructure/proxmox-05-ip-pool.webp)

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.

      ![Card de anexar cluster à zona com uma zona existente selecionada](https://nexcmp.com/pt/docs/images/infrastructure/proxmox-06-attach-zone.webp)

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 {#import-a-vm-that-already-exists}

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`:

  ```bash
  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 {#what-is-and-is-not-supported-on-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 {#verify}

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 {#limits-and-notes}

::: tip 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 {#troubleshooting}

| 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ó. |