Versión 1.0.0-alpha.1 más reciente
Capítulo 2.5
Comprobación previa con nexusctl
Cada comprobación que realiza `nexusctl preflight`, qué lee cada una y cómo falla, el informe que imprime y guarda, cómo llega ese informe a la página de comprobación previa de la consola, y cada opción.
Esta página fue traducida por IA a partir del original en inglés. Si algo no está claro, la página en inglés es la referencia. Leer esta página en inglés

Nuestra primera comprobación previa en Harrow Port Authority falló en cuatro controles, y dos de ellos nos habrían costado mucho más que una tarde. Habíamos empezado el archivo de valores copiando el ejemplo del chart, y la comprobación previa rechazó tanto el nombre de instalación de ejemplo como el custodio de ejemplo. Nadie posee la clave privada de ese custodio. Una instalación sellada con ella nunca puede desellarse tras el reinicio de un nodo. La comprobación previa detectó eso en pocos segundos, antes de que existiera nada que perder.
nexusctl preflight lee su clúster y su archivo de valores, muestra lo que encontró, guarda un informe y no cambia nada en el clúster. Ejecútelo antes de cada instalación y de cada actualización. Este capítulo aborda todas las comprobaciones que realiza, el formato del informe, adónde va el informe y los indicadores.
Puesta en marcha y operación
La comprobación previa necesita dos cosas: el contexto kube del clúster en el que realizará la instalación y el archivo de valores que utilizará la instalación. Escriba primero el archivo de valores; el capítulo 2.6, Instalación de Community en Kubernetes, recorre cada clave. A continuación:
nexusctl preflight --context harrow-prod --values harrow-values.yamlLee el clúster a través de client-go únicamente con llamadas get y list. Si su tls.mode es existing, cree el espacio de nombres nexus y el Secret de seguridad de la capa de transporte (TLS) antes de ejecutarlo (capítulo 2.6, Instalación de Community en Kubernetes, paso 3), o la comprobación del certificado informará de que falta el Secret.
| Indicador | Qué hace | Valor predeterminado |
|---|---|---|
--context <name> |
El contexto kube que se va a comprobar. Obligatorio | ninguno |
--values <file> |
El archivo de valores que utilizará la instalación. Obligatorio | ninguno |
--namespace <name> |
Dónde se instala Nexus | nexus |
--release <version> |
La versión que se está comprobando | la versión propia del chart incluido |
--report-dir <dir> |
Dónde se guardan los dos archivos de informe | la carpeta actual |
--record <mode> |
auto, always o never: si se debe entregar el informe al servicio de claves de esta instalación, para que lo muestre su página del instalador |
auto |
--kubeconfig <file> |
El kubeconfig que se va a leer | KUBECONFIG, luego ~/.kube/config |
--ca-bundle <file> |
Sus propios certificados de autoridad de certificación (CA), para una cadena en la que las comprobaciones deban confiar | ninguno |
--single-node |
Comprobar una máquina para una instalación en una sola máquina (capítulo 2.8, Instalaciones en una sola máquina) | desactivado |
El mínimo de la versión para Kubernetes no está escrito directamente en nexusctl. Lee el límite inferior del propio kubeVersion del chart que incluye, por lo que la comprobación y helm install nunca pueden discrepar.
Qué imprime una ejecución
Aquí está la primera ejecución de Harrow, tal como se mostró:
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
Cuando algo falla, los fallos aparecen primero, luego las advertencias y después los aciertos. Cada fila muestra el resultado, el nombre de la comprobación, lo que se encontró y lo que necesita; cada fila que no ha sido superada tiene una línea fix debajo. Las dos últimas líneas son el resumen y el archivo de informe.
Corregimos los valores, añadimos los dos registros del Sistema de Nombres de Dominio (DNS), creamos el Secret y lo ejecutamos de nuevo:
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
Una ejecución sin fallos enumera las comprobaciones bajo sus tres encabezados: Clúster, Red y Tiempo y claves. Las advertencias nunca bloquean. Mantuvimos la advertencia de gráficos a propósito: en este clúster piloto conectado, el asistente de Harrow utilizó un modelo alojado con la clave propia del puerto.
Códigos de salida
| Código | Significado |
|---|---|
0 |
La instalación puede continuar. Las advertencias no bloquean |
1 |
La instalación está bloqueada: al menos una comprobación ha fallado |
2 |
La comprobación previa no pudo ejecutarse: no se pudo leer el kubeconfig, el contexto, el archivo de valores o la interfaz de programación de aplicaciones (API) del clúster, o bien un indicador era incorrecto |
Los scripts deben leer el código de salida, no las palabras. El nuestro ejecuta la comprobación previa como primer paso de cada actualización y se detiene ante cualquier valor distinto de 0.
Ejecute el nexusctl de la versión a la que va a pasar, no el de aquella con la que instaló. Los requisitos provienen del chart que incluye, por lo que una versión más reciente puede elevar el mínimo de Kubernetes o pedir más memoria, y solo su propio nexusctl lo sabe. --release cambia la versión que nombra el informe; no cambia qué reglas del chart se aplican. En Harrow guardamos el nexusctl de cada versión junto a su chart en el registro de cambios, de modo que una reversión se comprueba con la herramienta que le corresponde.
Cada comprobación
Hay once comprobaciones. Diez de ellas producen una fila cada una; la comprobación de dirección produce una fila por host, por lo que una ejecución completa tiene trece filas. Nueve comprobaciones deben superarse, y no hacerlo supone un fallo. Dos, los nodos gráficos y el certificado, deberían superarse, y no hacerlo supone una advertencia. La última columna es el texto de requisito que cada fila lleva al informe; en él, CPU es la unidad central de procesamiento.
| ID de comprobación | Sección | Debe superarse | Requisito que muestra |
|---|---|---|---|
kubernetes-version |
cluster | sí | Kubernetes 1.33 o posterior |
nodes-ready |
cluster | sí | Todos los nodos listos |
storage-class |
cluster | sí | Una clase de almacenamiento para los datos |
resources |
cluster | sí | Suficiente CPU y memoria para la versión |
graphics-nodes |
cluster | no | Nodos gráficos |
ingress-class |
network | sí | Una clase de ingress para las tres direcciones |
ingress-ports |
network | sí | El controlador de ingress abierto en los puertos 80 y 443 |
address-console, address-api, address-auth |
network | sí | La dirección de consola, api o auth se resuelve en DNS |
certificate |
network | no | Certificado válido durante 30 días más |
custodians |
time-and-keys | sí | Las personas que poseen las claves de recuperación de esta instalación |
installation-name |
time-and-keys | sí | El nombre permanente propio de esta instalación |
kubernetes-version
Lee la versión del servidor de la API y la compara con el mínimo del chart. Encuentra, por ejemplo, 1.33.6+k3s1. Por debajo de 1.33 falla con la solución upgrade the cluster to 1.33 or later. Si la cadena de versión no es una que nexusctl pueda leer, falla en lugar de adivinar.
nodes-ready
Enumera los nodos y cuenta aquellos cuya condición Ready es verdadera, como 3 of 3. Se nombra cualquier nodo que no esté listo, y la solución le indica que lo devuelva al estado Ready y lea sus condiciones. Un clúster sin ningún nodo falla con una sugerencia de que el contexto puede apuntar al clúster equivocado.
storage-class
Si sus valores definen storage.className, la comprobación busca esa clase y falla con <name> does not exist cuando falta. Si no lo hacen, busca una clase marcada como predeterminada e informa de ella como local-path (default). Sin ninguna predeterminada falla con none marked default, y la columna de necesidades indica por qué eso importa: the database cannot claim a disk. Si hay dos clases marcadas como predeterminadas, el clúster asigna a una nueva solicitud la más reciente, por lo que esa es de la que se informa.
resources
Calcula lo que solicita la versión a partir del chart y de sus valores, y luego suma los núcleos de unidad central de procesamiento (CPU) asignables y la memoria de cada nodo que esté Ready, no acordonado y que no tenga ningún taint NoSchedule o NoExecute. Los pods del chart no llevan tolerancias, por lo que un nodo con taint no puede ejecutarlos y no cuenta. Un clúster insuficiente falla indicando el déficit exacto, 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. Las necesidades se redondean hacia arriba y la capacidad disponible hacia abajo, por lo que la comprobación nunca resulta complaciente.
graphics-nodes
Busca un nodo Ready con una unidad de procesamiento gráfico (GPU) que pueda asignar, nvidia.com/gpu. Si no hay ninguno, advierte: the assistant will need a hosted model. La comprobación previa lo trata como una recomendación y nunca bloquea por ello, porque el asistente puede responder en su lugar a través de un modelo de inteligencia artificial (IA) alojado. El capítulo 2.14, Proveedores y modelos de IA, aborda ambas vías.
ingress-class
Si ingress.className está definido, la comprobación busca esa clase. Si no, busca exactamente una clase marcada como predeterminada. Dos clases marcadas como predeterminadas también fallan, porque el servidor de la API rechaza entonces un Ingress sin clase. La comprobación se omite, y su fila se excluye, cuando ingress.enabled es false.
ingress-ports
Busca en el espacio de nombres indicado por networkPolicy.ingressNamespace (de forma predeterminada kube-system, donde k3s ejecuta Traefik) un Service LoadBalancer o NodePort que exponga tanto el 80 como el 443. La política de red del chart permite que solo ese espacio de nombres alcance los tres Services públicos, por lo que un controlador de ingress en cualquier otro lugar no podría servir a Nexus aunque estuviera escuchando. La solución indica ambas salidas: exponer el controlador allí, o definir networkPolicy.ingressNamespace donde se ejecute. Se omite cuando ingress.enabled es false.
address
Busca hosts.console, hosts.api y hosts.auth desde su estación de trabajo, cinco segundos cada uno, y muestra una fila por host. Un host sin registro falla con <host> → no record. Un host no definido falla con hosts.<key> is not set. Cuando un nombre tiene varias direcciones, la fila muestra la primera, IPv4 antes que IPv6, y cuántas más hay.
certificate
Se ejecuta solo cuando tls.mode es existing y tls.existingSecret nombra un Secret; con cert-manager o none no hay ningún certificado suyo que leer, y la fila se excluye. Lee tls.crt del Secret en el espacio de nombres de instalación y nada más. Un certificado válido durante 30 días o más supera la comprobación como ends 3 Nov 2027. Uno que venza antes advierte ends in 9 days; uno ya vencido advierte ended 4 days ago. Un Secret que falta, o uno sin certificado en su interior, advierte indicando la solución.
custodians
Lee keys.custody.recipients. Si no hay ninguno, falla con el código KEYS_CUSTODIAN_MISSING. Si algún destinatario es el custodio de ejemplo de los propios archivos de valores del chart, falla con KEYS_CUSTODIAN_EXAMPLE, porque nadie posee esa clave y las claves de recuperación de la instalación quedarían selladas para nadie. Si se supera, muestra el recuento, como 3 custodians.
installation-name
Lee keys.installationName. Si no está definido, falla con INSTALLATION_NAME_MISSING. Si se define con el nombre de ejemplo de los archivos de valores del chart, falla con INSTALLATION_NAME_EXAMPLE. Si se supera, muestra el nombre. La columna de necesidades indica por qué este importa más que la mayoría: the first key-store bootstrap mints the installation identity under it, permanently.
Las dos últimas comprobaciones informan exactamente de los mismos códigos con los que el propio chart rechaza una instalación. La comprobación previa simplemente se lo dice antes, antes de que Helm haya creado nada.
Los archivos de informe
Cada ejecución guarda dos archivos en --report-dir, nombrados según la hora en que se ejecutó: preflight-2026-11-12-0902.txt, las líneas tal como se mostraron sin códigos de color, y preflight-2026-11-12-0902.json, la misma ejecución en un formato fijo que un programa puede leer. La salida del terminal y las líneas guardadas provienen de la misma lista, por lo que nunca difieren.
El informe JSON sigue el esquema nexus.preflight/v1:
| Campo | Qué contiene |
|---|---|
schema |
Exactamente nexus.preflight/v1 |
tool |
Un objeto: name (nexusctl) y version |
release |
La versión comprobada |
ran_at |
Cuándo se ejecutó, en tiempo universal coordinado (UTC) |
context |
El nombre del contexto kube |
values |
Solo el nombre base del archivo de valores |
read_only |
Siempre true |
checks |
Una entrada por fila: id, section, name, requirement, must_pass, outcome (pass, warn o fail), found, needs, fix, y cuando no se supera por una causa de máquina, code |
counts |
passed, warnings y failed |
can_install |
true cuando nada ha fallado |
report_file |
El nombre del archivo .txt |
transcript |
Un objeto: title (nexusctl preflight) y lines, cada línea con su kind (prompt, ok, warn, bad, note, out o blank), su text y at, y a veces marks |
El informe está diseñado para mostrarse antes de que alguien inicie sesión, por lo que no contiene ningún nombre de usuario, ningún nombre de host de estación de trabajo, ninguna ruta de archivo, ningún token ni nada de su kubeconfig. values es un nombre base y context es el nombre del contexto. Si el informe de una ejecución infringiera cualquiera de esas reglas, nexusctl se niega a mostrarlo, guardarlo o entregarlo, y así lo indica. Un informe tiene como máximo 256 KiB, con un máximo de 64 comprobaciones y 512 caracteres en cualquier campo de texto.
Cómo llega el informe a la consola
La única escritura de la comprobación previa es el informe finalizado, entregado al servicio de claves de la instalación, nexus-keys, para que el instalador de la consola pueda mostrarlo en su página de comprobación previa antes de que alguien haya reclamado la instalación. --record decide si se intenta:
--record |
Qué ocurre |
|---|---|
auto |
Entrega el informe solo cuando el espacio de nombres tiene un Deployment nexus-keys |
always |
Insiste; la comprobación previa sale con 2 si no hay nada a lo que entregarlo |
never |
No lo entrega |
Así pues, una ejecución anterior a la primera instalación no tiene nada a lo que entregarlo y conserva el informe en su estación de trabajo. Una ejecución posterior a la instalación y anterior a la reclamación lo registra.
La entrega utiliza su propio acceso al clúster. nexusctl ejecuta /app/nexus-keys preflight-record en el contenedor keys de un pod nexus-keys listo y pasa el informe por la entrada estándar. Es lo mismo que:
kubectl exec -i -n nexus -c keys deploy/nexus-keys -- /app/nexus-keys preflight-record < preflight-2026-11-12-0902.jsonEl servicio de claves comprueba el informe con las mismas reglas que aplica nexusctl y conserva únicamente el más reciente. Cuando se entrega, nexusctl muestra una línea más indicándolo, y el JSON guardado incorpora un note que registra la entrega.
El instalador de la consola lo lee desde la ruta pública del servicio de claves GET /v1/installation/preflight. Esa ruta responde solo mientras la instalación no ha sido reclamada: antes de que se registre ningún informe responde 404 RECORD_NOT_FOUND, y una vez que alguien reclama la instalación responde ROUTE_NOT_FOUND de forma definitiva, exactamente igual que la ruta de reclamación. Un informe entregado después de la reclamación se rechaza con INSTALLATION_CLAIMED.
En la consola, una ejecución con fallos aparece como "La comprobación previa no puede continuar": los recuentos de fallos, advertencias y superadas, y luego cada comprobación agrupada bajo "Debe superarse" y "Debería superarse", con las que no se superaron primero y las palabras encontradas junto a cada una. Una ejecución sin fallos no recibe esa página; la consola pasa directamente a la reclamación (capítulo 2.12, La primera ejecución).
Permisos que necesita la ejecución
La comprobación previa se ejecuta como usted, con su kubeconfig. La cuenta necesita leer:
- nodos, para las comprobaciones de versión, disponibilidad, recursos y gráficos;
- clases de almacenamiento y clases de ingress;
- Services en el espacio de nombres de ingress;
- el Secret TLS en el espacio de nombres de instalación, cuando se ejecuta la comprobación del certificado.
Cuando se deniega una lectura, la fila indica could not read <what> (the cluster refused), y la solución indica qué acceso de lectura conceder. Las palabras nunca incluyen la dirección del servidor ni su propio texto de error, porque el informe puede mostrarse antes de iniciar sesión. La entrega también necesita pods/exec en los pods nexus-keys; sin ello, auto guarda los archivos y muestra una advertencia, y always sale con 2.
Cuando la propia comprobación previa no puede ejecutarse
El código de salida 2 significa que no se generó ningún informe. El mensaje en el error estándar indica el motivo:
| Mensaje | Qué hacer |
|---|---|
--context is required: the kube context to check |
Añada --context |
--values is required: the values file the install will use |
Añada --values |
could not read the values file harrow-values.yaml |
Compruebe la ruta y los permisos del archivo |
preflight takes flags only |
Elimine el argumento sobrante |
the report breaks its contract and was not printed, saved or handed over |
Un campo habría contenido algo privado; informe de ello a Adverant con los indicadores de la ejecución |
--record always: there is no nexus-keys Deployment in the namespace nexus to hand the report to |
Instale primero, o utilice --record auto |
could not hand the report to this installation |
Compruebe su acceso para ejecutar exec en nexus-keys |
Un clúster cuya API no se puede alcanzar también sale con 2. Corrija el kubeconfig o la red y ejecútelo de nuevo.
Una vez que la comprobación previa termine con 0 failed, pase al capítulo 2.6, Instalación de Community en Kubernetes, para instalar Community, o al capítulo 2.7, Instalación de Enterprise y aplicación de una licencia, para Enterprise.

