Iniciar sesiónReservar sesión

Capítulo 2.8

Instalaciones en una sola máquina

Instale Nexus en un servidor Linux con nexusctl, o evalúelo en un portátil con k3d, y acceda a la consola mediante HTTPS para que funcionen el inicio de sesión y las llaves de acceso (passkeys).

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

18 minutos de lectura

Antes de que Harrow Port Authority pusiera Nexus en su clúster de producción, Tomás Reilly quiso realizar dos instalaciones más pequeñas. Una fue un piloto en un servidor Linux de repuesto en el edificio de operaciones, para las doce personas que lo probarían primero. La otra se ejecutó en su propio portátil, para poder romper cosas sin que nadie se diera cuenta. Este capítulo cubre ambas. Utilizan el mismo chart, las mismas imágenes y la misma primera ejecución que una instalación completa de Kubernetes, por lo que lo que aprenda en una máquina se traslada a la otra.

La vía del servidor es un solo comando: nexusctl install --single-node construye un clúster k3s en la máquina, instala cert-manager y luego instala Nexus. La vía del portátil es más práctica. Usted mismo construye un clúster k3d, instala cert-manager y el chart con Helm, y luego realiza una tarea adicional en la que tropieza casi todo el mundo: pone la consola detrás de HTTPS en su propia máquina, porque un simple reenvío de puertos nunca puede iniciar la sesión de nadie.

Qué tamaño debe tener la máquina

Nexus solicita aproximadamente 2.05 núcleos de CPU (unidad central de procesamiento) y 6.7 GiB de memoria en solicitudes con los valores predeterminados del chart, y sus volúmenes suman 142 GiB. Ese total corresponde a PostgreSQL 50, Valkey 5, Neo4j 20, Qdrant 10, el almacén de objetos 50, los dos almacenes de OpenBao 1 y 5, y el volumen de recibos 1. Las solicitudes son lo que reserva el planificador, y el uso real es mayor una vez que las personas están trabajando.

Máquina CPU Memoria (RAM, memoria de acceso aleatorio) Disco
Nodo único recomendado 8 vCPU 32 GiB SSD (unidad de estado sólido) de 250 GB
Mínimo para evaluación 4 vCPU 16 GiB 200 GB

Un portátil que cumpla con el mínimo de evaluación ejecutará Nexus, pero cuenta el límite de memoria propio de Docker, no el del portátil. Asigne a Docker al menos 16 GiB antes de comenzar.

Ambas vías necesitan Kubernetes 1.33 o posterior. La vía de nodo único trae el suyo propio: k3s v1.33.6+k3s1, la distribución en la que se prueba cada versión.

Primera parte: un servidor Linux con nexusctl

El servidor piloto de Tomás es una máquina de 8 núcleos con 32 GiB de memoria y un SSD de 500 GB, que ejecuta un Linux actual sin nada más instalado. La instalación necesita permisos de root, porque instala k3s como un servicio del sistema.

Obtener nexusctl y verificarlo

  1. Descargue nexusctl para su arquitectura desde https://downloads.adverant.ai/nexus/1.0.0-alpha.1/, junto con la clave pública de la versión. Guarde la clave como release.pub. El capítulo 2.4, Obtención y verificación de una versión, explica cómo comprobar la huella digital de la clave con la que publica Adverant.
  2. Verifique el binario y la versión con la clave:
nexusctl version --json
nexusctl verify

nexusctl verify comprueba la descarga contra la clave de versión de Adverant y rechaza cualquier cosa que no pueda verificar. Si falla, deténgase y descargue de nuevo. Nunca ejecute una instalación desde un archivo que no se haya verificado.

Crear la clave de custodio

El almacén de claves de la instalación sella sus claves de recuperación para uno o más custodios. Un custodio es una persona que posee un archivo de identidad age fuera de línea, y el chart se niega a instalarse sin al menos uno. En la propia máquina del custodio:

age-keygen -o custodian.key

El archivo comienza con una línea # public key: age1.... Esa mitad pública es lo que va en el archivo de valores. El archivo de identidad en sí nunca sale de la máquina del custodio. En un Mac con Secure Enclave, age-plugin-se keygen --access-control=any-biometry -o custodian.key crea una clave que necesita Touch ID para usarse, y su mitad pública comienza con age1se1.

