--- title: CloudStack description: Conecte o Apache CloudStack ao NexCMP: crie um domínio, conta e chave de API dedicados com o cmk e informe-os no assistente ou no console admin. url: https://nexcmp.com/pt/docs/infrastructure/cloudstack/ applies_to: NexCMP 1.6.1 updated: 2026-11-02 --- # CloudStack > **Onde no admin:** Infrastructure › Cloud provider › CloudStack › API connection (`/infra/cloudstack?tab=connect`). A primeira conexão também pode ser feita no [setup wizard](https://nexcmp.com/pt/docs/getting-started/setup-wizard/), etapa 2. ## O que faz {#what-it-does} O NexCMP vende máquinas virtuais executadas na sua nuvem Apache CloudStack. Ele implanta, inicia, para, redimensiona, tira snapshots e exclui VMs por meio da API do CloudStack, distribui endereços IP públicos da zona, lê o uso para faturamento e largura de banda, e exibe a capacidade e o status no console do administrador. O CloudStack continua sendo a fonte da verdade para os hipervisores; o NexCMP é a vitrine, o faturamento e o portal integrados. Use esta página quando o CloudStack for (ou for ser) sua principal fonte de VMs. Para uma segunda fonte ao lado dela, consulte [Proxmox VE](https://nexcmp.com/pt/docs/infrastructure/proxmox/). ## Requisitos {#requirements} | Item | Requisito | |---|---| | Versão do CloudStack | 4.23 é a versão testada. O console da VM precisa da 4.18 ou mais recente, e o escalonamento ao vivo de CPU/RAM de uma VM em execução requer a 4.23 com KVM. | | Tipo de zona | Uma zona com pelo menos uma rede de convidado para as VMs dos clientes e um intervalo de IP público com endereços livres. | | Hipervisor | O KVM é o hipervisor testado. | | Conta | Um **domínio e conta dedicados** criados para o NexCMP. Nunca use a chave de administrador ROOT. | | Acessibilidade da API | O servidor do painel deve alcançar a URL da API do servidor de gerenciamento (`https://cloudstack.example.com/client/api`) via HTTP(S). O console da VM, a largura de banda e os recursos do Kubernetes usam o mesmo endpoint. | | Chave somente leitura opcional | Uma segunda chave somente leitura permite que o console administrativo exiba hosts, armazenamento, VMs de sistema e intervalos de IPs públicos. Não é necessária para vender VMs. | | IP público | Endereços IPv4 públicos gratuitos na zona. O prefixo que o NexCMP pode vender é configurado em Sales IP pools. | | Templates | Pelo menos um template pronto e habilitado para senha e uma oferta de serviço que sua conta possa ver. Consulte [Templates](https://nexcmp.com/pt/docs/infrastructure/templates/). | | Armazenamento | Armazenamento primário para os volumes da conta e, se você vender snapshots ou imagens, armazenamento secundário. | | Depende de | Nenhum. Kubernetes, Private Cloud, Images e Bandwidth dependem desta página. | ::: warning Não use a chave de administrador ROOT Crie um domínio e uma conta dedicados para o NexCMP. Assim, a chave atinge apenas esse domínio, e uma chave vazada não pode afetar o resto da sua nuvem. O assistente de configuração também verifica se a rede escolhida pertence à zona **e** à conta proprietária da chave. ::: ## Preparar a infraestrutura {#prepare-the-infrastructure} Os comandos usam o [CloudMonkey](https://cloudstack.apache.org/) (`cmk`) conectado como administrador do CloudStack. Substitua os nomes de exemplo e os espaços reservados entre colchetes angulares. ### Criar uma conta dedicada e uma chave de API {#create-a-dedicated-account-and-api-key} 1. Crie o domínio que conterá tudo o que pertence ao NexCMP. ```bash cmk create domain name=nexcmp ``` Anote o `id` na saída; ele é usado como `` abaixo. 2. Encontre a função que deseja atribuir à conta. ```bash cmk list roles type=DomainAdmin filter=id,name ``` | Função | Quando escolher | |---|---| | **Domain Admin** (recomendado) | Conjunto completo de recursos: VMs, redes, projetos para Kubernetes, VPC, imagens. O alcance para no domínio `nexcmp`. | | Usuário | Apenas ciclo de vida da VM. Um usuário comum não pode excluir permanentemente (expunge) VMs, a menos que a configuração global `allow.user.expunge.recover.vm` seja true; o NexCMP então para a VM e o CloudStack a expunge após `expunge.delay`. | 3. Crie a conta e seu primeiro usuário. Use uma senha longa e aleatória; ela nunca mais será digitada. ```bash cmk create account name=nexcmp-api username=nexcmp-api \ password='CHANGE-ME-LONG-RANDOM' email=ops@example.com \ firstname=NexCMP lastname=API roleid= domainid= ``` 4. Gere o par de chaves de API para o novo usuário. ```bash cmk list users domainid= username=nexcmp-api filter=id,username cmk generate userkeys id= ``` Copie `apikey` e `secretkey`. Elas são a **API key** e a **Secret key** que você insere no NexCMP. O NexCMP as armazena criptografadas e exibe apenas os últimos quatro caracteres posteriormente. 5. Certifique-se de que o domínio não tenha limites de recursos restritivos (instâncias, volumes, IPs públicos, redes, snapshots, templates, projetos). ```bash cmk list resourcelimits domainid= ``` ### Criar a rede de convidados para VMs de clientes {#create-the-guest-network-for-customer-vms} As VMs de clientes são implantadas em uma rede de convidados que pertence à nova conta. Uma rede isolada com um roteador virtual (VR) e os serviços Static NAT, Firewall e Port Forwarding funciona bem, pois o NexCMP associa um IP público a cada VM com NAT estático. ```bash cmk list networkofferings state=Enabled guestiptype=Isolated filter=id,name cmk create network name=customers displaytext=customers zoneid= \ networkofferingid= account=nexcmp-api domainid= ``` Verifique a política de egress padrão da oferta: se for "deny", as VMs dos clientes não terão acesso de saída até que regras de egress do firewall sejam adicionadas. ### Tornar ofertas e templates visíveis {#make-offerings-and-templates-visible} - **Service offerings** e **network offerings** devem ser públicos ou atribuídos ao domínio `nexcmp`; caso contrário, a conta não poderá listá-los ou usá-los. - Registre ou compartilhe pelo menos um template (consulte [Templates](https://nexcmp.com/pt/docs/infrastructure/templates/)). O NexCMP lista os templates que estão prontos e marcados como em destaque. ### Opcional: chave somente leitura para páginas de infraestrutura {#optional-read-only-key-for-infrastructure-pages} As abas **Capacity**, **Host**, **Storage** e **System VM** e a lista de faixas de IP público usam uma segunda chave que precisa apenas de permissão de leitura para seis comandos. Crie uma função limitada em vez de reutilizar uma chave de administrador completa: ```bash cmk create role name=nexcmp-readonly type=Admin # is the id printed above for api in listHosts listCapacity listSystemVms listVlanIpRanges listClusters listStoragePools; do cmk create rolepermission roleid= rule=$api permission=allow done cmk create rolepermission roleid= rule='*' permission=deny ``` Em seguida, crie uma conta com essa função (no domínio ROOT, pois ela lê dados de toda a zona), gere suas chaves como no passo 4 e insira-as como **RO API key** na seção seguinte. ### Verificar o caminho de rede {#check-the-network-path} A partir do servidor do painel: ```bash curl -fsS -o /dev/null -w '%{http_code}\n' https://cloudstack.example.com/client/api ``` Qualquer resposta HTTP (mesmo 4xx) prova que a porta está acessível. Um tempo limite (timeout) significa um problema de firewall ou de DNS do seu lado. ## Conectar no NexCMP {#connect-in-nexcmp} ### No assistente de configuração {#in-the-setup-wizard} O passo 2 do [setup wizard](https://nexcmp.com/pt/docs/getting-started/setup-wizard/) solicita os mesmos valores. **Test connection** lista as zonas e redes que a chave consegue ver; escolha a zona e a rede de convidados, um nome de exibição para a zona e o país, depois clique em **Save CloudStack**. O assistente rejeita uma rede que não esteja nessa zona ou que não seja visível para a chave. ![Passo 2 do assistente com a URL da API do CloudStack e as chaves preenchidas, e a zona e a rede escolhidas após Test connection](https://nexcmp.com/pt/docs/images/infrastructure/cloudstack-01-wizard-step.webp) ### Mais tarde, no console do administrador {#later-in-the-admin-console} 1. Abra **Infrastructure › Cloud provider › CloudStack** e escolha a aba **API connection**. 2. Preencha o cartão **Connection**: | Campo | Valor de exemplo | |---|---| | Endpoint API | `https://cloudstack.example.com/client/api` | | Chave de API (acesso de escrita) | `XXXX` (deixe em branco para manter a chave salva) | | Chave secreta | `XXXX` | | Chave de API SO / Chave secreta SO | opcional, da conta somente leitura | | ID da zona | o UUID da sua zona | ![A aba de conexão da API com um endpoint de exemplo e chaves mascaradas](https://nexcmp.com/pt/docs/images/infrastructure/cloudstack-02-connect-form.webp) 3. Clique em **Test connection** antes de salvar. Isso testa as chaves que você digitou, sem salvá-las: a chave de gravação com `listZones` e `listCapabilities`, e a chave somente leitura com `listSystemVms`. 4. Clique em **Save connection**. Mantenha **Enable CloudStack connection** ativado; desativá-lo faz o worker parar todos os jobs do CloudStack, sem perder dados. 5. Abra **Services › Virtual Machines › Policy › Provisioning** para definir a rede de convidados padrão, ofertas personalizadas e o par de chaves padrão para novas VMs. ![Política de VM, aba Provisioning, com o ID de rede padrão](https://nexcmp.com/pt/docs/images/infrastructure/cloudstack-04-provisioning.webp) 6. Abra **Infrastructure › Cloud provider › Sales IP pools** e, em **Configure sales ranges**, defina **Sellable IP range prefixes** (por exemplo `203.0.113.`) e **Excluded IP prefixes** se alguns endereços na zona nunca devem ser vendidos. Deixe o prefixo em branco para permitir todos os endereços livres. ![Pools de IP de vendas com o prefixo comercializável 203.0.113. definido](https://nexcmp.com/pt/docs/images/infrastructure/cloudstack-05-sales-ip-pool.webp) ### O que o NexCMP lê e escreve {#what-nexcmp-reads-and-writes} | Área | Leituras | Alterações | |---|---|---| | VMs | lista, estados, histórico de uso, endpoint do console | implantar, iniciar, parar, reiniciar, reinstalar, destruir, redimensionar, redefinir senha e chave SSH | | Discos e snapshots | volumes, snapshots de VM, backups | criar, anexar, desanexar, redimensionar, excluir, fazer snapshot, restaurar | | Rede | redes, roteadores, IPs públicos, firewall, encaminhamento de porta, regras de balanceador de carga | associar e liberar IPs públicos, NAT estático, firewall, encaminhamento de porta, regras de saída, redes e ACLs para Cloud Privado | | Catálogo | ofertas de serviço, disco e rede, templates, ISOs, tipos de SO | registrar e excluir templates e ISOs (Imagens), ofertas de serviço ao criar planos personalizados | | Kubernetes | versões suportadas, clusters, configuração | projetos, limites de recursos, redes, clusters (módulo Kubernetes) | | Chave somente leitura | hosts, clusters, pools de armazenamento, VMs de sistema, capacidade, faixas de IP VLAN | nenhuma | ### CPU e RAM em tempo real e largura de banda {#live-cpu-and-ram-and-bandwidth} - **Hot-plug.** Uma VM em execução pode ser redimensionada sem reinicialização apenas quando o template permitir (escalabilidade dinâmica) e o convidado colocar novos CPUs e RAM online. O NexCMP ativa o Auto Scaling para templates cujo nome termine em `vN` com N igual a 6 ou mais, ou quando você definir manualmente no campo **vCPU/RAM hot-plug** do template. Consulte [Templates](https://nexcmp.com/pt/docs/infrastructure/templates/). - **Origem de largura de banda.** Com as configurações padrão, o NexCMP mede o tráfego a partir das estatísticas de VM do CloudStack (`listVirtualMachinesUsageHistory`, consultadas a cada 5 minutos e somadas por interface de rede da VM). Os números incluem o tráfego entre VMs, portanto podem ser um pouco maiores do que um roteador de borda contabilizaria. Mantenha a coleta de estatísticas de VM do CloudStack ativada; lacunas maiores do que a retenção de estatísticas são ignoradas. Consulte [Bandwidth](https://nexcmp.com/pt/docs/catalog/bandwidth/). ## Verificar {#verify} 1. **Test connection** retorna "Write key: OK" com sua zona e a versão do CloudStack. 2. **Infrastructure › Cloud provider › Providers** mostra o provedor como ativo com um horário de teste recente. O painel de integridade do dashboard não exibe mais "CloudStack: not connected". 3. **Sales IP pools** lista endereços livres (atualiza cerca de uma vez por minuto). 4. Peça uma VM pequena no portal do cliente ou no console administrativo e verifique se ela chega ao estado Running, possui um IP público e se você consegue abrir o console. ## Limites e observações {#limits-and-notes} - Um cluster CloudStack pode ser conectado nesta versão do NexCMP. O diálogo **Add cloud provider** consegue testar as chaves de um segundo cluster, mas não pode salvá-lo. - Uma zona do CloudStack está anexada à zona padrão do NexCMP; um CloudStack com várias zonas tem escopo limitado à zona inserida, portanto VMs, IPs e redes de outras zonas são ignorados. - Excluir a rede de convidados no CloudStack faz com que todo novo provisionamento falhe. O console administrativo exibe um aviso em vermelho quando a rede desaparece. - As credenciais nunca saem do servidor. A API retorna apenas os últimos quatro caracteres. ## Resolução de problemas {#troubleshooting} | Sintoma | Causa | Correção | |---|---|---| | `listCapabilities: cloudstack 401: unable to verify user credentials and/or request signature` | Chave ou segredo de API incorretos, chave de outro usuário ou problema de relógio no servidor do painel | Gere as chaves novamente com `cmk generate userkeys` e cole ambas. Verifique a hora do servidor do painel. | | Teste: `listZones: …` ou timeout | O servidor do painel não consegue alcançar a URL da API | Verifique o DNS, o firewall e o caminho exato `/client/api`. | | Assistente: "network not found in that zone for this API key" | A rede escolhida pertence a outra conta ou zona | Crie a rede na conta dedicada (consulte acima) e execute **Test connection** novamente. | | Assistente: "pick a zone and a network" | Teste não executado, ou nenhuma zona ou rede selecionada | Clique em **Test connection** e escolha ambas as listas. | | Banner "chave do CloudStack não configurada" | Nenhuma chave salva ainda ("Connect later") | Preencha o cartão Connection, **Save connection** e, em seguida, **Test connection**. | | Banner "CloudStack connection is OFF" | O botão **Enable CloudStack connection** está desativado | Ative-o e salve. | | Chave somente leitura: "unusable …" no teste | Permissão de função ausente ou conta incorreta | Verifique os seis comandos permitidos e se a conta está no domínio ROOT. | | "Zone public IP ranges not measured yet" ou "no public IP ranges declared" | Nenhuma chave somente leitura, ou a zona realmente não possui faixa pública | Adicione a chave somente leitura ou adicione um intervalo de IP público no CloudStack. | | "Pool vazio — aguarde 60 s para a sincronização do vmd" | A lista de IPs é atualizada pelo worker uma vez por minuto | Aguarde um minuto e recarregue. | | "sem IPs livres no intervalo 203.0.113." | Todos os endereços no prefixo comercializável estão em uso | Adicione endereços à zona, amplie o prefixo ou libere IPs não utilizados. | | "Falha ao buscar dados de rede (CloudStack não está respondendo ou chave sem permissões)" | A chave perdeu o acesso ou o CloudStack está fora do ar | Execute **Test connection**; verifique se a conta está ativada. | | "Rede de convidados NÃO existe" | A rede foi excluída no CloudStack | Crie a rede novamente e defina-a como padrão em Provisioning. |