Skip to main content

Implementación de conjuntos de escalado de ejecutor con Actions Runner Controller

Aprende a implementar conjuntos de escalado de ejecutor con Actions Runner Controller y a usar opciones de configuración avanzadas para adaptar Actions Runner Controller a tus necesidades.

Aviso legal

Acerca de los conjuntos de escalado de ejecutor

Los conjuntos de escalado de ejecutor son un grupo de ejecutores homogéneos a los que se pueden asignar trabajos de GitHub Actions. El número de ejecutores activos que pertenecen a un conjunto de escalado de ejecutor se puede controlar mediante soluciones de ejecutor de escalado automático, como Actions Runner Controller (ARC).

Puedes usar grupos de ejecutores para administrar conjuntos de escalado de ejecutor. De forma similar a los ejecutores autohospedados, puedes agregar conjuntos de escalado de ejecutor a grupos de ejecutores existentes. Sin embargo, los conjuntos de escalado de ejecutor solo pueden pertenecer a un grupo de ejecutores a la vez y solo pueden tener una etiqueta asignada. Para obtener más información acerca de los grupos de ejecutores, consulta "Administración del acceso a los ejecutores autohospedados mediante grupos."

Para asignar trabajos a un conjunto de escalado de ejecutor, debes configurar el flujo de trabajo para hacer referencia al nombre del conjunto de escalado del ejecutor. Para obtener más información, vea «Uso de ejecutores de Actions Runner Controller en un flujo de trabajo».

Implementación de un conjunto de escalado de ejecutor

Para implementar un conjunto de escalado de ejecutor, debes tener ARC en funcionamiento. Para obtener más información, vea «Inicio rápido para Actions Runner Controller».

Puedes implementar conjuntos de escalado de ejecutor con gráficos de Helm de ARC o mediante la implementación de los manifiestos necesarios. El uso de gráficos de Helm de ARC es el método preferido, especialmente si no tienes experiencia previa con ARC.

Notas:

  • Como procedimiento recomendado de seguridad, crea los pods del ejecutor en un espacio de nombres diferente al espacio de nombres que contiene los pods del operador.
  • Como procedimiento recomendado de seguridad, crea secretos de Kubernetes y pasa las referencias de los secretos. Pasar los secretos en texto sin formato a través de la CLI puede suponer un riesgo de seguridad.
  • Se recomienda ejecutar cargas de trabajo de producción de forma aislada. Los flujos de trabajo de GitHub Actions están diseñados para ejecutar código arbitrario y el uso de un clúster de Kubernetes compartido para cargas de trabajo de producción podría suponer un riesgo de seguridad.
  • Asegúrese de que ha implementado una manera de recopilar y conservar registros del controlador, los agentes de escucha y los ejecutores efímeros.
  1. Para configurar el conjunto de escalado del ejecutor, ejecuta el siguiente comando en el terminal mediante valores de la configuración de ARC.

    Al ejecutar el comando, ten en cuenta lo siguiente.

    • Actualiza el valor INSTALLATION_NAME cuidadosamente. Usarás el nombre de instalación como valor de runs-on en los flujos de trabajo.

    • Actualiza el valor NAMESPACE a la ubicación en la que deseas que se creen los pods del ejecutor.

    • Establece el valor GITHUB_CONFIG_URL en la dirección URL del repositorio, de la organización o de la empresa. Esta es la entidad a la que pertenecerán los ejecutores.

    • Este comando de ejemplo instala la versión más reciente del gráfico de Helm. Para instalar una versión específica, puedes pasar el argumento --version con la versión del gráfico que deseas instalar. Puedes encontrar la lista de versiones en el repositorio actions-runner-controller.

      Bash
      INSTALLATION_NAME="arc-runner-set"
      NAMESPACE="arc-runners"
      GITHUB_CONFIG_URL="http(s)://<HOSTNAME>/<'enterprises/your_enterprise'/'org'/'org/repo'>"
      GITHUB_PAT="<PAT>"
      helm install "${INSTALLATION_NAME}" \
          --namespace "${NAMESPACE}" \
          --create-namespace \
          --set githubConfigUrl="${GITHUB_CONFIG_URL}" \
          --set githubConfigSecret.github_token="${GITHUB_PAT}" \
          oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set
      

      Para ver más opciones de configuración de Helm, consulta values.yaml en el repositorio de ARC.

  2. Para comprobar la instalación, ejecuta el siguiente comando en el terminal.

    Bash
    helm list -A
    

    Debería ver una salida similar a la siguiente.

    NAME            NAMESPACE       REVISION        UPDATED                                 STATUS          CHART                                       APP VERSION
    arc             arc-systems     1               2023-04-12 11:45:59.152090536 +0000 UTC deployed        gha-runner-scale-set-controller-0.4.0       0.4.0
    arc-runner-set  arc-systems     1               2023-04-12 11:46:13.451041354 +0000 UTC deployed        gha-runner-scale-set-0.4.0                  0.4.0
    
  3. Para comprobar el pod del administrador, ejecuta el siguiente comando en el terminal.

    Bash
    kubectl get pods -n arc-systems
    

    Si la instalación se realizó correctamente, los pods mostrarán el estado Running.

    NAME                                                   READY   STATUS    RESTARTS   AGE
    arc-gha-runner-scale-set-controller-594cdc976f-m7cjs   1/1     Running   0          64s
    arc-runner-set-754b578d-listener                       1/1     Running   0          12s
    