Escribir el archivo de valores

# harrow-pilot-values.yaml (Helm values)
global:
  imageRegistry: registry.adverant.ai
  domain: harrow.example
hosts:
  console: console.harrow.example
  api: api.harrow.example
  auth: auth.harrow.example
edition: community
enterprise:
  enabled: false
tls:
  mode: existing
  existingSecret: harrow-public-tls
keys:
  installationName: harrow-pilot
  custody:
    recipients:
      - "<custodian-age-recipient>"

<custodian-age-recipient> es la línea age1... de custodian.key. Añada una entrada de lista por cada custodio.

keys.installationName es permanente. El primer inicio del almacén de claves acuña la identidad de la instalación bajo ese nombre, y nada lo cambia después. Debe coincidir con ^[a-z][a-z0-9-]{0,62}$: minúsculas, comenzando con una letra, como máximo 63 caracteres. No copie nexus-example ni el destinatario de ejemplo de los propios archivos de ejemplo del chart. El chart rechaza ambos por su nombre, y la comprobación previa informa primero de los mismos códigos.

Los tres hosts son la identidad de la instalación. Todos los servicios se niegan a iniciarse sin ellos, y cada inicio de sesión, cookie y passkey está vinculado a hosts.console. Elija nombres que aún quiera conservar dentro de cinco años.

Apuntar los tres nombres al servidor

Los usuarios llegan a la consola, a la API (interfaz de programación de aplicaciones) y al servicio de inicio de sesión a través del controlador ingress integrado de k3s, Traefik, en los puertos 80 y 443 del servidor. Añada tres registros DNS (sistema de nombres de dominio) para console.harrow.example, api.harrow.example y auth.harrow.example, cada uno apuntando a la dirección del servidor. La comprobación previa verifica cada nombre y le indica cuál no tiene registro.

La política de red del chart permite que solo un espacio de nombres llegue a los tres servicios públicos. Su valor predeterminado, kube-system, es donde k3s ejecuta Traefik, por lo que en un nodo único se deja networkPolicy.ingressNamespace sin tocar.

Ejecutar la comprobación previa y luego instalar

  1. Ejecute la comprobación previa con el indicador de nodo único. Lee la máquina y su archivo de valores y no cambia nada.
sudo nexusctl preflight --single-node --values harrow-pilot-values.yaml
  1. Lea la línea de resumen al final. Una advertencia nunca bloquea la instalación, pero un fallo sí, y cada fila con fallo incluye una línea fix.
 ────────────────────────────────────────────────────────────
 9 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
  1. Instale. El indicador --edition debe coincidir con edition en el archivo de valores.
sudo nexusctl install --single-node --values harrow-pilot-values.yaml --edition community
  1. Observe cómo se ejecuta. Ejecuta la comprobación previa de nuevo, instala k3s v1.33.6+k3s1, instala cert-manager v1.21.3, instala Nexus y espera a que cada servicio responda a su comprobación de estado. En el servidor de Tomás tardó algo menos de diez minutos.
 done   Preflight again        9 passed · 1 warning
 done   k3s v1.33.6+k3s1       node Ready
 done   cert-manager v1.21.3   ready
 done   Database and search    ready
 done   Engines                started
 done   Console                https://console.harrow.example
 Installed. Nobody can sign in yet.
 Open https://console.harrow.example/claim
 Code <code>  works once, for 30 minutes
 Fingerprint of this installation, to compare in the browser:
 3F9A C21B 77E0 5D4C 9B12 A6F3 0E88 41D7

Mantenga esa huella digital en pantalla. La comparará en el navegador cuando reclame la instalación con el código. Si el código caduca antes de que lo use, nexusctl claim-code --administrator <email> genera uno nuevo. El capítulo 2.12, La primera ejecución, continúa a partir de ahí.

Instalar la edición Community
Instalar la edición Community
La instalación de la edición Community en un servidor consiste en descargar, verificar, ejecutar la comprobación previa e instalar, y luego configurar el primer administrador. No hay paso de licencia.

