Iniciar sesiónReservar sesión

Capítulo 2.6

Instalación de Community en Kubernetes

Una instalación paso a paso de la edición Community con Helm, desde cert-manager hasta tener todas las cargas de trabajo listas, con el archivo de valores explicado clave por clave, por qué no se usa --wait, el orden en que se ejecutan los hooks del chart y la vía de instalación con nexusctl como alternativa.

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

La instalación en sí consiste en un único helm install. Todo lo que la rodea está ahí para que ese único comando funcione a la primera: cert-manager antes, un archivo de valores que haya leído línea por línea y una espera posterior que sabe qué debe esperar. En Harrow Port Authority instalamos primero la edición Community, para una prueba piloto de seis semanas, en el clúster k3s de tres nodos de nuestra hoja de trabajo de planificación. La versión estuvo en funcionamiento en unos veinte minutos y nadie pudo iniciar sesión hasta que la reclamamos, que es como debe ser.

Este capítulo asume que ya ha hecho tres cosas: completado la hoja de trabajo de planificación (capítulo 2.3, Planificación de una instalación), descargado y comprobado la versión (capítulo 2.4, Obtención y verificación de una versión) y ejecutado las comprobaciones previas (capítulo 2.5, Comprobaciones previas con nexusctl). Si alguno de estos pasos sigue pendiente, retroceda. La instalación rechaza la mayoría de los errores indicando su nombre, pero hay algunos, como un custodio cuya clave ya haya perdido, que no puede detectar.

Paso 1: confirmar sus herramientas y contexto

  1. Compruebe que Helm sea la versión 4.

    helm version

    La instalación depende de que Helm 4 espere de forma predeterminada a los Jobs de los hooks del chart. Nosotros utilizamos la versión v4.3.1.

  2. Apunte kubectl al clúster de su hoja de trabajo y confírmelo.

    kubectl config use-context harrow-prod
    kubectl get nodes

    Cada nodo debería mostrar Ready. Las comprobaciones previas ya verificaron esto, pero un nodo puede caerse entre dichas comprobaciones y la instalación, y es más rápido verlo aquí.

Paso 2: instalar cert-manager primero

El chart crea su propia autoridad de certificación (CA) local con cert-manager, y cada servicio se comunica con los demás mediante los certificados que esta emite: un Issuer autofirmado, un certificado de CA local de diez años y certificados de corta duración para los servicios. Por lo tanto, cert-manager debe estar en ejecución antes que Nexus. La versión necesita v1.21.3 y no requiere trust-manager.

  1. Instale cert-manager desde su propio chart, con sus recursos personalizados:

    helm install cert-manager <cert-manager-chart> -n cert-manager --create-namespace \
      --set crds.enabled=true --wait --timeout 10m

    <cert-manager-chart> es el chart de cert-manager v1.21.3 de la propia versión del proyecto cert-manager. Esperar aquí es lo correcto; se trata de la instalación del propio cert-manager, sin hooks que dependan de nada más.

  2. Espere a su webhook, por el que pasa cada solicitud de certificado:

    kubectl -n cert-manager rollout status deploy/cert-manager-webhook --timeout=300s
    deployment "cert-manager-webhook" successfully rolled out

Paso 3: crear el espacio de nombres y el Secret de TLS

Con tls.mode: existing, el chart espera su certificado como un Secret de Kubernetes en el espacio de nombres antes de la instalación. La seguridad de la capa de transporte (TLS) para las tres direcciones proviene de este único Secret, por lo que su certificado debe incluir los nombres de los tres hosts.

kubectl create namespace nexus
kubectl -n nexus create secret tls harrow-public-tls \
  --cert=harrow-public.crt --key=harrow-public.key

harrow-public.crt es el certificado, con su cadena, y harrow-public.key su clave privada. Si eligió tls.mode: cert-manager o none en el capítulo 2.3, Planificación de una instalación, omita el Secret; aun así, puede crear el espacio de nombres ahora o dejar que Helm lo haga con --create-namespace en el paso 6.

Paso 4: escribir el archivo de valores