Si la instalación no se realizó correctamente, consulta "Solución de errores de Actions Runner Controller" para obtener información sobre solución de problemas.

Uso de opciones de configuración avanzada

ARC ofrece varias opciones de configuración avanzadas.

Configuración del nombre del conjunto de escalado del ejecutor

Nota: Los nombres de conjuntos de escalado de ejecutor son únicos dentro del grupo de ejecutores al que pertenecen. Si deseas implementar varios conjuntos de escalado de ejecutor con el mismo nombre, deben pertenecer a grupos de ejecutores diferentes.

Para configurar el nombre del conjunto de escalado de ejecutor, puedes definir INSTALLATION_NAME o establecer el valor de runnerScaleSetName en la copia del archivo values.yaml.

## The name of the runner scale set to create, which defaults to the Helm release name
runnerScaleSetName: "my-runners"

Asegúrate de pasar el archivo values.yaml en el comando helm install. Consulta la documentación de instalación de Helm para obtener más detalles.

Elección de destinos de ejecutor

Los conjuntos de escalado de ejecutor se pueden implementar en los niveles de repositorio, organización o empresa.

Nota: Solamente puedes implementar conjuntos de escalado de ejecutor en el nivel empresarial al usar la autenticación de personal access token (classic).

Para implementar conjuntos de escalado de ejecutor en un nivel específico, establece el valor de githubConfigUrl de la copia de values.yaml en la dirección URL del repositorio, de la organización o de la empresa.

En el ejemplo siguiente se muestra cómo configurar ARC para agregar ejecutores a octo-org/octo-repo.

githubConfigUrl: "http(s)://<HOSTNAME>/<'enterprises/your_enterprise'/'org'/'org/repo'>"

Para ver más opciones de configuración de Helm, consulta values.yaml en el repositorio de ARC.

Uso de una GitHub App para la autenticación

Si no usa ejecutores de nivel empresarial, puede usar GitHub Apps para autenticarse con la API de GitHub . Para obtener más información, vea «Autenticación en la API de GitHub».

Nota: Dado el riesgo de seguridad asociado a exponer la clave privada en texto sin formato en un archivo en el disco, se recomienda crear un secreto de Kubernetes y pasar la referencia en su lugar.

Puedes crear un secreto de Kubernetes o especificar valores en el archivo values.yaml.

Una vez que hayas creado tu GitHub App, crea un secreto de Kubernetes y pasa la referencia a ese secreto en la copia del archivo values.yaml.

Nota: Crea el secreto en el mismo espacio de nombres donde está instalado el gráfico gha-runner-scale-set. En este ejemplo, el espacio de nombres es arc-runners para que corresponda a la documentación de inicio rápido. Para obtener más información, vea «Inicio rápido para Actions Runner Controller».

kubectl create secret generic pre-defined-secret \
  --namespace=arc-runners \
  --from-literal=github_app_id=123456 \
  --from-literal=github_app_installation_id=654321 \
  --from-literal=github_app_private_key='-----BEGIN RSA PRIVATE KEY-----********'

En la copia de values.yaml pasa el nombre del secreto como referencia.

githubConfigSecret: pre-defined-secret

Opción 2: Especificación de valores en el archivo values.yaml

Como alternativa, puedes especificar los valores de app_id, installation_id y private_key en la copia del archivo values.yaml.

## githubConfigSecret is the Kubernetes secret to use when authenticating with GitHub API.
## You can choose to use a GitHub App or a personal access token (classic)
githubConfigSecret:
  ## GitHub Apps Configuration
  ## IDs must be strings, use quotes
  github_app_id: "123456"
  github_app_installation_id: "654321"
  github_app_private_key: |
    -----BEGIN RSA PRIVATE KEY-----
    ...
    HkVN9...
    ...
    -----END RSA PRIVATE KEY-----

Para ver más opciones de configuración de Helm, consulta values.yaml en el repositorio de ARC.

Administración del acceso con grupos de ejecutores

Puedes usar grupos de ejecutores para controlar qué organizaciones o repositorios tienen acceso a los conjuntos de escalado de ejecutor. Para obtener más información acerca de los grupos de ejecutores, consulta "Administración del acceso a los ejecutores autohospedados mediante grupos."

Para agregar un conjunto de escalado de ejecutor a un grupo de ejecutores, ya debes tener un grupo de ejecutores creado. A continuación, establece la propiedad runnerGroup en la copia del archivo values.yaml. En el ejemplo siguiente se agrega un conjunto de escalado de ejecutor al grupo de ejecutores Octo-Group.

runnerGroup: "Octo-Group"

Para ver más opciones de configuración de Helm, consulta values.yaml en el repositorio de ARC.

Configuración de un proxy de salida

Para exigir que el tráfico HTTP del controlador y de los ejecutores pase por el proxy de salida, establece las siguientes propiedades en el gráfico de Helm.

proxy:
  http:
    url: http://proxy.com:1234
    credentialSecretRef: proxy-auth # a Kubernetes secret with `username` and `password` keys
  https:
    url: http://proxy.com:1234
    credentialSecretRef: proxy-auth # a Kubernetes secret with `username` and `password` keys
  noProxy:
    - example.com
    - example.org

