Iniciar sesiónReservar sesión

Capítulo 2.3

Planificación de una instalación

Qué necesita una instalación de Nexus en Kubernetes antes de escribir un comando, qué tamaño tiene y las dos decisiones irreversibles: el nombre de la instalación y los custodios de claves. Termina con la hoja de planificación cumplimentada de Harrow Port Authority.

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

Cuando instalamos Nexus en Harrow Port Authority, ejecutar los comandos llevó una tarde. La planificación llevó una semana, y la mayor parte de esa semana se dedicó a dos preguntas que no tienen nada que ver con Kubernetes: cómo llamaríamos a la instalación y qué personas custodiarían sus claves de recuperación. Ambas respuestas son permanentes. Todo lo demás en este capítulo se puede cambiar más adelante con un archivo de valores y un helm upgrade.

Soy Tomás Reilly, el ingeniero de plataformas en Harrow. Harrow ejecuta dos instalaciones. Este capítulo planifica la que está conectada a nuestra red corporativa, donde primero hicimos la prueba piloto de la edición Community. La red de operaciones del puerto, que no tiene salida a internet, tuvo su propia instalación más adelante; el capítulo 2.10, Instalación aislada de la red (air-gapped), la aborda. Este capítulo es lo que me habría gustado tener la primera mañana: el clúster que Nexus espera, los nombres a los que responde, cuánto exige de sus nodos y las decisiones que debe acordar con su director de TI antes de la instalación. Cierra con la hoja de trabajo que Aoife Brennan, nuestra directora de TI, aprobó antes de que empezáramos. El capítulo 2.4, Obtención y verificación de una versión, explica cómo descargar y comprobar la versión, y el capítulo 2.5, Comprobación previa con nexusctl, verifica su clúster frente a todo lo expuesto aquí.

Qué debe tener el clúster

Nexus se instala como un único chart de Helm, nexus, versión 1.0.0-alpha.1. El chart contiene los servicios de la plataforma y su capa de datos, y se niega a instalarse en un clúster al que le falten los elementos indicados a continuación.

Requisito Qué espera Nexus Por qué
Kubernetes 1.33 o posterior. Probado en k3s v1.33.6+k3s1 El kubeVersion del chart es >=1.33.0-0, y helm install lo exige
cert-manager v1.21.3, instalado antes que Nexus El chart crea su propia autoridad de certificación (CA) local y los certificados que sus servicios utilizan para comunicarse entre sí
Helm v4 (nosotros usamos v4.3.1) Helm 4 espera de forma predeterminada a los Jobs de tipo hook del chart, de los cuales depende la instalación
Una clase de almacenamiento Una marcada como predeterminada, o una que especifique en storage.className Cada almacén de datos reclama un volumen persistente
Una clase de ingress Una marcada como predeterminada, o una que especifique en ingress.className Las tres direcciones públicas son recursos Ingress networking.k8s.io/v1 estándar
Puertos 80 y 443 Abiertos en el controlador de ingress, como un Service de tipo LoadBalancer o NodePort Los usuarios acceden a Nexus a través del controlador de ingress
Arquitectura Nodos linux/amd64 o linux/arm64 Cada imagen está compilada para ambos

Hay dos elementos ausentes de esa tabla a propósito. Nexus no necesita una malla de servicios (service mesh): el TLS mutuo (mTLS, seguridad de la capa de transporte en ambas direcciones) entre servicios proviene de la CA local del chart a través de cert-manager. El chart tiene una clave istio.enabled cuyo valor predeterminado es false, y debe dejarla así. Nexus tampoco necesita un motor de políticas de admisión propio.

En su estación de trabajo necesitará kubectl, Helm v4, cosign v3 para verificar firmas, age para generar claves de custodio y nexusctl, la interfaz de línea de comandos (CLI) del operador de Nexus. El capítulo 2.4, Obtención y verificación de una versión, indica dónde se encuentra cada descarga de Nexus.

Tres direcciones

Cada instalación responde en tres nombres de host. El chart los denomina la identidad de la instalación, y todos los servicios se niegan a iniciarse sin ellos.

