Versão 1.0.0-alpha.1mais recente
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

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.yamlLê 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.
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.jsonO 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).
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.