ARC admite el uso de proxies anónimos o autenticados. Si usas proxies autenticados, debes establecer el valor credentialSecretRef para hacer referencia a un secreto de Kubernetes. Puedes crear un secreto con las credenciales de proxy con el siguiente comando.

Nota: Crea el secreto en el mismo espacio de nombres donde está instalado el gráfico gha-runner-scale-set. En este ejemplo, el espacio de nombres es arc-runners para que corresponda a la documentación de inicio rápido. Para obtener más información, vea «Inicio rápido para Actions Runner Controller».

Bash
  kubectl create secret generic proxy-auth \
    --namespace=arc-runners \
    --from-literal=username=proxyUsername \
    --from-literal=password=proxyPassword \

Para ver más opciones de configuración de Helm, consulta values.yaml en el repositorio de ARC.

Establecimiento del número máximo y mínimo de ejecutores

Las propiedades maxRunners y minRunners proporcionan numerosas opciones para personalizar la configuración de ARC.

Nota: ARC no admite configuraciones máximas y mínimas programadas. Puedes usar un cronjob o cualquier otra solución de programación para actualizar la configuración según una programación.

Ejemplo: Número de ejecutores sin enlazar

Si comentas las propiedades maxRunners y minRunners, ARC se escalará verticalmente al número de trabajos asignados al conjunto de escalado del ejecutor y se reducirá verticalmente a 0 si no hay ningún trabajo activo.

## maxRunners is the max number of runners the auto scaling runner set will scale up to.
# maxRunners: 0

## minRunners is the min number of idle runners. The target number of runners created will be
## calculated as a sum of minRunners and the number of jobs assigned to the scale set.
# minRunners: 0

Ejemplo: Número mínimo de ejecutores

Puede establecer la propiedad minRunners en cualquier número y ARC se asegurará de que siempre haya el número especificado de ejecutores activos y disponibles para llevar trabajos asignados al conjunto de escalado del ejecutor en todo momento.

## maxRunners is the max number of runners the auto scaling runner set will scale up to.
# maxRunners: 0

## minRunners is the min number of idle runners. The target number of runners created will be
## calculated as a sum of minRunners and the number of jobs assigned to the scale set.
minRunners: 20

Ejemplo: Establecimiento del número máximo y mínimo de ejecutores

En esta configuración, Actions Runner Controller se escalará verticalmente hasta un máximo de 30 ejecutores y se reducirá verticalmente a 20 ejecutores cuando se completen los trabajos.

Nota: El valor de minRunners nunca puede ser superior al de maxRunners, a menos que maxRunners se comente.

## maxRunners is the max number of runners the auto scaling runner set will scale up to.
maxRunners: 30

## minRunners is the min number of idle runners. The target number of runners created will be
## calculated as a sum of minRunners and the number of jobs assigned to the scale set.
minRunners: 20

Ejemplo: Purga de colas de trabajos

En determinados escenarios, es posible que desees purgar la cola de trabajos para solucionar un problema o realizar el mantenimiento en el clúster. Si estableces ambas propiedades en 0, Actions Runner Controller no creará nuevos pods de ejecutor cuando haya nuevos trabajos disponibles y asignados.

## maxRunners is the max number of runners the auto scaling runner set will scale up to.
maxRunners: 0

## minRunners is the min number of idle runners. The target number of runners created will be
## calculated as a sum of minRunners and the number of jobs assigned to the scale set.
minRunners: 0

Personalización de certificados TLS

Nota: Si usas una imagen de ejecutor personalizada que no se basa en la distribución Debian, las instrucciones siguientes no funcionarán.

Algunos entornos requieren certificados TLS firmados por una entidad de certificación (CA) personalizada. Dado que los certificados de entidad de certificación personalizados no se incluyen con los contenedores de controlador o ejecutor, debes insertarlos en sus respectivos almacenes de confianza.

githubServerTLS:
  certificateFrom:
    configMapKeyRef:
      name: config-map-name
      key: ca.crt
  runnerMountPath: /usr/local/share/ca-certificates/

Al hacerlo, asegúrate de que usas el formato de correo mejorado de privacidad (PEM) y que la extensión del certificado es .crt. Se pasará por alto todo lo demás.

El controlador ejecuta las acciones siguientes.

  • Crea un volumen github-server-tls-cert que contiene el certificado especificado en certificateFrom.
  • Monta ese volumen en la ruta de acceso runnerMountPath/<certificate name>.
  • Establece la variable de entorno NODE_EXTRA_CA_CERTS en esa misma ruta de acceso.
  • Establece la variable de entorno RUNNER_UPDATE_CA_CERTS en 1 (a partir de la versión 2.303.0, esto indicará al ejecutor que vuelva a cargar los certificados en el host).

ARC observa los valores establecidos en la plantilla de pod del ejecutor y no los sobrescribe.

Para ver más opciones de configuración de Helm, consulta values.yaml en el repositorio de ARC.

Uso de un registro de contenedor privado

Advertencia: Esta opción de personalización de Actions Runner Controller puede estar fuera del ámbito de la asistencia de Soporte de GitHub y es posible que cause un comportamiento inesperado cuando se configura incorrectamente.

Para obtener más información sobre cómo puede ayudar Soporte de GitHub, consulta "Acerca de la compatibilidad con Actions Runner Controller".

