Nutanix Enterprise AI no NKPParte 3: do catálogo ao primeiro token

Resumo: nesta parte o Nutanix Enterprise AI (NAI) sai do papel. Crio um cluster NKP dedicado, habilito as sete dependências do catálogo, instalo o NAI 2.8.1 com certificado da CA interna e aplico a licença no mesmo dia, porque o trial dura só 2 dias. Depois importo dois modelos do Hugging Face, um validado pela Nutanix e um custom, e coloco o primeiro endpoint para responder em CPU, com API key e API compatível com a OpenAI. Reuni aqui os quatro pré-requisitos e detalhes de configuração que fazem a instalação sair limpa, com a causa e o ajuste de cada um. No fim: 0,5 s até o primeiro token e 4,5 tokens/s num Xeon de 2019, e o que explica esse número no hardware do lab. Esta é a parte 3 de 4.

Onde estamos

A série acompanha a habilitação do Nutanix Enterprise AI num lab com NKP 2.19 e um cluster HCI Nutanix sem GPU.

Na Parte 1 ficou decidido o desenho (cluster dedicado, como nos Nutanix Validated Designs) e na Parte 2 ficou pronta a storage class RWX nai-nfs. Agora é a instalação de verdade, numa sessão só, de ponta a ponta.

O roteiro em uma tabela

1. Um cluster só para o NAI

Os dois NVDs da Nutanix para o NAI colocam a plataforma num cluster dedicado, com workspace próprio. Segui o mesmo caminho: workspace ws-nai e um cluster com 1 control plane de 4 vCPU / 16 GiB e 3 workers de 12 vCPU / 40 GiB, todos com a imagem Ubuntu 24.04 do NKP 2.19, que é a do guia.

Do Create aos nós Ready foram 3 min 33 s. O cluster subiu com Kubernetes 1.36.2.

Dois ajustes que todo cluster novo precisou

Os dois já tinham aparecido no primeiro cluster de workload do lab, e voltaram aqui:

2. As sete dependências

O app do NAI no catálogo traz a lista de dependências na anotação required-dependencies, e a tela de Enable também mostra. Na NKP 2.19, ficaram assim:

As sete ficaram prontas em cerca de 7 minutos. A compatibilidade com a NKP 2.19 está na própria anotação do app: nkp-version-support: >=2.18 <2.20.

3. Antes do Enable: o que eu li no chart (e o que deixei passar)

Antes de clicar em Enable, baixei o artefato do catálogo (nutanix-ai:2.8.1) e o chart nai-core para ver o que o app faz. Valeu a pena:

Certificado da CA interna

Para o navegador confiar no NAI sem aviso, emiti o certificado pela CA interna do lab. O chart aceita um ClusterIssuer do cert-manager. Criei o secret com o certificado e a chave da CA e o issuer:

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: lab-ca
spec:
  ca:
    secretName: lab-ca   # secret tls no namespace cert-manager

Um certificado de teste para nai.lab.exemplo.local saiu assinado pela CA e passou no openssl verify.

4. O Enable

No workspace, Applications → Nutanix Enterprise AI → Enable. O formulário tem dois campos de configuração: um para o workspace inteiro e um por cluster.

Usei só o campo do cluster. Hostname e certificado são deste cluster; se ficassem no campo do workspace, valeriam para qualquer cluster novo do workspace, e o NKP habilita o app sozinho nos clusters que entram depois.

O override final (com o imagePullSecrets do pré-requisito abaixo):

global:
  storage:
    storageClassName: nutanix-volume      # RWO
    storageClassNameRWX: nai-nfs          # o padrão é nai-nfs-storage
  imagePullSecrets:
    - name: nai-dockerhub                 # repositórios privados nutanix/nai-*
gateway:
  tlsSecretName: ingress-certificate
  certManager:
    selfSigned: false
    issuerRef:
      name: lab-ca
      kind: ClusterIssuer
      group: cert-manager.io
    dnsNames:
      - nai.lab.exemplo.local

Pré-requisito: o token do Docker Hub do NAI

