Iniciar sesiónReservar sesión

Capítulo 2.9

La imagen de disco del instalador

Arranque un servidor físico o una máquina virtual desde la imagen del instalador de Nexus e instalará el sistema operativo, k3s, cert-manager y Nexus sin red, comprobando cada archivo antes de utilizarlo.

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

17 minutos de lectura

La oficina del capitán de puerto en el muelle este de Harrow tiene un servidor, no tiene conexión a internet y no hay nadie en las instalaciones que gestione Kubernetes. Aun así, Tomás Reilly necesitaba instalar Nexus en él. Grabó la imagen en una memoria USB (Universal Serial Bus), colocó al lado una segunda memoria pequeña con cuatro líneas de configuración e inició el servidor. Una hora más tarde, la pantalla mostraba la dirección de la consola y las tres líneas que debían añadirse al archivo hosts. No escribió ni un solo comando de Kubernetes.

Esa es la función de la imagen de disco del instalador. Escribe un sistema operativo mínimo en el disco del servidor y, en el primer arranque, comprueba cada archivo que contiene con la clave de versión de Adverant, instala k3s sin red, importa todas las imágenes, instala cert-manager y Nexus, y comprueba que todos los pods estén en ejecución. Cada paso se detiene indicando un motivo concreto en el momento en que algo falla. No hay modo degradado ni contraseñas predeterminadas en ninguna parte.

Las dos imágenes

Cada versión se presenta en dos tipos de imagen, para dos arquitecturas de procesador: amd64 y arm64.

Archivo Qué contiene Quién puede descargarla
nexus-alpha-installer-1.0.0-alpha.1-<arch>.iso Solo el instalador: el sistema operativo, k3s v1.33.6+k3s1, cert-manager v1.21.3 y el instalador de primer arranque. Funciona para cualquiera de las ediciones y no contiene imágenes de Nexus. Cualquier persona, desde downloads.adverant.ai
nexus-alpha-<edition>-1.0.0-alpha.1-<arch>.iso El mismo instalador con el paquete sin conexión de esa edición añadido como una segunda partición etiquetada como NEXUS-BUNDLE. Un único medio lo instala todo. Community: cualquier persona. Enterprise: solo desde su cuenta de Adverant

<arch> es amd64 o arm64, y <edition> es community o enterprise.

El instalador busca únicamente un sistema de archivos etiquetado como NEXUS-BUNDLE. En la imagen todo en uno, esa es la partición de la propia imagen. Con la imagen que contiene solo el instalador, usted aporta el paquete en un segundo disco o memoria USB con esa etiqueta, lo cual resulta práctico cuando instala varios sitios desde una misma memoria de instalación y cambia solo el paquete. El capítulo 2.10, Instalación aislada de la red, describe el paquete.

Las imágenes Enterprise y los paquetes Enterprise nunca son anónimos. Se descargan desde su cuenta de Adverant en https://account.adverant.ai, en la página de descargas, junto a su licencia. Las imágenes y los paquetes Community son públicos.

Dos ilustraciones de discos aparecen una al lado de la otra. La de la izquierda, «imagen de solo instalador», tiene una partición etiquetada como «instalador del sistema operativo, k3s, cert-manager, instalador de primer arranque» y, junto a ella, una memoria USB separada etiquetada como «NEXUS-BUNDLE: el paquete sin conexión de la edición». La de la derecha, «imagen todo en uno», tiene la misma primera partición y una segunda partición en el mismo disco etiquetada como «NEXUS-BUNDLE». Debajo de ambas, una pequeña memoria USB está etiquetada como «NEXUS-SEED: seed.yaml, y licence.json para Enterprise», con una nota que indica «opcional para Community». Las flechas de las tres etiquetas apuntan hacia abajo, a un único recuadro: «el primer arranque encuentra cada parte por su etiqueta».
La imagen de solo instalador y la imagen todo en uno, y dónde encuentra cada parte el primer arranque.

De qué está construida la imagen

