Controlador del ejecutor de acciones

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 más información sobre el escalado automático, consulta Referencia de ejecutores autohospedados.

En el siguiente diagrama se ilustra la arquitectura del modo de autoescalado de los conjuntos de escalado del 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 del grupo de 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 despliega un pod oyente de conjunto de escalado de corredor. En este pod, la aplicación de escucha se conecta al servicio GitHub Actions para autenticar y establecer una conexión HTTPS de sondeo largo. El cliente de escucha permanece inactivo hasta que recibe un mensaje 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 coincide con el nombre del conjunto de escalado del ejecutor o las etiquetas de los ejecutores autohospedados.
5. Cuando el Listener de Runner ScaleSet recibe el mensaje, comprueba si puede escalar horizontalmente al recuento deseado. Si es posible, el cliente de escucha del conjunto de escalado del ejecutor confirma el mensaje.
6. El escuchador de la escala de conjunto de ejecutores utiliza una cuenta de servicio y un rol vinculados a esa cuenta para realizar una llamada HTTPS a través de las APIs de Kubernetes y actualizar el recurso RunnerSet efímero con el número de réplicas deseadas.
7. El RunnerSet efímero intenta crear nuevos runners y el controlador EphemeralRunner requiere un token de configuración Just-in-Time (JIT) para registrar a estos runners. El controlador intenta crear pods de ejecución. Si el estado del pod es , el controlador reintenta hasta cinco veces. Después de 24 horas, el servicio GitHub Actions desasigna el trabajo si ningún runner lo acepta.
8. Una vez creado el pod del ejecutor, la aplicación del ejecutor en el pod utiliza el token de configuración JIT para registrarse 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 runner y envía 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 desplegados por

Recursos desplegados por

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

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

Acerca de la imagen del 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 runner. La imagen más reciente tendrá la versión de los binarios del corredor y servirá 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 entorno de ejecución. 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.

Puedes encontrar la definición de la imagen del ejecutor de ARC en este Dockerfile. Para ver la imagen base actual, verifica la línea en el Dockerfile de la imagen del runner, y luego busca esa etiqueta en el repositorio.

Por ejemplo, si la línea del Dockerfile de la imagen del ejecutor es , puedes encontrar la imagen base en .

Creación de tu propia imagen de ejecutor

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

• Usa una imagen base que pueda ejecutar la aplicación del "runner" autohospedado. Consulta AUTOTITLE.

• El binario del ejecutor debe colocarse bajo e iniciarse mediante .

• Si usas el modo de Kubernetes, los enlaces del contenedor del ejecutor deben colocarse en .

Puedes usar el siguiente Dockerfile de ejemplo para comenzar a crear tu propia imagen de corredor.

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

Software instalado en la imagen del corredor de ARC

La imagen del entorno de ejecución de ARC incluye el siguiente software:

• Binarios del ejecutor
• Ganchos del contenedor ejecutor
• Docker (necesario para el modo Docker-in-Docker)

Para obtener más información, consulta el Dockerfile de la imagen del corredor de ARC en el repositorio de Acciones.

Activos y lanzamientos

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:

• Helm chart
• Helm chart
• Imagen de contenedor

La imagen de corredor admitida se publica como una imagen de contenedor por separado, que puedes encontrar en 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.

Pasos siguientes

Cuando quieras usar ARC para ejecutar flujos de trabajo, consulta AUTOTITLE.

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 . Consulta AUTOTITLE.

Puedes escalar escaladores de forma estática o dinámica según tus necesidades. Consulta AUTOTITLE.