Acerca de Actions Runner Controller

Aviso legal

Acerca de Actions Runner Controller

Actions Runner Controller (ARC) es un operador de Kubernetes que organiza y escala los ejecutores autohospedados para GitHub Actions. Para obtener más información, consulta Patrón de operador en la documentación de Kubernetes.

Con ARC, puedes crear conjuntos de escalado de ejecutor que se escalen automáticamente en función del número de flujos de trabajo que se ejecutan en el repositorio, la organización o la empresa. Dado que los ejecutores controlados pueden ser efímeros y estar basados en contenedores, las nuevas instancias de ejecutores se pueden escalar o reducir verticalmente de forma rápida y limpia. Para obtener más información sobre el escalado automático, consulta "Autoescalar con ejecutores auto-hospedados".

En el diagrama siguiente se muestra la arquitectura del modo de escalado automático de conjuntos de escalado de ejecutor de ARC.

1. El componente Actions Runner Controller se instala con los gráficos de Helm proporcionados y el pod del administrador del controlador se implementa en el espacio de nombres especificado. Un nuevo recurso AutoScalingRunnerSet se implementa a través de los gráficos de Helm proporcionados o de un archivo de manifiesto personalizado. El controlador AutoScalingRunnerSet llama a las API de GitHub para capturar el identificador de grupo del ejecutor al que pertenecerá el conjunto de escalado del ejecutor.
2. El controlador AutoScalingRunnerSet llama a las API una vez más para capturar o crear un conjunto de escalado del ejecutor en el servicio GitHub Actions antes de crear el recurso de cliente de escucha del conjunto de escalado del ejecutor.
3. El controlador AutoScalingListener implementa un pod de cliente de escucha del conjunto de escalado del ejecutor. En este pod, la aplicación de escucha se conecta al servicioGitHub Actions para autenticar y establecer una conexión HTTPS de sondeo largo. El cliente de escucha permanece inactivo hasta que recibe un mensaje Job Available del servicio GitHub Actions.
4. Cuando se desencadena una ejecución de flujo de trabajo desde un repositorio, el servicio GitHub Actions distribuye ejecuciones de trabajos individuales a los ejecutores o conjuntos de escalado de ejecutores donde la clave runs-on coincide con el nombre del conjunto de escalado del ejecutor o las etiquetas de los ejecutores autohospedados.
5. Cuando el cliente de escucha del conjunto de escalado del ejecutor recibe el mensaje Job Available, este comprueba si se puede escalar verticalmente al recuento deseado. Si es posible, el cliente de escucha del conjunto de escalado del ejecutor confirma el mensaje.
6. El cliente de escucha del conjunto de escalado del ejecutor usa una cuenta de servicio y un rol enlazados a esa cuenta a fin de realizar una llamada HTTPS a través de las API de Kubernetes para aplicar revisiones al recurso RunnerSet efímero con el número de réplicas deseadas.
7. El elemento RunnerSet efímero intenta crear ejecutores y el controlador EphemeralRunner solicita un token de configuración Just-In-Time (JIT) para registrar estos ejecutores. El controlador intenta crear pods del ejecutor. Si el estado del pod es failed, el controlador lo reintenta hasta cinco veces. Después de 24 horas, el servicio GitHub Actions anula la asignación del trabajo si no lo acepta ningún ejecutor.
8. Una vez creado el pod del ejecutor, la aplicación del ejecutor del pod usa el token de configuración JIT para registrarse automáticamente con el servicio GitHub Actions. Después, establece otra conexión HTTPS de sondeo largo para recibir los detalles del trabajo que debe ejecutar.
9. El servicio GitHub Actions reconoce el registro del ejecutor y distribuye los detalles de la ejecución del trabajo.
10. Durante la ejecución del trabajo, el ejecutor comunica continuamente los registros y el estado de ejecución del trabajo al servicio GitHub Actions.
11. Cuando el ejecutor completa su trabajo correctamente, el controlador EphemeralRunner comprueba con el servicio GitHub Actions si se puede eliminar el ejecutor. Si es posible, el RunnerSet efímero elimina el ejecutor.

Componentes de Actions Runner Controller

ARC consta de un conjunto de recursos, algunos de los cuales se crean de manera específica para ARC. Una implementación de ARC aplica estos recursos a un clúster de Kubernetes. Después de aplicarlos, crea un conjunto de pods que contienen los contenedores de los ejecutores autohospedados. Con ARC, GitHub puede tratar estos contenedores de ejecutores como ejecutores autohospedados y asignarles trabajos según sea necesario.

