Sobre o Actions Runner Controller
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".
O diagrama a seguir ilustra a arquitetura do modo de conjunto de dimensionamento automático do executor do ARC.
Nota: para exibir o diagrama a seguir em um tamanho maior, confira a documentação Modo Conjuntos de Dimensionamento do Executor de Dimensionamento Automático no repositório Controlador do Executor de Ações.
- Actions Runner Controller é instalado usando os gráficos do Helm fornecidos e o pod de gerenciador de controlador é implantado no namespace especificado. Um novo recurso AutoScalingRunnerSet é implantado por meio dos gráficos do Helm fornecidos ou de um arquivo de manifesto personalizado. O Controlador AutoScalingRunnerSet chama as APIs do GitHub para buscar a ID do grupo de executores à qual o conjunto de dimensionamento do executor pertencerá.
- O Controlador AutoScalingRunnerSet chama as APIs mais uma vez para buscar ou criar um conjunto de dimensionamento de executores no serviço GitHub Actions antes de criar o recurso Ouvinte ScaleSet do Executor.
- Um pod Ouvinte ScaleSet do Executor é implantado pelo controlador AutoScalingListener. Nesse pod, o aplicativo de ouvinte se conecta ao serviço GitHub Actions para autenticar e estabelecer uma conexão de sondagem longa HTTPS. O ouvinte permanece ocioso até receber uma mensagem
Job Available
do serviço GitHub Actions. - Quando uma execução de fluxo de trabalho é disparada de um repositório, o serviço GitHub Actions despacha execuções de trabalho individuais para os executores ou conjuntos de dimensionamento de executor em que a chave
runs-on
corresponde ao nome do conjunto de dados do executor ou rótulos de executores auto-hospedados. - Quando o Ouvinte ScaleSet do Executor recebe a mensagem
Job Available
, ele verifica se ele pode escalar verticalmente para a contagem desejada. Se for possível, o Ouvinte ScaleSet do Executor reconhecerá a mensagem. - O Ouvinte ScaleSet do Executor usa uma Conta de Serviço e uma Função associada a essa conta para fazer uma chamada HTTPS por meio das APIs do Kubernetes para aplicar patch ao recurso RunnerSet Efêmero com o número de réplicas desejadas.
- O RunnerSet Efêmero tenta criar executores e o Controlador EphemeralRunner solicita um token de configuração JIT (Just-In-Time) para registrar esses executores. O controlador tenta criar pods do executor. Se o status do pod for
failed
, o controlador tentará novamente até 5 vezes. Após 24 horas, o serviço GitHub Actions cancelará a atribuição do trabalho se nenhum executor o aceitar. - Depois que o pod do executor é criado, o aplicativo executor no pod usa o token de configuração JIT para se registrar no serviço GitHub Actions. Em seguida, ele estabelece outra conexão de sondagem longa HTTPS para receber os detalhes do trabalho que precisa executar.
- O serviço GitHub Actions reconhece o registro do executor e envia os detalhes da execução do trabalho.
- Durante toda a execução do trabalho, o executor comunica continuamente os logs e a execução do trabalho status de volta para o serviço GitHub Actions.
- Quando o executor conclui o trabalho com êxito, o Controlador EphemeralRunner verifica com o serviço GitHub Actions para ver se o executor pode ser excluído. Se puder, o RunnerSet Efêmero excluirá o executor.
Componentes do Actions Runner Controller
O ARC consiste em um conjunto de recursos, alguns dos quais criados especificamente para ele. A implantação do ARC aplica esses recursos personalizados a um cluster do Kubernetes. Uma vez aplicado, ele cria um conjunto de Pods que contêm os contêineres dos executores auto-hospedados. Com o ARC, o GitHub pode tratar esses contêineres do executor como executores auto-hospedados e alocar trabalhos a eles conforme necessário.
Cada recurso implantado pelo ARC recebe um nome formado por estes elementos:
- O nome da instalação, que é o nome que você especifica ao instalar o gráfico do Helm.
- um sufixo de identificação do recurso, que é uma cadeia de caracteres que identifica o tipo de recurso. Este valor não é configurável.
Observação: versões diferentes do Kubernetes têm limites de comprimento diferentes para os nomes dos recursos. O limite do comprimento do nome do recurso é calculado adicionando o comprimento do nome da instalação ao comprimento do sufixo de identificação do recurso. Se o nome do recurso for maior que o comprimento reservado, você receberá uma mensagem de erro.
Recursos implantados por gha-runner-scale-set-controller
Modelo | Tipo de recurso | Nome | Comprimento reservado | Descrição | Observações |
---|---|---|---|---|---|
deployment.yaml | Implantação | INSTALLATION_NAME-gha-rs-controller | 18 | O recurso que executa o gerenciador do controlador | Os pods criados por esse recurso têm os sufixos ReplicaSet e Pod. |
serviceaccount.yaml | ServiceAccount | INSTALLATION_NAME-gha-rs-controller | 18 | Esse recurso será criado se serviceAccount.create em values.yaml estiver definido como verdadeiro. | O nome pode ser personalizado em values.yaml |
manager_cluster_role.yaml | ClusterRole | INSTALLATION_NAME-gha-rs-controller | 18 | ClusterRole do gerenciador do controlador | Esse recurso será criado se o valor de flags.watchSingleNamespace estiver vazio. |
manager_cluster_role_binding.yaml | ClusterRoleBinding | INSTALLATION_NAME-gha-rs-controller | 18 | ClusterRoleBinding do gerenciador do controlador | Esse recurso será criado se o valor de flags.watchSingleNamespace estiver vazio. |
manager_single_namespace_controller_role.yaml | Função | INSTALLATION_NAME-gha-rs-controller-single-namespace | 35 | Função do gerenciador do controlador | Esse recurso será criado se for definido um valor para flags.watchSingleNamespace . |
manager_single_namespace_controller_role_binding.yaml | RoleBinding | INSTALLATION_NAME-gha-rs-controller-single-namespace | 35 | RoleBinding do gerenciador do controlador | Esse recurso será criado se for definido um valor para flags.watchSingleNamespace . |
manager_single_namespace_watch_role.yaml | Função | INSTALLATION_NAME-gha-rs-controller-single-namespace-watch | 41 | Função do gerenciador do controlador no namespace configurado | Esse recurso será criado se for definido um valor para flags.watchSingleNamespace . |
manager_single_namespace_watch_role_binding.yaml | RoleBinding | INSTALLATION_NAME-gha-rs-controller-single-namespace-watch | 41 | RoleBinding do gerenciador do controlador no namespace configurado | Esse recurso será criado se for definido um valor para flags.watchSingleNamespace . |
manager_listener_role.yaml | Função | INSTALLATION_NAME-gha-rs-controller-listener | 26 | Função do ouvinte | Esse recurso é sempre criado. |
manager_listener_role_binding.yaml | RoleBinding | INSTALLATION_NAME-gha-rs-controller-listener | 26 | RoleBinding do ouvinte | Esse recurso é sempre criado e associa a função de ouvinte à conta de serviço, que é criada por serviceaccount.yaml ou configurada com values.yaml . |
Recursos implantados por gha-runner-scale-set
Modelo | Tipo de recurso | Nome | Comprimento reservado | Descrição | Observações |
---|---|---|---|---|---|
autoscalingrunnerset.yaml | AutoscalingRunnerSet | INSTALLATION_NAME | 0 | Recurso de nível superior ao se trabalhar com conjuntos de dimensionamento | O comprimento do nome está limitado a 45 caracteres. |
no_permission_service_account.yaml | ServiceAccount | INSTALLATION_NAME-gha-rs-no-permission | 21 | Conta de serviço criada no contêiner do executor | Esse recurso será criado se o modo do contêiner não for "kubernetes" e template.spec.serviceAccountName não for especificado. |
githubsecret.yaml | Segredo | INSTALLATION_NAME-gha-rs-github-secret | 20 | Segredo que contém os valores necessários para fazer autenticações na API do GitHub | Esse recurso será criado se githubConfigSecret for um objeto. Se for fornecida uma cadeia de caracteres, o segredo não será criado. |
manager_role.yaml | Função | INSTALLATION_NAME-gha-rs-gerente | 15 | Função fornecida ao gerenciador para permitir a reconciliação de recursos no namespace do conjunto de executores de dimensionamento automático | Esse recurso é sempre criado. |
manager_role_binding.yaml | RoleBinding | INSTALLATION_NAME-gha-rs-gerente | 15 | Associa manager_role à conta de serviço do gerenciador. | Esse recurso é sempre criado. |
kube_mode_role.yaml | Função | INSTALLATION_NAME-gha-rs-kube-modo | 17 | Função que fornece as permissões necessárias para o gancho | Esse recurso é criado quando o modo do contêiner é definido como "kubernetes" e template.spec.serviceAccount não é fornecido. |
kube_mode_serviceaccount.yaml | ServiceAccount | INSTALLATION_NAME-gha-rs-kube-modo | 17 | Conta de serviço associada ao pod do executor. | Esse recurso é criado quando o modo do contêiner é definido como "kubernetes" e template.spec.serviceAccount não é fornecido. |
Sobre recursos personalizados
O ARC consiste em várias CRDs (definições de recursos personalizados). Para obter mais informações sobre recursos personalizados, confira Recursos personalizados na documentação do Kubernetes. Você pode encontrar a lista de definições de recursos personalizados usadas para ARC nas definições de esquema de API a seguir.
Como os recursos personalizados são extensões da API do Kubernetes, eles não estarão disponíveis em uma instalação do Kubernetes padrão. Você precisará instalar esses recursos personalizados para usar o ARC. Para obter mais informações sobre como instalar recursos personalizados, confira "Guia de início rápido do Actions Runner Controller".
Depois que os recursos personalizados forem instalados, você poderá implantar o ARC no cluster do Kubernetes. Para saber mais sobre como implantar o ARC, confira "Como implantar conjuntos de dimensionamento de executores com o Actions Runner Controller".
Sobre a imagem de contêiner do executor
O GitHub mantém uma imagem de contêiner do executor mínima. Uma nova imagem será publicada com cada versão de binários do executor. A imagem mais recente terá a versão de binários do executor e latest
como tags.
Essa imagem contém a menor quantidade de pacotes necessários para o runtime de contêiner e os binários do executor. Para instalar software adicional, você poderá criar sua imagem de executor. Você pode usar a imagem do executor do ARC como base ou usar as ações de configuração correspondentes. Por exemplo, actions/setup-java
para Java ou actions/setup-node
para Node.
Você pode encontrar a definição da imagem do executor do ARC neste Dockerfile e a definição da imagem base neste Dockerfile.
Criar sua imagem do executor
Você pode criar sua imagem de executor que atenda às suas necessidades. A imagem do executor deve atender às condições a seguir.
- Use uma imagem base que possa executar o aplicativo executor auto-hospedado. Para obter mais informações, confira "Sobre executores auto-hospedados".
- O binário do executor deve ser colocado em
/home/runner/
e iniciado usando/home/runner/run.sh
. - Se você usar o modo Kubernetes, os ganchos de contêiner do executor deverão ser colocados em
/home/runner/k8s
.
Você pode usar o Dockerfile de exemplo a seguir para começar a criar sua imagem de executor.
FROM mcr.microsoft.com/dotnet/runtime-deps:6.0 as build # Replace value with the latest runner release version # source: https://github.com/actions/runner/releases # ex: 2.303.0 ARG RUNNER_VERSION="" ARG RUNNER_ARCH="x64" # Replace value with the latest runner-container-hooks release version # source: https://github.com/actions/runner-container-hooks/releases # ex: 0.3.1 ARG RUNNER_CONTAINER_HOOKS_VERSION="" ENV DEBIAN_FRONTEND=noninteractive ENV RUNNER_MANUALLY_TRAP_SIG=1 ENV ACTIONS_RUNNER_PRINT_LOG_TO_STDOUT=1 RUN apt update -y && apt install curl unzip -y RUN adduser --disabled-password --gecos "" --uid 1001 runner \ && groupadd docker --gid 123 \ && usermod -aG sudo runner \ && usermod -aG docker runner \ && echo "%sudo ALL=(ALL:ALL) NOPASSWD:ALL" > /etc/sudoers \ && echo "Defaults env_keep += \"DEBIAN_FRONTEND\"" >> /etc/sudoers WORKDIR /home/runner RUN curl -f -L -o runner.tar.gz https://github.com/actions/runner/releases/download/v${RUNNER_VERSION}/actions-runner-linux-${RUNNER_ARCH}-${RUNNER_VERSION}.tar.gz \ && tar xzf ./runner.tar.gz \ && rm runner.tar.gz RUN curl -f -L -o runner-container-hooks.zip https://github.com/actions/runner-container-hooks/releases/download/v${RUNNER_CONTAINER_HOOKS_VERSION}/actions-runner-hooks-k8s-${RUNNER_CONTAINER_HOOKS_VERSION}.zip \ && unzip ./runner-container-hooks.zip -d ./k8s \ && rm runner-container-hooks.zip USER runner
FROM mcr.microsoft.com/dotnet/runtime-deps:6.0 as build
# Replace value with the latest runner release version
# source: https://github.com/actions/runner/releases
# ex: 2.303.0
ARG RUNNER_VERSION=""
ARG RUNNER_ARCH="x64"
# Replace value with the latest runner-container-hooks release version
# source: https://github.com/actions/runner-container-hooks/releases
# ex: 0.3.1
ARG RUNNER_CONTAINER_HOOKS_VERSION=""
ENV DEBIAN_FRONTEND=noninteractive
ENV RUNNER_MANUALLY_TRAP_SIG=1
ENV ACTIONS_RUNNER_PRINT_LOG_TO_STDOUT=1
RUN apt update -y && apt install curl unzip -y
RUN adduser --disabled-password --gecos "" --uid 1001 runner \
&& groupadd docker --gid 123 \
&& usermod -aG sudo runner \
&& usermod -aG docker runner \
&& echo "%sudo ALL=(ALL:ALL) NOPASSWD:ALL" > /etc/sudoers \
&& echo "Defaults env_keep += \"DEBIAN_FRONTEND\"" >> /etc/sudoers
WORKDIR /home/runner
RUN curl -f -L -o runner.tar.gz https://github.com/actions/runner/releases/download/v${RUNNER_VERSION}/actions-runner-linux-${RUNNER_ARCH}-${RUNNER_VERSION}.tar.gz \
&& tar xzf ./runner.tar.gz \
&& rm runner.tar.gz
RUN curl -f -L -o runner-container-hooks.zip https://github.com/actions/runner-container-hooks/releases/download/v${RUNNER_CONTAINER_HOOKS_VERSION}/actions-runner-hooks-k8s-${RUNNER_CONTAINER_HOOKS_VERSION}.zip \
&& unzip ./runner-container-hooks.zip -d ./k8s \
&& rm runner-container-hooks.zip
USER runner
Executar fluxos de trabalho
Depois que a instalação e a configuração forem concluídas, você poderá usar o ARC para realizar execuções de fluxo de trabalho. Um fluxo de trabalho pode ser criado no mesmo repositório que pode ter como destino um executor auto-hospedado criado pelo ARC. Para obter mais informações sobre como direcionar fluxos de trabalho para realizar em executores auto-hospedados, confira "Usar os executores auto-hospedados em um fluxo de trabalho".
Usar executores ARC em um fluxo de trabalho
Você não pode usar rótulos adicionais para direcionar executores criados pelo ARC. Você só pode usar o nome da instalação do conjunto de dimensionamento do executor especificado durante a instalação ou definindo o valor do campo runnerScaleSetName
em seu arquivo values.yaml
. Estes são usados como o "rótulo único" para usar como seu destino runs-on
. Para obter mais informações, confira "Usar executores do Controlador do Executor de Ações em um fluxo de trabalho".
Executores de dimensionamento
Você pode dimensionar executores estaticamente ou dinamicamente, dependendo de suas necessidades. Para obter mais informações, confira "Como implantar conjuntos de dimensionamento de executores com o Actions Runner Controller".
Software instalado na imagem do executor ARC
A imagem do executor ARC é agrupada com o seguinte software:
- Binários do executor
- Ganchos de contêiner do executor
- Docker (necessário para o modo Docker-in-Docker)
Para obter mais informações, confira Dockerfile da imagem do executor do ARC no repositório Ações.
Ativos e lançamentos
O ARC é lançado como dois gráficos do Helm e uma imagem de contêiner. Os gráficos do Helm são publicados apenas como pacotes do Open Container Initiative (OCI). O ARC não fornece tarballs ou repositórios do Helm em GitHub Pages.
Você pode encontrar as versões mais recentes dos gráficos do Helm e da imagem do contêiner do ARC em GitHub Packages:
- Gráfico do Helm
gha-runner-scale-set-controller
. - Gráfico do Helm
gha-runner-scale-set
. - Imagem do contêiner
gha-runner-scale-set-controller
A imagem de executor compatível é lançada como uma imagem de contêiner separada e pode ser encontrada em actions-runner
em GitHub Packages.
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.