Guia de início rápido do Actions Runner Controller

Introdução

O Actions Runner Controller (ARC) é um operador Kubernetes que orquestra e dimensiona executores auto-hospedados para o GitHub Actions. Para obter mais informações, confira Padrão do operador da documentação do Kubernetes.

Com o ARC, você pode criar conjuntos de dimensionamento de executores que são dimensionados automaticamente com base no número de fluxos de trabalho em execução em seu repositório, organização ou empresa. Como os executores controlados podem ser efêmeros e baseados em contêineres, novas instâncias do executor podem expandir ou reduzir rapidamente e de forma limpa. Para obter mais informações sobre o dimensionamento automático, confira "Redimensionamento automático com executores auto-hospedados".

Você pode configurar o ARC no Kubernetes usando o Helm e, em seguida, criar e executar um fluxo de trabalho que usa conjuntos de dimensionamento de executores. Para obter mais informações sobre os conjuntos de dimensionamento de executores, confira Como implantar conjuntos de dimensionamento de executores com o Actions Runner Controller.

Pré-requisitos

Para usar o ARC, verifique se você tem os itens a seguir.

Um cluster do Kubernetes
- Para um ambiente de nuvem gerenciado, você pode usar o AKS. Para obter mais informações, confira Serviço de Kubernetes do Azure na documentação do Azure.
- Para uma configuração local, você pode usar o minikube ou o kind. Para obter mais informações, confira minikube start na documentação do minikube e kind na documentação do kind.
  
  Note
  
  Os clusters OpenShift não têm suporte no momento.
Helm 3
- Para obter mais informações, confira Como instalar o Helm na documentação do Helm.
Embora não seja necessário implantar o ARC, é recomendável garantir que você tenha uma maneira de coletar e reter logs do controlador, dos ouvintes e dos executores efêmeros antes de implantar o ARC em fluxos de trabalho da produção.

Como instalar o Actions Runner Controller

Para instalar o operador e as CRDs (definições de recursos personalizados) no cluster, execute as etapas a seguir.
1. No gráfico do Helm, atualize o valor NAMESPACE para o local em que deseja criar os pods do operador. Esse namespace precisa permitir o acesso ao servidor de API do Kubernetes.
2. Instale o gráfico do Helm.
O exemplo a seguir instala a última versão do gráfico. 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 Registro de Contêiner do GitHub.
Bash
```
NAMESPACE="arc-systems"
helm install arc \
    --namespace "${NAMESPACE}" \
    --create-namespace \
    oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set-controller
```
```
NAMESPACE="arc-systems"
helm install arc \
    --namespace "${NAMESPACE}" \
    --create-namespace \
    oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set-controller
```
Para ver mais opções de configuração do Helm, confira values.yaml na documentação do ARC.
Para permitir que o ARC se autentique no GitHub, gere um personal access token (classic). Para saber mais, confira Como se autenticar na API do GitHub.

Como configurar um conjunto de dimensionamento de executores

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. Para saber mais, confira Sintaxe de fluxo de trabalho para o GitHub Actions.
- Atualize o valor NAMESPACE para o local em que deseja que os pods do executor sejam criados.
- Defina 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 Registro de Contêiner do GitHub.
  Note
  - Como uma melhor prática de segurança, crie os pods do executor em um namespace diferente do namespace que contém os pods do operador.
  - Como uma melhor prática de segurança, crie segredos do Kubernetes e passe as referências secretas. Passar seus segredos em texto sem formatação por meio da CLI pode representar um risco à segurança. Para obter mais informações, confira Como implantar conjuntos de dimensionamento de executores com o 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
```
```
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 ver mais opções de configuração do Helm, confira values.yaml na documentação do ARC.

No terminal, execute o comando a seguir para verificar sua instalação.

Bash

helm list -A

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-runners     1               2023-04-12 11:46:13.451041354 +0000 UTC deployed        gha-runner-scale-set-0.4.0                  0.4.0

Para verificar o pod do gerenciador, execute o comando a seguir no terminal.

Bash

kubectl get pods -n arc-systems

kubectl get pods -n arc-systems

Se tudo tiver sido instalado com sucesso, a status dos pods será exibido como Em execução.

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 conjuntos de dimensionamento de executores

Agora você criará e executará um fluxo de trabalho de teste simples que usa os executores do conjunto de dimensionamento de executores.

Em um repositório, crie um fluxo de trabalho semelhante ao exemplo a seguir. O valor runs-on deve corresponder ao nome de instalação do Helm usado quando você instalou o conjunto de executores de dimensionamento automático.

Para obter mais informações sobre como adicionar fluxos de trabalho a um repositório, confira Início rápido para GitHub Actions.

YAML

name: Actions Runner Controller Demo
on:
  workflow_dispatch:

jobs:
  Explore-GitHub-Actions:
    # You need to use the INSTALLATION_NAME from the previous step
    runs-on: arc-runner-set
    steps:
    - run: echo "🎉 This job uses runner scale set runners!"

name: Actions Runner Controller Demo
on:
  workflow_dispatch:

jobs:
  Explore-GitHub-Actions:
    # You need to use the INSTALLATION_NAME from the previous step
    runs-on: arc-runner-set
    steps:
    - run: echo "🎉 This job uses runner scale set runners!"

Depois de adicionar o fluxo de trabalho ao repositório, dispare manualmente o fluxo de trabalho. Para saber mais, confira Executar um fluxo de trabalho manualmente.

Para ver os pods do executor que estão sendo criados enquanto o fluxo de trabalho está em execução, execute o comando a seguir no terminal.

Bash

kubectl get pods -n arc-runners

kubectl get pods -n arc-runners

Uma saída bem-sucedida será semelhante à seguinte.

NAMESPACE     NAME                                                  READY   STATUS    RESTARTS      AGE
arc-runners   arc-runner-set-rmrgw-runner-p9p5n                     1/1     Running   0             21s

Próximas etapas

O Actions Runner Controller pode ajudar você a gerenciar com eficiência seus executores do GitHub Actions. Pronto para começar? Confira alguns recursos úteis para dar seus próximos passos com o ARC:

Para obter informações detalhadas sobre autenticação, confira Como se autenticar na API do GitHub.
Para obter ajuda no uso de executores do ARC nos fluxos de trabalho, confira Usar executores do Controlador do Executor de Ações em um fluxo de trabalho.
Para obter informações sobre a implantação, consulte Como implantar conjuntos de dimensionamento de executores com o Actions Runner Controller.

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.

Neste artigo

Introdução

Pré-requisitos

Como instalar o Actions Runner Controller

Como configurar um conjunto de dimensionamento de executores

Como usar conjuntos de dimensionamento de executores

Próximas etapas

Aviso legal