Como implantar conjuntos de dimensionamento de executores com o Actions Runner Controller

Aviso legal

Sobre os conjuntos de dimensionamento de executores

Os conjuntos de dimensionamento de executores são um grupo de executores homogêneos que podem receber trabalhos do GitHub Actions. O número de executores ativos pertencentes a um conjunto de dimensionamento de executores pode ser controlado por soluções de executor de dimensionamento automático, como o ARC (Actions Runner Controller).

Use grupos de executores para gerenciar conjuntos de dimensionamento de executores. De modo semelhante aos executores auto-hospedados, você pode adicionar conjuntos de dimensionamento de executores a grupos de executores existentes. No entanto, os conjuntos de dimensionamento de executores podem pertencer a apenas um grupo de executores por vez e não podem ter rótulos atribuídos. Para obter mais informações sobre os grupos de executores, confira "Gerenciar o acesso a executores auto-hospedados usando grupos".

Para atribuir trabalhos a um conjunto de dimensionamento de executores, você precisa configurar o fluxo de trabalho para referenciar o nome do conjunto de dimensionamento de executores. Para obter mais informações, confira "Usar executores do Controlador do Executor de Ações em um fluxo de trabalho".

Como implantar um conjunto de dimensionamento de executores

Para implantar um conjunto de dimensionamento de executores, você precisa ter o ARC em execução. Para obter mais informações, confira "Guia de início rápido do Actions Runner Controller".

Você pode implantar conjuntos de dimensionamento de executores com os gráficos do Helm do ARC ou implantando os manifestos necessários. O uso de gráficos do Helm do ARC é o método preferencial, especialmente se você não tem experiência anterior no uso do ARC.

1. Para configurar o conjunto de dimensionamento de executores, execute o comando a seguir no terminal usando valores da configuração do ARC.

   Ao executar o comando, tenha em mente as instruções a seguir.

   • Atualize o valor INSTALLATION_NAME com cuidado. Você usará o nome da instalação como o valor de runs-on nos seus fluxos de trabalho.

   • Atualize o valor NAMESPACE para o local em que deseja criar os pods do executor.

   • Defina o valor GITHUB_CONFIG_URL como a URL do repositório, da organização ou da empresa. Essa é a entidade à qual os executores pertencerão.

   • Este exemplo de comando instala a última versão do gráfico do Helm. Para instalar uma versão específica, transmita o argumento --version com a versão do gráfico que deseja instalar. Encontre a lista de versões no repositório actions-runner-controller.

     Bash

     INSTALLATION_NAME="arc-runner-set"
     NAMESPACE="arc-runners"
     GITHUB_CONFIG_URL="https://github.com/<your_enterprise/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 obter opções adicionais de configuração do Helm, confira values.yaml no repositório ARC.

2. Para verificar sua instalação, execute o comando a seguir no terminal.

   Bash

   helm list -A
   

   Você deverá ver um resultado semelhante ao seguinte.

   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 verificar o pod do gerenciador, execute o comando a seguir no terminal.

   Bash

   kubectl get pods -n arc-systems
   

   Se a instalação tiver sido bem-sucedida, os pods mostrarão o status 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
   

Se a instalação não tiver sido bem-sucedida, confira "Solução de problemas de erros do Controlador do Executor de Ações" para obter informações sobre solução de problemas.

Como usar as opções de configuração avançada

O ARC oferece várias opções de configuração avançada.

Como configurar o nome do conjunto de dimensionamento de executores

Para configurar o nome do conjunto de dimensionamento de executores, defina um INSTALLATION_NAME ou defina o valor de runnerScaleSetName na sua cópia do arquivo values.yaml.

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

Transmita o arquivo values.yaml no comando helm install. Confira a documentação instalação do Helm para obter mais detalhes.

Como escolher destinos do executor

Os conjuntos de dimensionamento de executores podem ser implantados nos níveis do repositório, da organização ou da empresa.

Para implantar conjuntos de dimensionamento de executores em um nível específico, defina o valor de githubConfigUrl na sua cópia do values.yaml como a URL do repositório, da organização ou da empresa.

O exemplo a seguir mostra como configurar o ARC para adicionar executores a octo-org/octo-repo.