El sistema operativo se basa en Debian 13 y no es una imagen oficial de Debian. Contiene el sistema base de Debian y nada más: sin paquetes adicionales, sin entorno de escritorio y sin servidor de réplica. k3s aporta su propio entorno de ejecución de contenedores y sus propias redes. La cadena de arranque (shim, GRUB, el kernel y el disco RAM inicial) es, byte por byte, la que distribuye Debian, por lo que una máquina con Secure Boot activado la inicia como cualquier instalador de Debian.

Dos compilaciones de la misma versión producen imágenes idénticas, byte por byte, y la versión no se publica hasta que esto se cumple. Los paquetes fuente de Debian para cada binario de la imagen se publican junto a ella como nexus-alpha-installer-1.0.0-alpha.1-debian-source.tar, en la misma lista de sumas de comprobación.

Comprobar la descarga antes de grabarla

El directorio de imágenes en downloads.adverant.ai contiene las imágenes, un archivo SHA256SUMS que abarca todos los archivos publicados y SHA256SUMS.sigstore.json, la firma sobre esa lista realizada con la clave de versión de Adverant. Obtenga la clave pública de la versión por separado, guárdela como release.pub y compruebe su huella digital tal como se describe en el capítulo 2.4, Obtención y verificación de una versión.

  1. Verifique la firma de la lista de sumas de comprobación. No existe un registro de transparencia para las versiones de Nexus, por lo que es obligatorio utilizar la opción que omite la búsqueda en el registro.
cosign verify-blob --key release.pub --insecure-ignore-tlog=true \
  --bundle SHA256SUMS.sigstore.json SHA256SUMS
Verified OK
  1. Compruebe la imagen descargada con la lista:
grep nexus-alpha-community-1.0.0-alpha.1-amd64.iso SHA256SUMS | sha256sum -c -
nexus-alpha-community-1.0.0-alpha.1-amd64.iso: OK

En un Mac, utilice shasum -a 256 -c - en lugar de sha256sum -c -.

  1. Grabe la imagen en una memoria USB con la herramienta que utilice habitualmente, o conéctela a la máquina virtual como un disco óptico.

k3s publica sumas de comprobación para sus archivos de versión pero no una firma, por lo que los archivos de k3s dentro de la imagen se comprueban con las sumas de comprobación que publica k3s, desde el mismo origen que los archivos. Todo lo compilado por Adverant está firmado.

Paquetes divididos en partes

Un paquete que se transporta en una memoria separada ocupa varios gigabytes. Algunos sistemas de archivos, entre ellos FAT (File Allocation Table), no admiten archivos de 4 GiB o más, por lo que los archivos del paquete se publican en partes de 2047 MiB que caben en cualquier memoria. Una las partes en orden y compruebe el archivo resultante con su .sha256 antes de utilizarlo.

El hardware que necesita

El primer arranque comprueba la máquina antes de modificar nada y se niega a continuar si la máquina es demasiado pequeña.

Comprobación La base común Cuándo se comprueba
Arquitectura La propia de la imagen: una imagen amd64 en amd64, arm64 en arm64 Primer arranque
Memoria 16 GiB Primer arranque
Disco de destino Exactamente un disco vacío de al menos 64 GB, o el disco indicado en la semilla Antes de escribir el sistema operativo
Espacio libre en / 50 GB una vez instalado el sistema operativo Primer arranque
Reloj No anterior a la fecha en que se compiló la imagen Primer arranque

Esos valores son límites mínimos, no una recomendación. Con los valores predeterminados del chart, solo los volúmenes de Nexus suman 142 GiB, por lo que un disco de 64 GB supera la comprobación del instalador pero se llena en cuestión de días. Utilice lo que debe tener un nodo único: 8 vCPU (unidades centrales de procesamiento virtuales), 32 GiB de memoria y un SSD (unidad de estado sólido) de 250 GB. Para una evaluación bastan cuatro vCPU, 16 GiB y 200 GB.

