Guía sobre el operador de GitLab Runners en OpenShift

Los canales de integración e implementación continuas (CI/CD) se convirtieron en una parte fundamental del desarrollo de software moderno, ya que permiten a los desarrolladores diseñar, probar e implementar cambios en el código de manera rápida y eficiente. Al automatizar el proceso de diseño e implementación de las aplicaciones, los canales de CI/CD permiten que los equipos mejoren la calidad del código, reduzcan los errores y aceleren el tiempo de comercialización de las funciones y las aplicaciones nuevas.

GitLab Runners son las aplicaciones que procesan tareas de CI/CD en GitLab.com y las instancias GitLab autoalojadas. GitLab.com proporciona sus propios ejecutores alojados, que se comparten entre los usuarios del sitio, pero a través de diferentes tipos de instalación también puedes configurar ejecutores privados exclusivos para tus proyectos. Para las empresas o las personas que desean gestionar su propia infraestructura de canales en la nube, el operador de GitLab Runner, disponible como Red Hat Certified Operator en OpenShift, ofrece una instalación directa en la nube que es rápida y sencilla.

A fin de demostrar la simplicidad y la funcionalidad del operador de GitLab Runner, pensé que sería divertido destacar también algunos desarrollos interesantes en Fedora Linux y usar el operador de GitLab Runner para compilar imágenes base personalizadas para Fedora Silverblue.

Fedora Silverblue es una distribución inmutable y de última generación de Fedora Linux. Recientemente, su sistema híbrido de gestión de imágenes y paquetes  rpm-ostree adquirió la capacidad de iniciarse desde los contenedores OCI. Esto permite que los usuarios o las empresas compilen sus propias imágenes base personalizadas con el flujo de trabajo conocido de Dockerfiles y Containerfiles.

En el siguiente tutorial, usaremos el operador de GitLab Runner para configurar un sistema de compilación completamente automatizado para nuestras imágenes de Fedora Silverblue.

Requisitos previos

Necesitarás algunos recursos configurados e instalados previamente que no abordaremos en el tutorial:

• Un clúster de OpenShift
• Una instalación de Fedora Silverblue (si realmente deseas usar las imágenes personalizadas)
• Una cuenta de GitLab.com

Instalación y configuración del operador de GitLab Runner

Abre el encabezado "Operators" en la barra lateral del clúster de OpenShift y haz clic en OperatorHub. Busca el operador de GitLab Runner y haz clic en la opción "Certified" (también está disponible la versión del operador desarrollada por la comunidad, pero este tutorial se ceñirá a la variante con la certificación de OpenShift). Antes de hacer clic en Install, observa la sección "Prerequisites" de la descripción del operador. El operador de GitLab Runner requiere que primero instales cert-manager:

oc apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.7.1/cert-manager.yaml

Después de hacerlo, haz clic en Install para instalar el operador de GitLab Runner.

En la pantalla siguiente, se solicitará que cambies cualquiera de las opciones de instalación predeterminadas. Si necesitas o deseas utilizar un espacio de nombres específico, hazlo en esta etapa; de lo contrario, continúa con las opciones predeterminadas. También sugiero dejar establecido Update approval en Automatic porque esa es una de las principales ventajas de usar un operador.

Espera un momento hasta que finalice la instalación. Luego, dirígete a Installed Operators y, a continuación, al operador de GitLab Runner. Aquí verás el mismo texto informativo anterior, así como un enlace en Provided APIs donde puedes crear una instancia de Runner. En el siguiente texto informativo, encontrarás instrucciones para vincular tus Runners a tus repositorios de GitLab, las cuales seguiremos ahora.

Creación y registro de la instancia de Runner

1. Creación del secreto de token de registro