Clave de valores Nombre en Harrow Qué responde ahí
hosts.console console.harrow.example La consola, la aplicación web en la que los usuarios inician sesión
hosts.api api.harrow.example La pasarela (gateway), que sirve la interfaz de programación de aplicaciones (API) y enruta cada solicitud de inteligencia artificial (IA)
hosts.auth auth.harrow.example El servicio de inicio de sesión, nexus-auth

global.domain contiene el dominio bajo el cual se ubican los tres, harrow.example en nuestro caso. Cada host es un nombre completo por derecho propio y puede ubicarse bajo cualquier dominio que usted controle. Mantuvimos los tres bajo un mismo dominio para que un solo certificado pudiera cubrirlos.

Cree un registro en el sistema de nombres de dominio (DNS) para cada uno de los tres, apuntando a la dirección de su controlador de ingress. Hágalo antes de la comprobación previa. nexusctl preflight busca cada nombre desde su estación de trabajo y hace fallar la instalación si alguno de ellos no tiene registro, ya que un usuario no puede acceder a un nombre que no se resuelve.

A la izquierda, tres nombres DNS: console.harrow.example, api.harrow.example y auth.harrow.example, cada uno con una flecha hacia un recuadro etiquetado como "ingress controller, ports 80 and 443". Desde ese recuadro, tres flechas conducen a un recuadro más grande etiquetado como "namespace nexus": la flecha de console hacia "nexus-alpha :3000", la flecha de api hacia "nexus-gateway :9092" y la flecha de auth hacia "nexus-auth :9101". Un borde discontinuo alrededor del espacio de nombres está etiquetado como "default deny; only the ingress namespace may reach these three".
Cómo los tres nombres públicos llegan a los servicios detrás de ellos.

Elegir dónde termina TLS

La clave tls.mode del chart decide quién gestiona los certificados para las tres direcciones públicas. Hay tres opciones, y puede cambiar entre ellas más adelante mediante una actualización.

tls.mode Usted proporciona Qué hace el chart
existing (el valor predeterminado) Un Secret TLS de Kubernetes en el espacio de nombres nexus, nombrado en tls.existingSecret Los tres recursos Ingress utilizan ese único Secret
cert-manager Un ClusterIssuer que usted ejecuta, nombrado en tls.clusterIssuer Anota cada Ingress para que cert-manager emita nexus-console-tls, nexus-api-tls y nexus-auth-tls
none Algún elemento delante del clúster que termine TLS, como su propio balanceador de carga Genera los recursos Ingress sin sección TLS

Con existing, un certificado sirve a los tres hosts, por lo que debe incluir los tres, ya sea como tres nombres alternativos del sujeto (SAN) o como un comodín (wildcard) para su dominio. Nosotros utilizamos un certificado de la CA interna de Harrow. La comprobación previa lee el Secret antes de instalar y advierte si su certificado vence en menos de 30 días.

Con cert-manager y un emisor del entorno automatizado de gestión de certificados (ACME), el chart no añade ninguna redirección propia, de modo que una solicitud /.well-known/acme-challenge/ en el puerto 80 llega al solucionador intacta. No añada una redirección de HTTP a HTTPS en su controlador de ingress que se ejecute antes de la ruta del desafío; un certificado que no puede renovarse falla silenciosamente, semanas después.

Independientemente de lo que elija para el borde público, los servicios dentro del espacio de nombres siempre se comunican mediante TLS a partir de la CA local del chart. Esa parte no es opcional, y es la razón por la que cert-manager es un requisito previo incluso cuando tls.mode es existing o none.

Qué sale del clúster y qué no

El chart genera una política de red de denegación predeterminada para el espacio de nombres nexus. Después de eso, solo se permiten estos flujos:

  • tráfico entre pods de Nexus dentro del espacio de nombres;
  • consultas DNS al servicio DNS del clúster;
  • el servidor de la API de Kubernetes, para los pocos servicios que revisan tokens de cargas de trabajo;
  • el espacio de nombres del controlador de ingress, hacia los tres Services públicos;
  • cualquier rango de enrutamiento entre dominios sin clases (CIDR) que especifique en networkPolicy.externalEgressCIDRs.

Esa última lista está vacía de forma predeterminada. Si va a utilizar un relé de correo o un servidor de modelos fuera del clúster, su rango va ahí. La telemetría está desactivada y permanece desactivada: el esquema solo acepta telemetry.enabled: false, y los informes de uso propios de los almacenes de datos también están desactivados.