Colocar el certificado en su lugar

Con tls.mode: existing, las tres rutas de ingress sirven el certificado en el Secret nombrado por tls.existingSecret. Tiene que cubrir los tres hosts. La comprobación previa lee ese Secret cuando existe y advierte cuando el certificado vence en menos de 30 días. Cuando el Secret aún no está ahí, la fila le indica que lo cree, y es una advertencia, no un fallo.

En un nodo único, el clúster no existe hasta que la instalación lo ha creado, así que cree el Secret inmediatamente después de la instalación. Escriba primero el kubeconfig del clúster (la última sección de este capítulo lo explica) y luego cree el Secret con él:

sudo nexusctl kubeconfig > harrow-pilot.kubeconfig
chmod 600 harrow-pilot.kubeconfig
export KUBECONFIG=$PWD/harrow-pilot.kubeconfig
kubectl -n nexus create secret tls harrow-public-tls --cert=harrow-public.crt --key=harrow-public.key

harrow-public.crt contiene el certificado seguido de cualquier certificado intermedio, y harrow-public.key su clave privada. Si sus certificados provienen de una CA (autoridad de certificación) privada, nexusctl preflight y nexusctl install toman --ca-bundle <file> para poder comprobar la cadena. Las otras formas de manejar TLS (seguridad de la capa de transporte) están en el capítulo 2.11, Variaciones: almacenes externos, TLS e ingress.

Si esto falla

Lo que ve Qué significa Qué hacer
PREFLIGHT_FAILED (409) La comprobación previa encontró un fallo, por lo que la instalación no se inició. No se instaló nada. Corrija cada fila con fallo, utilizando su línea fix, y ejecute la instalación de nuevo.
INSTALLATION_NAME_MISSING keys.installationName está vacío. Establezca el nombre permanente propio de la instalación.
INSTALLATION_NAME_EXAMPLE El nombre es el de los valores de ejemplo del chart. Elija su propio nombre.
KEYS_CUSTODIAN_MISSING keys.custody.recipients está vacío. Añada el destinatario age1... público de cada custodio.
KEYS_CUSTODIAN_EXAMPLE Un destinatario es el custodio de ejemplo del chart, cuya identidad nadie posee. Reemplácelo con los destinatarios de sus custodios.

nexusctl sale con 0 cuando puede continuar, con 1 cuando una comprobación lo bloqueó y con 2 cuando no pudo ejecutarse en absoluto (un archivo de valores ilegible, un indicador incorrecto). Un script puede bifurcarse en función de esos tres valores.

Segunda parte: una evaluación en un portátil con k3d

k3d ejecuta k3s dentro de contenedores Docker, por lo que un clúster entero vive en un portátil y desaparece con un solo comando. Las herramientas de lanzamiento que prueban cada versión de Nexus construyen sus clústeres exactamente de esta manera, y copiar su configuración le ahorra redescubrir los problemas que ellas ya encontraron.

Necesita Docker, k3d 5.8.3, kubectl, Helm v4 y Chrome. Tomás usó su Mac.

Crear el clúster

k3d cluster create harrow-eval --agents 0 --wait --timeout 300s \
  --image rancher/k3s:v1.33.6-k3s1 \
  --k3s-arg "--disable=traefik@server:0"
k3d kubeconfig get harrow-eval > harrow-eval.kubeconfig
chmod 600 harrow-eval.kubeconfig
export KUBECONFIG=$PWD/harrow-eval.kubeconfig

Cada indicador tiene una razón.

  • --agents 0 proporciona un nodo servidor y ningún nodo trabajador. Nexus se ejecuta sin problemas en un nodo, y un segundo nodo solo consume memoria.
  • --image rancher/k3s:v1.33.6-k3s1 fija la versión de k3s en la que se prueba cada lanzamiento. Sin él, obtiene la versión predeterminada de k3d.
  • --disable=traefik@server:0 omite Traefik. Un portátil no tiene una dirección pública que servir, y en su lugar usted llega a la consola a través de su propio frontal HTTPS (más abajo).
  • --wait --timeout 300s regresa solo cuando el clúster responde, o falla después de cinco minutos.