Este es el archivo de valores de Harrow para la prueba piloto. Cada clave que contiene es una clave que el esquema del chart acepta; el esquema rechaza cualquier otra, por lo que una clave mal escrita hace que falle la instalación en lugar de ignorarse silenciosamente.

# harrow-values.yaml (Helm values, Community)
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
ingress:
  className: traefik
storage:
  className: local-path
networkPolicy:
  ingressNamespace: kube-system
  externalEgressCIDRs: ["10.20.9.25/32"]
keys:
  installationName: harrow-port-authority
  custody:
    recipients:
      - "<recipient-aoife>"
      - "<recipient-tomas>"
      - "<recipient-safe-laptop>"

Cada <recipient-...> es el destinatario age público de un custodio, la línea age1... o age1se1... que le enviaron. Aquí está cada clave que configuramos y el porqué.

global.imageRegistry es el registro desde el que sus nodos descargan las imágenes. El chart no tiene ningún valor predeterminado; construye cada imagen como <this>/nexus/<service>@<digest>. Para una instalación conectada, es registry.adverant.ai. Si copió las imágenes en su propio registro, es ese host.

global.domain es el dominio bajo el que se sitúan las tres direcciones.

hosts.console, hosts.api y hosts.auth son la identidad de la instalación: los tres nombres que utilizan las personas y los programas. Cada uno debe resolverse ya en el sistema de nombres de dominio (DNS), lo cual se verificó en las comprobaciones previas.

edition y enterprise.enabled deben coincidir: community con false, o enterprise con true. El chart rechaza cualquier otra combinación, y rechaza una edición para la que no se haya creado su bloqueo de imágenes.

tls.mode y tls.existingSecret eligen cómo obtiene su certificado el borde público. Con cert-manager establecería tls.clusterIssuer en su lugar, y con none ninguno de los dos.

ingress.className indica el nombre de la clase de ingress. Déjelo sin configurar para utilizar la clase predeterminada del clúster.

storage.className indica el nombre de la clase de almacenamiento para cada volumen de datos. Déjelo sin configurar para utilizar el valor predeterminado.

networkPolicy.ingressNamespace es el espacio de nombres en el que se ejecuta su controlador de ingress. El valor predeterminado, kube-system, es el correcto para Traefik de k3s; lo configuramos de todos modos para que quede explícito en el archivo.

networkPolicy.externalEgressCIDRs enumera los rangos de direcciones, en notación de enrutamiento entre dominios sin clases (CIDR), fuera del espacio de nombres a los que pueden acceder los servicios, más allá del DNS y del servidor de la interfaz de programación de aplicaciones (API) de Kubernetes. El nuestro contiene la dirección única del retransmisor de correo; con la lista vacía, no se puede acceder a nada fuera del espacio de nombres.

keys.installationName es el nombre permanente bajo el cual el almacén de claves acuña la identidad de la instalación.

keys.custody.recipients enumera los destinatarios age públicos de los custodios. El Job de custodia cifra cada fragmento de desbloqueo y clave de recuperación para cada uno de ellos.

Claves que puede necesitar y claves que no debe tocar

Clave Cuándo configurarla
networkPolicy.apiServerCIDRs Cuando el chart no puede leer las direcciones del servidor de la API desde los Endpoints de kubernetes. Indíquelas como rangos /32
proxy.trustedCIDRs Cuando los pods de su controlador de ingress no están en el 10.42.0.0/16 de k3s
ai.localProvider.baseUrl Cuando la organización ejecuta su propio servidor de modelos de inteligencia artificial (IA) compatible con OpenAI (capítulo 2.14, Proveedores y modelos de IA)
ai.installationHosts Cuando ese servidor de modelos utiliza nombres privados dentro de la instalación
dataTier.<store>.size Cuando un almacén necesita más que su volumen predeterminado
dataTier.<store>.mode external para un almacén que usted mismo ejecuta (capítulo 2.11, Variaciones: almacenes externos, TLS e ingress)
components.<service>.replicas, components.<service>.resources Cuando amplía la capacidad de un servicio
auth.rateLimitPerMinute Cuando la automatización intensiva necesita más de 5,000 solicitudes por minuto por persona
schemaWait.timeoutSeconds Cuando un disco lento hace que las primeras migraciones tarden más de 30 minutos