A cada recurso implementado por ARC se le asigna un nombre compuesto por:

• un nombre de instalación, que es el nombre de instalación que se especifica al instalar el gráfico de Helm;
• un sufijo de identificación de recursos, que es una cadena que identifica el tipo de recurso. Este valor no es configurable.

Recursos implementados por gha-runner-scale-set-controller

Recursos implementados por gha-runner-scale-set

Acerca de los recursos personalizados

ARC consta de varias definiciones de recursos personalizados (CRD). Para obtener más información sobre los recursos personalizados, consulta Recursos personalizados en la documentación de Kubernetes. Encontrarás la lista de definiciones de recursos personalizados que se usan para ARC en las siguientes definiciones de esquema de API.

• actions.github.com/v1alpha1
• actions.summerwind.net/v1alpha1

Dado que los recursos personalizados son extensiones de la API de Kubernetes, no estarán disponibles en una instalación predeterminada de Kubernetes. Tendrás que instalar estos recursos personalizados para usar ARC. Para obtener más información sobre la instalación de recursos personalizados, consulta "Inicio rápido para Actions Runner Controller".

Una vez que se han instalado los recursos personalizados, puedes implementar ARC en el clúster de Kubernetes. Para obtener información sobre la implementación de ARC, consulta "Implementación de conjuntos de escalado de ejecutor con Actions Runner Controller".

Acerca de la imagen de contenedor del ejecutor

GitHub mantiene una imagen de contenedor del ejecutor mínima. Se publicará una imagen nueva con cada versión de binarios del ejecutor. La imagen más reciente tendrá la versión de binarios del ejecutor y latest como etiquetas.

Esta imagen contiene la menor cantidad de paquetes necesarios para el runtime del contenedor y los binarios del ejecutor. Para instalar software adicional, puedes crear tu propia imagen de ejecutor. Puedes emplear la imagen del ejecutor de ARC como base, o bien usar las acciones de configuración correspondientes. Por ejemplo, actions/setup-java para Java o actions/setup-node para Node.

Encontrarás la definición de la imagen del ejecutor de ARC en este Dockerfile y la definición de la imagen base en este Dockerfile.

Creación de tu propia imagen de ejecutor

Puedes crear una imagen de ejecutor que cumpla tus requisitos. La imagen de ejecutor debe cumplir las condiciones siguientes.

• Usa una imagen base que pueda ejecutar la aplicación del ejecutor autohospedado. Para obtener más información, vea «Acerca de los ejecutores autohospedados».
• El binario del ejecutor debe colocarse en /home/runner/ e iniciarse mediante /home/runner/run.sh.
• Si usas el modo de Kubernetes, los enlaces del contenedor del ejecutor deben colocarse en /home/runner/k8s.

Puedes usar el siguiente Dockerfile de ejemplo para empezar a crear tu propia imagen de ejecutor.

FROM mcr.microsoft.com/dotnet/runtime-deps:6.0 as build

# Replace value with the latest runner release version
# source: https://github.com/actions/runner/releases
# ex: 2.303.0
ARG RUNNER_VERSION=""
ARG RUNNER_ARCH="x64"
# Replace value with the latest runner-container-hooks release version
# source: https://github.com/actions/runner-container-hooks/releases
# ex: 0.3.1
ARG RUNNER_CONTAINER_HOOKS_VERSION=""

ENV DEBIAN_FRONTEND=noninteractive
ENV RUNNER_MANUALLY_TRAP_SIG=1
ENV ACTIONS_RUNNER_PRINT_LOG_TO_STDOUT=1

RUN apt update -y && apt install curl unzip -y

RUN adduser --disabled-password --gecos "" --uid 1001 runner \
    && groupadd docker --gid 123 \
    && usermod -aG sudo runner \
    && usermod -aG docker runner \
    && echo "%sudo   ALL=(ALL:ALL) NOPASSWD:ALL" > /etc/sudoers \
    && echo "Defaults env_keep += \"DEBIAN_FRONTEND\"" >> /etc/sudoers

WORKDIR /home/runner

RUN curl -f -L -o runner.tar.gz https://github.com/actions/runner/releases/download/v${RUNNER_VERSION}/actions-runner-linux-${RUNNER_ARCH}-${RUNNER_VERSION}.tar.gz \
    && tar xzf ./runner.tar.gz \
    && rm runner.tar.gz

RUN curl -f -L -o runner-container-hooks.zip https://github.com/actions/runner-container-hooks/releases/download/v${RUNNER_CONTAINER_HOOKS_VERSION}/actions-runner-hooks-k8s-${RUNNER_CONTAINER_HOOKS_VERSION}.zip \
    && unzip ./runner-container-hooks.zip -d ./k8s \
    && rm runner-container-hooks.zip