Si replica el registro de versiones en su portátil, añada --registry-config <registries.yaml> para enviar las descargas de imágenes al espejo, y --k3s-arg "--disable-default-registry-endpoint@server:0" para que nada recurra a un registro de origen. Las herramientas de lanzamiento se ejecutan de esta manera, con cada imagen proveniente únicamente a través del espejo.

Instalar cert-manager

El chart crea su propia CA local, nexus-local-ca, como un emisor de cert-manager, y cada servicio obtiene su certificado de ella. Sin los recursos de cert-manager en el clúster, helm install rechaza el chart en cuestión de segundos. Instale primero cert-manager v1.21.3, desde el chart que publica el proyecto cert-manager:

helm install cert-manager cert-manager-v1.21.3.tgz -n cert-manager \
  --create-namespace --set crds.enabled=true --wait --timeout 10m

Nexus no necesita nada más de cert-manager, y en particular ningún trust-manager.

Instalar Nexus

  1. Escriba un archivo de valores para el portátil. TLS termina en su propio frontal, por lo que tls.mode es none.
# harrow-eval-values.yaml (Helm values)
global:
  imageRegistry: registry.adverant.ai
  domain: harrow.example
hosts:
  console: console.harrow.example
  api: api.harrow.example
  auth: auth.harrow.example
edition: community
tls:
  mode: none
keys:
  installationName: harrow-eval
  custody:
    recipients:
      - "<custodian-age-recipient>"
  1. Instale el chart desde el registro y omita --wait (la advertencia a continuación explica por qué).
helm install nexus oci://registry.adverant.ai/nexus/charts/nexus --version 1.0.0-alpha.1 \
  -n nexus --create-namespace -f harrow-eval-values.yaml --timeout 45m
  1. Luego espere a las cargas de trabajo usted mismo:
kubectl -n nexus wait --for=condition=Available deploy --all --timeout=900s
for s in $(kubectl -n nexus get sts -o name); do
  want=$(kubectl -n nexus get "$s" -o jsonpath='{.spec.replicas}')
  kubectl -n nexus wait "$s" --for=jsonpath='{.status.readyReplicas}'="$want" --timeout=900s
done

El bucle de StatefulSet está ahí porque algunos de ellos actualizan un pod a la vez bajo petición, y kubectl rollout status los rechaza. Esperar a readyReplicas funciona para cualquier estrategia de actualización.

Cuando ambos comandos regresan, cada Deployment está Available y cada StatefulSet tiene sus pods listos. Nadie puede iniciar sesión todavía. Eso es correcto: la instalación no ha sido reclamada.

Por qué un reenvío de puertos nunca permite iniciar sesión

El siguiente paso obvio es kubectl port-forward svc/nexus-alpha 3000:3000 y abrir un navegador en http://127.0.0.1:3000. Las páginas de la consola se cargan, por lo que parece que funciona. No es así, y ningún ajuste hará que funcione. Tres cosas se interponen en el camino, cada una a propósito.

Qué lo detiene Por qué
El origen El inicio de sesión de la consola rechaza una solicitud cuyo origen no sea https://<hosts.console>, aquí https://console.harrow.example. Una página servida desde http://127.0.0.1:3000 tiene el origen incorrecto, por lo que el inicio de sesión nunca comienza.
La cookie La sesión es una cookie __Host- marcada como Secure. Los navegadores almacenan dicha cookie solo a través de HTTPS, sin atributo de dominio, exactamente para el host que la estableció. A través de HTTP simple, el navegador la descarta.
La passkey El primer administrador inicia sesión con una passkey, y una passkey necesita un contexto seguro con un certificado válido. Chrome se niega a crear una passkey detrás de una advertencia de certificado, incluso si usted hizo clic para ignorarla.

Por lo tanto, el navegador tiene que hablar con https://console.harrow.example, con un certificado en el que confíe, y ese nombre tiene que dirigir a su portátil.

Acceder a la consola mediante HTTPS en su portátil