Primero, debemos crear un secreto con un token de registro de GitLab, que el nuevo Runner usará para registrarse en nuestro repositorio. Abre GitLab.com o tu instancia privada de GitLab y, luego, el repositorio que deseas registrar. Dirígete a "Settings" y, después, a "CI/CD". Expande la sección titulada Runners y busca la sección Project runners. Aquí es donde encontraremos el token de registro y la URL que usarás para registrar tu instancia de Runner.

Observa también la sección Shared runners si usas GitLab.com, que contiene los ejecutores públicos proporcionados por GitLab.com. Para este proyecto, deshabilita los ejecutores compartidos, ya que usaremos nuestros propios ejecutores privados.

Crea tu secreto e inserta el token de registro del repositorio en el campo runner-registration-token.  Puedes hacerlo en la consola web o a través de la interfaz del terminal. Creé un archivo denominado gitlab-runner-secret.yml y lo agregué al clúster:

apiVersion: v1
kind: Secret
metadata:
  name: gitlab-runner-secret
type: Opaque
stringData:
  runner-registration-token: YOUR_TOKEN_HERE

oc apply -f gitlab-runner-secret.yml

2. Configuración del ejecutor con un ConfigMap

Antes de crear el ejecutor, también debemos crear un ConfigMap con algunas opciones de personalización. Por lo general, puedes usar un archivo config.toml para configurar los GitLab Runners. En un contexto de Kubernetes, podemos agregar esas personalizaciones con un ConfigMap que contenga nuestro archivo config.toml .

Dado que estamos ejecutando los contenedores de compilación en el entorno de un clúster de OpenShift, debemos asegurarnos de que los contenedores de compilación se ejecuten sin mayores privilegios y como usuarios comunes., (nota: hay formas de evitar esto si realmente sabes que necesitas un entorno de compilación con privilegios, pero seguiremos el tutorial con una configuración común). Aquí hay un archivo config.toml sencillo que especifica que el pod del ejecutor se ejecutará como usuario común 1000:

[[runners]]
  name = "gitlab-runner"
  url = "https://gitlab.com"
  executor = "kubernetes"
  [runners.kubernetes]
    [runners.kubernetes.pod_security_context]
      run_as_non_root = true
      run_as_user = 1000

Usa el comando a continuación para agregar esto al clúster como ConfigMap:

oc create configmap my-runner-config --from-file=config.toml

3. Inicio de la instancia de Runner

Ahora podemos crear nuestra instancia de Runner. De nuevo, puedes hacer esto con la consola web haciendo clic en Create instance en la página del operador de GitLab Runner, o a través del terminal. En cualquiera de los dos casos, debemos asegurarnos de que nuestra definición de recursos personalizados (CRD) incluya la URL de GitLab correcta, el nombre del secreto de token de registro y el nombre del ConfigMap y, además, que contenga "openshift" en las etiquetas para que los trabajos se pasen al clúster. A continuación, hay una CRD básica denominada gitlab-runner.yml que cumple con todos nuestros criterios:

apiVersion: apps.gitlab.com/v1beta2
kind: Runner
metadata:
 name: gitlab-runner
spec:
 gitlabUrl: https://gitlab.com
 token: gitlab-runner-secret
 tags: openshift
 config: my-runner-config

Utiliza el comando a continuación para la instalación en el clúster:

oc apply -f gitlab-runner.yml

Ahora puedes verificar el estado de tu nuevo ejecutor en la consola web o a través del terminal con oc get runners. También debemos verificar la configuración de CI/CD del proyecto GitLab para asegurarnos de que el ejecutor se vinculó correctamente al repositorio. Ahora bajo el encabezado Assigned project runners deberías ver un ejecutor con el mismo nombre que la CRD que creamos e instalamos.

Uso de nuestro Runner para compilar imágenes de Silverblue

1. Definición de las tareas de los canales de CI/CD de GitLab

Ahora que el ejecutor está instalado, configurado y vinculado al proyecto, podemos escribir el archivo GitLab CI que definirá nuestra compilación de imagen. GitLab proporciona muchos ejemplos de la estructura de archivos gitlab-ci.yml para diferentes tipos de proyectos. Escribiremos los nuestros con buildah para compilar nuestras imágenes de Silverblue.