Deje istio.enabled en false; Nexus no necesita malla de servicios. Deje telemetry.enabled en false; el esquema no acepta ningún otro valor. Deje orchestrator.platformServiceUserId y probitas.flags tal como los establece el chart.

Ninguna credencial es nunca un valor del chart. No hay ninguna clave para la clave de API de un proveedor de modelos, una contraseña de correo o un token de descarga. Los servicios generan sus propios secretos internos durante la instalación y los conservan al actualizar, y las claves de modelo de cada organización se introducen en su propio grupo de claves desde la consola después de la primera ejecución.

Paso 5: ejecutar la comprobación previa con el archivo final

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

La ejecución debe terminar con 0 failed. El capítulo 2.5, Comprobaciones previas con nexusctl, explica cada fila. Si ha cambiado algo desde la última ejecución, aunque sea un tamaño, vuelva a ejecutarlo.

Paso 6: instalar, sin --wait

helm install nexus oci://registry.adverant.ai/nexus/charts/nexus --version 1.0.0-alpha.1 \
  --namespace nexus -f harrow-values.yaml --timeout 45m

Si no creó el espacio de nombres en el paso 3, añada --create-namespace. Si está instalando desde un archivo de chart que descargó y comprobó, ponga su ruta en lugar de la referencia oci://.

No añada --wait. El arranque de la base de datos del chart se ejecuta como un hook posterior a la instalación, después de que existan los recursos propios de la versión, y es ese hook el que proporciona a cada servicio su rol y contraseña de base de datos. --wait retendría la instalación hasta que cada Deployment estuviera Available, y ningún Deployment puede pasar a estar Available antes de que se haya ejecutado el hook al que está esperando. Los servicios se quedan rechazando sus inicios de sesión en la base de datos, y Helm los espera hasta que se agota el tiempo de espera. Sin --wait, Helm 4 sigue esperando a cada Job de hook, en orden, y esa es la espera que usted necesita.

Cuando el último hook ha terminado, Helm imprime su resumen:

NAME: nexus
NAMESPACE: nexus
STATUS: deployed
REVISION: 1

STATUS: deployed significa que todos los hooks se completaron correctamente. Todavía no significa que todos los servicios estén prestando servicio; el paso 7 espera a que eso ocurra.

Qué se ejecuta y en qué orden

Helm ejecuta los hooks por peso, de menor a mayor, y espera a que termine cada uno antes de pasar al siguiente. Cada Job de migración tiene backoffLimit: 0: una migración fallida hace que falle la instalación y nunca se vuelve a intentar a sus espaldas. Un Job que tiene éxito se elimina; un Job que falla permanece, junto con su registro, para que usted pueda leerlo.

Peso Hook Qué hace
-30 Requisitos previos La cuenta de hook nexus-migrations, el Secret exclusivo para hooks nexus-migrations-env con las credenciales de base de datos generadas, y la cuenta, el rol, la configuración y el certificado del Job de custodia
-20 nexus-db-bootstrap Crea las bases de datos y los roles, ninguno de ellos como superusuario y ninguno capaz de eludir la seguridad a nivel de fila (RLS); añade las extensiones, entre ellas PostGIS y pgvector; crea el libro mayor de versiones
-15 nexus-openbao-custody-init Inicializa el almacén de claves y su desbloqueador, cifra los fragmentos y las claves de recuperación para sus custodios, revoca ambos tokens raíz y acuña la identidad de la instalación bajo keys.installationName
-12 nexus-graphrag-migrations Despliega primero el esquema del servicio de grafos, porque el esquema del servicio de inicio de sesión hace referencia a objetos que le pertenecen
-10 nexus-auth-migrations Despliega el esquema del servicio de inicio de sesión y sus dos roles de tiempo de ejecución
-5 nexus-orchestrator-migrations, nexus-gateway-migrations, nexus-probitas-migrations El esquema propio de cada servicio; probitas se ejecuta después de auth porque comprueba primero las tablas de auth
0 nexus-alpha-bff-migrations Aprovisiona la base de datos del backend para frontend (BFF) y sus roles, y luego aplica sus migraciones

