Templates de OS e ISOs

Onde no admin: Services › Virtual Machines › Template (/vm/templates). Os templates do Proxmox são listados por cluster em Infrastructure › Cloud provider › Providers › (cluster) › Clusters.

O que faz

Um template é a imagem de sistema operacional da qual uma nova VM é iniciada. O NexCMP não armazena imagens por conta própria: ele lê o que o CloudStack reporta (templates prontos e em destaque) ou o que você lista para um cluster Proxmox, e permite escolher quais são vendidos, com um nome voltado ao cliente, ícone e usuário de login. Esta página mostra como preparar imagens que funcionam bem com o NexCMP: login por senha, redimensionamento dinâmico de CPU e RAM, arquivo swap e um disco raiz que cresce até o tamanho do plano.

Requisitos

Item	Requisito
Construtor de templates do CloudStack	Uma máquina Linux com libguestfs-tools (virt-customize, virt-sparsify, guestfish), qemu-utils, curl e cerca de 5 GB de disco livre. Não são necessários KVM nem root. Acesso à internet para instalações de pacotes (ou compile com --offline).
Onde fica o construtor	Ele vem incluído em todas as versões em /opt/nexcmp/releases/<version>/share/templates/ no servidor do painel. Você não precisa executá-lo lá: copie a pasta para qualquer máquina Linux.
Servidor web	Qualquer servidor HTTP(S) que a VM de armazenamento secundário do CloudStack possa alcançar para publicar o arquivo .qcow2 finalizado. Ele não precisa estar acessível a partir da Internet.
CloudStack	Uma conta que possa registrar templates, e o ID da sua zona e de um tipo de OS correspondente. Consulte CloudStack.
Proxmox VE	VMs de template com cloud-init e o agente convidado QEMU, uma por OS e por nó. Consulte Proxmox VE.
Depende de	CloudStack ou Proxmox VE conectado primeiro.

Preparar a infraestrutura

CloudStack: criar um template

Imagens base suportadas (a imagem do fornecedor é baixada e seu checksum é verificado antes de qualquer alteração):

Imagem	--distro	Usuário de login
Ubuntu 22.04	ubuntu-22.04	ubuntu
Ubuntu 24.04	ubuntu-24.04	ubuntu
Debian 12	debian-12	debian
Rocky Linux 9	rocky-9	rocky

Mais distribuições: adicione uma linha a distros.conf (URL da imagem, arquivo de checksum, família deb ou rpm).

1. Copie o construtor para uma máquina de compilação e execute-o:

   cp -r /opt/nexcmp/releases/<version>/share/templates ~/templates && cd ~/templates
   ./build-template.sh --distro ubuntu-24.04 --version v7 --work ./out

   Adicione --panel-url https://cloud.example.com para incluir um agente opcional de monitoramento no primeiro boot que se registra com o seu painel (somente HTTPS). Sem ele, nenhum agente é adicionado. Outras opções: --base <file> para usar uma imagem que você baixou, --offline para ignorar instalações de pacotes.

2. O resultado é out/ubuntu-24.04-v7.qcow2 e seu .sha256. A compilação termina executando verify-image.sh, que inspeciona a imagem finalizada como somente leitura e rejeita imagens defeituosas (ela é mantida como .unverified). Você pode executá-lo novamente a qualquer momento: ./verify-image.sh out/ubuntu-24.04-v7.qcow2 --no-agent.

O que o construtor insere na imagem:

Item	Motivo
qemu-guest-agent	O CloudStack pode consultar a VM sobre CPUs e IPs, e colocá-la em espera (quiesce) para snapshots.
cloud-init com a fonte de dados do CloudStack, set_passwords em cada inicialização, login de senha por SSH	A senha gerada é obtida a partir do roteador virtual e Reset password funciona.
Uma regra udev para CPU e RAM adicionadas a quente (hot-added)	vCPUs e RAM adicionadas a quente entram em atividade sozinhas, fazendo com que o dimensionamento em tempo real (live scaling) e o Auto Scaling funcionem.
Um serviço de arquivo de troca (swap file)	Cria /swapfile do menor valor entre 50% da RAM e 4 GiB após o disco crescer. touch /etc/cmp-swap.disabled o desativa.
cloud-init growpart e resizefs	O pequeno disco raiz cresce para o tamanho de disco do plano na primeira inicialização.
machine-id vazio, sem chaves de host SSH	Cada VM obtém sua própria identidade.

Nomeie o template como <OS> <version> <vN>

O NexCMP ativa o Auto Scaling para templates cujo nome termina em vN ou vN.M com N de 6 ou mais (Ubuntu 24.04 v7, Rocky Linux 9 v7.1). O construtor impõe isso para --version. Registre o template exatamente com o nome impresso.

3. Publique o arquivo e registre-o no CloudStack. Use o SHA-256 impresso pelo build e registre somente após o arquivo ser totalmente gravado:

   cmk list ostypes keyword="Ubuntu 24.04" filter=id,description
   cmk register template name="Ubuntu 24.04 v7" displaytext="Ubuntu 24.04 v7" \
     url=https://files.example.com/ubuntu-24.04-v7.qcow2 zoneid=<zone-id> format=QCOW2 hypervisor=KVM \
     ostypeid=<os-type-id> passwordenabled=true sshkeyenabled=true isdynamicallyscalable=true \
     requireshvm=true isextractable=false ispublic=true isfeatured=true \
     checksum="{SHA-256}<sha256 of the file>" \
     details[0].guest.cpu.mode=host-passthrough details[0].rootDiskController=osdefault

   • passwordenabled=true permite que o CloudStack gere a senha da VM.
   • isdynamicallyscalable=true permite o dimensionamento em tempo real (live scaling).
   • host-passthrough é necessário para as imagens atuais do Rocky e Alma inicializarem; osdefault mantém o controlador de disco portátil.