USER runner

FROM mcr.microsoft.com/dotnet/runtime-deps:6.0 as build

# Replace value with the latest runner release version
# source: https://github.com/actions/runner/releases
# ex: 2.303.0
ARG RUNNER_VERSION=""
ARG RUNNER_ARCH="x64"
# Replace value with the latest runner-container-hooks release version
# source: https://github.com/actions/runner-container-hooks/releases
# ex: 0.3.1
ARG RUNNER_CONTAINER_HOOKS_VERSION=""

ENV DEBIAN_FRONTEND=noninteractive
ENV RUNNER_MANUALLY_TRAP_SIG=1
ENV ACTIONS_RUNNER_PRINT_LOG_TO_STDOUT=1

RUN apt update -y && apt install curl unzip -y

RUN adduser --disabled-password --gecos "" --uid 1001 runner \
    && groupadd docker --gid 123 \
    && usermod -aG sudo runner \
    && usermod -aG docker runner \
    && echo "%sudo   ALL=(ALL:ALL) NOPASSWD:ALL" > /etc/sudoers \
    && echo "Defaults env_keep += \"DEBIAN_FRONTEND\"" >> /etc/sudoers

WORKDIR /home/runner

RUN curl -f -L -o runner.tar.gz https://github.com/actions/runner/releases/download/v${RUNNER_VERSION}/actions-runner-linux-${RUNNER_ARCH}-${RUNNER_VERSION}.tar.gz \
    && tar xzf ./runner.tar.gz \
    && rm runner.tar.gz

RUN curl -f -L -o runner-container-hooks.zip https://github.com/actions/runner-container-hooks/releases/download/v${RUNNER_CONTAINER_HOOKS_VERSION}/actions-runner-hooks-k8s-${RUNNER_CONTAINER_HOOKS_VERSION}.zip \
    && unzip ./runner-container-hooks.zip -d ./k8s \
    && rm runner-container-hooks.zip

USER runner

Ejecución de flujos de trabajo

Una vez que la instalación y la configuración se han completado, puedes usar ARC para ejecutar flujos de trabajo. Se puede crear un flujo de trabajo en un mismo repositorio que pueda tener como destino un ejecutor autohospedado creado mediante ARC. Para obtener más información sobre cómo establecer que los flujos de trabajo se ejecuten en ejecutores autohospedados, consulta "Uso de ejecutores autohospedados en un flujo de trabajo".

Uso de ejecutores de ARC en un flujo de trabajo

No se pueden usar etiquetas adicionales para establecer como destino ejecutores creados por ARC. Solo se puede usar el nombre de la instalación del conjunto de escalado de ejecutor que se especificó durante la instalación o mediante la definición del valor del campo runnerScaleSetName en el archivo values.yaml. Se usan como la "etiqueta única" para emplearla como destino runs-on . Para obtener más información, consulta "Uso de ejecutores de Actions Runner Controller en un flujo de trabajo".

Escalado de ejecutores

Puedes escalar ejecutores de forma estática o dinámica según tus necesidades. Para obtener más información, vea «Implementación de conjuntos de escalado de ejecutor con Actions Runner Controller».

Software instalado en la imagen del ejecutor de ARC

La imagen del ejecutor de ARC incluye el software siguiente:

• Binarios del ejecutor
• Enlaces del contenedor del ejecutor
• Docker (necesario para el modo Docker en Docker)

Para obtener más información, consulta Dockerfile de imagen del ejecutor de ARC en el repositorio de acciones.

Recursos y versiones

ARC se libera como dos gráficos de Helm y una imagen de contenedor. Los gráficos de Helm solo se publican como paquetes de Open Container Initiative (OCI). ARC no proporciona tarballs ni repositorios de Helm a través de GitHub Pages.

Puedes encontrar las versiones más recientes de los gráficos de Helm y la imagen de contenedor de ARC en GitHub Packages:

• Gráfico de Helm de gha-runner-scale-set-controller
• Gráfico de Helm de gha-runner-scale-set
• Imagen de contenedor de gha-runner-scale-set-controller

La imagen de ejecutor admitida se publica como una imagen de contenedor independiente, que puedes encontrar en actions-runner en GitHub Packages.

Aviso legal

Algunas partes se han adaptado a partir de https://github.com/actions/actions-runner-controller/ con licencia Apache-2.0:

Copyright 2019 Moto Ishizawa

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.