Iniciar sesiónReservar sesión

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

16 minutos de lectura

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.yaml

Lee 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.

Antes de instalar
Antes de instalar
Comprobación previa en el terminal del operador, con los recuentos al lado. Observe que cada advertencia tiene su solución impresa debajo, y que la ejecución indica claramente que no ha cambiado nada en el clúster.

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.json

El 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).

La comprobación previa no puede continuar
La comprobación previa no puede continuar
La página de la consola para una ejecución de comprobación previa que no puede continuar. Las comprobaciones fallidas aparecen primero, cada una nombrada con palabras junto con lo que se encontró, y la instalación permanece bloqueada hasta que se superen.
Tres columnas. Izquierda, "Estación de trabajo del operador": un recuadro "nexusctl preflight --context --values" con dos salidas debajo, "preflight-<time>.txt" y "preflight-<time>.json". Centro, "La instalación, sin reclamar": un recuadro "nexus-keys" con la etiqueta "preflight-record, solo el último informe". Una flecha desde el recuadro izquierdo hasta nexus-keys lleva la etiqueta "pod exec con su propio acceso al clúster (--record auto o always)". Derecha, "Navegador, antes de iniciar sesión": un recuadro "Instalador de la consola, La comprobación previa no puede continuar". Una flecha desde nexus-keys hasta él lleva la etiqueta "GET /v1/installation/preflight". Debajo del recuadro central, una pequeña nota dice "después de la reclamación: ROUTE_NOT_FOUND".
Adónde va un informe de comprobación previa, desde la estación de trabajo del operador hasta el navegador.

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.