4. Aguarde o template atingir Download Complete / Ready.

A imagem do fornecedor mantém seu tamanho virtual pequeno (cerca de 3.5 GiB para Ubuntu e Debian, 10 GiB para Rocky). Lembre-se de que o disco de um plano não pode ser menor do que o disco do template.

Proxmox VE: criar um template

Crie um template de VM cloud-init por SO em cada nó em que você fizer o deploy, com o agente de convidado instalado e o login de root ativado, e registre-o como os-key=vmid. Os comandos completos estão em Proxmox VE. O construtor do CloudStack acima não é para o Proxmox: ele configura o cloud-init para a fonte de dados do CloudStack.

ISOs

Os clientes montam suas próprias ISOs através do módulo Images (CloudStack) ou do módulo de Servidores Dedicados. Eles são separados dos templates de SO nesta página. Consulte Modules e Dedicated servers.

Conectar no NexCMP

1. Abra Services › Virtual Machines › Template. Clique em Sync now ou aguarde até 15 minutos. A sincronização adiciona templates prontos e em destaque no CloudStack.

   

2. Clique em Edit em um novo template e defina o que os clientes veem:

   Campo	Valor de exemplo
   Nome de exibição para clientes	Ubuntu 24.04 LTS
   Família do SO	ubuntu (ícone e usuário padrão)
   Versão	24.04
   Nome de usuário para login	ubuntu (Windows: Administrator; outros: root)
   Ícone	URL da imagem, um caminho ou um nome
   Order	10
   Active	On
   Hot-plug de vCPU/RAM (escala em tempo real)	Auto by name (v6 or later), Yes ou No (needs a restart)

   

3. Ative o template. Um template que o CloudStack não lista mais é ocultado automaticamente (e você é alertado no Telegram se configurado); ele nunca é excluído do NexCMP.

Substituir um modelo por uma versão mais recente

Use More › Replace with new version no modelo comercializado. Escolha o novo modelo pronto e atualmente desativado. A entrada comercializada passa a apontar para a nova compilação, mantendo o nome, a ordem e o ícone; a antiga é desativada como opção de retorno (para voltar, use Replace na nova entrada). As VMs em execução não são afetadas. Se a nova compilação pertencer a uma família de SO diferente, marque a confirmação primeiro.

Verificar

1. A linha mostra ready e, para compilações chamadas vN com N igual a 6 ou mais, CPU hot-plug: supported.
2. Implante uma VM de teste a partir do modelo e verifique dentro dela:
   • você pode fazer login com a senha exibida no portal;
   • df -h / exibe o tamanho do disco do plano;
   • após um redimensionamento dinâmico (Change plan sem reinicialização), nproc e free -m aumentam;
   • swapon --show lista /swapfile (discos com menos de swap mais 2 GiB livres são ignorados);
   • systemctl is-active qemu-guest-agent exibe active.
3. Se você integrou o agente, a VM aparecerá nos hosts monitorados do painel um minuto após a primeira inicialização. A VM precisa de um IP público próprio: o painel a reconhece pelo IP de origem público.

Limites e observações

• O construtor é exclusivo para Linux e compila imagens Linux. Outras imagens (por exemplo, Windows) podem ser registradas no CloudStack por outros meios; o NexCMP lista o que o CloudStack reporta.
• Apenas o agente amd64 é distribuído; outras arquiteturas ignoram a instalação do agente.
• A imagem é verificada com guestfish, mas nunca inicializada pelo construtor. Sempre implante uma VM de teste antes de disponibilizar uma nova imagem.
• Ignore o agente em uma VM com touch /etc/cmp-agent.disabled antes da primeira inicialização. Remova-o mais tarde com systemctl disable --now cmp-agent cmp-agent-install; rm -rf /etc/cmp-agent /usr/local/bin/cmp-agent e, em seguida, exclua o agente no console de administração.

Resolução de problemas

Sintoma	Causa	Correção
virt-customize falha ao baixar pacotes	A máquina de compilação não tem rede de saída	Corrija o DNS ou o proxy nessa máquina ou compile com --offline em uma imagem base que já possua os pacotes.
libguestfs: error: /usr/bin/supermin exited with error status 1	O kernel do host não pode ser lido pelo usuário atual (Ubuntu)	sudo chmod +r /boot/vmlinuz* ou execute a compilação como root.
A soma de verificação difere ou a imagem do fornecedor não existe mais	Os fornecedores movem seus arquivos "latest"	Baixe a imagem você mesmo, verifique-a com o arquivo de soma de verificação do fornecedor e forneça-a com --base.
Rocky: um XFS mais recente não pode ser montado	O kernel do host é muito antigo	Compile em uma máquina com um kernel recente.
--version must be v6 or higher	O nome deve ser vN com N igual a 6 ou mais	Use --version v7.
--panel-url must be a plain https:// URL	O agente é baixado e executado como root, portanto, HTTP simples é recusado	Use uma URL https:// sem espaços, aspas ou string de consulta.
O modelo permanece not ready	O CloudStack ainda não concluiu o download	Aguarde Download Complete, verifique se a VM de armazenamento secundário consegue alcançar a URL.
A linha exibe no-pass	O modelo foi registrado sem passwordenabled=true	Registre-o novamente com essa flag.
O hot-plug de CPU exibe unsupported	O nome não termina em vN (N igual a 6 ou mais)	Renomeie o modelo ou defina vCPU/RAM hot-plug como Yes em Edit se a imagem possuir a regra udev.
"Empty template list" após a primeira conexão	A sincronização não foi executada	Clique em Sync now (requer o worker em execução) ou aguarde o ciclo de 15 minutos.