Na minha primeira tentativa eu não tinha criado essa credencial, e um minuto depois do Enable os pods do nai-system estavam em ImagePullBackOff: pull access denied … insufficient_scope. Se você vir essa mensagem, há dois pontos a conferir:

1. A ordem da injeção da credencial do NKP. O NKP injeta a credencial do registry com uma mutação do Gatekeeper, que só age quando o pod é criado num namespace com o label inject-registry-creds. O namespace nai-system nasceu às 21:51:22, os pods às 21:51:25, e o label e o secret só chegaram às 21:52:21. Os primeiros pods foram criados antes da credencial.
2. O NAI tem credencial própria. Mesmo recriando os pods, o pull continuou negado: o usuário de registry do NKP baixa as imagens do NKP, e os repositórios nutanix/nai-* são privados do NAI. O NAI usa o access token do Docker Hub do NAI, gerado no portal em Downloads → Nutanix Enterprise AI → Generate Access Token (usuário de registry próprio do NAI).

O ajuste: criar um secret docker-registry com o token do NAI em dois namespaces, nai-system e envoy-gateway-system (o Envoy do NAI usa uma imagem privada), e apontar o global.imagePullSecrets no override.

Quando o primeiro Enable não conclui: Disable + Enable

Com a configuração ajustada, o NAI não reinstalou sozinho. Como a primeira instalação dos operadores não tinha concluído (por causa do ImagePull), o Flux entrou em desinstalação para tentar de novo. O chart tem um hook de pré-desinstalação que espera o HelmRelease nutanix-ai sair, e esse depende dos operadores. O hook espera até 30 minutos; o uninstall expira em 15.

O caminho mais rápido foi Disable → limpeza → Enable. Depois do Disable, sobraram um PVC do Valkey, um ConfigMap criado fora do Helm e um secret de webhook, todos sem dados. Apaguei os três e mantive o namespace, os secrets do registry e o issuer.

O segundo Enable: 8 minutos

O Envoy do NAI pegou o próximo IP livre do pool do MetalLB (198.51.100.131) e o certificado ficou pronto, emitido pela CA do lab. Pela bastion, um curl --resolve com a CA do lab validou a cadeia e recebeu o redirecionamento para o login.

5. Primeiro login: EULA, Pulse e senha

Com o nome no DNS (no lab, por enquanto, no /etc/hosts), a tela de login abre em https://nai.lab.exemplo.local com o certificado válido.

Usuário admin com a senha padrão do guia. No 2.8.1, a ordem das telas é: EULA (nome e empresa), depois Pulse, depois a troca de senha (o guia mostra outra ordem).

Depois do Pulse: entre de novo

Depois de Save and Proceed no Pulse, a minha sessão mostrou 403 Access Denied. Nos logs, as gravações de EULA e Pulse voltaram 200 e o Envoy não registrou nenhum 403: a sessão aberta antes da EULA só não tinha os atributos de autorização atualizados.

O que fazer: Back to login e entrar de novo. Aí veio a troca de senha e o dashboard.

6. A licença: no mesmo dia

O NAI tem trial de só 2 dias depois da instalação, e a licença de CPU ou GPU só pode ser adicionada na primeira instalação. Então ela vem logo depois do primeiro login.

O caminho:

1. No NAI, Settings → Licensing → Add License mostra o Kubernetes Cluster ID. É o UID do namespace kube-system do cluster (conferi pela bastion).
2. No portal da Nutanix, Licenses → Manage Licenses → Manage NAI/NKP License → NAI: informar o nome e o UUID do cluster, escolher NAI Pro (VCPU) e a quantidade.
3. Gerar a chave e voltar ao NAI.

Escolhi 36 vCPU, os 3 workers × 12, o teto que um endpoint consegue usar nesse cluster.

E o Agent Gateway?

A tela de licença tem um terceiro tipo, Agentic Gateway License: “Required for accessing Unified Endpoints and MCP Connectors”. É um direito separado, medido em access keys. Uma chave de vCPU colada nesse campo dá “Meter type mismatch”.

O lab ainda não tem o direito de Agent Gateway. Ele fica para a Parte 4.

7. Um node pool só para inferência