Para usar un registro de contenedor privado, puedes copiar la imagen del controlador y la imagen del ejecutor en el registro de contenedor privado. A continuación, configura los vínculos a esas imágenes y establece los valores imagePullPolicy y imagePullSecrets.

Configuración de la imagen del controlador

Puedes actualizar la copia del archivo values.yaml y establecer las propiedades image de la siguiente manera.

image:
  repository: "custom-registry.io/gha-runner-scale-set-controller"
  pullPolicy: IfNotPresent
  # Overrides the image tag whose default is the chart appVersion.
  tag: "0.4.0"

imagePullSecrets:
  - name: <registry-secret-name>

El contenedor del cliente de escucha hereda imagePullPolicy que se ha definido para el controlador.

Configuración de la imagen del ejecutor

Puedes actualizar la copia del archivo values.yaml y establecer las propiedades template.spec de la siguiente manera.

template:
  spec:
    containers:
      - name: runner
        image: "custom-registry.io/actions-runner:latest"
        imagePullPolicy: Always
        command: ["/home/runner/run.sh"]
    imagePullSecrets:
      - name: <registry-secret-name>

Para ver más opciones de configuración de Helm, consulta values.yaml en el repositorio de ARC.

Actualización de la especificación del pod para el pod del ejecutor

Advertencia: Esta opción de personalización de Actions Runner Controller puede estar fuera del ámbito de la asistencia de Soporte de GitHub y es posible que cause un comportamiento inesperado cuando se configura incorrectamente.

Para obtener más información sobre cómo puede ayudar Soporte de GitHub, consulta "Acerca de la compatibilidad con Actions Runner Controller".

Puedes personalizar completamente PodSpec del pod del ejecutor y el controlador aplicará la configuración que especifiques. A continuación se muestra una especificación de pod de ejemplo.

template:
  spec:
    containers:
      - name: runner
        image: ghcr.io/actions/actions-runner:latest
        command: ["/home/runner/run.sh"]
        resources:
          limits:
            cpu: 500m
            memory: 512Mi
        securityContext:
          readOnlyRootFilesystem: true
          allowPrivilegeEscalation: false
          capabilities:
            add:
              - NET_ADMIN

Para ver más opciones de configuración de Helm, consulta values.yaml en el repositorio de ARC.

Actualización de la especificación del pod para el pod de escucha

Advertencia: Esta opción de personalización de Actions Runner Controller puede estar fuera del ámbito de la asistencia de Soporte de GitHub y es posible que cause un comportamiento inesperado cuando se configura incorrectamente.

Para obtener más información sobre cómo puede ayudar Soporte de GitHub, consulta "Acerca de la compatibilidad con Actions Runner Controller".

Puede personalizar PodSpec del pod de escucha y el controlador aplicará la configuración que especifique. A continuación se muestra una especificación de pod de ejemplo.

Es importante no cambiar el valor listenerTemplate.spec.containers.name del contenedor de escucha. De lo contrario, la configuración que especifique se aplicará a un nuevo contenedor lateral.

listenerTemplate:
  spec:
    containers:
    # If you change the name of the container, the configuration will not be applied to the listener,
    # and it will be treated as a side-car container.
    - name: listener
      securityContext:
        runAsUser: 1000
      resources:
        limits:
          cpu: "1"
          memory: 1Gi
        requests:
          cpu: "1"
          memory: 1Gi

Para ver más opciones de configuración de Helm, consulta values.yaml en el repositorio de ARC.

Uso del modo Docker en Docker o Kubernetes para contenedores

Advertencia: Esta opción de personalización de Actions Runner Controller puede estar fuera del ámbito de la asistencia de Soporte de GitHub y es posible que cause un comportamiento inesperado cuando se configura incorrectamente.

Para obtener más información sobre cómo puede ayudar Soporte de GitHub, consulta "Acerca de la compatibilidad con Actions Runner Controller".

Si usas trabajos de contenedor y servicios o acciones de contenedor, el valor containerMode debe establecerse en dind o kubernetes.

Uso del modo Docker en Docker

Nota: El contenedor de Docker en Docker requiere el modo con privilegios. Para obtener más información, consulta Configuración de un contexto de seguridad para un pod o contenedor en la documentación de Kubernetes.

De manera predeterminada, el contenedor dind utiliza la imagen docker:dind, que ejecuta el demonio de Docker como raíz. Puede reemplazar esta imagen con docker:dind-rootless siempre y cuando usted sea consciente de las limitaciones conocidas y ejecute los pods con el modo --privileged. Para obtener información sobre cómo personalizar la configuración de Docker en Docker, consulte "Personalización de los modos del contenedor".

El modo Docker en Docker es una configuración que permite ejecutar Docker dentro de un contenedor de Docker. En esta configuración, para cada pod de ejecutor creado, ARC crea los siguientes contenedores.

  • Un contenedor init
  • Un contenedor runner
  • Un contenedor dind

Para habilitar el modo Docker en Docker, establece containerMode.type en dind como se indica a continuación.

containerMode:
  type: "dind"

template.spec se actualizará a la siguiente configuración predeterminada.