Cada hook de migración termina escribiendo una fila en el libro mayor de versiones, nexus_release.schema_applied: el nombre de su cadena y el resumen criptográfico (digest) de la imagen que la ejecutó. Escribe esa fila solo después de que su ejecutor de migraciones haya finalizado sin errores. El Job de arranque imprime db-bootstrap: done; los hooks de migración SQL imprimen schema-ledger: recorded <chain> for this release's image como su última línea. El propio hook de migración de la consola, nexus-alpha-bff-migrations, registra su fila de la misma manera y luego imprime bff-migrate: done.

Una línea de tiempo horizontal que va de izquierda a derecha, etiquetada como "helm install". En la pista superior, siete recuadros de hooks en orden: "-30 prerequisites", "-20 db-bootstrap", "-15 custody init", "-12 graphrag migrations", "-10 auth migrations", "-5 orchestrator, gateway, probitas migrations", "0 BFF migrations". Cada recuadro de migración tiene una pequeña flecha hacia abajo que apunta a un cilindro en una pista intermedia etiquetado como "release ledger: nexus_release.schema_applied". En la pista inferior, una barra larga que comienza a la izquierda etiquetada como "Deployments start, wait-for-schema holds each pod"; desde ella suben flechas verticales cortas hacia el libro mayor, y la barra de cada Deployment se vuelve sólida cuando aparece su propia fila en el libro mayor.
El orden de una instalación desde cero, con los hooks y las cargas de trabajo lado a lado.

Cómo esperan los servicios a su esquema

Los Deployments se inician tan pronto como Helm los crea, mientras los hooks aún se están ejecutando. Un servicio que se iniciara contra una base de datos sin rol, sin contraseña o sin esquema fallaría y se reiniciaría hasta que los hooks terminaran. Por eso, cada Deployment que utiliza la base de datos lleva un contenedor de inicialización, wait-for-schema, que retiene el pod en su lugar.

Lee el libro mayor de versiones como nexus_ledger_reader, un inicio de sesión que puede leer esa única tabla y nada más, y espera hasta que el libro mayor muestre sus cadenas para los resúmenes criptográficos de imagen de esta versión. Realiza consultas cada schemaWait.intervalSeconds (3 de forma predeterminada), imprime su estado cuando cambia y cada veinte consultas, y desiste después de schemaWait.timeoutSeconds (1,800 de forma predeterminada) con un fallo que indica el nombre del servicio.

Despliegue Espera a
nexus-auth nexus-auth-migrations
nexus-orchestrator, nexus-workflows nexus-orchestrator-migrations
nexus-gateway nexus-gateway-migrations
nexus-graphrag nexus-graphrag-migrations
nexus-probitas nexus-probitas-migrations
nexus-skills-engine nexus-db-bootstrap
nexus-alpha-bff nexus-alpha-bff-migrations

Para observar la espera de un servicio en tiempo real, lea el registro de su contenedor de inicialización:

kubectl -n nexus logs deploy/nexus-auth -c wait-for-schema
wait-for-schema: nexus-auth waits for nexus_release.schema_applied (read as nexus_ledger_reader) to show: nexus-auth-migrations; gives up after 1800s
wait-for-schema: ready after 212s: the release ledger shows nexus-auth-migrations

Dado que la espera se basa en el resumen criptográfico de la imagen, y no en un recuento de archivos, los pods de una actualización posterior esperan a las filas de la nueva versión, y un pod que se reinicia tras un cambio exclusivo de valores encuentra su fila de inmediato.

Paso 7: esperar a todas las cargas de trabajo

Espere a los Deployments, con un límite de tiempo:

kubectl -n nexus wait --for=condition=Available deploy --all --timeout=900s
deployment.apps/nexus-alpha condition met
deployment.apps/nexus-alpha-bff condition met
deployment.apps/nexus-auth condition met
deployment.apps/nexus-gateway condition met
deployment.apps/nexus-graphrag condition met
deployment.apps/nexus-keys condition met
deployment.apps/nexus-orchestrator condition met
deployment.apps/nexus-probitas condition met
deployment.apps/nexus-skills-engine condition met
deployment.apps/nexus-workflows condition met

Luego, a los StatefulSets. Los dos servidores del almacén de claves se actualizan solo cuando usted elimina sus pods, y kubectl rollout status rechaza esa estrategia de actualización, por lo que debe esperar al recuento de listos en su lugar:

for s in $(kubectl -n nexus get statefulset -o name); do
  kubectl -n nexus wait "$s" --for=jsonpath='{.status.readyReplicas}'=1 --timeout=900s
done

Cada uno imprime condition met. En nuestro clúster, ambas esperas juntas tardaron menos de cinco minutos después de que Helm terminara.

Cómo se ve cuando está listo

kubectl -n nexus get deploy,statefulset
NAME                                  READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/nexus-alpha           1/1     1            1           14m
deployment.apps/nexus-alpha-bff       1/1     1            1           14m
deployment.apps/nexus-auth            1/1     1            1           14m
deployment.apps/nexus-gateway         1/1     1            1           14m
deployment.apps/nexus-graphrag        1/1     1            1           14m
deployment.apps/nexus-keys            1/1     1            1           14m
deployment.apps/nexus-orchestrator    1/1     1            1           14m
deployment.apps/nexus-probitas        1/1     1            1           14m
deployment.apps/nexus-skills-engine   1/1     1            1           14m
deployment.apps/nexus-workflows       1/1     1            1           14m

NAME                                READY   AGE
statefulset.apps/nexus-neo4j        1/1     14m
statefulset.apps/nexus-postgres     1/1     14m
statefulset.apps/nexus-qdrant       1/1     14m
statefulset.apps/nexus-seaweedfs    1/1     14m
statefulset.apps/nexus-valkey       1/1     14m
statefulset.apps/openbao            1/1     14m
statefulset.apps/openbao-unsealer   1/1     14m

Diez Deployments y siete StatefulSets, todos listos. Junto a ellos encontrará tres CronJobs, nexus-keys-rotate-epoch, nexus-keys-run-schedule y nexus-keys-export-receipts, encargados del mantenimiento nocturno del servicio de claves. kubectl -n nexus get jobs no debería mostrar ningún Job de hook: los que tuvieron éxito se eliminaron.

Vale la pena hacer dos cosas antes de salir de la terminal. Confirme el archivo de valores en el repositorio donde su equipo guarde la configuración; cada actualización parte de él. Y no toque el Secret nexus-generated. El chart genera las contraseñas y claves internas una sola vez, durante la instalación, las guarda ahí y las vuelve a leer en cada actualización, por lo que eliminarlo dejaría a los servicios sin poder acceder a sus propios datos.

Listo significa que la plataforma está en ejecución y sin reclamar. Abra https://console.harrow.example y llegará al instalador, no a una página de inicio de sesión: nadie puede iniciar sesión hasta que alguien reclame la instalación. Esa es la primera ejecución, en el capítulo 2.12, La primera ejecución.

Esta instalación (Community)
Esta instalación (Community)
La página propia de una instalación Community una vez reclamada: la versión en ejecución, el estado del motor, el uso del disco, las copias de seguridad y la promesa de correcciones de seguridad, con las funciones Enterprise mostradas como avances que indican quién puede activarlas.

Si esto falla

La mayoría de los fallos indican su propio nombre. Lea el mensaje antes de cambiar nada.