githubConfigUrl: "https://github.com/octo-ent/octo-org/octo-repo"

Para obter opções adicionais de configuração do Helm, confira values.yaml no repositório ARC.

Como usar o GitHub App para a autenticação

Se você não estiver usando executores de nível empresarial, use os GitHub Apps para se autenticar com a API do GitHub. Para obter mais informações, confira "Como se autenticar na API do GitHub".

Você pode criar um segredo do Kubernetes ou especificar valores no arquivo values.yaml.

Opção 1: Criar um segredo do Kubernetes (recomendado)

Depois de criar o GitHub App, crie um segredo do Kubernetes e transmita a referência a esse segredo na sua cópia do arquivo 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-----********'

Na cópia do values.yaml, transmita o nome do segredo como uma referência.

githubConfigSecret: pre-defined-secret

Opção 2: Especificar valores no arquivo values.yaml

Como alternativa, você pode especificar os valores de app_id, installation_id e private_key na cópia do arquivo 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 obter opções adicionais de configuração do Helm, confira values.yaml no repositório ARC.

Como gerenciar o acesso com grupos de executores

Use grupos de executores para controlar quais organizações ou repositórios têm acesso aos conjuntos de dimensionamento de executores. Para obter mais informações sobre os grupos de executores, confira "Gerenciar o acesso a executores auto-hospedados usando grupos".

Para adicionar um conjunto de dimensionamento de executores a um grupo de executores, você já precisa ter criado um grupo de executores. Em seguida, defina a propriedade runnerGroup na sua cópia do arquivo values.yaml. O exemplo a seguir adiciona um conjunto de dimensionamento de executores ao grupo de executores Octo-Group.

runnerGroup: "Octo-Group"

Para obter opções adicionais de configuração do Helm, confira values.yaml no repositório ARC.

Como configurar um proxy de saída

Para forçar o tráfego HTTP para que o controlador e os executores passem pelo proxy de saída, defina as propriedades a seguir no gráfico do 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

O ARC dá suporte ao uso de proxies anônimos ou autenticados. Se você usar proxies autenticados, precisará definir o valor credentialSecretRef para referenciar um segredo do Kubernetes. Você pode criar um segredo com suas credenciais de proxy com o comando a seguir.

  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 obter opções adicionais de configuração do Helm, confira values.yaml no repositório ARC.

Como definir o número máximo e mínimo de executores

As propriedades maxRunners e minRunners fornecem uma variedade de opções para personalizar a configuração do ARC.

Exemplo: número desassociado de executores

Se você comentar as propriedades maxRunners e minRunners, o ARC aumentará para o número de trabalhos atribuídos ao conjunto de dimensionamento de executores e reduzirá para 0 se não houver trabalhos ativos.

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

## minRunners is the min number of runners the auto scaling runner set will scale down to.
# minRunners: 0

Exemplo: número mínimo de executores

Defina a propriedade minRunners com qualquer número e o ARC garantirá que haja, no mínimo, esse número de executores ativos e disponíveis para realizar trabalhos atribuídos ao conjunto de dimensionamento de executores o tempo todo.

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

## minRunners is the min number of runners the auto scaling runner set will scale down to.
minRunners: 20

Exemplo: definir o número máximo e mínimo de executores

Nessa configuração, o Actions Runner Controller aumentará para, no máximo, 30 executores e reduzirá para 20 executores quando os trabalhos forem concluídos.

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

## minRunners is the min number of runners the auto scaling runner set will scale down to.
minRunners: 20

Exemplo: esvaziamento da fila de trabalhos

Em alguns cenários, o ideal é esvaziar a fila de trabalhos para solucionar um problema ou para executar a manutenção do cluster. Se você definir ambas as propriedades como 0, o Actions Runner Controller não criará pods do executor quando novos trabalhos estiverem disponíveis e atribuídos.

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

## minRunners is the min number of runners the auto scaling runner set will scale down to.
minRunners: 0

Certificados TLS personalizados

Alguns ambientes exigem certificados TLS assinados por uma AC (autoridade de certificação) personalizada. Como os certificados de autoridade de certificação personalizados não são agrupados com os contêineres do controlador ou do executor, você precisa injetá-los nos respectivos repositórios confiáveis.

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

