Iniciar sessãoAgendar apresentação

Capítulo 2.5

Verificação prévia com o nexusctl

Cada verificação que o `nexusctl preflight` efetua, o que cada uma lê e como falha, o relatório que apresenta e guarda, como esse relatório chega à página de verificação prévia da consola e todas as opções (flags).

Esta página foi traduzida por IA a partir do original em inglês. Em caso de dúvida, a página em inglês serve de referência. Ler esta página em inglês

16 minutos de leitura

A nossa primeira verificação prévia na Harrow Port Authority falhou em quatro verificações, e duas delas ter-nos-iam custado muito mais do que uma tarde. Tínhamos começado o ficheiro de valores copiando o exemplo do chart, e a verificação prévia recusou tanto o nome de instalação de exemplo como o custódio de exemplo. Ninguém detém a chave privada desse custódio. Uma instalação selada para ele nunca poderá ser desselada após o reinício de um nó. A verificação prévia detetou isso em poucos segundos, antes que existisse algo a perder.

nexusctl preflight lê o seu cluster e o seu ficheiro de valores, imprime o que encontrou, guarda um relatório e não altera nada no cluster. Execute-o antes de cada instalação e de cada atualização. Este capítulo aborda todas as verificações que efetua, o formato do relatório, para onde vai o relatório e as flags.

Operação

A verificação prévia precisa de duas coisas: o contexto kube do cluster onde vai instalar e o ficheiro de valores que a instalação irá utilizar. Escreva primeiro o ficheiro de valores; o capítulo 2.6, Instalar o Community no Kubernetes, percorre cada chave. Em seguida:

nexusctl preflight --context harrow-prod --values harrow-values.yaml

Lê o cluster através do client-go apenas com chamadas get e list. Se o seu tls.mode for existing, crie o namespace nexus e o Secret de Transport Layer Security (TLS) antes de o executar (capítulo 2.6, Instalar o Community no Kubernetes, passo 3), caso contrário, a verificação do certificado indicará que o Secret está em falta.

Indicador O que faz Predefinição
--context <name> O contexto kube a verificar. Obrigatório nenhum
--values <file> O ficheiro de valores que a instalação irá utilizar. Obrigatório nenhum
--namespace <name> Onde o Nexus é instalado nexus
--release <version> A versão a ser verificada a própria versão do chart incluído
--report-dir <dir> Onde são guardados os dois ficheiros de relatório a pasta atual
--record <mode> auto, always ou never: se deve entregar o relatório ao serviço de chaves desta instalação, para que a página do instalador o apresente auto
--kubeconfig <file> O kubeconfig a ler KUBECONFIG, depois ~/.kube/config
--ca-bundle <file> Os seus próprios certificados de autoridade de certificação (CA), para uma cadeia na qual as verificações devam confiar nenhum
--single-node Verificar uma máquina para uma instalação numa única máquina (capítulo 2.8, Instalações numa única máquina) desativado

O requisito mínimo desta versão para o Kubernetes não está fixado em nexusctl. Lê o limite inferior do próprio kubeVersion do chart a partir do chart que transporta, para que a verificação e o helm install nunca possam discordar.

O que uma execução apresenta

Eis a primeira execução na Harrow, tal como foi impressa:

Adverant Nexus 1.0.0-alpha.1 · preflight · Tue 10 Nov 2026 08:40 · read-only

Failed first
  FAIL  Address (api)             api.harrow.example → no record    people reach Nexus by this name
        fix  add a DNS record for api.harrow.example that points at the ingress, then run preflight again
  FAIL  Address (auth)            auth.harrow.example → no record   people reach Nexus by this name
        fix  add a DNS record for auth.harrow.example that points at the ingress, then run preflight again
  FAIL  Key custodians            the example custodian of the chart's values-community.yaml and values-enterprise.yaml (age1u63etg5v…)   the key store seals its recovery keys to them; no one holds the example custodian's key
        fix  replace it in keys.custody.recipients in harrow-values.yaml with your custodians' own recipients: each custodian makes a key on their own machine with `age-keygen -o custodian.key` (the `# public key: age1...` line is the recipient), or `age-plugin-se keygen --access-control=any-biometry -o custodian.key` for a Secure Enclave key, keeps the identity file offline, and gives you only the recipient
  FAIL  Installation name         nexus-example, the example name of the chart's values-community.yaml and values-enterprise.yaml   the first key-store bootstrap mints the installation identity under it, permanently
        fix  set keys.installationName in harrow-values.yaml to this installation's own name