La comprobación del reloj existe porque el servidor no tiene red y, por tanto, carece de servicio de hora durante la instalación. Los certificados y las firmas se verifican con respecto al reloj. Si el reloj de hardware de la máquina está atrasado respecto a la fecha de compilación de la imagen, el primer arranque se detiene y le pide que lo ajuste. Ajústelo en la configuración del firmware y vuelva a arrancar.

Servidores físicos y máquinas virtuales

La imagen arranca en firmware UEFI (Unified Extensible Firmware Interface), tanto en servidores físicos como en máquinas virtuales. Instala el gestor de arranque en la ruta de medios extraíbles además de en la ruta habitual, de modo que una VM (máquina virtual) sin entradas de arranque guardadas pueda encontrarlo tras el primer reinicio. Asigne a la VM la memoria y el disco indicados en la tabla anterior, un disco virtual vacío y la imagen como un CD.

El instalador elige el disco de destino siguiendo una regla estricta y nunca selecciona «el primer disco».

  • Omite el medio desde el que ha arrancado.
  • Omite los discos extraíbles, a menos que la semilla indique uno.
  • Omite cualquier disco que ya tenga una tabla de particiones, de cualquier tipo.
  • Omite los discos de menos de 64 GB y lo indica en la consola.
  • Solo realiza la instalación cuando queda exactamente un disco.

En un servidor con dos discos vacíos, se detiene y le pide que elija. La elección se realiza indicando el disco en la semilla, con wipe: true, que es la única manera en que escribirá en un disco que ya tenga particiones.

El volumen NEXUS-SEED

La semilla es un volumen pequeño, normalmente una memoria USB, con un sistema de archivos etiquetado como NEXUS-SEED y un archivo seed.yaml en su directorio raíz. El instalador lo monta en modo de solo lectura, lee la configuración y vuelve a montarlo con permisos de escritura únicamente al final, para dejarle la contraseña del sistema operativo.

# seed.yaml on the NEXUS-SEED volume
domain: harrow.example
adminEmail: aoife.brennan@harrow.example
edition: enterprise
timeout: 45m
Clave Qué configura Si se omite
domain El dominio de la instalación. El instalador deriva de él los tres hosts: console.<domain>, api.<domain> y auth.<domain>. Se solicita en la consola del servidor
adminEmail El correo electrónico de la persona que será el primer administrador Se solicita en la consola del servidor
edition community o enterprise. Si se define, debe coincidir con la edición del paquete. Se toma del paquete
timeout Cuánto tiempo pueden tardar cert-manager y la instalación de Nexus, expresado como una duración tal como 30m o 1h 30m
time La hora actual en UTC, en el formato que muestra el mensaje del reloj (2026-11-14T09:00:00Z), para una máquina cuyo reloj de hardware no se pueda ajustar o no conserve su configuración. Una máquina sin conexión no tiene ningún servidor de hora al que consultar. Se utiliza el reloj de hardware
disk El disco de destino, como /dev/<name>, utilizado únicamente junto con wipe: true La regla de disco vacío anterior
wipe true permite al instalador borrar el disco indicado por disk No se borra ningún disco en ningún caso

Para Enterprise, coloque el archivo de licencia en el mismo volumen como licence.json. Sin él, el primer arranque se detiene en el paso de la semilla e indica que falta la licencia. Community no necesita licencia y, para Community, toda la semilla es opcional: el instalador solicita el dominio y el correo electrónico en la consola y continúa.

El instalador lee cada línea como key: value al principio de la línea. Escriba una clave por línea, en el nivel superior, sin comillas y sin sangría. Un valor entre comillas se lee con sus comillas incluidas.

En el primer arranque, el instalador también solicita en la consola el custodio del almacén de claves: la mitad pública de una clave age, age1..., generada en la propia máquina del custodio con age-keygen -o custodian.key. El almacén de claves sella sus claves de recuperación con ella. El capítulo 2.8, Instalaciones en una sola máquina, explica la figura de los custodios. El custodio guarda la mitad privada sin conexión y en un lugar seguro: sin ella, nadie puede abrir el almacén de claves tras un reinicio.