Ao fazer isso, verifique se você está usando o formato PEM (Privacy Enhanced Mail) e se a extensão do certificado é .crt. O restante será ignorado.

O controlador executa as ações a seguir.

• Cria um volume github-server-tls-cert que contém o certificado especificado em certificateFrom.
• Monta esse volume no caminho runnerMountPath/<certificate name>.
• Define a variável de ambiente NODE_EXTRA_CA_CERTS como esse mesmo caminho.
• Define a variável de ambiente RUNNER_UPDATE_CA_CERTS como 1 (a partir da versão 2.303.0, isso instruirá o executor a recarregar os certificados no host).

O ARC observa os valores definidos no modelo de pod do executor e não os substitui.

Para obter opções adicionais de configuração do Helm, confira values.yaml no repositório ARC.

Como usar o modo Docker-in-Docker ou Kubernetes para contêineres

Se você estiver usando trabalhos de contêiner e serviços ou ações de contêiner, o valor containerMode precisará ser definido como dind ou kubernetes.

• Para obter mais informações sobre os trabalhos e os serviços de contêiner, confira "Executar trabalhos em um contêiner".
• Para obter mais informações sobre as ações de contêiner, confira "Criando uma ação de contêiner do Docker".

Como usar o modo Docker-in-Docker

O modo Docker-in-Docker é uma configuração que permite executar o Docker dentro de um contêiner do Docker. Nessa configuração, para cada pod de executor criado, o ARC cria os contêineres a seguir.

• Um contêiner init
• Um contêiner runner
• Um contêiner dind

Para habilitar o modo Docker-in-Docker, defina o containerMode.type como dind conforme mostrado a seguir.

containerMode:
  type: "dind"

O template.spec será atualizado com a configuração padrão a seguir.

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:///run/docker/docker.sock
      volumeMounts:
        - name: work
          mountPath: /home/runner/_work
        - name: dind-sock
          mountPath: /run/docker
          readOnly: true
    - name: dind
      image: docker:dind
      args:
        - dockerd
        - --host=unix:///run/docker/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: /run/docker
        - name: dind-externals
          mountPath: /home/runner/externals
    volumes:
    - name: work
      emptyDir: {}
    - name: dind-sock
      emptyDir: {}
    - name: dind-externals
      emptyDir: {}

Não é possível substituir valores que são injetados automaticamente. Se você quiser personalizar essa configuração, terá que remover a definição de containerMode.type, copiar essa configuração e aplicá-la diretamente em sua cópia do arquivo values.yaml.

Para obter opções adicionais de configuração do Helm, confira values.yaml no repositório ARC.

Como usar o modo Kubernetes

No modo Kubernetes, o ARC usa ganchos de contêiner do executor para criar um pod no mesmo namespace para executar o serviço, o trabalho de contêiner ou a ação.

Pré-requisitos

O modo Kubernetes depende de volumes persistentes para compartilhar detalhes do trabalho entre o pod do executor e o pod do trabalho de contêiner. Confira a documentação Volumes persistentes do Kubernetes para obter mais informações.

Para usar o modo Kubernetes, você precisa executar as etapas a seguir.

• Crie volumes persistentes disponíveis para reivindicação dos pods do executor.
• Use uma solução para provisionar automaticamente volumes persistentes sob demanda.

Para o teste, você pode usar uma solução como o OpenEBS.

Como configurar o modo Kubernetes

Para habilitar o modo Kubernetes, defina o containerMode.type como kubernetes.

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

Para obter opções adicionais de configuração do Helm, confira values.yaml no repositório ARC.

Quando o modo Kubernetes estiver habilitado, ocorrerá uma falha nos fluxos de trabalho que não estiverem configurados com um trabalho de contêiner com um erro semelhante a:

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 os trabalhos sem um contêiner de trabalho sejam executados, você precisa instruir o executor a desabilitar essa verificação. Faça isso definindo ACTIONS_RUNNER_REQUIRE_JOB_CONTAINER como false no contêiner do executor:

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"

Como usar um registro de contêiner privado

Para usar um registro de contêiner privado, você pode copiar a imagem do controlador e a imagem do executor para o registro de contêiner privado. Em seguida, configure os links para essas imagens e defina os valores imagePullPolicy e imagePullSecrets.