Warnings
  warn  Graphics nodes            none                   the assistant will need a hosted model
        fix  add a node with a graphics card and its device plugin, or have the assistant use a hosted model
  warn  Certificate               secret harrow-public-tls not found in nexus   the public address needs it before people sign in
        fix  create the TLS secret harrow-public-tls in nexus before installing, or change tls.existingSecret in harrow-values.yaml

Passed
  pass  Kubernetes version        1.33.6+k3s1            needs 1.33 or later
  pass  Nodes ready               3 of 3
  pass  Storage class             local-path (default)
  pass  Resources                 24 cores, 93.9 GiB     needs 2.1 cores, 6.7 GiB
  pass  Ingress class             traefik (default)
  pass  Ingress ports             traefik (LoadBalancer) on 80 and 443
  pass  Address (console)         console.harrow.example → 10.20.4.10
────────────────────────────────────────────────────────────────────────────
7 passed · 2 warnings · 4 failed   Install cannot continue until the failures pass.
Nothing was changed. Report saved to preflight-2026-11-10-0840.txt

Quando algo falha, as falhas aparecem primeiro, seguidas dos avisos e, por fim, das aprovações. Cada linha mostra o resultado, o nome da verificação, o que foi encontrado e o que é necessário; cada linha que não passou tem uma linha fix por baixo. As duas últimas linhas são o resumo e o ficheiro de relatório.

Corrigimos os valores, adicionámos os dois registos de Domain Name System (DNS), criámos o Secret e executámo-lo novamente:

Adverant Nexus 1.0.0-alpha.1 · preflight · Thu 12 Nov 2026 09:02 · read-only

Cluster
  pass  Kubernetes version        1.33.6+k3s1            needs 1.33 or later
  pass  Nodes ready               3 of 3
  pass  Storage class             local-path (default)
  pass  Resources                 24 cores, 93.9 GiB     needs 2.1 cores, 6.7 GiB
  warn  Graphics nodes            none                   the assistant will need a hosted model
        fix  add a node with a graphics card and its device plugin, or have the assistant use a hosted model

Network
  pass  Ingress class             traefik (default)
  pass  Ingress ports             traefik (LoadBalancer) on 80 and 443
  pass  Address (console)         console.harrow.example → 10.20.4.10
  pass  Address (api)             api.harrow.example → 10.20.4.10
  pass  Address (auth)            auth.harrow.example → 10.20.4.10
  pass  Certificate               ends 3 Nov 2027

Time and keys
  pass  Key custodians            3 custodians
  pass  Installation name         harrow-port-authority
────────────────────────────────────────────────────────────────────────────
12 passed · 1 warning · 0 failed   You can install. Warnings do not block; fix them when you can.
Report saved to preflight-2026-11-12-0902.txt · nothing was changed on the cluster

Uma execução sem falhas lista as verificações sob os seus três títulos: Cluster, Rede, e Tempo e chaves. Os avisos nunca bloqueiam. Mantivemos o aviso sobre os nós gráficos de propósito: neste cluster piloto ligado, o assistente da Harrow utilizou um modelo alojado com a própria chave do porto.

Antes de instalar
Antes de instalar
A verificação prévia no terminal do operador, com as contagens ao lado. Note que cada aviso tem a respetiva correção impressa por baixo e que a execução indica claramente que nada foi alterado no cluster.

Códigos de saída

Código Significado
0 A instalação pode avançar. Os avisos não bloqueiam
1 A instalação está bloqueada: pelo menos uma verificação falhou
2 Não foi possível executar a verificação prévia: não foi possível ler o kubeconfig, o contexto, o ficheiro de valores ou a interface de programação de aplicações (API) do cluster, ou uma flag estava incorreta

Os scripts devem ler o código de saída, não as palavras. O nosso executa a verificação prévia como o primeiro passo de cada atualização e para em qualquer valor diferente de 0.

Execute o nexusctl da versão para a qual está a mudar, não daquela com que instalou. Os requisitos vêm do chart que transporta, pelo que uma versão mais recente pode elevar o requisito mínimo do Kubernetes ou pedir mais memória, e apenas o seu próprio nexusctl o sabe. --release altera a versão que o relatório indica; não altera as regras do chart que são aplicadas. Na Harrow, mantemos o nexusctl de cada versão ao lado do respetivo chart no registo de alterações, para que uma reversão seja verificada pela ferramenta que lhe corresponde.

Cada verificação