Qué ocurre, desde el encendido hasta la dirección de la consola

Etapa uno: el sistema operativo

La imagen arranca en un instalador de Debian desatendido. No configura ninguna red, no utiliza ningún servidor de réplica ni instala ningún paquete más allá del sistema base. Establece la zona horaria en UTC (Tiempo Universal Coordinado), deshabilita el inicio de sesión de root y crea un único usuario, nexus, cuya contraseña está bloqueada. Elige el disco de destino según la regla anterior y escribe un disco GPT (tabla de particiones de identificador único global) con una partición del sistema EFI (Extensible Firmware Interface) y un sistema de archivos raíz ext4, sin área de intercambio (swap).

Al final, copia el instalador de Nexus en el nuevo sistema, comprueba cada archivo copiado con la lista de sumas de comprobación de la imagen y habilita un servicio de primer arranque. Si algún archivo copiado no coincide, se detiene ahí mismo. A continuación, expulsa el medio y reinicia.

Etapa dos: el primer arranque

En el primer arranque, el servicio nexus-install se ejecuta una vez. Cada paso se muestra en la consola del servidor y en el registro del sistema (journal), y queda registrado como completado, de modo que un reintento comienza desde el primer paso pendiente. El servicio en su conjunto puede ejecutarse durante un máximo de cuatro horas antes de que systemd lo detenga, lo que deja margen para un disco lento y hasta una hora de espera para conectar la memoria con el paquete.

  1. Comprobaciones previas (Preflight). La arquitectura, el reloj, la memoria y el espacio libre en disco, según la tabla anterior.
  2. Carga útil (Payload). Los propios archivos del instalador: la firma de su lista de sumas de comprobación con la clave de versión que incluye y, a continuación, cada archivo con respecto a esa lista.
  3. Semilla (Seed). Lee seed.yaml y solicita en la consola cualquier dato que falte.
  4. Paquete (Bundle). Busca el volumen etiquetado como NEXUS-BUNDLE y lo monta en modo de solo lectura. Si no lo encuentra, muestra waiting-for-bundle y espera hasta una hora a que usted lo conecte. A continuación, ejecuta la comprobación completa del paquete, que termina en VERIFY-BUNDLE PASS, con la clave de versión que incluye, antes de importar nada. Un paquete Enterprise requiere licence.json en la semilla, y la edición de la semilla debe coincidir con la del paquete.
  5. k3s. Instala k3s v1.33.6+k3s1 a partir de los propios archivos de la imagen con las descargas desactivadas, y espera hasta diez minutos a que el nodo pase al estado Ready. Después, elimina el archivo comprimido de imágenes para entornos aislados de k3s, con el fin de que las imágenes no vuelvan a importarse en cada inicio.
  6. Importación (Import). Importa todas las imágenes verificadas del paquete, así como las imágenes de cert-manager, en el almacén de contenedores del nodo. En ningún momento se descarga nada de un registro.
  7. cert-manager y, después, Nexus. Instala cert-manager v1.21.3 y, a continuación, el chart de Nexus desde el paquete, ambos dentro del tiempo timeout definido en la semilla.
  8. Aceptación (Acceptance). Comprueba que todos los pods estén en estado Running y que todos los Jobs de tipo hook se hayan completado.
  9. Credencial (Credential). Asigna al usuario del sistema operativo nexus una nueva contraseña aleatoria, la muestra una sola vez en la consola y la escribe en nexus-os-password.txt, en el volumen de la semilla, si dicho volumen permite la escritura.

La comprobación del paquete en el paso 4 es el mismo script que se ejecuta manualmente en el capítulo 2.10, Instalación aislada de la red, y muestra las mismas líneas:

  1 SHA256SUMS OK files=<n>
  2 SHA256SUMS signature OK
  3 images signed + SBOM-attested: <n>
  4 helm lint --strict OK nexus-1.0.0-alpha.1.tgz
  5 coverage OK rendered=<n> lock=<n>
  6 source offer OK images=5 files=<n>