template:
  spec:
    initContainers:
      - name: init-dind-externals
        image: ghcr.io/actions/actions-runner:latest
        command:
          ["cp", "-r", "-v", "/home/runner/externals/.", "/home/runner/tmpDir/"]
        volumeMounts:
          - name: dind-externals
            mountPath: /home/runner/tmpDir
    containers:
      - name: runner
        image: ghcr.io/actions/actions-runner:latest
        command: ["/home/runner/run.sh"]
        env:
          - name: DOCKER_HOST
            value: unix:///var/run/docker.sock
        volumeMounts:
          - name: work
            mountPath: /home/runner/_work
          - name: dind-sock
            mountPath: /var/run
      - name: dind
        image: docker:dind
        args:
          - dockerd
          - --host=unix:///var/run/docker.sock
          - --group=$(DOCKER_GROUP_GID)
        env:
          - name: DOCKER_GROUP_GID
            value: "123"
        securityContext:
          privileged: true
        volumeMounts:
          - name: work
            mountPath: /home/runner/_work
          - name: dind-sock
            mountPath: /var/run
          - name: dind-externals
            mountPath: /home/runner/externals
    volumes:
      - name: work
        emptyDir: {}
      - name: dind-sock
        emptyDir: {}
      - name: dind-externals
        emptyDir: {}

Los valores de template.spec se insertan automáticamente y no se pueden invalidar. Si deseas personalizar esta configuración, debes anular containerMode.type, copiar la configuración y aplicarla directamente en la copia del archivo values.yaml.

Para ver más opciones de configuración de Helm, consulta values.yaml en el repositorio de ARC.

Uso del modo Kubernetes

En el modo Kubernetes, ARC usa enlaces de contenedor de ejecutor para crear un nuevo pod en el mismo espacio de nombres para ejecutar el servicio, el trabajo de contenedor o la acción.

Requisitos previos

El modo Kubernetes se basa en volúmenes persistentes para compartir los detalles del trabajo entre el pod del ejecutor y el pod de trabajo del contenedor. Para obtener más información, consulte la sección Volúmenes persistentes en la documentación de Kubernetes.

Para usar el modo de Kubernetes, debes hacer lo siguiente.

  • Crea volúmenes persistentes disponibles para que los pods de corredores los reclamen.
  • Usa una solución para aprovisionar automáticamente volúmenes persistentes a petición.

Para realizar pruebas, puedes usar una solución como OpenEBS.

Configuración del modo de Kubernetes

Para habilitar el modo Kubernetes, establezca el containerMode.type en kubernetes en su archivo values.yaml.

containerMode:
  type: "kubernetes"
  kubernetesModeWorkVolumeClaim:
    accessModes: ["ReadWriteOnce"]
    storageClassName: "dynamic-blob-storage"
    resources:
      requests:
        storage: 1Gi

Para ver más opciones de configuración de Helm, consulta values.yaml en el repositorio de ARC.

Nota: Cuando el modo Kubernetes está habilitado, los flujos de trabajo que no están configurados con un trabajo de contenedor producirán un error similar al siguiente:

Jobs without a job container are forbidden on this runner, please add a 'container:' to your job or contact your self-hosted runner administrator.

Para permitir que los trabajos sin un contenedor de trabajos se ejecuten, establezca ACTIONS_RUNNER_REQUIRE_JOB_CONTAINER en false en el contenedor del ejecutor. Esto indica al ejecutor que deshabilite esta comprobación.

template:
  spec:
    containers:
      - name: runner
        image: ghcr.io/actions/actions-runner:latest
        command: ["/home/runner/run.sh"]
        env:
          - name: ACTIONS_RUNNER_REQUIRE_JOB_CONTAINER
            value: "false"

Personalización de los modos del contenedor

Cuando configure el containerMode en el archivo values.yaml para el gha-runner-scale-setgráfico helm, puede utilizar cualquiera de los siguientes valores:

  • dind o
  • kubernetes

Dependiendo del valor que establezca para containerMode, se insertará automáticamente una configuración en la sección template del archivo values.yaml para el gráfico de Helm gha-runner-scale-set.

Para personalizar la especificación, convierta en comentario o elimine containerMode y anexe la configuración que desee en la sección template.

Ejemplo: la ejecución de dind-rootless

Antes de decidir ejecutar dind-rootless, asegúrese de que conoce las limitaciones conocidas.

## githubConfigUrl is the GitHub url for where you want to configure runners
## ex: https://<HOSTNAME>/enterprises/my_enterprise or https://<HOSTNAME>/myorg
githubConfigUrl: "https://<HOSTNAME>/actions/actions-runner-controller"

## githubConfigSecret is the k8s secrets to use when auth with GitHub API.
## You can choose to use GitHub App or a PAT token
githubConfigSecret: my-super-safe-secret

## maxRunners is the max number of runners the autoscaling runner set will scale up to.
maxRunners: 5

## minRunners is the min number of idle runners. The target number of runners created will be
## calculated as a sum of minRunners and the number of jobs assigned to the scale set.
minRunners: 0

runnerGroup: "my-custom-runner-group"

## name of the runner scale set to create.  Defaults to the helm release name
runnerScaleSetName: "my-awesome-scale-set"

