ansible-koji/README.rst

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-hub.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

Despliegue Híbrido (Local + GCP con WireGuard)

System Message: WARNING/2 (<stdin>, line 203)

Title underline too short.

Despliegue Híbrido (Local + GCP con WireGuard)
---------------------------------------------

Para acelerar las compilaciones de paquetes pesados, este proyecto permite usar una arquitectura híbrida: el plano de control central (Koji Hub, Base de Datos, Servidor NFS, Dist-Git y Repositorio Caddy) se ejecuta localmente usando VMs de Libvirt/KVM, mientras que se despliegan adicionalmente 2 constructores Spot de alto rendimiento en GCP (tipo n2-highcpu-16 con discos SSD NVMe de 150 GiB).

Toda la comunicación entre los constructores en GCP y la red local (Libvirt 192.168.122.0/24) se realiza de forma segura a través de un túnel VPN WireGuard bidireccional y auto-enrutado.

Pasos para el despliegue híbrido:

1. Aprovisionar la infraestructura local (Libvirt/KVM): Inicia y despliega el plano de control local de manera normal:

   make init
   make deploy
   make bootstrap

2. Aprovisionar los constructores Spot en la nube (GCP): Esto creará la red VPC y las instancias de constructores en GCP, además de generar el inventario híbrido dinámicamente en inventories/gcp/hosts.yaml:

   make env=gcp tofu-init
   make env=gcp tofu-apply

3. Configurar y levantar el túnel WireGuard: Ejecuta el playbook dedicado que instala WireGuard en los constructores en GCP, genera sus llaves criptográficas y configura el túnel local en tu máquina Fedora utilizando NetworkManager (como tu usuario normal):

   ansible-playbook -i inventories/gcp/hosts.yaml --vault-pass-file=.pass wireguard.yaml

   Nota: Este paso añade automáticamente la interfaz cs10-wg a la zona trusted de firewalld en tu máquina local para permitir el reenvío de paquetes (IP forwarding) hacia y desde la red de VMs locales (192.168.122.0/24).

4. Desplegar la configuración híbrida total: Aplica los roles y las configuraciones de Koji a todo el cluster híbrido (nodos locales + constructores de GCP conectados a través del túnel VPN):

   make env=gcp deploy

5. Compilar los paquetes de la distribución: Puedes ejecutar los playbooks de importación y compilación topológica usando los recursos combinados del cluster:

   # Generación 1 (mxos0)
   make env=gcp bootstrap-mxos0
   
   # Generación 2 (mxos10)
   make env=gcp bootstrap-mxos10

Limpieza de Recursos en la Nube:

Para detener y destruir los constructores Spot de GCP para evitar costos, ejecuta:

make env=gcp tofu-destroy

Acceso al Entorno:

Puedes acceder a la interfaz de administración web en: https://cs10-koji-hub.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-hub.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-hub.mx-os
sudo -u kojiadmin koji moshimoshi

Gestión de Fuentes (Lookaside Cache)

El servidor Dist-Git (cs10-koji-distgit.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 bootstrap-mxos0:

Ejecuta el playbook para importar repositorios y compilar los paquetes de la Generación 1 (mxos0).

make bootstrap-mxos10:

Ejecuta el playbook para importar repositorios y compilar los paquetes de la Generación 2 (mxos10).

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/