Depois do Enable, os requests de CPU dos três workers ficaram em 77%, 96% e 83%, com uso real de ~5%. Sobravam ~2,7 vCPU agendáveis no melhor nó. O guia confirma o motivo: os 3 workers de 10 vCPU da tabela de requisitos são só para o plano de controle do NAI, e os recursos de inferência são à parte.

A solução foi um node pool nai-cpu: 1 worker de 12 vCPU / 48 GiB, sem taint (no NAI 2.8.1, os endpoints em CPU usam o agendamento padrão, sem toleration nem nodeSelector).

Do Add ao nó Ready: 1 min 40 s, com ~11,6 vCPU livres.

8. Modelos: Hugging Face, validado e custom

Uma conta de serviço no Hugging Face

Criei uma conta do lab no Hugging Face, em vez de usar a pessoal: o token não depende de uma pessoa e a separação fica limpa. Dois modelos para comparar:

O token é do tipo Read. Em cliente, prefira um token fine-grained com leitura só dos repositórios usados.

No NAI, Settings → Third Party Credentials → Add Credential, plataforma Hugging Face. A tela avisa que só cabe um token do Hugging Face por NAI.

O modelo validado

Models → Import Models → From Hugging Face Model Hub lista 52 modelos validados.

O status passa por Pending → Waiting for storage. Por trás, o NAI cria um objeto Model e um PVC RWX na nai-nfs, o Files cria o share e um job baixa o modelo. Tempo total: ~1,5 min.

Governança: o NAI começa fechado (deny by default)

Com o Gemma pronto, o NAI mostrou o aviso “The usage of this model has been restricted by the administrator”. É a governança funcionando: numa instalação nova, o Model Access Control começa sem modelos liberados (0 de 52 do Hugging Face e 0 de 32 do NGC), com import por URL e upload manual desligados, e o administrador libera o que for usar.

No lab, liberei os catálogos e os dois toggles. Um detalhe: no NGC, Allow all validated libera 27 de 32. Os outros 5 estão no catálogo sem o selo de validado, e só entram com Allow specific models.

O custom model, pela URL

Na mesma tela do Hub, o link Import using Model URL aceita qualquer repositório do Hugging Face. O NAI pede uma confirmação explícita:

Import em 59 s (o share ficou pronto em 3 s e a imagem do processador já estava em cache).

No objeto Model, apareceu uma diferença que vale conhecer:

9. O primeiro endpoint

Escolha um modelo com perfil de CPU

Local Endpoints → Create Endpoint com o Gemma, e a tela mostrou: “No supported accelerator types available”.

O cluster estava pronto: o NFD detectou AVX-512 em todos os nós e o inventário do NAI via 11,6 vCPU livres no nai-cpu. O que define a opção é o perfil do modelo: no catálogo 2.8.1, o Gemma 3 270M é validado para GPU. Com o Qwen3 custom, a opção CPU aparece (e a de Intel AMX fica cinza, porque o Xeon do lab é de 2ª geração).

A configuração

Motor vLLM, imagem da Nutanix v0.26.0. A tela avisa que o vLLM é community-supported e mostra outras origens de imagem.

Para custom model, você define o tamanho. Usei:

De Pending a Active: 8,5 minutos

Por trás, o NAI cria um InferenceService do KServe com o pod do vLLM no nó nai-cpu, com requests iguais aos limits (8 CPU / 16 GiB).

A página do endpoint mostra a URL compatível com a OpenAI. No campo model, vai o nome do endpoint.

10. O primeiro token

Pela interface

O botão Test responde com o modo de raciocínio do Qwen3 ligado (o padrão do modelo): a resposta começa com o raciocínio em inglês e depois vem em português. Pela API, dá para desligar com enable_thinking: false.

Pela API

Pela bastion, com a API key num prompt sem eco:

curl https://nai.lab.exemplo.local/enterpriseai/v1/chat/completions \
  -H "Authorization: Bearer $NAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-06b-cpu",
    "messages": [
      {"role": "system", "content": "Responda sempre em português do Brasil."},
      {"role": "user", "content": "Explique em 3 frases o que é o Nutanix Enterprise AI."}
    ],
    "max_tokens": 200,
    "chat_template_kwargs": {"enable_thinking": false}
  }'