El método a continuación utiliza la propia CA del chart para emitir el certificado, un reenvío de puertos para llegar a la consola y un perfil separado de Chrome que confía en esa única CA y asigna el nombre de la consola a su portátil. El almacén de confianza de su sistema y /etc/hosts permanecen como están.

El diagrama muestra a Chrome a la izquierda, etiquetado como "perfil separado: confía solo en nexus-local-ca; console.harrow.example:443 asignado a 127.0.0.1:28443". Una flecha etiquetada como "HTTPS" va a un cuadro "frontal HTTPS en 127.0.0.1:28443 (certificado de nexus-local-ca)". Una flecha etiquetada como "HTTP, Host mantenido, X-Forwarded-Proto https" va a "kubectl port-forward 127.0.0.1:3000", y una flecha final entra en el cuadro del clúster k3d hacia "Service nexus-alpha, puerto http (3000)". Una línea de puntos desde cert-manager dentro del clúster hacia el cuadro frontal está etiquetada como "emite el certificado".
Cómo un navegador en el portátil llega a la consola en el clúster k3d a través de HTTPS.

Emitir un certificado para el nombre de la consola

  1. Pida a cert-manager un certificado para el host de la consola, firmado por el emisor del chart:
# console-front-certificate.yaml (a cert-manager Certificate)
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: nexus-console-front
  namespace: nexus
spec:
  secretName: nexus-console-front-tls
  dnsNames: [console.harrow.example]
  duration: 24h
  usages: [server auth, digital signature, key encipherment]
  privateKey: { algorithm: ECDSA, size: 256, rotationPolicy: Always }
  issuerRef: { name: nexus-local-ca, kind: Issuer, group: cert-manager.io }
kubectl apply -f console-front-certificate.yaml
kubectl -n nexus wait --for=condition=Ready certificate/nexus-console-front --timeout=120s

cert-manager lo firma dentro del clúster. Usted nunca lee la clave privada de la CA.

  1. Copie el certificado, su clave y el certificado de la CA fuera del Secret:
kubectl -n nexus get secret nexus-console-front-tls -o jsonpath='{.data.tls\.crt}' | base64 -d > tls.crt
kubectl -n nexus get secret nexus-console-front-tls -o jsonpath='{.data.tls\.key}' | base64 -d > tls.key
kubectl -n nexus get secret nexus-console-front-tls -o jsonpath='{.data.ca\.crt}' | base64 -d > ca.crt
chmod 600 tls.key
  1. Calcule el pin de la CA. Chrome identifica una clave de confianza mediante el SHA-256 en base64 de su clave pública:
openssl x509 -in ca.crt -pubkey -noout | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | base64

Fije la clave de la CA, no la del certificado. El certificado dura un día y obtiene una clave nueva cada vez que cert-manager lo renueva, mientras que la CA sigue siendo la misma.

Poner un frontal HTTPS delante de un reenvío de puertos

  1. Reenvíe el Service de la consola. Su puerto es el llamado http, que es el 3000 en esta versión:
kubectl -n nexus port-forward svc/nexus-alpha 3000:3000
  1. Ejecute un receptor HTTPS en 127.0.0.1:28443 que reenvíe a 127.0.0.1:3000. Cualquier proxy inverso en el que ya confíe servirá, siempre que haga cuatro cosas:
    • sirva tls.crt seguido de ca.crt como la cadena, con tls.key;
    • mantenga el encabezado Host como console.harrow.example;
    • establezca X-Forwarded-Proto: https;
    • deje pasar las actualizaciones de WebSocket, porque la consola las utiliza.

Un reenvío de puertos a un Service se vincula al único pod que eligió cuando se inició. Después de que una actualización o un reinicio reemplace el pod de la consola, el reenvío permanece activo pero no reenvía a nada, y el navegador muestra un error de puerta de enlace incorrecta (bad gateway). Reinicie el reenvío de puertos cada vez que cambie el pod de la consola.

Abrir Chrome con el pin y la asignación de nombres

En un Mac:

open -na "Google Chrome" --args --user-data-dir="$HOME/.nexus-eval-chrome" \
  "--host-resolver-rules=MAP console.harrow.example:443 127.0.0.1:28443" \
  "--ignore-certificate-errors-spki-list=<ca-pin>" \
  https://console.harrow.example/install