El gitlab-ci.yml que usaremos tiene el siguiente aspecto:

stages:
  - build

buildah-build:
  stage: build
  tags:
    - openshift
  image: quay.io/buildah/stable
  variables:
    STORAGE_DRIVER: vfs
  script:
    - export HOME=/tmp
    - buildah login --username "$CI_REGISTRY_USER" --password "$CI_REGISTRY_PASSWORD" "$CI_REGISTRY"
    - buildah build -t "$CI_REGISTRY_IMAGE:latest" .
    - buildah push "$CI_REGISTRY_IMAGE:latest"
    - buildah logout "$CI_REGISTRY"

En este archivo hay varios elementos importantes.

• Como se mencionó anteriormente, necesitamos incluir al menos la etiqueta openshift para que el operador de GitLab Runner seleccione nuestras tareas.
• Usamos la imagen estable oficial de Buildah alojada en Quay.io como imagen de compilación.
• Establecemos el controlador de almacenamiento en vfs debido a los problemas con los sistemas de archivos superpuestos. El uso de vfs es la solución más sencilla por ahora.
• Cambiamos $HOME a /tmp para asegurarnos de poder escribir, ya que la mayoría de los sistemas de archivos de contenedores en OpenShift serán de solo lectura.

La última sección, script, incluye una lista de los comandos que ejecutará la tarea de compilación. Aquí utilizamos variables predefinidas de integración continua (CI) de GitLab para iniciar sesión en el registro de contenedores de GitLab, compilar y etiquetar la imagen y, finalmente, enviarla al registro antes de cerrar sesión.

2. Escritura del Containerfile para nuestra imagen personalizada de Silverblue

Después de agregar el archivo gitlab-ci.yml al repositorio, también debemos agregar el Containerfile que queremos compilar. Para la imagen personalizada de Fedora Silverblue, me basé en el excelente trabajo que se realiza en la comunidad  Universal Blue . Sus miembros han trabajado en diversas versiones de Silverblue para diferentes casos prácticos. Son un gran recurso si tú o tu equipo están interesados en crear imágenes base personalizadas e inmutables para sistemas Fedora Silverblue.

Pensé que sería útil crear una imagen base que incluya las versiones más recientes de todas las herramientas de OpenShift y el operador que uso a diario. Dado que configuraremos el sistema para que efectúe compilaciones a diario, mi imagen base se actualizará con los paquetes de Fedora más recientes y siempre tendré las últimas versiones de estas herramientas de OpenShift y el operador, las cuales normalmente requerirían actualizaciones manuales.

ARG FEDORA_MAJOR_VERSION=38

FROM quay.io/fedora-ostree-desktops/silverblue:${FEDORA_MAJOR_VERSION}
# Starting with Fedora 39, the new official location for these images is quay.io/fedora/fedora-silverblue
# See https://pagure.io/releng/issue/11047 for more information

# Install Openshift tools -- oc, opm, kubectl, operator-sdk, odo, helm, crc from official OpenShift sources
RUN curl -SL https://mirror.openshift.com/pub/openshift-v4/x86_64/clients/ocp/latest/opm-linux.tar.gz | tar xvzf - -C /usr/bin
RUN curl -SL https://mirror.openshift.com/pub/openshift-v4/x86_64/clients/operator-sdk/latest/operator-sdk-linux-x86_64.tar.gz | tar xvzf - --strip-components 2 -C /usr/bin
RUN curl -SL https://mirror.openshift.com/pub/openshift-v4/clients/oc/latest/linux/oc.tar.gz | tar xvzf - -C /usr/bin
RUN curl -SL https://mirror.openshift.com/pub/openshift-v4/x86_64/clients/helm/latest/helm-linux-amd64 -o /usr/bin/helm && chmod +x /usr/bin/helm
RUN curl -SL https://mirror.openshift.com/pub/openshift-v4/x86_64/clients/odo/latest/odo-linux-amd64 -o /usr/bin/odo && chmod +x /usr/bin/odo
RUN curl -SL https://mirror.openshift.com/pub/openshift-v4/x86_64/clients/crc/latest/crc-linux-amd64.tar.xz | tar xfJ - --strip-components 1 -C /usr/bin