El chart lee las direcciones del servidor de la API desde el clúster cuando usted realiza la instalación. Si su cuenta no puede leer los Endpoints kubernetes en el espacio de nombres default, indíquelos usted mismo en networkPolicy.apiServerCIDRs, como rangos /32. proxy.trustedCIDRs nombra la red de pods en la que se encuentra su controlador de ingress, para que nexus-auth sepa en qué encabezado X-Forwarded-For confiar. El valor predeterminado, 10.42.0.0/16, es la red de pods de k3s.

Dimensionamiento

Las solicitudes predeterminadas del chart suman alrededor de 2.05 núcleos de unidad central de procesamiento (CPU) y 6.7 GiB de memoria. Eso es lo que reserva el planificador (scheduler); los límites son más altos, y los almacenes de datos crecen hasta alcanzarlos a medida que añade usuarios y archivos.

Componente CPU solicitada Memoria solicitada
Nueve servicios de plataforma (console, backend for frontend (BFF), auth, orchestrator, workflows, gateway, graphrag, probitas, skills engine) 1.1 núcleos 2.6 GiB
El servicio de claves, nexus-keys 0.05 núcleos 64 MiB
PostgreSQL 0.25 núcleos 1 GiB
Neo4j 0.25 núcleos 2 GiB
Valkey, Qdrant y el almacén de objetos juntos 0.25 núcleos 640 MiB
Los dos servidores OpenBao del almacén de claves 0.15 núcleos 384 MiB

Los volúmenes predeterminados suman 142 GiB:

Almacén Clave de valores Tamaño predeterminado
PostgreSQL 16 con PostGIS 3 y pgvector 0.8 dataTier.postgres.size 50Gi
Almacén de objetos (SeaweedFS) dataTier.objectStore.size 50Gi
Neo4j 5.26 Community Edition dataTier.neo4j.size 20Gi
Qdrant dataTier.qdrant.size 10Gi
Valkey dataTier.valkey.size 5Gi
El almacén de claves y su desbloqueador (unsealer) keys.openbao.storage.keystore, keys.openbao.storage.unsealer 5Gi y 1Gi
Recibos del servicio de claves keys.receiptsStorage 1Gi

Para un solo nodo, planifique 8 vCPU, 32 GiB de memoria de acceso aleatorio (RAM) y una unidad de estado sólido (SSD) de 250 GB. Para una evaluación, bastará con 4 vCPU, 16 GiB y 200 GB. La imagen de disco del instalador rechaza una máquina con menos de 16 GiB de memoria (consulte el capítulo 2.9, La imagen de disco del instalador), y yo trataría eso como el mínimo indispensable en cualquier entorno.

Los nodos gráficos son opcionales. Sin un nodo que ofrezca una unidad de procesamiento gráfico (GPU), el asistente responde a través de un modelo alojado, utilizando la clave propia de la organización. La comprobación previa informa de ello como una advertencia, nunca como un fallo. El capítulo 2.14, Proveedores y modelos de IA, aborda ambas vías.

Cada almacén también puede ejecutarse fuera del clúster: configure dataTier.<store>.mode en external y especifique su host y un Secret. Un PostgreSQL externo necesita una cuenta de superusuario para el arranque inicial de la instalación y un certificado que Nexus pueda verificar. El capítulo 2.11, Variaciones: almacenes externos, TLS e ingress, trata este tema. Si los mantiene en el clúster, colóquelos en una clase de almacenamiento respaldada por discos reales. La base de datos es la parte que más echará de menos si falla el disco local de un nodo.

El nombre de la instalación es permanente

keys.installationName es como los operadores llaman a esta instalación. Debe coincidir con ^[a-z][a-z0-9-]{0,62}$: una letra minúscula, seguida de hasta 62 letras minúsculas, dígitos o guiones.

La primera vez que se inicia el almacén de claves, acuña la identidad de la instalación bajo este nombre, y esa identidad queda fijada para siempre. Una licencia de Adverant se emite para esa identidad, por lo que una licencia creada para una instalación es rechazada en otra con LICENCE_OTHER_INSTALLATION. Cambiar el nombre implicaría una nueva instalación, una nueva identidad y nuevas licencias.