## template is the PodSpec for each runner Pod
## For reference: https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#PodSpec
template:
  spec:
    initContainers:
    - name: init-dind-externals
      image: ghcr.io/actions/actions-runner:latest
      command: ["cp", "-r", "-v", "/home/runner/externals/.", "/home/runner/tmpDir/"]
      volumeMounts:
        - name: dind-externals
          mountPath: /home/runner/tmpDir
    - name: init-dind-rootless
      image: docker:dind-rootless
      command:
        - sh
        - -c
        - |
          set -x
          cp -a /etc/. /dind-etc/
          echo 'runner:x:1001:1001:runner:/home/runner:/bin/ash' >> /dind-etc/passwd
          echo 'runner:x:1001:' >> /dind-etc/group
          echo 'runner:100000:65536' >> /dind-etc/subgid
          echo 'runner:100000:65536' >>  /dind-etc/subuid
          chmod 755 /dind-etc;
          chmod u=rwx,g=rx+s,o=rx /dind-home
          chown 1001:1001 /dind-home
      securityContext:
        runAsUser: 0
      volumeMounts:
        - mountPath: /dind-etc
          name: dind-etc
        - mountPath: /dind-home
          name: dind-home
    containers:
    - name: runner
      image: ghcr.io/actions/actions-runner:latest
      command: ["/home/runner/run.sh"]
      env:
        - name: DOCKER_HOST
          value: unix:///var/run/docker.sock
      volumeMounts:
        - name: work
          mountPath: /home/runner/_work
        - name: dind-sock
          mountPath: /var/run
    - name: dind
      image: docker:dind-rootless
      args:
        - dockerd
        - --host=unix:///var/run/docker.sock
      securityContext:
        privileged: true
        runAsUser: 1001
        runAsGroup: 1001
      volumeMounts:
        - name: work
          mountPath: /home/runner/_work
        - name: dind-sock
          mountPath: /var/run
        - name: dind-externals
          mountPath: /home/runner/externals
        - name: dind-etc
          mountPath: /etc
        - name: dind-home
          mountPath: /home/runner
    volumes:
    - name: work
      emptyDir: {}
    - name: dind-externals
      emptyDir: {}
    - name: dind-sock
      emptyDir: {}
    - name: dind-etc
      emptyDir: {}
    - name: dind-home
      emptyDir: {}

Reconocimiento de runner-container-hooks

Cuando el ejecutor detecta una ejecución de flujo de trabajo que usa un trabajo de contenedor, un contenedor de servicios o una acción de Docker, llamará a runner-container-hooks para crear un pod. El ejecutor se basa en runner-container-hooks para llamar a las API de Kubernetes y crear un pod en el mismo espacio de nombres que el pod del ejecutor. Este pod recién creado se usará para ejecutar el trabajo de contenedor, el contenedor de servicios o la acción de Docker. Para más información, consulte el repositorio runner-container-hooks.

Configuración de las extensiones de enlace

A partir de la versión 0.4.0 de ARC, runner-container-hooks es compatible con extensiones de enlace. Puede utilizarlos para configurar el pod creado por runner-container-hooks. Por ejemplo, podría usar una extensión de enlace para configurar un contexto de seguridad en el pod. Las extensiones de enlace permiten especificar un archivo YAML que se usa para actualizar el PodSpec del pod creado por runner-container-hooks.

Hay dos opciones para configurar extensiones de enlace.

  • Almacenar en la imagen del ejecutor personalizado. Puede almacenar el PodSpec en un archivo YAML en cualquier lugar de la imagen del ejecutor personalizado. Para obtener más información, vea «Acerca de Actions Runner Controller».
  • Almacenar en un ConfigMap. Puede crear un ConfigMap con el PodSpec y montar ese ConfigMap en el contenedor del ejecutor. Para obtener más información, consulte ConfigMaps en la documentación de Kubernetes.

Nota: Con ambas opciones, debe configurar la ACTIONS_RUNNER_CONTAINER_HOOK_TEMPLATE variable de entorno en la especificación del contenedor del ejecutor para que apunte a la ruta de acceso del archivo YAML montado en el contenedor del ejecutor.

Ejemplo: Uso de ConfigMap para configurar securityContext

Cree un ConfigMap en el mismo espacio de nombres que los pods del ejecutor. Por ejemplo:

apiVersion: v1
kind: ConfigMap
metadata:
  name: hook-extension
  namespace: arc-runners
data:
  content: |
    metadata:
      annotations:
        example: "extension"
    spec:
      containers:
        - name: "$job" # Target the job container
          securityContext:
            runAsUser: 1000
  • Los campos .metadata.labels y metadata.annotations se anexarán tal como están, a menos que sus claves estén reservadas. No se pueden invalidar los campos .metadata.name y metadata.namespace.
  • La mayoría de los campos PodSpec se aplican a partir de la plantilla especificada e invalidarán los valores pasados desde el archivo values.yaml de gráfico de Helm.
  • Si especifica volúmenes adicionales, se anexarán a los volúmenes predeterminados especificados por el ejecutor.
  • Los spec.containers se combinan en función de los nombres que se les asignan.
    • Si el nombre del contenedor es $job:
      • Los campos spec.containers.name y spec.containers.image se omiten.
      • Los campos spec.containers.env, spec.containers.volumeMounts y spec.containers.ports se anexan a la especificación de contenedor predeterminada creada por el enlace.
      • El resto de los campos se aplican según lo previsto.
    • Si el nombre del contenedor no es $job, los campos se añadirán a la definición de pod tal como están.

Habilitación de métricas