# Install awscli
RUN curl -SL https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip -o awscliv2.zip && unzip awscliv2.zip && ./aws/install --bin-dir /usr/bin --install-dir /usr/bin

# Install overrides and additions, remove lingering files
RUN rpm-ostree install podman-docker
RUN rm -rf aws && \
    rm -f awscliv2.zip && \
    rm -f /usr/bin/README.md && \
    rm -f /usr/bin/LICENSE

Veamos un breve desglose de lo que sucede en este Containerfile:

• Para comenzar, especificamos la versión de Fedora que queremos compilar, en este caso, la versión estable actual 38.
• A continuación, especificamos la imagen base que se usará para nuestra compilación, que es silverblue:38, después de la sustitución FEDORA_MAJOR_VERSION (consulta los comentarios en el Containerfile sobre la ubicación de estas imágenes).
• En la sección más grande, ejecutamos varios comandos curl para descargar todos los programas de OpenShift que quiero instalar, asegurándome de colocar sus archivos binarios en el directorio /usr/bin .
• También instalamos awscli , lo que implica desempaquetar el archivo .zip y ejecutar el script de instalación.
• Por último, usamos rpm-ostree para instalar podman-docker desde los repositorios de paquetes de Fedora (esto esencialmente crea un alias de los comandos docker para podman para quienes estamos acostumbrados a ejecutar docker) y, luego, eliminamos algunos archivos persistentes de la extracción awscli .

Como mencioné anteriormente, si deseas obtener más información sobre la personalización de Silverblue, consulta la comunidad en Universal Blue. Para aprender este flujo de trabajo me basé en gran medida en el trabajo de sus miembros, quienes ya están trabajando en muchas aplicaciones nuevas e interesantes de la función OCI de arranque en Silverblue.

3. Uso y supervisión de las tareas de canales

Deberíamos agregar este archivo Containerfile, o cualquier Containerfile o Dockerfile que prefieras compilar, a la raíz del repositorio del proyecto, ya que gitlab-ci.yml especifica que buildah debe usar el directorio de trabajo actual como el argumento del archivo Containerfile. Según cómo hayas confirmado los cambios en el repositorio, es posible que ya hayas recibido notificaciones sobre errores en las tareas de canales, o si confirmas todo a la vez, verás que el primer intento de ejecutar la tarea de compilación comienza ahora. Para ver los registros de tu compilación, dirígete al encabezado CI/CD en la página del proyecto de GitLab.com y, luego, haz clic en Pipelines o Jobs  hasta que veas el resultado de registro para la tarea denominada buildah-build.

Si configuramos todo de manera correcta, deberías ver registros que describan cada paso de los archivos gitlab-ci.yml y Containerfile que escribimos, y que finalicen con "Job secceeded". Si la tarea se realiza correctamente, también deberíamos poder ver el contenedor terminado en el registro del proyecto. En la barra de navegación de la izquierda, haz clic en Packages and registries y, luego, en Container Registry. Deberías ver una única imagen con el nombre de tu proyecto con una sola etiqueta: "latest". Esta imagen se ubicará en registry.gitlab.com/{YOUR_USERNAME}/{YOUR_REPOSITORY_NAME}.