Como configurar a imagem do controlador

Você pode atualizar sua cópia do arquivo values.yaml e definir as propriedades image conforme mostrado a seguir.

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>

O contêiner do ouvinte herda a imagePullPolicy definida para o controlador.

Como configurar a imagem do executor

Você pode atualizar sua cópia do arquivo values.yaml e definir as propriedades template.spec conforme mostrado a seguir.

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

Para obter opções adicionais de configuração do Helm, confira values.yaml no repositório ARC.

Como atualizar a especificação de pod para o pod do executor

Você pode personalizar totalmente a PodSpec do pod do executor e o controlador aplicará a configuração especificada. Veja a seguir um exemplo de especificação de pod.

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 obter opções adicionais de configuração do Helm, confira values.yaml no repositório ARC.

Habilitar métricas

O ARC pode emitir métricas para os executores, os trabalhos e o tempo gasto na execução dos fluxos de trabalho. As métricas podem ser usadas para identificar congestionamentos, monitorar a integridade da implantação do ARC, visualizar tendências de uso, otimizar o consumo de recursos, além de muitos outros casos de uso. As métricas são emitidas pelos pods controller-manager e listener no formato Prometheus. Para obter mais informações, consulte Formatos de exposição na documentação do Prometheus.

Para habilitar métricas no ARC, configure a propriedade metrics no arquivo values.yaml do gráfico do gha-runner-scale-set-controller.

A seguir, há um exemplo de configuração.

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

Depois que essas propriedades são configuradas, os pods controller-manager e listener emitem métricas por meio do listenerEndpoint associado às portas especificadas no arquivo values.yaml. No exemplo acima, o ponto de extremidade é /metrics e a porta é :8080. Você pode usar esse ponto de extremidade para extrair métricas dos pods controller-manager e listener.

Para desligar as métricas, atualize o arquivo values.yaml removendo ou comentando o objeto metrics: e suas propriedades.

Métricas disponíveis no ARC

As métricas emitidas pelos pods controller-manager e listener são exibidas na tabela a seguir.

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

Alta disponibilidade e failover automático

O ARC pode ser implantado em uma configuração de alta disponibilidade (ativo-ativo). Se você tiver dois clusters Kubernetes distintos implantados em regiões separadas, poderá implantar o ARC em ambos os clusters e configurar conjuntos de dimensionamento de executor para usar o mesmo runnerScaleSetName. Para fazer isso, cada conjunto de dimensionamento de executores deve ser atribuído a um grupo de executores distinto. Por exemplo, você pode ter dois conjuntos de dimensionamento de executores, cada um nomeado arc-runner-set, desde que um conjunto de dimensionamento de executores pertença a runner-group-A e o outro pertença a runner-group-B. Para obter informações sobre como atribuir conjuntos de dimensionamento de executores a grupos de executores, consulte "Gerenciar o acesso a executores auto-hospedados usando grupos".

Se os dois conjuntos de dimensionamento de executores estiverem online, os trabalhos atribuídos a eles serão distribuídos arbitrariamente (corrida de atribuição). Não é possível configurar o algoritmo de atribuição de trabalho. Se um dos clusters ficar inativo, o conjunto de dimensionamento de executores no outro cluster continuará a adquirir trabalhos normalmente sem qualquer intervenção ou alteração de configuração.

Como usar o ARC entre organizações

Uma instalação individual do Actions Runner Controller permite configurar um ou mais conjuntos de dimensionamento de executores. Esses conjuntos de dimensionamento de executores podem ser registrados em um repositório, uma organização ou uma empresa. Use também grupos de executores para controlar os limites de permissões desses conjuntos de dimensionamento de executores.

Como melhor prática, crie um namespace exclusivo para cada organização. Você também pode criar um namespace para cada grupo de executores ou cada conjunto de dimensionamento de executores. Você pode instalar quantos conjuntos de dimensionamento de executores forem necessários em cada namespace. Isso vai fornecer os níveis mais altos de isolamento e aprimorar sua segurança. Use os GitHub Apps para autenticação e defina permissões granulares para cada conjunto de dimensionamento de executores.

Aviso legal

Partes foram adaptadas do https://github.com/actions/actions-runner-controller/ de acordo com a licença 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.