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 escalas do corredor podem pertencer a apenas um grupo de corredores por vez e só podem ter uma etiqueta atribuída a eles. 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.
Observações:
- 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.
- Recomendamos executar cargas de trabalho de produção isoladamente. Os fluxos de trabalho do GitHub Actions foram projetados para executar códigos arbitrários, e o uso de um cluster compartilhado do Kubernetes para cargas de trabalho de produção pode representar um risco à segurança.
- Certifique-se de que implementou uma maneira de coletar e reter logs do controlador, dos ouvintes e dos executores efêmeros.
-
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 deruns-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órioactions-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
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 obter opções adicionais de configuração do Helm, confira
values.yaml
no repositório ARC.
-
-
Para verificar sua instalação, execute o comando a seguir no terminal.
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-systems 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 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
Observação: os nomes do conjunto de dimensionamento de executores são exclusivos no grupo de executores ao qual pertencem. Caso deseje implantar vários conjuntos de dimensionamento de executores com o mesmo nome, eles precisam pertencer a diferentes grupos 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.
Observação: você só pode implantar conjuntos de dimensionamento de executores no nível empresarial ao usar a autenticação do personal access token (classic).
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: "http(s)://<HOSTNAME>/<'enterprises/your_enterprise'/'org'/'org/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".
Observação: considerando o risco de segurança associado à exposição da sua chave privada em texto sem formatação em um arquivo em disco, recomendamos criar um segredo do Kubernetes e transmitir a referência.
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
.
Nota: crie o segredo no mesmo namespace onde o gráfico gha-runner-scale-set
está instalado. Neste exemplo, o namespace é arc-runners
para corresponder à documentação de início rápido. Para obter mais informações, confira "Guia de início rápido do Actions Runner Controller".
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.
Nota: crie o segredo no mesmo namespace onde o gráfico gha-runner-scale-set
está instalado. Neste exemplo, o namespace é arc-runners
para corresponder à documentação de início rápido. Para obter mais informações, confira "Guia de início rápido do Actions Runner Controller".
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.
Observação: o ARC não dá suporte a configurações máxima e mínima agendadas. Use um cronjob ou qualquer outra solução de agendamento para atualizar a configuração em um agendamento.
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 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
Exemplo: número mínimo de executores
Você pode definir a propriedade minRunners
com qualquer número e o ARC garantirá que sempre haverá o número específico 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 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
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.
Observação: o valor de minRunners
nunca pode exceder o de maxRunners
, a menos maxRunners
que seja comentado.
## 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
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 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
Certificados TLS personalizados
Observação: se você estiver usando uma imagem de executor personalizada que não se baseie na distribuição Debian
, as instruções a seguir não funcionarão.
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 emcertificateFrom
. - 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
como1
(a partir da versão2.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 um registro de contêiner privado
Aviso: essa opção de personalização do Actions Runner Controller pode estar fora do escopo do que o Suporte do GitHub pode ajudar e pode causar um comportamento inesperado quando configurada incorretamente.
Para obter mais informações sobre com o que o Suporte do GitHub pode te ajudar, consulte Sobre o suporte para o Actions Runner Controller.
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"]
imagePullSecrets:
- name: <registry-secret-name>
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
Aviso: essa opção de personalização do Actions Runner Controller pode estar fora do escopo do que o Suporte do GitHub pode ajudar e pode causar um comportamento inesperado quando configurada incorretamente.
Para obter mais informações sobre com o que o Suporte do GitHub pode te ajudar, consulte Sobre o suporte para o Actions Runner Controller.
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.
Como atualizar a especificação de pod para o pod do ouvinte
Aviso: essa opção de personalização do Actions Runner Controller pode estar fora do escopo do que o Suporte do GitHub pode ajudar e pode causar um comportamento inesperado quando configurada incorretamente.
Para obter mais informações sobre com o que o Suporte do GitHub pode te ajudar, consulte Sobre o suporte para o Actions Runner Controller.
Você pode personalizar o PodSpec do pod do ouvinte e o controlador aplicará a configuração especificada. Veja a seguir um exemplo de especificação de pod.
É importante não alterar o valor listenerTemplate.spec.containers.name
do contêiner ouvinte. Caso contrário, a configuração especificada será aplicada a um novo contêiner side-car.
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 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
Aviso: essa opção de personalização do Actions Runner Controller pode estar fora do escopo do que o Suporte do GitHub pode ajudar e pode causar um comportamento inesperado quando configurada incorretamente.
Para obter mais informações sobre com o que o Suporte do GitHub pode te ajudar, consulte Sobre o suporte para o Actions Runner Controller.
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
Observação: o contêiner do Docker-in-Docker exige o modo privilegiado. Para obter mais informações, confira Configurar um contexto de segurança para um pod ou um contêiner na documentação do Kubernetes.
Por padrão, o contêiner dind
usa a imagem docker:dind
, que executa o daemon do Docker como raiz. Você pode substituir essa imagem por docker:dind-rootless
desde que esteja ciente das limitações conhecidas e executar os pods com o modo --privileged
. Para saber como personalizar a configuração do Docker-in-Docker, consulte "Customizing container modes".
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", "/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: {}
Os valores em template.spec
são injetados automaticamente e não podem ser substituídos. 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. Para obter mais informações, consulte a seção Volumes Persistentes na documentação do Kubernetes.
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
no arquivo values.yaml
.
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.
Nota: quando o modo Kubernetes estiver habilitado, ocorrerá uma falha nos workflows que não estiverem configurados com um trabalho de contêiner, com um erro similar 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 trabalhos sem um contêiner de trabalho sejam executados, defina ACTIONS_RUNNER_REQUIRE_JOB_CONTAINER
para false
no contêiner do executor. Isso instrui o executor a desabilitar essa verificação.
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 personalizar modos de contêiner
Quando você define o containerMode
no arquivo values.yaml
para o gráfico helm gha-runner-scale-set
, você pode usar um dos seguintes valores:
dind
oukubernetes
Dependendo do valor definido para o containerMode
, uma configuração será automaticamente injetada na seção template
do arquivo values.yaml
para o gráfico helm gha-runner-scale-set
.
- Consulte a configuração
dind
. - Consulte a configuração
kubernetes
.
Para personalizar a especificação, comente ou remova containerMode
e acrescente a configuração desejada na seção template
.
Por exemplo: executar dind-rootless
Antes de decidir executar dind-rootless
, esteja ciente das limitações conhecidas.
## 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: {}
Como reconhecer os ganchos do contêiner do executor
Quando o executor detecta uma execução de workflow que usa um trabalho de contêiner, contêiner de serviço ou ação do Docker, ele chama ganchos do contêiner do executor para criar um novo pod. O executor depende de ganchos do contêiner do executor para chamar as APIs do Kubernetes e criar um novo pod no mesmo namespace que o do pod do executor. Esse pod recém-criado é usado para executar o trabalho de contêiner, o contêiner de serviço ou a ação do Docker. Para obter mais informações, confira o repositório runner-container-hooks
.
Como configurar as extensões de gancho
A partir da versão 0.4.0 do ARC, os ganchos do contêiner do executor suportam extensões de gancho. Você pode usá-los para configurar o pod criado por ganchos do contêiner do executor. Por exemplo, você pode usar uma extensão de gancho para definir um contexto de segurança no pod. As extensões de gancho permitem especificar um arquivo YAML que é usado para atualizar o PodSpec do pod criado por ganchos do contêiner do executor.
Há duas opções para configurar extensões de gancho.
- Armazene em sua imagem de executor personalizada. Você pode armazenar o PodSpec em um arquivo YAML em qualquer lugar da sua imagem de executor personalizada. Para obter mais informações, confira "Sobe o Controlador de Executores de Ação".
- Armazene em um ConfigMap. Você pode criar um mapa de configurações com o PodSpec e montar esse mapa de configurações no contêiner do executor. Para obter mais informações, consulte ConfigMaps na documentação do Kubernetes.
Nota: com ambas as opções, você deve definir a variável de ambiente ACTIONS_RUNNER_CONTAINER_HOOK_TEMPLATE
na especificação do contêiner do executor para apontar para o caminho do arquivo YAML montado no contêiner do executor.
Exemplo: o uso do mapa de configurações para definir securityContext
Crie um mapa de configurações no mesmo namespace que os pods do executor. Por exemplo:
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
- Os campos
.metadata.labels
emetadata.annotations
serão acrescentados no estado em que se encontram, a menos que suas chaves sejam reservadas. Não é possível substituir os campos.metadata.name
emetadata.namespace
. - A maioria dos campos PodSpec é aplicada com base no modelo especificado e substitui os valores passados do arquivo
values.yaml
do gráfico Helm. - Se você especificar volumes adicionais, eles serão acrescentados aos volumes padrão especificados pelo executor.
- Os
spec.containers
são mesclados com base nos nomes atribuídos a eles.- Se o nome do contêiner for
$job
:- Os campos
spec.containers.name
espec.containers.image
são ignorados. - Os campos
spec.containers.env
,spec.containers.volumeMounts
espec.containers.ports
são acrescentados à especificação de contêiner padrão criada pelo gancho. - O restante dos campos é aplicado conforme fornecido.
- Os campos
- Se o nome do contêiner não for
$job
, os campos serão adicionados à definição do pod como estão.
- Se o nome do contêiner for
Habilitar métricas
Nota: as métricas do ARC estão disponíveis a partir da versão gha-runner-scale-set-0.5.0.
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"
Nota: se o objeto metrics:
não for fornecido ou for comentado, estes sinalizadores serão aplicados aos pods controller-manager e listener com valores vazios: --metrics-addr
, --listener-metrics-addr
e --listener-metrics-endpoint
. Quando isso acontece, as métricas são desabilitadas no ARC.
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.
Nota: as métricas que o controller-manager emite dizem respeito ao runtime do controlador e não pertencem ao GitHub.
Proprietário | Métrica | Tipo | Descrição |
---|---|---|---|
gerenciador-controlador | gha_controller_pending_ephemeral_runners | medidor | Número de executores efêmeros em estado pendente |
gerenciador-controlador | gha_controller_running_ephemeral_runners | medidor | Número de executores efêmeros em estado de execução |
gerenciador-controlador | gha_controller_failed_ephemeral_runners | medidor | Número de executores efêmeros em estado de falha |
gerenciador-controlador | gha_controller_running_listeners | medidor | Número de ouvintes em um estado de execução |
listener | gha_assigned_jobs | medidor | Número de trabalhos atribuídos ao conjunto de dimensionamento de executores |
listener | gha_running_jobs | medidor | Número de trabalhos em execução ou na fila para execução |
listener | gha_registered_runners | medidor | Número de executores registrados pelo conjunto de dimensionamento de executores |
listener | gha_busy_runners | medidor | Número de executores registrados executando um trabalho no momento |
listener | gha_min_runners | medidor | Número mínimo de executores configurados para o conjunto de dimensionamento de executores |
listener | gha_max_runners | medidor | Número máximo de executores configurados para o conjunto de dimensionamento de executores |
listener | gha_desired_runners | medidor | Número de executores desejados (meta de escala/redução vertical) pelo conjunto de dimensionamento de executores |
listener | gha_idle_runners | medidor | Número de executores registrados que não estão executando um trabalho |
listener | gha_started_jobs_total | contador | Número total de trabalhos iniciados desde que o listener ficou pronto [1] |
listener | gha_completed_jobs_total | contador | Número total de trabalhos concluídos desde que o listener ficou pronto [1] |
listener | gha_job_startup_duration_seconds | histogram | Número de segundos gastos aguardando a tarefa do fluxo de trabalho para iniciar no executor de propriedade do conjunto de dimensionamento do executor |
listener | gha_job_execution_duration_seconds | histogram | Número de segundos gastos executando tarefas do fluxo de trabalho pelo conjunto de dimensionamento do executor |
[1]: Listener metrics that have the counter type are reset when the listener pod restarts.
Usando o ARC com o Dependabot e o code scanning
Você pode usar Actions Runner Controller para criar executores dedicados na sua instância do GitHub Enterprise Server que o Dependabot pode usar para ajudar a proteger e manter as dependências usadas nos repositórios na sua empresa. Para obter mais informações, confira "Gerenciar executores auto-hospedados para atualizações de Dependabot na sua empresa".
Você pode usar o ARC com o CodeQL para identificar vulnerabilidades e erros no seu código. Para obter mais informações, confira "Sobre a varredura de código com CodeQL". Se você já estiver usando o code scanning e quiser configurar um conjunto de dimensionamento de executores para usar a configuração padrão, defina INSTALLATION_NAME=code-scanning
. Para obter mais informações sobre a configuração padrão do code scanning, consulte "Como definir a configuração padrão da verificação de código".
Actions Runner Controller não usa vários rótulos para direcionar trabalhos para conjuntos de dimensionamento de executores específicos. Em vez disso, para designar um conjunto de dimensionamento de executores para atualizações ou do Dependabot ou o code scanning com o CodeQL, use um nome de instalação descritivo no seu gráfico do Helm, como dependabot
ou code-scanning
. Depois disso você pode definir o valor de runs-on
nos fluxos de trabalho para o nome da instalação como o único rótulo e usar o conjunto de dimensionamento de executor designado para atualizações do Dependabot ou trabalhos de code scanning.
Se estiver usando a configuração padrão para o code scanning, a análise procurará automaticamente um conjunto de dimensionamento de executores com o nome de instalação code-scanning
.
A Ação Dependabot é usada para executar atualizações do Dependabot por meio de GitHub Actions. Essa ação requer o Docker como uma dependência. Por esse motivo, você só poderá usar Actions Runner Controller com Dependabot quando o modo DinD (Docker-in-Docker) estiver habilitado. Para obter mais informações, confira "Gerenciar executores auto-hospedados para atualizações de Dependabot na sua empresa" e "Como implantar conjuntos de dimensionamento de executores com o Actions Runner Controller."
Como atualizar o ARC
Como não há suporte para atualizar ou excluir CRDs com o Helm, não é possível usar o Helm para atualizar o ARC. Para obter mais informações, consulte Custom Resource Definitions na documentação do Helm. Para atualizar o ARC para uma versão mais recente, você deve concluir as etapas a seguir.
- Desinstale todas as instalações do
gha-runner-scale-set
. - Aguarde a limpeza dos recursos.
- Desinstale o ARC.
- Se houver uma alteração nos CRDs da versão que está instalada no momento para a versão atualizada, remova todos os CRDs associados ao grupo de APIs do
actions.github.com
. - Reinstale o ARC novamente.
Para obter mais informações, consulte "Como implantar um conjunto de dimensionamento de executores".
Se você quiser atualizar o ARC, mas estiver preocupado com o tempo de inatividade, poderá implantar o ARC em uma configuração de alta disponibilidade para garantir que os executores estejam sempre disponíveis. Para obter mais informações, consulte “Alta disponibilidade e failover automático”.
Observação:
A transição da versão suportada pela comunidade do ARC para a versão suportada pelo GitHub é uma alteração arquitetônica substancial. A versão suportada pelo GitHub envolve um redesign de muitos componentes do ARC. Não é um pequeno upgrade de software. Por esses motivos, recomendamos testar as novas versões em um ambiente de preparo que corresponda primeiro ao seu ambiente de produção. Isso garantirá a estabilidade e a confiabilidade da configuração antes da implantação em produção.
Como implantar uma imagem canário
Você pode testar os recursos antes que eles sejam liberados usando versões canário da imagem de contêiner controller-manager. As imagens canário são publicadas no formato de tag canary-SHORT_SHA
. Para obter mais informações, consulte gha-runner-scale-set-controller
em Container registry.
Observações:
- Você deve usar gráficos Helm em seu sistema de arquivos local.
- Você não pode usar os gráficos Helm liberados.
- Atualize o
tag
no arquivo gha-runner-scale-set-controllervalues.yaml
para:canary-SHORT_SHA
- Atualize o campo
appVersion
no arquivoChart.yaml
degha-runner-scale-set
para:canary-SHORT_SHA
- Reinstale o ARC usando o gráfico e os arquivos
values.yaml
atualizados do Helm.
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.