La tarea, tal como la escribimos, se ejecutará con cada confirmación a la rama main , pero puedes personalizar este comportamiento en el archivo gitlab-ci.yml . Si queremos programar compilaciones regulares, podemos hacerlo en la página del repositorio dentro de la configuración de CI/CD en la sección Schedule . Haz clic en New schedule para configurar el tiempo y la frecuencia del canal. Puedes obtener más información sobre la programación de canales de GitLab.com aquí. Para una imagen de Silverblue personalizada, probablemente desees efectuar compilaciones al menos diariamente para seguir el ritmo de compilación de las imágenes oficiales.

Uso de nuestras imágenes personalizadas

Para usar esta imagen como base de arranque para Silverblue, primero debes instalar Fedora Silverblue desde las imágenes oficiales si no tienes una instalación ya disponible. Una vez que finalice la instalación e inicies sesión, podremos reorganizar la instalación en nuestra imagen personalizada.

Ten en cuenta que el arranque desde las imágenes de OCI aún es una función experimental, así que sigue tu propio criterio si lo usas en máquinas personales o de producción. Sin embargo, Silverblue está diseñado para resistir fallas, por lo que si tu imagen personalizada no funciona según lo esperado, deberías poder volver a la imagen base original. Para asegurarnos de no eliminar esa base original, podemos ejecutar sudo ostree admin pin 0 para anclar la imagen actual. Esto garantiza que la referencia no se pierda en actualizaciones posteriores, ya que, por lo general, Silverblue solo conserva las referencias de imagen actuales y anteriores. Para reorganizar la imagen personalizada, ejecutamos:

rpm-ostree rebase ostree-unverified-registry:registry.gitlab.com/{YOUR_USERNAME}/{YOUR_REPOSITORY_NAME}:latest

y, luego, reiniciamos el sistema.

Después de hacerlo, podemos comprobar que estamos ejecutando nuestra imagen personalizada observando el resultado de rpm-ostree status. Tu implementación actual, identificada por el círculo/pip en el lado izquierdo, debe mostrar el identificador uniforme de recursos (URI) ostree-unverified-registry de la imagen personalizada. También puedes intentar ejecutar cualquiera de las herramientas de OpenShift que agregamos en un terminal, como oc, operator-sdk o helm.

Además, deberías ver nuestra implementación anclada con la referencia base anterior en el resultado de rpm-ostree status. Si deseas volver al estado anterior, simplemente ejecuta rpm-ostree rollback y reinicia el sistema. Para obtener más información sobre la administración de Fedora Silverblue, consulta la documentación.

Resultados

Suponiendo que todo se llevó a cabo sin problemas, ahora tenemos un canal de CI/CD autoalojado que se ejecuta en nuestro propio clúster de OpenShift y crea nuevas imágenes personalizadas de Silverblue periódicamente. Nuestros ejecutores no deberían requerir intervención manual, a menos que deseemos reconfigurar las etiquetas de trabajo de compilación o crear más ejecutores para manejar más trabajos simultáneos. Las compilaciones comenzarán en los intervalos programados y cuando confirmemos código nuevo a la rama main . Si ejecutamos la imagen personalizada en una instalación de Silverblue, simplemente necesitaremos ejecutar rpm-ostree update para obtener las actualizaciones diarias.

Este ejemplo de tutorial es una ilustración sencilla de las funciones del operador de GitLab Runner y el sistema de CI/CD de GitLab. Ambos pueden gestionar necesidades de CI/CD mucho más sofisticadas, y al ejecutar el operador certificado de GitLab Runner en OpenShift, puedes eliminar gran parte de las actividades manuales de configuración y mantenimiento de los propios ejecutores, para dedicar más tiempo y esfuerzo al contenido y a la configuración de las compilaciones.

Creé un repositorio de referencia con todos los archivos de texto que se utilizaron en este tutorial aquí. Consulta también una lista de referencias útiles a continuación.

• Documentación de GitLab Runners
• Documentación de Fedora Silverblue
• Operador de GitLab Runner certificado por Red Hat
• Universal Blue: imágenes de SO basadas en Fedora y creadas por la comunidad