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.

Ansible:

Para la configuración y el despliegue de Koji.

libvirt, libvirt-nss y qemu:

Para la virtualización de las máquinas y resolución DNS interna por nombre.

# instalar dependencias
dnf -y install @virtualization libvirt-nss

# activar servicio de libvirt
systemctl enable --now libvirtd.socket

# configurar resolucion de nombres nss
authselect enable-feature with-libvirt
authselect check
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:

usermod -aG libvirt,kvm,qemu renich

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:

Copia la imagen base de CentOS Stream 10 qcow2 en ~/VirtualMachines/cs10-system.qcow2. OpenTofu utilizará esta ruta definida en opentofu/variables.tf para clonar los discos de las VMs.

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/