VERIFY-BUNDLE PASS files=<n> images=<n>

La línea 3 contabiliza las imágenes que llevan una firma válida y un SBOM (lista de materiales de software) firmado, es decir, la lista de lo que contiene cada imagen. Los recuentos (<n>) dependen de la edición. Lo importante es la última línea.

La instalación escribe los valores con el formato actual del chart: global.domain y los tres nombres hosts.* obtenidos del dominio de la semilla, y keys.custody.recipients a partir del custodio que usted indicó en la consola. Instala a partir del propio chart y de las propias imágenes del paquete, por lo que la versión instalada en el disco es exactamente la versión que se ha verificado.

Una cadena horizontal de nueve recuadros: Preflight, Payload, Seed, Bundle, k3s, Import, cert-manager y Nexus, Acceptance, Credential. Debajo de cada recuadro, una breve etiqueta roja muestra qué lo detiene: «memoria, disco, reloj, arquitectura», «firma o suma de comprobación», «sin dominio ni correo electrónico; sin licencia para Enterprise», «sin NEXUS-BUNDLE en 1 h; VERIFY-BUNDLE FAIL», «el nodo no pasa a Ready en 10 min», «una imagen no se puede importar», «helm install falla dentro del tiempo de espera», «un pod no está en ejecución, un Job no se ha completado», y nada debajo de Credential. Una flecha de retorno desde cada recuadro hasta el inicio de la cadena lleva la etiqueta «nexus-install retry reanuda en el primer paso no completado».
El primer arranque de la imagen del instalador, paso a paso, donde cada uno puede detener la instalación.

Las últimas líneas en la consola

Cuando todos los pasos se han completado correctamente, la consola muestra una sola vez la contraseña del sistema operativo y la dirección que se debe abrir:

nexus-install: OS login: user nexus, password <shown-once>  (shown once; change it with passwd)
nexus-install: DONE: https://console.harrow.example  (add to /etc/hosts: 10.20.4.15 console.harrow.example api.harrow.example auth.harrow.example)

Anote la contraseña o tómela de la memoria de la semilla; a continuación, inicie sesión como nexus y cámbiela con passwd. Nadie, incluido Adverant, conoce una contraseña predeterminada para esta máquina, porque no existe.

La dirección que aparece en la línea de hosts es la del propio servidor. Al no haber DNS (Domain Name System) en el muelle, Tomás añadió esa única línea al archivo hosts de cada portátil que fuera a utilizar la consola. En un sitio que disponga de DNS, añada en su lugar los registros correspondientes a los tres nombres.

Listo, o todavía no
Listo, o todavía no
Tras la instalación, la lista de preparación incluye una prueba de tráfico saliente, para que un operador pueda demostrar que nada ha intentado salir durante la última hora.

Después de la instalación

La instalación está sin reclamar. Nadie puede iniciar sesión hasta que alguien la reclame desde un navegador, comparando la huella digital de la instalación con la que muestra el servidor. El capítulo 2.12, La primera ejecución, explica el proceso de reclamación, el primer administrador y la clave de acceso (passkey). El primer administrador debe ser la persona cuyo correo electrónico figura en la semilla.

El archivo kubeconfig propio del nodo se encuentra en /etc/rancher/k3s/k3s.yaml y solo root tiene permisos de lectura sobre él. Para trabajar en el clúster desde una estación de trabajo, nexusctl kubeconfig lo imprime en pantalla, tal como se describe en el capítulo 2.8, Instalaciones en una sola máquina.

Las actualizaciones llegan del mismo modo que la instalación: una versión en un medio firmado, verificada con la clave que ya está instalada en el servidor y nunca con una clave que traiga consigo el propio disco. El capítulo 2.10, Instalación aislada de la red, describe esa comprobación.