<ca-pin> es la salida de la línea openssl. En Linux, inicie Chrome con los mismos tres indicadores.

Los tres indicadores funcionan juntos. --host-resolver-rules envía console.harrow.example en el puerto 443 a su frontal, solo dentro de este perfil. --ignore-certificate-errors-spki-list confía en los certificados emitidos por esa única clave de CA, y Chrome lo respeta solo con --user-data-dir. El perfil separado mantiene la excepción alejada de su navegación diaria. No es un interruptor general para "ignorar errores de certificado": cualquier cosa que no esté firmada por la CA del clúster seguirá fallando.

Con ese perfil abierto, https://console.harrow.example/install lleva a la página de reclamación y se puede crear una passkey. El capítulo 2.12, La primera ejecución, continúa a partir de aquí.

Cuando el portátil se reinicia

El almacén de claves tiene dos partes: el propio almacén de claves y un pequeño abridor (unsealer) que contiene su clave de desbloqueo. Después de cualquier reinicio del nodo (un reinicio de Docker, un reinicio del portátil, k3d cluster stop y start) el abridor se inicia sellado. El almacén de claves se abre a sí mismo a través de él, por lo que hasta que un custodio abra el abridor con su propia identidad age, nada que necesite una clave funcionará. Esa es una propiedad del diseño, y es igual en un clúster de producción. El capítulo 2.15, Día dos: operación de Nexus, muestra el proceso de apertura.

Cuando haya terminado con la evaluación:

k3d cluster delete harrow-eval

Eliminar el clúster elimina la instalación y todo lo que contiene.

nexusctl kubeconfig

Un clúster construido por nexusctl install --single-node pertenece a nexusctl. Para llegar a él con kubectl, helm o cualquier otra herramienta, solicite su kubeconfig:

sudo nexusctl kubeconfig > harrow-pilot.kubeconfig
chmod 600 harrow-pilot.kubeconfig
export KUBECONFIG=$PWD/harrow-pilot.kubeconfig
kubectl -n nexus get deploy,statefulset

El archivo otorga acceso administrativo completo al clúster. Manténgalo en modo 600, en las máquinas de las personas que administran la instalación, y en ningún otro lugar. Cada comando posterior en la Parte 2 que toma --context o lee KUBECONFIG funciona contra un nodo único a través de este archivo. Lo mismo se aplica a una actualización: nexusctl upgrade plan --bundle <file> y nexusctl upgrade apply --bundle <file> en un nodo único también actualizan el clúster k3s que posee nexusctl.

El diagrama es una pila de cuatro capas sobre un cuadro etiquetado como "un servidor Linux". Desde abajo: "k3s v1.33.6+k3s1 (Traefik en kube-system, puertos 80 y 443)", luego "cert-manager v1.21.3 y la CA local del chart nexus-local-ca", luego "capa de datos de Nexus: PostgreSQL, Valkey, Neo4j, Qdrant, SeaweedFS, OpenBao", luego "servicios de Nexus: consola, inicio de sesión, puerta de enlace y el resto". A la derecha, tres flechas desde la capa superior salen del cuadro etiquetadas como console.harrow.example, api.harrow.example y auth.harrow.example. A la izquierda, un icono de terminal etiquetado como "nexusctl kubeconfig" apunta hacia la capa de k3s.
Lo que nexusctl install --single-node instala en un servidor Linux.

Qué se conserva al pasar a un clúster

Todo lo que hizo en una máquina tiene un equivalente en un clúster. El archivo de valores es el mismo archivo con un registro, modo TLS o clase de almacenamiento diferente, como muestra el capítulo 2.11, Variaciones: almacenes externos, TLS e ingress. La primera ejecución es idéntica. Lo que no se traslada es la instalación en sí: el nombre de la instalación queda fijado para siempre, y una instalación no se puede trasladar de un portátil a un servidor. Cuando Tomás pasó de su portátil al servidor piloto, comenzó de nuevo con un nombre nuevo, harrow-pilot, y mantuvo harrow-eval para experimentos.