Versión 1.0.0-alpha.1 más reciente
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

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.
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.keyLa 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.keyEse 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.
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.
