28 de janeiro de 2025 Wallison Barbosa 299 Views

GitHub Actions – Self-Hosted Runner no Kubernetes

O GitHub Actions é uma plataforma de integração contínua (CI) e entrega contínua (CD) que faz parte do GitHub. Ele permite automatizar fluxos de trabalho diretamente no repositório, como testes, builds, deploys e outras tarefas repetitivas, sem precisar de ferramentas externas.

No GitHub Actions, um runner é o ambiente onde os jobs de um workflow são executados. Existem duas opções principais de runners: GitHub Hosted Runners e Self-Hosted Runners. A diferença entre eles está na infraestrutura, controle e customização que você tem sobre o ambiente de execução.

GitHub Hosted Runners

Os GitHub Hosted Runners são fornecidos e gerenciados diretamente pelo GitHub. Ou seja, o GitHub cuida da infraestrutura, manutenção, e configuração do ambiente onde seus jobs serão executados.

Vantagens:

Facilidade de uso: Não é necessário se preocupar com a configuração ou manutenção de servidores.
Escalabilidade: Como o GitHub gerencia os runners, a infraestrutura pode facilmente escalar conforme a necessidade.
Variedade de Ambientes: Vem com uma ampla variedade de imagens de sistemas operacionais e ferramentas já configuradas (por exemplo, Ubuntu, macOS, Windows).

Desvantagens:

Falta de personalização: Não é possível alterar a configuração do runner ou instalar software personalizado de forma persistente entre execuções. Cada execução começa com um ambiente limpo.
Limitação de tempo e recursos: Existe um limite para a quantidade de tempo e recursos disponíveis para cada execução, especialmente em planos gratuitos.

Self-Hosted Runners

Os Self-Hosted Runners são runners que você configura e gerencia em sua própria infraestrutura, seja em servidores próprios, máquinas virtuais, ou até mesmo em containers. Esses runners podem ser personalizados conforme as necessidades específicas do seu projeto ou da sua organização.

Vantagens:

Personalização: Ideal para projetos que precisam de ferramentas ou dependências específicas que não estão disponíveis em GitHub Hosted Runners.
Maior controle sobre a infraestrutura: Como você controla a máquina, pode ajustar recursos (CPU, RAM) conforme necessário, e até mesmo manter o estado da máquina entre as execuções.
Economia de tempo em builds grandes: Para builds ou testes longos, você pode configurar caches ou otimizações para evitar a necessidade de configurar o ambiente do zero a cada execução.

Desvantagens:

Gerenciamento e manutenção: Você precisa configurar e manter o servidor ou máquina que roda o runner, o que pode ser mais trabalhoso e exigir monitoramento.
Infraestrutura adicional: Se você não tiver infraestrutura própria, pode ter que gerenciar a infraestrutura na nuvem ou em servidores locais, o que pode aumentar os custos e o gerenciamento.

Ambos têm suas vantagens e desvantagens, e a escolha depende das necessidades específicas do seu projeto.

Neste artigo veremos como implementar Self-Hosted Runner no Kubernetes utilizando o ARC (Actions Runner Controller)

Pré-requisitos

Cluster Kubernetes
Helm 3

Instalando o Actions Runner Controller

O Actions Runner Controller (ARC) atua como um operator no Kubernetes que orquestra e dimensiona self-hosted runners para o GitHub Actions.

Faremos a instalação do controller utilizando o Helm:

helm install arc \
    --namespace arc-controller \
    --create-namespace \
    oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set-controller

Autenticando na API do GitHub

Para que o controller consiga registrar os runners na API do GitHub, precisamos configurar a autenticação. Para isso, podemos utilizar um Github App, para registrar os runners a nível de organização, ou utilizar um PAT, para utilizar os runners a nível de repositório.

Nesse artigo iremos criar um GitHub App. Caso deseje utilizar um PAT, visite a documentação oficial do GitHub.

Criando um GitHub App

Vá até a url da sua organização no GitHub e clique em Settings

No canto inferior esquerdo, expanda o item Developer settings e clique em GitHub Apps

Crie um novo GitHub App e defina um nome para o mesmo.

Em Homepage URL defina como https://github.com/actions/actions-runner-controller

Em Permissions devemos garantir as seguintes permissões:

Repositoru permissions
- Metadata: Read-only
Organization permissions
- Self-hosted runners: Read and write

Após a criação do GitHub App, seremos redirecionados para uma nova página contendo algumas informações sobre o processo que executamos. Nessa página, anote o valor do App ID.

Ainda na mesma página, em Private keys clique no botão para gerar uma nova chave e faça o download do arquivo .pem.

No menu lateral localizado no canto superior esquedo da página clique em Install app e faça a instalação do app na sua organização.

Após a confirmação da instalação na sua organização, guarde o valor do Installation ID, também iremos precisar dessa informação.

Em posse do app ID, installation ID e da chave .pem, iremos criar uma secret no Kubernetes com o seguinte comando:

kubectl create secret generic arc-controller-manager \
   --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-----********'

Note que, neste exemplo, estou utilizando namespaces diferentes para o arc-controller e para o arc-runners.

Configurando os runners

Para configurar os runners, primeiro iremos fazer o download do arquivo values.yaml disponível no repositório oficial para utilizarmos como base da nossa configuração.

O arquivo com as mínimas configurações ficaria dessa forma:

githubConfigUrl: "https://github.com/fsociety-xyz"
githubConfigSecret: arc-controller-manager
template:
  spec:
    containers:
      - name: runner
        image: ghcr.io/actions/actions-runner:latest
        command: ["/home/runner/run.sh"]

Nele alteramos o parâmetro githubConfigUrl com a URL da nossa organização e o githubConfigSecret com o nome da secret que criamos na etapa anterior.

Em template podemos definir a configuração dos nossos runners.

Para fazer a instalação, novamente utilizaremos o Helm:

INSTALLATION_NAME="arc-runners"
NAMESPACE="arc-runners"
helm install "${INSTALLATION_NAME}" \
    --namespace "${NAMESPACE}" \
    --create-namespace \
    --values values.yaml \
    oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set

Se atente ao INSTALLATION_NAME, iremos utilizar esse nome como valor do runs-on nos nossos workflows.

Ao executar o comando kubectl get pods -n arc-runners poderemos ver que não há nenhum pod rodando nesse namespace. Isso acontece porque o pod somente será criado durante a execução de algum workflow e será removido instantaneamente após a finalização do mesmo. Essa é a mágica por trás do ARC, teremos um pod para cada workflow em execução, podendo paralelizar ao máximo as nossas pipelines.

Testando os runners

Para testar a criação e execução dos runners, iremos criar um workflow simples que utilize os runners que acabamos de configurar.

Em um repositório qualquer dentro da organização, podemos criar o arquivo test-runner.yaml dentro do diretório .github/workflows/ com o seguinte conteúdo:

name: Actions Runner Controller Demo
on:
  workflow_dispatch:

jobs:
  Explore-GitHub-Actions:
    runs-on: arc-runners
    steps:
    - run: echo "🎉 Esse job utiliza um runner criado pelo ARC!"

Faça o push dessa alteração para o repositório e execute o workflow manualmente.

Durante a execução do mesmo, podemos rodar novamente o comando kubectl get pods -n arc-runners e, dessa vez, pelo menos um pod deverá estar rodando:

❯ kubectl get pods -n arc-runners
NAME                                READY   STATUS    RESTARTS   AGE
arc-runner-set-xwvwr-runner-dk5lf   1/1     Running   0          6s