Skip to main content

Acerca de Actions Runner Controller

Puedes alojar tus propios ejecutores y personalizar el entorno utilizado para ejecutar trabajos en tus flujos de trabajo de GitHub Actions.

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.

Nota: Para ver el diagrama siguiente en un tamaño más grande, consulta la documentación sobre el modo de escalado automático de conjuntos de escalado de ejecutor en el repositorio de Actions Runner Controller.

Diagrama que muestra el 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.

Nota: Las distintas versiones de Kubernetes tienen límites de longitud diferentes para los nombres de los recursos. El límite de longitud del nombre del recurso se calcula mediante la suma de la longitud del nombre de instalación y la longitud del sufijo de identificación de recursos. Si el nombre del recurso es mayor que la longitud reservada, recibirás un error.

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

PlantillaTipo de recursoNombreLongitud reservadaDescripciónNotas
deployment.yamlImplementaciónINSTALLATION_NAME-gha-rs-controller18El recurso que ejecuta controller-managerLos pods creados por este recurso tienen el sufijo ReplicaSet y el sufijo Pod.
serviceaccount.yamlServiceAccountINSTALLATION_NAME-gha-rs-controller18Esto se crea si serviceAccount.create en values.yaml está establecido en true.El nombre se puede personalizar en values.yaml
manager_cluster_role.yamlClusterRoleINSTALLATION_NAME-gha-rs-controller18ClusterRole para el administrador de controladoresSe crea si el valor de flags.watchSingleNamespace está vacío.
manager_cluster_role_binding.yamlClusterRoleBindingINSTALLATION_NAME-gha-rs-controller18ClusterRoleBinding para el administrador de controladoresSe crea si el valor de flags.watchSingleNamespace está vacío.
manager_single_namespace_controller_role.yamlRoleINSTALLATION_NAME-gha-rs-controller-single-namespace35Rol para el administrador de controladoresSe crea si el valor de flags.watchSingleNamespace está establecido.
manager_single_namespace_controller_role_binding.yamlRoleBindingINSTALLATION_NAME-gha-rs-controller-single-namespace35RoleBinding para el administrador de controladoresSe crea si el valor de flags.watchSingleNamespace está establecido.
manager_single_namespace_watch_role.yamlRoleINSTALLATION_NAME-gha-rs-controller-single-namespace-watch41Rol del administrador de controladores para el espacio de nombres configuradoSe crea si el valor de flags.watchSingleNamespace está establecido.
manager_single_namespace_watch_role_binding.yamlRoleBindingINSTALLATION_NAME-gha-rs-controller-single-namespace-watch41RoleBinding para el administrador de controladores para el espacio de nombres configuradoSe crea si el valor de flags.watchSingleNamespace está establecido.
manager_listener_role.yamlRoleINSTALLATION_NAME-gha-rs-controller-listener26Rol para el agente de escucha.Esto siempre se crea.
manager_listener_role_binding.yaml RoleBindingINSTALLATION_NAME-gha-rs-controller-listener26RoleBinding para el agente de escuchaEsto siempre se crea y enlaza el rol de agente de escucha con la cuenta de servicio, que se crea mediante serviceaccount.yaml o se configura con values.yaml.

Recursos implementados por gha-runner-scale-set

PlantillaTipo de recursoNombreLongitud reservadaDescripciónNotas
autoscalingrunnerset.yamlAutoscalingRunnerSetINSTALLATION_NAME0Recurso de nivel superior que funciona con conjuntos de escaladoLa longitud del nombre está limitada a 45 caracteres.
no_permission_service_account.yamlServiceAccountINSTALLATION_NAME-gha-rs-no-permission21Cuenta de servicio montada en el contenedor del ejecutorEsto se crea si el modo de contenedor no es "kubernetes" y template.spec.serviceAccountName no se especifica.
githubsecret.yamlSecretoINSTALLATION_NAME-gha-rs-github-secret20Secreto que contiene los valores necesarios para autenticarse en la API de GitHubSe crea si githubConfigSecret es un objeto. Si se proporciona una cadena, este secreto no se creará.
manager_role.yamlRoleINSTALLATION_NAME-gha-rs-manager15Rol proporcionado al administrador para poder conciliar los recursos del espacio de nombres del ejecutor de escalado automático.Esto siempre se crea.
manager_role_binding.yamlRoleBindingINSTALLATION_NAME-gha-rs-manager15Enlazando manager_role a la cuenta de servicio del administrador.Esto siempre se crea.
kube_mode_role.yamlRoleINSTALLATION_NAME-gha-rs-kube-mode17Rol que proporciona permisos necesarios para el enlaceEsto se crea cuando el modo de contenedor se establece en "kubernetes" y template.spec.serviceAccount no se proporciona.
kube_mode_serviceaccount.yamlServiceAccountINSTALLATION_NAME-gha-rs-kube-mode17Cuenta de servicio enlazada al pod del ejecutor.Esto se crea cuando el modo de contenedor se establece en "kubernetes" y template.spec.serviceAccount no se proporciona.

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.

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.

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

Dockerfile
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 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. 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:

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:

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

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.