Playbook de Ansible para MxOS Koji

Este playbook de Ansible automatiza el despliegue, configuración y ciclo de vida de un cluster de compilación Koji local (Staging/PoC) para la distribución MxOS, un fork de CentOS Stream 10 (y CentOS Stream 11 en el futuro).

El objetivo es mantener una compatibilidad estricta con la infraestructura oficial de CentOS Stream para facilitar la colaboración ascendente y el aprendizaje del ecosistema de empaquetado de Red Hat.

Entorno de Desarrollo

Para empezar a desarrollar, necesitas configurar un entorno de virtualización local. Este proyecto usa OpenTofu para aprovisionar 5 máquinas virtuales CentOS Stream 10 con Libvirt/KVM.

Requisitos

Este proyecto tiene las siguientes dependencias de software y entorno:

Software:

OpenTofu:

Para aprovisionar la infraestructura virtual.

# Agregar el repositorio oficial e instalar OpenTofu
curl --proto '=https' --tlsv1.2 -fsSL https://get.opentofu.org/tofu-repositories.noarch.rpm -o tofu-repositories.noarch.rpm
sudo dnf install -y ./tofu-repositories.noarch.rpm && rm -f tofu-repositories.noarch.rpm
sudo dnf install -y tofu

Ansible:

Para la configuración y el despliegue de Koji.

# Instalar Ansible Core
sudo dnf install -y ansible-core

Virtualización y Utilidades (libvirt, libvirt-nss, qemu y guestfs-tools):

Para la virtualización de las máquinas, resolución DNS interna por nombre y modificación de imágenes qcow2.

# Instalar dependencias de virtualización y utilidades
sudo dnf install -y @virtualization libvirt-nss guestfs-tools git

# Activar el servicio de libvirt
sudo systemctl enable --now libvirtd.socket

# Configurar resolución de nombres NSS para libvirt
sudo authselect enable-feature with-libvirt
sudo authselect check
sudo authselect apply-changes

Note

El módulo libvirt-nss permite acceder a las máquinas virtuales usando su nombre de host directo (FQDN) sin requerir IPs estáticas en el inventario. Por ejemplo: ssh root@cs10-koji-00.mx-os.

Colecciones de Ansible:

Instalar las colecciones requeridas definidas en el proyecto:

ansible-galaxy collection install -r requirements.yaml

Sistema Operativo:

Todo el desarrollo y las pruebas se han realizado sobre Fedora 43 x86_64 con SELinux en modo Enforcing.

Permisos de Usuario:

Tu usuario local debe pertenecer a los grupos de virtualización:

sudo usermod -aG libvirt,kvm,qemu \<tu_usuario\>

Configuración Inicial

Antes de desplegar el entorno, debes realizar los siguientes pasos de configuración:

Credenciales de Ansible Vault:

Crea el archivo cifrado vars/credentials.yaml con las credenciales del cluster.

ansible-vault encrypt vars/credentials.yaml

El archivo credentials.yaml debe contener las siguientes variables:

# Base de Datos
koji_db_user: koji
koji_db_password: "tu-contraseña-segura"
koji_db_name: koji
koji_db_network: "192.168.122.0/24"

# Clave Secreta Web
web_secret: "tu-clave-secreta-web"

# Passphrase GPG
gpg_key_passphrase: "tu-passphrase-de-llave-gpg"

# Correo Electrónico
kojid_smtp_pass: "tu-contraseña-smtp"

Note

El playbook utiliza un archivo de contraseña llamado .pass en la raíz del proyecto para descifrar automáticamente el Vault de Ansible. Asegúrate de crearlo y añadir la contraseña correspondiente.

Imagen Base de la VM

OpenTofu utiliza la imagen base de CentOS Stream 10 qcow2 en ~/VirtualMachines/cs10-system.qcow2 (definida en opentofu/variables.tf) para clonar los discos de las VMs.

Generación Automatizada:

Puedes generar la imagen de manera automática usando las herramientas de automatización incluidas en el proyecto. Desde la raíz del repositorio, ejecuta:

# Generar la imagen por defecto (CentOS Stream 10)
make -C opentofu/ base-image

# O especificar variables personalizadas (ej. versión 9, disco de 10 GiB)
make -C opentofu/ base-image version=9 size=10

Important

Dado que la herramienta de generación de imagen interactúa con el hipervisor del sistema (qemu:///system), el archivo de disco virtual resultante en ~/VirtualMachines/cs10-system.qcow2 se creará con propietario root:root.

Debes cambiar el propietario del archivo a tu usuario local ($USER:$USER) para que OpenTofu tenga permisos de lectura suficientes al ejecutar make init:

sudo chown $USER:$USER ~/VirtualMachines/cs10-system.qcow2

Detalles Técnicos y Requisitos (Manual):

Si decides configurar o crear la imagen de forma manual, asegúrate de cumplir con los siguientes requisitos estructurales y de empaquetado para asegurar la compatibilidad con el despliegue automático:

• Acomodo de Particiones (sin LVM): Debe usar una tabla de partición GPT (indispensable para arranque UEFI) y colocar la partición raíz (/) al final del disco (en el índice más alto, ej. vda4). Esto permite que el paquete growpart expanda dinámicamente el sistema de archivos en caliente en el primer arranque de la VM sin obstrucciones de otras particiones.

  Ejemplo de la estructura de particiones esperada:

  vda    253:0    0  100G  0 disk
  ├─vda1 253:1    0  512M  0 part /boot/efi (Partición UEFI ESP)
  ├─vda2 253:2    0    1G  0 part /boot
  ├─vda3 253:3    0    1G  0 part [SWAP]
  └─vda4 253:4    0  2.5G  0 part /         (Raíz al final del disco)

• Paquetes Necesarios: La imagen base requiere tener preinstalados los siguientes paquetes esenciales:

  • cloud-init: Gestiona la configuración inicial de red y la inyección automática de llaves SSH.

  • cloud-utils-growpart: Permite expandir en caliente la partición raíz durante el arranque.

  • Herramientas de sistema: bash-completion, rsync, tmux y vim.

• Consola Serial: Habilita la consola serial configurando los parámetros console=ttyS0,115200n8 console=tty0 en la línea de comando del kernel y actualiza GRUB usando grubby para poder acceder usando virsh console.

Actualización de la Imagen:

Para mantener actualizados los paquetes del sistema directamente en la imagen base sin reconstruirla por completo, puedes ejecutar:

virt-customize -a $HOME/VirtualMachines/cs10-system.qcow2 --smp=4 --memsize=8192 --update

Despliegue y Uso

1. Aprovisionar la Infraestructura (OpenTofu): Crea las 5 VMs CentOS Stream 10 (Hub, DB, NFS, Builder, Dist-Git) y expande sus volúmenes de almacenamiento.

   make init

2. Desplegar la Configuración (Ansible): Aplica los roles del playbook sobre los nodos virtuales aprovisionados.

   make deploy

3. Arrancar e Inicializar Koji: Crea los usuarios, certificados base, tags de compilación (mxos0), grupos y destinos necesarios en la base de datos de Koji.

   make bootstrap

Acceso al Entorno:

Puedes acceder a la interfaz de administración web en: https://cs10-koji-00.mx-os/koji

Note

Debes usar el FQDN exacto (con el sufijo .mx-os) para acceder a la URL y evitar errores de discrepancia de nombre de host (SSL hostname mismatch).

Autenticación SSL en Koji Web:

El inicio de sesión de Koji Web requiere autenticación estricta basada en certificados de cliente SSL. Para poder acceder, sigue estos pasos en tu PC de escritorio:

1. Instalar la confianza de la CA: Instala el certificado de la CA en el almacén de confianza del sistema de tu máquina local:

   sudo make install-ca

2. Importar el certificado de cliente: Importa el archivo PKCS#12 del usuario administrador en tu navegador web (Chrome, Firefox, etc.):

   • Archivo: certs/kojiadmin_browser_cert.p12

   • Contraseña de importación: Ninguna (déjala vacía y presiona Enter)

3. Acceder e Iniciar Sesión: Navega a https://cs10-koji-00.mx-os/koji/login. Tu navegador te solicitará seleccionar el certificado de cliente. Tras seleccionarlo, Koji Web autenticará tu sesión de forma segura redirigiéndote al index.

   Warning

   Si intentas ingresar a la URL de login sin haber importado previamente el certificado de cliente en tu navegador, el servidor web rechazará la conexión con un error de nivel SSL/TLS (ssl/tls alert handshake failure). Esto es completamente normal y forma parte de la política de seguridad del servidor.

Uso del Cliente (CLI):

Para administrar Koji, accede al nodo Hub y ejecuta comandos como kojiadmin:

ssh root@cs10-koji-00.mx-os
sudo -u kojiadmin koji moshimoshi

Gestión de Fuentes (Lookaside Cache)

El servidor Dist-Git (cs10-koji-04.mx-os) actúa únicamente como Lookaside Cache para tarballs pesados. Los metadatos y archivos de especificación (.spec) de los paquetes se mantienen en repositorios Git independientes bajo git.mx-os.mx/RPMs/.

Sincronización de Fuentes:

Para compilar paquetes, los tarballs deben existir en el lookaside cache.

Sincronizar un paquete individual:

./bin/sync-sources.bash bash c10s

Sincronizar todos los paquetes de MxOS: Obtiene los repositorios del servidor Git de MxOS y sincroniza sus fuentes automáticamente:

./bin/sync-all-sources.bash

Firma de paquetes

Para cumplir con los estándares de seguridad de CentOS Stream, las compilaciones exitosas se firman criptográficamente mediante Sigul.

Flujo de Firma en Staging

1. Koji Hub finaliza una compilación en estado COMPLETE y activa el plugin sigul_sign.py.

2. El plugin encola el ID de compilación en el spooler local en /var/spool/koji-sign/queue/.

3. El demonio independiente koji-sign-spooler.service detecta el archivo, espera a que finalice la transacción en base de datos, envía el RPM al servidor de firmas Sigul (simulado por Flask en staging) e importa la firma criptográfica de vuelta a Koji.

4. Nota: En la siguiente fase, el servidor Flask simulado se migrará a una instalación real del puente y servidor de Sigul.

Documentación del Proyecto

La documentación técnica detallada, especificaciones y justificaciones de diseño se encuentran en el directorio docs/.

Estructura de Documentos

• docs/technical/spec.rst: Especificaciones técnicas del cluster de MxOS Koji.

• docs/technical/roadmap.rst: Fases de igualación a CentOS Stream y mejoras de infraestructura futuras.

• docs/technical/decisiones/: Architecture Decision Records (ADRs) que justifican las decisiones clave de diseño del proyecto.

Desarrollo (Tareas de Makefile)

El GNUmakefile en la raíz del proyecto facilita las tareas de desarrollo comunes:

make init:

Destruye la infraestructura existente con OpenTofu y luego la recrea.

make deploy:

Ejecuta el playbook de despliegue principal.

make bootstrap:

Ejecuta el playbook de arranque para configurar los objetos de Koji.

make reset:

Ejecuta el playbook de reseteo.

make regenerate-certs:

Limpia el directorio certs/ y luego ejecuta las tareas de Ansible para regenerar todos los certificados.

Referencias

• https://docs.pagure.org/koji/server_howto/

• https://docs.pagure.org/koji/database_howto/

• https://docs.pagure.org/koji/server_bootstrap/

• https://docs.pagure.org/koji/using_the_koji_build_system/