El chart no tiene un valor predeterminado para el nombre. Rechaza una instalación sin nombre (INSTALLATION_NAME_MISSING) y rechaza el nombre de ejemplo de sus propios archivos de valores de ejemplo (INSTALLATION_NAME_EXAMPLE). La comprobación previa informa de ambos casos antes de llegar a ese punto.

En Harrow dedicamos a esto más tiempo del que me gustaría admitir. Nos decidimos por harrow-port-authority: nombra a la organización, no dice nada sobre en qué clúster se ejecuta y seguirá siendo válido cuando se reemplace el hardware. Evite nombres como prod-k3s-2 que describen las máquinas actuales.

Custodia de claves

Nexus guarda las claves de cada organización en su propio almacén de claves, dentro del clúster. Usted no lo opera en el día a día, pero sí decide, antes de la instalación, quién puede recuperarlo tras un reinicio. Esta es la decisión que más caro cuesta si se equivoca.

El almacén de claves consta de dos servidores OpenBao. El principal, openbao, guarda las claves y se desbloquea (unseals) a sí mismo a través de un segundo servidor más pequeño, openbao-unsealer. El desbloqueador está sellado con el esquema de Shamir: cinco fragmentos (shares), tres cualesquiera de los cuales lo abren. Cuando realiza la instalación, un Job de custodia inicializa ambos servidores dentro del clúster. En la memoria de ese Job, cifra los fragmentos del desbloqueador y las claves de recuperación del almacén de claves para cada custodio que usted nombre, almacena únicamente el texto cifrado (en los Secrets openbao-unseal-shares-encrypted y openbao-recovery-keys-encrypted) y revoca ambos tokens raíz antes de terminar. Ningún fragmento en texto plano llega nunca a un disco ni a un registro (log).

Tras cualquier reinicio del nodo del desbloqueador, este se inicia sellado. El almacén de claves lo espera, y nada que necesite una clave funciona hasta que un custodio lo desbloquea. Eso requiere un único descifrado con la clave privada del propio custodio. El procedimiento se encuentra en el capítulo 2.15, Día dos: operación de Nexus.

Creación de una clave de custodio

Un custodio se identifica mediante la mitad pública de una clave age, denominada su destinatario (recipient). Cada custodio genera su propia clave en su propia máquina y le entrega a usted únicamente el destinatario:

age-keygen -o custodian.key

La línea # public key: del archivo es el destinatario, que comienza por age1. Un custodio con un Mac puede guardar la clave en el Secure Enclave del Mac en su lugar, de modo que la mitad privada nunca sale del chip y cada uso solicita una huella dactilar:

age-plugin-se keygen --access-control=any-biometry -o custodian.key

Ese destinatario comienza por age1se1. El Job de custodia cifra para cinco formatos de destinatario: age1 (X25519), age1tag1 y age1tagpq1 (tag), age1pq1 (híbrido poscuántico) y age1se1 (Secure Enclave). Rechaza cualquier otro formato de complemento, como age1yubikey1; en su lugar, especifique esa clave en uno de los formatos aceptados.

El chart comprueba cada destinatario al generar las plantillas. Uno mal escrito falla su suma de comprobación bech32 y es rechazado, por lo que nunca se sella nada con una clave que nadie posee. Si alguien pega una clave privada en la lista por error, el chart la rechaza sin mostrarla en la salida. El destinatario de ejemplo en los propios archivos de valores del chart también es rechazado (KEYS_CUSTODIAN_EXAMPLE); nadie posee su mitad privada.

Cuántos custodios

Cada fragmento se cifra para cada custodio, por lo que cualquier custodio puede desbloquear por sí solo. Más custodios significa más formas de recuperarse y más personas que pueden actuar de manera independiente. En Harrow elegimos tres: Aoife, yo y una clave de Secure Enclave en un portátil de repuesto que se guarda en la caja fuerte del puerto. Dos es el mínimo que yo aceptaría. Uno es un punto único de fallo que, tarde o temprano, estará de vacaciones cuando se reinicie un nodo.

Elegir la edición

edition es community o enterprise, y enterprise.enabled debe coincidir con ello. El chart rechaza una discrepancia y rechaza cualquier edición que no sea una de las dos.