A resposta veio no formato pedido e genérica no conteúdo, como se espera de um modelo de 0,6B.

Por que 4,5 tokens/s

Medi em vez de supor:

Dá para melhorar o primeiro com VLLM_CPU_OMP_THREADS_BIND igual aos núcleos do pod. No NAI 2.8.1, a configuração avançada do endpoint oferece Engine Arguments e KV Cache Aware Routing; uma variável de ambiente como essa vai no InferenceService do KServe. A Parte 4 mostra o passo a passo e o ganho: +40% de tokens/s. O segundo é do hardware do lab. Para comparação, o appliance com GPU do lab serve um modelo de 30B com NIM a ~66 tokens/s.

Os números

O que aprendi

1. Leia o chart antes do Enable. O padrão vem com certificado autoassinado e com storage class e hostname genéricos: ajuste para o seu ambiente.
2. O NAI tem credencial própria de registry. Crie o namespace nai-system e o secret com o token do Docker Hub do NAI antes do Enable, inclusive em envoy-gateway-system.
3. Se o primeiro Enable não concluir, Disable + limpeza + Enable. É o caminho mais rápido, sem esperar o Flux.
4. Licença no mesmo dia, tipo CPU. O trial é de 2 dias, e a janela abre em GPU.
5. Dimensione os workers para o plano de controle do NAI. Os requests padrão pedem ~21 vCPU; reserve um node pool para inferência.
6. Governança desde o primeiro dia. O Model Access Control vem em deny by default; libere por lista.
7. Confira o tipo de acelerador do modelo antes de escolher o modelo da demo: validado para GPU não implica perfil de CPU.
8. No meu lab, CPU sem BF16/AMX serve para demonstração; para desempenho, GPU ou CPU com AMX. E ajuste as threads do vLLM ao limite do pod.

Checklist: NAI 2.8.1 no NKP

• Cluster dedicado com imagem Ubuntu; CoreDNS e cluster-info-configmap ajustados
• Storage class RWX pronta (Immediate)
• As 7 dependências do catálogo habilitadas
• ClusterIssuer da CA interna (ou aceitar o autoassinado)
• Token do Docker Hub do NAI e secret em nai-system e envoy-gateway-system
• Override no campo do cluster: storage classes, imagePullSecrets, issuer e dnsNames
• DNS do nome do NAI apontando para o IP do Envoy
• Primeiro login (EULA → Pulse → senha); se aparecer 403 depois do Pulse, entrar de novo
• Licença CPU aplicada no mesmo dia
• Node pool para inferência
• Token do Hugging Face (Read ou fine-grained) e licenças gated aceitas
• Model Access Control liberado por lista
• Endpoint com API key; teste sem chave (401) e com chave (200)

O que ainda não testei

• Endpoints em GPU no NAI. O cluster do lab não tem GPU, e a licença aplicada foi a de CPU. A GPU dentro do próprio NKP é o próximo passo do lab.
• Inferência em CPU com BF16 ou AMX. Os hosts do lab são Cascade Lake, sem AVX512_BF16 nem AMX, e o vLLM roda em FP32.
• O ajuste de threads do vLLM (VLLM_CPU_OMP_THREADS_BIND): ficou para a Parte 4, que mostra o passo a passo e o ganho de +40%.
• O Agent Gateway (unified endpoints e MCP): o lab ainda não tinha esse direito nesta etapa, e ele ficou para a Parte 4.

Referências

Nutanix

• Nutanix Enterprise AI Guide 2.8.1 (portal Nutanix): requisitos (p. 13–17), deploy no NKP, Docker Hub access token (p. 28), login (p. 132), licenciamento (p. 173–178), Model Access Control (p. 194), import de modelos (p. 197–202), endpoints (p. 225–246)
• Nutanix Validated Design: Nutanix Enterprise AI (NVD-2057)

Projetos e comunidade

• Cluster API: label sync entre Machine e Node
• vLLM: instalação e variáveis para CPU
• Hugging Face: User access tokens
• cert-manager: CA Issuer