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

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 más información, consulta 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 más información, consulta 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.

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

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.

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 más información, consulta Autenticación en la API de GitHub.

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

Opción 1: Creación de un secreto de Kubernetes (recomendado)

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.

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.

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

  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.

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.

## 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

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

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

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

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.

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

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

• Para obtener más información sobre los trabajos y servicios de contenedor, consulta Ejecutar trabajos en un contenedor.
• Para obtener más información sobre las acciones de contenedor, consulta Creación de una acción de contenedor de Docker.

Uso del modo Docker en Docker

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", "/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.

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

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.

• Consulte la dindconfiguración.
• Consulte la kubernetesconfiguración.

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", "/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 más información, consulta 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.

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

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"

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.

[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 más información, consulta 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 más información, consulta 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 de code scanning, el análisis buscará automáticamente un conjunto de escalado de ejecutores con el nombre de instalación code-scanning .

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, consulta 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, consulta Alta disponibilidad y conmutación automática por error.

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.

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.

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.