Lo que ve Causa Qué hacer
INSTALLATION_NAME_MISSING o INSTALLATION_NAME_EXAMPLE keys.installationName está vacío o es el de ejemplo Establezca su propio nombre permanente
KEYS_CUSTODIAN_MISSING o KEYS_CUSTODIAN_EXAMPLE No hay custodios, o está el de ejemplo Establezca los destinatarios propios de sus custodios
keys.installationName ... does not match ^[a-z][a-z0-9-]{0,62}$ Mayúsculas, puntos o un dígito inicial Utilice letras minúsculas, dígitos y guiones, comenzando por una letra
keys.custody.recipients: ... y un motivo Un destinatario tiene un error tipográfico, es una clave privada o tiene un formato para el que el Job de custodia no puede cifrar Pida de nuevo al custodio su destinatario
hosts.console is required (the installation identity) Falta por configurar un host Configure los tres hosts
tls.existingSecret is required when tls.mode is existing No se ha indicado ningún Secret Configúrelo o cambie tls.mode
networkPolicy.apiServerCIDRs is empty and the kubernetes Endpoints could not be read Su cuenta no puede leer las direcciones del servidor de la API Indíquelas como rangos /32
global.imageRegistry is required El registro no está configurado Configúrelo
Helm espera hasta agotar el tiempo de espera; nexus-auth registra password authentication failed Se indicó --wait Desinstale y vuelva a instalar sin --wait
Error: ... job failed nombrando un hook Falló una migración kubectl -n nexus logs job/<hook-name> y lea sus últimas líneas
Un pod atascado en Init Su wait-for-schema sigue esperando Lea su registro: indica el nombre de la cadena que le falta
wait-for-schema: FAILED El hook de la cadena nunca escribió su fila Encuentre primero el fallo de ese hook
ImagePullBackOff El nodo no puede descargar desde global.imageRegistry Compruebe que el nodo pueda acceder al registro y, para Enterprise, que tenga el token de descarga

Cada hook que espera a PostgreSQL espera un tiempo limitado y lo indica, waiting for postgres (12/60), por lo que una base de datos atascada aparece en el registro del hook en el plazo de un minuto.

La vía de instalación con nexusctl

nexusctl install realiza la misma instalación, ejecutando por usted las comprobaciones que la rodean. Utiliza el mismo archivo de valores:

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

Ejecuta de nuevo las comprobaciones previas y se detiene si alguna comprobación ha empezado a fallar. Verifica la firma del paquete del chart con la clave de la versión. Luego instala, espera a que terminen los hooks y las cargas de trabajo, e imprime cada paso con el tiempo que tardó. --edition community indica la edición tanto en la línea de comandos como en el archivo. --ca-bundle <file> añade sus propios certificados de CA, igual que en las comprobaciones previas. Para ver las operaciones de helm y kubectl que ejecutaría, sin llegar a ejecutarlas, añada --explain:

nexusctl install --context harrow-prod --values harrow-values.yaml --explain

Cuando termina, imprime la dirección de reclamación, un código de reclamación de un solo uso y la huella digital de la instalación:

Installed in <time>. 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:
         <eight groups of four>

El código consta de tres grupos y permite cinco intentos; la huella digital consta de ocho grupos de cuatro caracteres, y el navegador muestra los mismos ocho grupos para que usted los compare antes de reclamar.

Instalando
Instalando
La instalación ejecutándose en la terminal del operador. Cada paso se imprime con su tiempo, y la ejecución termina con un código de un solo uso y la huella digital de la instalación; nadie puede iniciar sesión hasta que la instalación se reclame en un navegador.

Paso del testigo a la primera ejecución

Si realizó la instalación con Helm, genere usted mismo el código de reclamación, indicando el nombre de la persona que será el primer administrador:

nexusctl claim-code --administrator aoife.brennan@harrow.example

Ejecuta el comando de código de reclamación propio del servicio de claves en el pod nexus-keys con su acceso al clúster, e imprime la dirección, el código y la huella digital como se muestra arriba. El código funciona durante 30 minutos; vuelva a ejecutarlo para obtener uno nuevo.

A partir de aquí, el navegador toma el relevo: reclame la instalación, cree el primer administrador con una clave de acceso (passkey) y complete los seis puntos antes de que nadie inicie sesión. Eso se aborda en el capítulo 2.12, La primera ejecución. Si va a aplicar la licencia de Enterprise de inmediato, lea primero el capítulo 2.7, Instalación de Enterprise y aplicación de una licencia, porque la licencia es uno de esos seis puntos.