Reclamar esta instalación
Reclamar esta instalación
La página de reclamación posterior a la instalación. La huella digital se muestra en ocho grupos de cuatro caracteres, para poder compararla línea por línea con la consola del servidor.

Si esto falla

Cada fallo muestra nexus-install: FAILED <step>: <what is missing> en la consola y escribe lo mismo en /var/lib/nexus/install.state. Corrija la causa y vuelva a ejecutar la instalación desde el primer paso que no se haya completado:

sudo nexus-install retry
Mensaje Qué significa Qué hacer
FAILED preflight: payload is for arm64, this machine is amd64 Ha arrancado la imagen correspondiente a la otra arquitectura. Utilice la imagen correspondiente a la arquitectura de esta máquina.
FAILED preflight: memory 11 GiB, need >= 16 GiB La máquina tiene menos memoria que el mínimo exigido. Añada memoria o asigne más a la VM.
FAILED preflight: free disk 38 GB on /, need >= 50 GB El sistema de archivos raíz es demasiado pequeño. Instale en un disco más grande.
FAILED preflight: the clock (...) is older than the build (...); set the RTC or give time: in the seed El reloj de hardware está atrasado respecto a la fecha en que se compiló el instalador. Ajuste el reloj en el firmware, o indique time en seed.yaml, y vuelva a intentarlo.
FAILED payload: SHA256SUMS signature does not verify Los propios archivos del instalador no coinciden con lo que firmó Adverant. Deténgase. Descargue de nuevo la imagen y compruébela antes de grabarla.
FAILED seed: the installation domain and the first administrator e-mail are required No se proporcionaron ni en la semilla ni en la consola. Añádalos a seed.yaml o responda a las solicitudes en pantalla.
FAILED seed: Enterprise bundle: licence file missing on NEXUS-SEED (licence.json) El paquete es Enterprise y la semilla no tiene licencia. Coloque licence.json en el volumen de la semilla.
FAILED bundle: no volume labelled NEXUS-BUNDLE within 1 h No se conectó ningún paquete a tiempo. Conecte la memoria con el paquete y vuelva a intentarlo.
FAILED bundle: the bundle does not verify with this installer's release key La comprobación del paquete no terminó en VERIFY-BUNDLE PASS. Su propia salida, encima del mensaje, indica el paso correspondiente. Deténgase. No utilice ese paquete. Obtenga uno nuevo.
FAILED bundle: the seed asks for enterprise, the bundle is community La semilla y el paquete no coinciden. Corrija edition en la semilla o utilice el paquete correcto.
FAILED k3s: node not Ready within 10 min k3s no llegó a iniciarse. Compruebe el registro del sistema (journal) para k3s y vuelva a intentarlo.
FAILED nexus: helm install nexus El chart no se instaló dentro del tiempo de espera. Consulte kubectl -n nexus get pods,jobs, aumente timeout en la semilla si la máquina es lenta y vuelva a intentarlo.
FAILED acceptance: pods not ready Algunos pods no están en ejecución tras la instalación. El mensaje enumera hasta cinco. Lea sus eventos, solucione el problema y vuelva a intentarlo.
FAILED acceptance: jobs not complete: <jobs> Un Job de tipo hook no ha finalizado. Lea el registro del Job indicado con kubectl -n nexus logs job/<name>, solucione lo que informe y vuelva a intentarlo.

Antes de que se escriba el sistema operativo, la selección del disco también puede detener la instalación. Su mensaje comienza por nexus select-disk: REFUSED:. El caso más común es found 2 empty disks of >= 64 GB; need exactly one, or a NEXUS-SEED seed.yaml naming the disk with wipe: true. Indique el disco en la semilla y vuelva a arrancar.

Un fallo en la comprobación del paquete es el caso que debe tomarse muy en serio. Significa que los archivos del disco no son los archivos que firmó Adverant, o bien que se ha añadido algún archivo. En ese punto el instalador aún no ha importado nada, por lo que el servidor permanece intacto. Conserve el disco para su equipo de seguridad.