La edición también decide qué imágenes instala. Cada paquete del chart lleva un bloqueo de imágenes (images lock), la lista de cada imagen por su resumen criptográfico (digest), para una edición. Una instalación Community toma únicamente imágenes Community. Una instalación Enterprise toma el bloqueo Enterprise, que contiene las imágenes Community más las compilaciones Enterprise, y las descarga con un token de extracción (pull token) de su cuenta de Adverant. El capítulo 2.4, Obtención y verificación de una versión, explica el bloqueo, y el capítulo 2.2, Ediciones al detalle, explica qué contiene cada edición.

No tiene que decidirlo de forma definitiva. Una instalación Community pasa a Enterprise in situ, conservando sus usuarios, archivos e historial; el capítulo 2.7, Instalación de Enterprise y aplicación de una licencia, muestra cómo hacerlo. En Harrow ejecutamos Community para la prueba piloto y pasamos a Enterprise seis semanas después.

La licencia nunca forma parte de este plan. No es un valor del chart ni un archivo montado: usted la importa después de la instalación, a través de la consola, nexusctl o la API.

Elegir el formato de entrega

Formato Cuándo encaja Capítulo
Chart de Helm desde registry.adverant.ai Su propio clúster de Kubernetes, con ruta hacia el registro de imágenes 2.6 y 2.7
nexusctl install El mismo clúster, con la comprobación previa y la verificación de firmas ejecutadas automáticamente en su nombre 2.6
nexusctl install --single-node Una máquina, donde nexusctl también configura el clúster 2.8
La imagen de disco del instalador Un servidor físico (bare metal) o máquina virtual (VM) que prefiere no preparar a mano 2.9
El paquete sin conexión (offline bundle) Sin ninguna ruta de salida; las imágenes y el chart vienen en un disco 2.10

El chart es el mismo en todos los formatos. Lo que cambia es quién crea el clúster y de dónde provienen las imágenes.

Obtener la versión
Obtener la versión
Esta es la página de versiones en la cuenta de Adverant. Observe la declaración clara de lo que promete una versión alfa, el tamaño y la firma junto a cada archivo, y los comandos sin conexión para verificar una descarga.

La hoja de planificación

Esta es la de Harrow, tal como la aprobó Aoife. Copie las dos columnas de la izquierda y rellene la de la derecha para su propia instalación.

Decisión Clave de valores o comando Harrow Port Authority
Kubernetes y versión (la comprobación previa lo lee) k3s v1.33.6+k3s1, tres nodos
Contexto de Kube para la instalación --context harrow-prod
Espacio de nombres --namespace nexus
Edición edition, enterprise.enabled community para el piloto, luego enterprise
Registro de imágenes global.imageRegistry registry.adverant.ai
Dominio global.domain harrow.example
Dirección de la consola hosts.console console.harrow.example
Dirección de la API hosts.api api.harrow.example
Dirección de inicio de sesión hosts.auth auth.harrow.example
TLS en el borde tls.mode, tls.existingSecret existing, Secret harrow-public-tls de la CA interna de Harrow
Clase de ingress ingress.className traefik
Espacio de nombres de ingress networkPolicy.ingressNamespace kube-system
Clase de almacenamiento storage.className local-path
Almacenes de datos dataTier.<store>.mode Todos in-cluster, tamaños predeterminados
Rangos de salida networkPolicy.externalEgressCIDRs Solo el rango del relé de correo
Nombre de la instalación (permanente) keys.installationName harrow-port-authority
Custodios (permanentes en la práctica) keys.custody.recipients Tres: Aoife Brennan, Tomás Reilly, el portátil de la caja fuerte (age1se1)
Nodos gráficos (la comprobación previa lo lee) Ninguno para el piloto conectado; modelo alojado con la clave propia de Harrow
Primer administrador nexusctl claim-code --administrator aoife.brennan@harrow.example

Dos filas de esa hoja no se pueden deshacer: el nombre de la instalación, y los custodios en el sentido de que perderlos a todos implica perder el almacén de claves. Haga que alguien con autoridad para dar el visto bueno apruebe esas dos. Todo lo demás es un cambio en los valores.

Con la hoja de trabajo lista, vaya al capítulo 2.4, Obtención y verificación de una versión, y descargue la versión.