Existem onze verificações. Dez delas produzem uma linha cada; a verificação de endereço produz uma linha por anfitrião, pelo que uma execução completa tem treze linhas. Nove verificações têm de passar, e uma falha é um erro. Duas, os nós gráficos e o certificado, devem passar, e uma falha é um aviso. A última coluna é o texto do requisito que cada linha leva para o relatório; nela, CPU significa unidade central de processamento.

ID da verificação Secção Tem de passar Requisito que imprime
kubernetes-version cluster sim Kubernetes 1.33 ou posterior
nodes-ready cluster sim Todos os nós prontos
storage-class cluster sim Uma classe de armazenamento para os dados
resources cluster sim CPU e memória suficientes para a versão
graphics-nodes cluster não Nós gráficos
ingress-class network sim Uma classe de ingress para os três endereços
ingress-ports network sim O controlador de ingress aberto nas portas 80 e 443
address-console, address-api, address-auth network sim O endereço console, api ou auth resolve no DNS
certificate network não Certificado válido por mais 30 dias
custodians time-and-keys sim As pessoas que detêm as chaves de recuperação desta instalação
installation-name time-and-keys sim O nome permanente próprio desta instalação

kubernetes-version

Lê a versão do servidor da API e compara-a com o requisito mínimo do chart. Encontra, por exemplo, 1.33.6+k3s1. Abaixo da 1.33, falha com a correção upgrade the cluster to 1.33 or later. Se a string da versão não for uma que o nexusctl consiga ler, falha em vez de adivinhar.

nodes-ready

Lista os nós e conta aqueles cuja condição Ready é verdadeira, como 3 of 3. Qualquer nó que não esteja pronto é nomeado, e a correção indica-lhe que o coloque novamente no estado Ready e leia as suas condições. Um cluster sem quaisquer nós falha com uma indicação de que o contexto pode estar a apontar para o cluster errado.

storage-class

Se os seus valores definirem storage.className, a verificação procura essa classe e falha com <name> does not exist quando está em falta. Se não o fizerem, procura uma classe marcada como predefinida e reporta-a como local-path (default). Sem predefinição, falha com none marked default, e a coluna de necessidades explica por que razão isso importa: the database cannot claim a disk. Se duas classes estiverem marcadas como predefinidas, o cluster atribui a mais recente a uma nova solicitação, pelo que é essa a reportada.

resources

Calcula o que a versão pede a partir do chart e dos seus valores e, em seguida, soma os núcleos de unidade central de processamento (CPU) e a memória alocáveis de cada nó que esteja Ready, não isolado (cordoned) e não tenha taints NoSchedule ou NoExecute. Os pods do chart não têm tolerâncias, pelo que um nó com taint não os pode executar e não conta. Um cluster insuficiente falha indicando o défice exato, tal como add nodes with 1 more core and 2.5 GiB more memory, or lower the sizes under components and dataTier in harrow-values.yaml. As necessidades são arredondadas por excesso e a oferta por defeito, pelo que a verificação nunca é demasiado otimista.

graphics-nodes

Procura um nó Ready com uma unidade de processamento gráfico (GPU) que possa alocar, nvidia.com/gpu. Se não existir nenhum, avisa: the assistant will need a hosted model. A verificação prévia trata isto como uma recomendação e nunca bloqueia por esse motivo, porque o assistente pode responder através de um modelo alojado de inteligência artificial (IA) em alternativa. O Capítulo 2.14, Fornecedores e modelos de IA, aborda ambas as vias.

ingress-class

Se ingress.className estiver definido, a verificação procura essa classe. Caso contrário, procura exatamente uma classe marcada como predefinida. Duas classes marcadas como predefinidas também falham, porque o servidor da API recusa então um Ingress sem classe. A verificação é ignorada, e a respetiva linha omitida, quando ingress.enabled é false.

ingress-ports

Procura no namespace indicado por networkPolicy.ingressNamespace (por predefinição kube-system, onde o k3s executa o Traefik) um Service LoadBalancer ou NodePort que exponha tanto a porta 80 como a 443. A política de rede do chart permite que apenas esse namespace alcance os três Services públicos, pelo que um controlador de ingress noutro local não poderia servir o Nexus mesmo que estivesse à escuta. A correção indica ambas as soluções: expor o controlador aí ou definir networkPolicy.ingressNamespace para o local onde é executado. Ignorada quando ingress.enabled é false.

address