Nota: Las métricas de ARC están disponibles a partir de la versión gha-runner-scale-set-0.5.0.

ARC puede emitir métricas sobre los ejecutores, los trabajos y el tiempo dedicados a ejecutar los flujos de trabajo. Las métricas se pueden usar para identificar la congestión, supervisar el estado de la implementación de ARC, visualizar las tendencias de uso, optimizar el consumo de recursos, entre muchos otros casos de uso. Las métricas las emite el administrador del controlador y los pods del agente de escucha en formato Prometheus. Para obtener más información, consulta Formatos de exposición en la documentación de Prometheus.

Para habilitar las métricas para ARC, configura la propiedad metrics en el archivo values.yaml del gráfico gha-runner-scale-set-controller.

A continuación se muestra una configuración de ejemplo.

metrics:
  controllerManagerAddr: ":8080"
  listenerAddr: ":8080"
  listenerEndpoint: "/metrics"

Nota: Si el objeto metrics: no se proporciona o se convierte en comentario, se aplicarán las marcas siguientes al administrador de controladores y pods del agente de escucha con valores vacíos: --metrics-addr, --listener-metrics-addr, --listener-metrics-endpoint. Esto deshabilitará las métricas para ARC.

Una vez configuradas estas propiedades, el administrador del controlador y los pods del agente de escucha emiten métricas a través del listenerEndpoint enlazado a los puertos que especificas en el archivo values.yaml. En el ejemplo anterior, el punto de conexión es /metrics y el puerto es :8080. Puedes usar este punto de conexión para extraer las métricas del administrador del controlador y los pods del agente de escucha.

Para desactivar las métricas, actualiza el archivo values.yaml quitando o convirtiendo en comentario el objeto metrics: y sus propiedades.

Métricas disponibles para ARC

En la tabla siguiente se muestran las métricas emitidas por el administrador del controlador y los pods del agente de escucha.

Nota: Las métricas que emite el administrador del controlador pertenecen al entorno de ejecución del controlador y no pertenecen a GitHub.

OwnerMétricaTipoDescripción
controller-managergha_controller_pending_ephemeral_runnersmedidorNúmero de ejecutores efímeros en estado pendiente
controller-managergha_controller_running_ephemeral_runnersmedidorNúmero de ejecutores efímeros en estado de ejecución
controller-managergha_controller_failed_ephemeral_runnersmedidorNúmero de ejecutores efímeros en estado de error
controller-managergha_controller_running_listenersmedidorNúmero de agentes de escucha en estado en ejecución
listenergha_assigned_jobsmedidorNúmero de trabajos asignados al conjunto de escalado del ejecutor
listenergha_running_jobsmedidorNúmero de trabajos en ejecución o en cola para ejecutarse
listenergha_registered_runnersmedidorNúmero de ejecutores registrados por el conjunto de escalado de ejecutores
listenergha_busy_runnersmedidorNúmero de ejecutores registrados que ejecutan actualmente un trabajo
listenergha_min_runnersmedidorNúmero mínimo de ejecutores configurados para el conjunto de escalado de ejecutores
listenergha_max_runnersmedidorNúmero máximo de ejecutores configurados para el conjunto de escalado de ejecutores
listenergha_desired_runnersmedidorNúmero de ejecutores deseados (escalar o reducir verticalmente el destino) por el conjunto de escalado del ejecutor
listenergha_idle_runnersmedidorNúmero de ejecutores registrados que no ejecutan actualmente un trabajo
listenergha_started_jobs_totalcounterNúmero total de trabajos iniciados desde que el agente de escucha estuvo listo [1]
listenergha_completed_jobs_totalcounterNúmero total de trabajos completados desde que el agente de escucha estuvo listo [1]
listenergha_job_startup_duration_secondshistogramNúmero de segundos dedicados a esperar a que el trabajo de flujo de trabajo empiece a trabajar en el ejecutor que es propiedad del conjunto de escalado del ejecutor
listenergha_job_execution_duration_secondshistogramNúmero de segundos dedicados a ejecutar trabajos de flujo de trabajo por el conjunto de escalado del ejecutor

[1]: Listener metrics that have the counter type are reset when the listener pod restarts.

Utilizar ARC con Dependabot y code scanning

Puedes usar Actions Runner Controller para crear ejecutores dedicados para la instancia de GitHub Enterprise Server que Dependabot puede usar para ayudar a proteger y mantener las dependencias usadas en los repositorios de tu empresa. Para obtener más información, vea «Administrar ejecutores autohospedados para actualizaciones del Dependabot en su empresa».

También puedes utilizar ARC con CodeQL para identificar las vulnerabilidades y errores en tu código. Para obtener más información, vea «Acerca del examen de código con CodeQL». Si ya usas code scanning y quieres configurar un conjunto de escalado de ejecutores para usar la configuración predeterminada, establece INSTALLATION_NAME=code-scanning. Para más información sobre la configuración predeterminada de code scanning, consulta «Establecimiento de la configuración predeterminada para el examen del código».

Actions Runner Controller no usa varias etiquetas para enrutar trabajos a conjuntos de escalado de ejecutores específicos. En su lugar, para designar un conjunto de escalado de ejecutores para las actualizaciones de Dependabot o el code scanning con CodeQL, usa un nombre de instalación descriptivo en el gráfico de Helm, como dependabot o code-scanning. A continuación, puedes establecer el valor runs-on de los flujos de trabajo en el nombre de la instalación como la etiqueta única y usar el conjunto de escalado de ejecutores designado para las actualizaciones de Dependabot o los trabajos de code scanning.