Procura hosts.console, hosts.api e hosts.auth a partir da sua estação de trabalho, cinco segundos cada, e imprime uma linha por anfitrião. Um anfitrião sem registo falha com <host> → no record. Um anfitrião não definido falha com hosts.<key> is not set. Quando um nome tem vários endereços, a linha mostra o primeiro, IPv4 antes de IPv6, e quantos mais existem.

certificate

É executada apenas quando tls.mode é existing e tls.existingSecret indica o nome de um Secret; com cert-manager ou none não há nenhum certificado seu para ler, e a linha é omitida. Lê tls.crt a partir do Secret no namespace de instalação e nada mais. Um certificado válido por 30 dias ou mais passa como ends 3 Nov 2027. Um que termine mais cedo avisa ends in 9 days; um já expirado avisa ended 4 days ago. Um Secret em falta, ou um sem certificado, emite um aviso com a respetiva correção.

custodians

Lê keys.custody.recipients. Se não existir nenhum, falha com o código KEYS_CUSTODIAN_MISSING. Se algum destinatário for o custódio de exemplo dos próprios ficheiros de valores do chart, falha com KEYS_CUSTODIAN_EXAMPLE, porque ninguém detém essa chave e as chaves de recuperação da instalação ficariam seladas para ninguém. Se passar, imprime a contagem, como 3 custodians.

installation-name

Lê keys.installationName. Se não estiver definido, falha com INSTALLATION_NAME_MISSING. Se estiver definido com o nome de exemplo dos ficheiros de valores do chart, falha com INSTALLATION_NAME_EXAMPLE. Se passar, imprime o nome. A coluna de necessidades indica por que razão este é mais importante do que a maioria: the first key-store bootstrap mints the installation identity under it, permanently.

As duas últimas verificações reportam exatamente os códigos com os quais o próprio chart recusa uma instalação. A verificação prévia apenas lho diz primeiro, antes de o Helm ter criado seja o que for.

Os ficheiros de relatório

Cada execução guarda dois ficheiros em --report-dir, com o nome da hora a que foi executada: preflight-2026-11-12-0902.txt, as linhas tal como foram impressas sem códigos de cor, e preflight-2026-11-12-0902.json, a mesma execução num formato fixo que um programa consegue ler. A saída do terminal e as linhas guardadas provêm da mesma lista, pelo que nunca diferem.

O relatório JSON segue o esquema nexus.preflight/v1:

Campo O que contém
schema Exatamente nexus.preflight/v1
tool Um objeto: name (nexusctl) e version
release A versão verificada
ran_at Quando foi executado, em Tempo Universal Coordenado (UTC)
context O nome do contexto kube
values Apenas o nome base do ficheiro de valores
read_only Sempre true
checks Uma entrada por linha: id, section, name, requirement, must_pass, outcome (pass, warn ou fail), found, needs, fix e, em caso de falha com causa de máquina, code
counts passed, warnings e failed
can_install true quando nada falhou
report_file O nome do ficheiro .txt
transcript Um objeto: title (nexusctl preflight) e lines, cada linha com o seu kind (prompt, ok, warn, bad, note, out ou blank), o seu text e at, e por vezes marks

O relatório é construído para ser apresentado antes de alguém iniciar sessão, pelo que não contém nenhum nome de utilizador, nome de anfitrião da estação de trabalho, caminho de ficheiro, token nem nada do seu kubeconfig. values é um nome base e context é o nome do contexto. Se o relatório de uma execução violasse qualquer uma dessas regras, o nexusctl recusar-se-ia a imprimi-lo, guardá-lo ou entregá-lo, indicando esse facto. Um relatório tem no máximo 256 KiB, com no máximo 64 verificações e 512 caracteres em qualquer campo de texto.

Como o relatório chega à consola

A única escrita da verificação prévia é o relatório concluído, entregue ao serviço de chaves da instalação, nexus-keys, para que o instalador da consola o possa mostrar na sua página de verificação prévia antes de alguém ter reivindicado a instalação. --record decide se deve tentar:

--record O que acontece
auto Entrega o relatório apenas quando o namespace tem um Deployment nexus-keys
always Insiste; a verificação prévia termina com 2 se não houver nada a que o entregar
never Não o entrega

Assim, uma execução antes da primeira instalação não tem a quem entregar e mantém o relatório na sua estação de trabalho. Uma execução após a instalação e antes da reivindicação regista-o.

A entrega utiliza o seu próprio acesso ao cluster. nexusctl executa /app/nexus-keys preflight-record no contentor keys de um pod nexus-keys pronto e passa o relatório na entrada padrão. É o mesmo que:

kubectl exec -i -n nexus -c keys deploy/nexus-keys -- /app/nexus-keys preflight-record < preflight-2026-11-12-0902.json

O serviço de chaves verifica o relatório face às mesmas regras que o nexusctl aplica e mantém apenas o mais recente. Quando é entregue, o nexusctl imprime mais uma linha a indicá-lo, e o JSON guardado ganha um note que regista a entrega.

O instalador da consola lê-o a partir da rota pública GET /v1/installation/preflight do serviço de chaves. Essa rota responde apenas enquanto a instalação não for reivindicada: antes de qualquer relatório ser registado, responde 404 RECORD_NOT_FOUND e, assim que alguém reivindica a instalação, responde ROUTE_NOT_FOUND em definitivo, exatamente como faz a rota de reivindicação. Um relatório entregue após a reivindicação é recusado com INSTALLATION_CLAIMED.

Na consola, uma execução com falhas aparece como "A verificação prévia não pode continuar": as contagens de falhas, avisos e aprovações, seguidas de cada verificação agrupada sob "Tem de passar" e "Deve passar", com as que não passaram primeiro e as palavras encontradas ao lado de cada uma. Uma execução sem falhas não apresenta essa página; a consola avança diretamente para a reivindicação (capítulo 2.12, A primeira execução).

A verificação prévia não pode continuar
A verificação prévia não pode continuar
A página da consola para uma execução de verificação prévia que não pode continuar. As verificações que falharam aparecem primeiro, cada uma descrita por palavras com o que foi encontrado, e a instalação permanece bloqueada até que passem.
Três colunas. À esquerda, "Estação de trabalho do operador": uma caixa "nexusctl preflight --context --values" com duas saídas por baixo, "preflight-<time>.txt" e "preflight-<time>.json". Ao centro, "A instalação, não reivindicada": uma caixa "nexus-keys" com a etiqueta "preflight-record, apenas o relatório mais recente". Uma seta da caixa da esquerda para nexus-keys tem a etiqueta "pod exec com o seu próprio acesso ao cluster (--record auto ou always)". À direita, "Navegador, antes do início de sessão": uma caixa "Instalador da consola, A verificação prévia não pode continuar". Uma seta de nexus-keys para ela tem a etiqueta "GET /v1/installation/preflight". Debaixo da caixa central, uma pequena nota diz "após a reivindicação: ROUTE_NOT_FOUND".
Para onde vai um relatório de verificação prévia, desde a estação de trabalho do operador até ao navegador.

Acessos de que a execução necessita

A verificação prévia é executada em seu nome, com o seu kubeconfig. A conta precisa de ler:

  • nós, para as verificações de versão, prontidão, recursos e gráficos;
  • classes de armazenamento e classes de ingress;
  • Services no namespace de ingress;
  • o Secret TLS no namespace de instalação, quando a verificação de certificado é executada.

Quando uma leitura é recusada, a linha indica could not read <what> (the cluster refused), e a correção indica que acesso de leitura deve conceder. As palavras nunca incluem o endereço do servidor nem o seu próprio texto de erro, porque o relatório pode ser mostrado antes do início de sessão. A entrega também precisa de pods/exec nos pods nexus-keys; sem isso, auto guarda os ficheiros e imprime um aviso, e always termina com 2.

Quando a própria verificação prévia não pode ser executada

O código de saída 2 significa que nenhum relatório foi gerado. A mensagem no erro padrão indica o motivo:

Mensagem O que fazer
--context is required: the kube context to check Adicione --context
--values is required: the values file the install will use Adicione --values
could not read the values file harrow-values.yaml Verifique o caminho e as permissões do ficheiro
preflight takes flags only Remova o argumento excedente
the report breaks its contract and was not printed, saved or handed over Um campo teria transportado algo privado; comunique-o à Adverant com as flags da execução
--record always: there is no nexus-keys Deployment in the namespace nexus to hand the report to Instale primeiro, ou utilize --record auto
could not hand the report to this installation Verifique o seu acesso para executar exec em nexus-keys

Um cluster cuja API não possa ser alcançada também termina com 2. Corrija o kubeconfig ou a rede e execute novamente.

Assim que a verificação prévia terminar com 0 failed, avance para o capítulo 2.6, Instalar o Community no Kubernetes, para instalar o Community, ou para o capítulo 2.7, Instalar o Enterprise e aplicar uma licença, para o Enterprise.