Si usas la configuración predeterminada para el code scanning, el análisis buscará automáticamente un conjunto de escalado de ejecutor con el nombre de instalación code-scanning.

La acción Dependabot se usa para ejecutar actualizaciones de Dependabot a través de GitHub Actions. Esta acción requiere Docker como dependencia. Por este motivo, solo puedes usar Actions Runner Controller con Dependabot cuando el modo Docker-in-Docker (DinD) está habilitado. Para obtener más información, vea «Administrar ejecutores autohospedados para actualizaciones del Dependabot en su empresa» y «Implementación de conjuntos de escalado de ejecutor con Actions Runner Controller».

Actualización de ARC

Dado que no hay compatibilidad con la actualización ni eliminación de CRD con Helm, no es posible utilizar Helm para actualizar ARC. Para obtener más información, consulte Definición de recursos personalizados en la documentación de Helm. Para actualizar ARC a una versión más reciente, debe completar los pasos siguientes.

  1. Desinstale todas las instalaciones de gha-runner-scale-set.
  2. Espere a que se limpien los recursos.
  3. Desinstale ARC.
  4. Si hay un cambio en los CRD de la versión que tiene instalada actualmente a la versión actualizada, quite todos los CRD asociados al grupo de API actions.github.com.
  5. Reinstale ARC.

Para obtener más información, consulte "Implementación de un conjunto de escalado de ejecutores".

Si desea actualizar ARC, pero le preocupa el tiempo de inactividad, puede implementar ARC en una configuración de alta disponibilidad para asegurarse de que los ejecutores estén siempre disponibles. Para más información, consulte "Alta disponibilidad y conmutación automática por error".

Nota:

La transición de la versión compatible de la comunidad de ARC a la versión compatible de GitHub es un cambio arquitectónico sustancial. La versión compatible de GitHub implica un rediseño de muchos componentes de ARC. No es una actualización de software menor. Por estos motivos, se recomienda probar las nuevas versiones en un entorno de ensayo que coincida primero con el entorno de producción. Esto garantizará la estabilidad y confiabilidad de la configuración antes de implementarla en producción.

Implementación de una imagen de valor controlado

Puede probar las características antes de que se publiquen mediante versiones de valor controlado de la imagen de contenedor de controller-manager. Las imágenes de valor controlado se publican con formato de etiqueta canary-SHORT_SHA. Para más información, consulte gha-runner-scale-set-controller Container registry.

Notas:

  • Debe utilizar gráficos de Helm en el sistema de archivos local.
  • No puede utilizar los gráficos de Helm publicados.
  1. Actualice el tag en el archivo gha-runner-scale-set-controller values.yamla: canary-SHORT_SHA
  2. Actualice el campo appVersion en el archivo Chart.yaml paragha-runner-scale-set a: canary-SHORT_SHA
  3. Reinstale ARC mediante el gráfico de Helm actualizado y los archivos values.yaml.

Alta disponibilidad y conmutación por error automática

ARC se puede implementar en una configuración de alta disponibilidad (activa-activa). Si tienes dos clústeres de Kubernetes distintos implementados en regiones independientes, puedes implementar ARC en ambos clústeres y configurar conjuntos de escalado de ejecutores para usar el mismo runnerScaleSetName. Para ello, cada conjunto de escalado de ejecutores debe asignarse a un grupo de ejecutor distinto. Por ejemplo, puedes tener dos conjuntos de escalado de ejecutores denominados arc-runner-set, siempre que un conjunto de escalado de ejecutor pertenezca a runner-group-A y el otro conjunto de escalado de ejecutores pertenezca a runner-group-B. Para obtener información sobre cómo asignar conjuntos de escalado de ejecutores a grupos de ejecutores, consulta "Administración del acceso a los ejecutores autohospedados mediante grupos".

Si ambos conjuntos de escalado de ejecutor están en línea, los trabajos asignados a ellos se distribuirán arbitrariamente (carrera de asignación). No se puede configurar el algoritmo de asignación de trabajos. Si uno de los clústeres deja de funcionar, el conjunto de escalado del ejecutor del otro clúster seguirá adquiriendo trabajos normalmente sin tener que intervenir ni cambiar la configuración.

Uso de ARC entre organizaciones

Una única instalación de Actions Runner Controller permite configurar uno o varios conjuntos de escalado de ejecutor. Estos conjuntos de escalado de ejecutor se pueden registrar en un repositorio, organización o empresa. También puedes usar grupos de ejecutores para controlar los límites de permisos de estos conjuntos de escalado de ejecutor.

Como procedimiento recomendado, crea un espacio de nombres único para cada organización. También puedes crear un espacio de nombres para cada grupo de ejecutores o para cada conjunto de escalado de ejecutor. Puedes instalar tantos conjuntos de escalado de ejecutor como sea necesario en cada espacio de nombres. Esto proporcionará los niveles más altos de aislamiento y mejorará la seguridad. Puedes usar GitHub Apps para la autenticación y definir permisos granulares para cada conjunto de escalado de ejecutor.

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.