Criar a infraestrutura para implantar Ações do GitHub altamente disponíveis no Serviço Kubernetes do Azure (AKS) usando Arquivos do Azure

Neste artigo, você cria a infraestrutura necessária para implantar uma infraestrutura altamente disponível do Actions Runner Controller (ARC) no AKS usando o Azure Files e o Helm.

Antes de começar

Revise a visão geral da implantação e verifique se você atende aos pré-requisitos.
Defina variáveis de ambiente para uso ao longo deste guia.
Instale as extensões necessárias.

Definir variáveis de ambiente

Defina as seguintes variáveis de ambiente para uso ao longo deste guia:

export AKS_AND_STORAGE_ACCOUNT_RG="aks-files-actions"
export AKS_CLUSTER_NAME="aks-actions"
export STORAGE_ACCOUNT_NAME=""
export AKS_STORAGE_ACCOUNT_LOCATION="westus3"
export GITHUB_CONFIG_URL="azure-files-samples/Workloads/azurefiles-actions-aks at master · Azure-Samples/azure-files-samples"

# Optional. Changes might require additional changes on ./install/*.yaml files.

export NAMESPACE_ARC_CONTROLLER="arc-systems"
export ARC_CONTROLLER_NAME="arc-controller"
export NAMESPACE_ARC_RUNNERS="arc-runners"
export ARC_RUNNER_SCALESET_NAME="arc-runner-set"
export ARC_RUNNER_GITHUB_SECRET_NAME=""

Certifique-se de substituir os valores para as seguintes variáveis necessárias :

AKS_AND_STORAGE_ACCOUNT_RG com o nome do grupo de recursos usado pela conta de armazenamento e pelo cluster AKS.
AKS_CLUSTER_NAME com o nome do cluster AKS.
STORAGE_ACCOUNT_NAME com o nome da conta de armazenamento.
AKS_STORAGE_ACCOUNT_LOCATION com o nome da região na qual criar os recursos. Neste exemplo, nós os implantamos na mesma região do cluster AKS para facilitar o gerenciamento de desempenho e custos.
GITHUB_CONFIG_URL com a URL para a organização ou repositório do GitHub.

Se possível, mantenha as seguintes variáveis opcionais como padrão:

NAMESPACE_ARC_CONTROLLER: O nome do namespace Kubernetes para executar o controlador de conjunto de escala de corredores ARC.
ARC_CONTROLLER_NAME: O nome do controlador de conjunto de escala de corredores ARC.
NAMESPACE_ARC_RUNNERS: O nome do namespace do Kubernetes para executar corredores auto-hospedados do ARC.
ARC_RUNNER_SCALESET_NAME: O nome do conjunto de escalas dos corredores ARC.
ARC_RUNNER_GITHUB_SECRET_NAME: O nome do segredo do GitHub.

Instalar as extensões necessárias

As extensões aks-preview, k8s-extension e amg fornecem mais funcionalidade para gerenciar clusters Kubernetes e consultar recursos do Azure. Instale essas extensões usando os seguintes az extension add comandos:

az extension add --upgrade --name aks-preview --yes --allow-preview true 
az extension add --upgrade --name k8s-extension --yes --allow-preview false 
az extension add --upgrade --name amg --yes --allow-preview false

Criar um grupo de recursos

Crie um grupo de recursos usando o comando az group create. Este grupo de recursos manterá o cluster AKS e a conta de armazenamento do Azure Files.

az group create \ 
    --name $AKS_AND_STORAGE_ACCOUNT_RG \ 
    --location $AKS_STORAGE_ACCOUNT_LOCATION

Criar um cluster do AKS

Crie um cluster AKS usando o comando az aks create.

az aks create --resource-group "${AKS_AND_STORAGE_ACCOUNT_RG}" --name "${AKS_CLUSTER_NAME}" \ 
    --os-sku AzureLinux \ 
    --node-count 1 \ 
    --enable-cluster-autoscaler \ 
    --min-count 1 \ 
    --max-count 3 \ 
    --node-vm-size standard_d4s_v5 \ 
    --max-pods=100 \ 
    --network-plugin azure \ 
    --network-plugin-mode overlay \ 
    --generate-ssh-keys

Conectar-se ao cluster AKS

Para gerenciar um cluster Kubernetes, use o cliente de linha de comando Kubernetes, kubectl. kubectl já está instalado se você usar o Azure Cloud Shell. Para instalar o kubectl localmente, use o az aks install-cli comando.

Configure o kubectl para se conectar ao cluster do Kubernetes usando o az aks get-credentials command. Este comando baixa credenciais e configura a CLI do Kubernetes para usá-las.
```
az aks get-credentials --resource-group "${AKS_AND_STORAGE_ACCOUNT_RG}" --name "${AKS_CLUSTER_NAME}"
```
Verifique a conexão ao seu cluster utilizando o comando kubectl get nodes. Este comando retorna uma lista de nós no cluster AKS.
```
kubectl get nodes
```

Antes de poder utilizar uma partilha de ficheiros do Azure Files como um volume do Kubernetes, precisa criar uma conta de armazenamento do Azure e uma partilha de ficheiros. Neste guia, usamos o compartilhamento de arquivos do Azure Premium SMB com suporte para cache de metadados. O mínimo é de 100 Gb para cada compartilhamento criado.

Crie uma conta de armazenamento usando o az storage account create comando. O comando a seguir cria uma conta de armazenamento usando o Premium_LRS SKU.

az storage account create --name "${STORAGE_ACCOUNT_NAME}" --resource-group "${AKS_AND_STORAGE_ACCOUNT_RG}" \
    --location "${AKS_STORAGE_ACCOUNT_LOCATION}" \
    --sku Premium_LRS \
    --kind FileStorage

Exporte a cadeia de conexão como uma variável de ambiente, que você usa para criar o compartilhamento de arquivos, usando o az storage account show-connection-string comando.

export AZURE_STORAGE_CONNECTION_STRING=$(az storage account show-connection-string --name "${STORAGE_ACCOUNT_NAME}" --resource-group "${AKS_AND_STORAGE_ACCOUNT_RG}" --query connectionString -o tsv)

Crie o compartilhamento de arquivos Premium de 100 Gb usando o az storage share create comando. Neste exemplo, usamos metadatacaching como o nome do compartilhamento. Se você alterar esse nome, também terá que alterar o arc-runners-set-pv.yaml arquivo para refletir essa alteração.
```
az storage share create --name metadatacaching --quota 100 --connection-string "${AZURE_STORAGE_CONNECTION_STRING}"
```

Instale o controlador do conjunto de escala de corredores ARC

Instale o controlador ARC runners scale set usando o seguinte helm install comando.

helm install "${ARC_CONTROLLER_NAME}" \ 
    --namespace "${NAMESPACE_ARC_CONTROLLER}" \ 
    --create-namespace \
    oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set-controller

Criar segredos do Kubernetes

Os Arquivos do Azure exigem que você crie um segredo no AKS com a chave de armazenamento usada para conectar o compartilhamento de arquivos do Azure a partir do contêiner de pod do AKS.

Exporte a chave da conta de armazenamento como uma variável de ambiente usando o az storage account keys list comando.

STORAGE_KEY=$(az storage account keys list --resource-group ${AKS_AND_STORAGE_ACCOUNT_RG} --account-name ${STORAGE_ACCOUNT_NAME} --query "[0].value" -o tsv)

Crie um namespace Kubernetes para executar runners autoalojados do ARC usando o comando kubectl create namespace.
```
kubectl create namespace "${NAMESPACE_ARC_RUNNERS}" 
```

Crie um segredo do Kubernetes para armazenar a chave de armazenamento de compartilhamento de arquivos do Azure usando o kubectl create secret generic comando.

kubectl create secret generic azure-storage-secret \ 
   --namespace "${NAMESPACE_ARC_RUNNERS}" \ 
   --from-literal=azurestorageaccountname=${STORAGE_ACCOUNT_NAME} \ 
   --from-literal=azurestorageaccountkey=${STORAGE_KEY}

Segredo do aplicativo GitHub

Crie um aplicativo GitHub para permitir que o corredor auto-hospedado acesse sua organização ou repositório do GitHub usando o guia Registrando um aplicativo GitHub . O processo de criação do GitHub fornece os seguintes parâmetros:
- GITHUB_APP_ID: O ID do aplicativo GitHub.
- GITHUB_APP_INSTALLATION_ID: O ID de instalação do aplicativo GitHub.
- github_app_private_key: A chave privada do aplicativo GitHub. Tem de substituir a secção -----BEGIN RSA PRIVATE KEY ----- pela sua chave privada.

Crie um segredo do Kubernetes para armazenar as credenciais do aplicativo GitHub usando o kubectl create secret generic comando. Certifique-se de substituir os espaços reservados pelos valores reais obtidos no processo de criação da aplicação GitHub.

GITHUB_APP_ID="app-id-placeholder"
GITHUB_APP_INSTALLATION_ID="installation-id-placeholder"

kubectl create secret generic ${ARC_RUNNER_GITHUB_SECRET_NAME} \ 
    --namespace=${NAMESPACE_ARC_RUNNERS} \
    --from-literal=github_app_id=${GITHUB_APP_ID} \
    --from-literal=github_app_installation_id=${GITHUB_APP_INSTALLATION_ID} \
    --from-literal=github_app_private_key=' <Private Key read here>'

Você pode montar um compartilhamento de arquivos do Azure Files em vários pods ao mesmo tempo usando AccessMode: ReadWriteMany para montar o mesmo compartilhamento de arquivos em todos os pods criados pelo conjunto de réplicas do ARC Kubernetes. Usamos o compartilhamento de arquivos do Azure Files das seguintes maneiras:

Como um compartilhamento de arquivos SMB persistente para armazenar em cache pacotes NuGet usados pelo aplicativo de exemplo .NET. O arquivo arc-runners-set-pv-pvc.yaml cria o PV e o PVC necessários para montar o compartilhamento de arquivos do Azure Files nos pods do conjunto de escala de executores ARC. Recomendamos o Azure File Premium para esta primeira opção. Por favor, personalize volumeAttributes e quaisquer parâmetros de espaço de nome nos manifestos PV e PVC, conforme mostrado no exemplo a seguir:
```
volumeAttributes: 
  resourceGroup: metadata-agroves  # Optional. Only set this when the storage account isn't in the same resource group as node. 
  shareName: metadatacaching
nodeStageSecretRef:
  name: azure-storage-secret
  namespace: arc-runners
```
Como um volume efémero para a pasta de trabalho dos GitHub runners. Também criamos duas classes de armazenamento: Azure Files Standard (github-azurefile) e Azure File Premium (github-azurefile-premium). Essas classes permitem que você crie e exclua volumes sob demanda. Quando um trabalho do GitHub é executado, é criado um novo pod runner no Kubernetes e uma nova partilha de ficheiros no Azure é criada e montada. O volume existe apenas durante a execução do trabalho. A classe Standard permite qualquer tamanho de volume e Premium permite um volume mínimo de 100 Gb . Você pode selecionar a classe que preferir. Tenha em mente que o Premium oferece um melhor desempenho. Você pode personalizar o arc-runners-storage-class-files.yaml arquivo, mas não é necessário.

Criar o volume persistente e a declaração de volume persistente

Crie o volume persistente e a declaração de volume persistente usando o kubectl apply comando.

kubectl apply -f ./install/arc-runners-set-pv-pvc.yaml --namespace "${NAMESPACE_ARC_RUNNERS}" --wait

Aplique a classe de armazenamento para Arquivos do Azure usando o kubectl apply comando.
```
kubectl apply -f ./install/arc-runners-storage-class-files.yaml --wait 
```

Instalar o conjunto de escala de corredores ARC

O trecho de código a seguir é do arc-runners-set-values.yaml arquivo na pasta de instalação que você pode personalizar antes de instalar o gráfico Helm do conjunto de executores.

containerMode: 
  type: "kubernetes" # Type can be set to dind or kubernetes 
  ## The following is required when containerMode.type=kubernetes 
  kubernetesModeWorkVolumeClaim: 
    accessModes: ["ReadWriteMany"] 
    storageClassName: "github-azurefile-premium" # or "github-azurefile" for Standard_LRS 
    resources: 
      requests: 
        storage: 100Gi # 100Gi minimum to premium or any size when using Standard_LRS "github-azurefile" storage class 
template: 
  spec: 
  securityContext: 
    fsGroup: 123 # Group used by GitHub default agent image 
  containers: 
  - name: runner 
    image: ghcr.io/actions/actions-runner:latest 
    command: ["/home/runner/run.sh"] 
    env: 
      - name: ACTIONS_RUNNER_REQUIRE_JOB_CONTAINER 
        value: "false" 
      - name: ACTIONS_RUNNER_CONTAINER_HOOK_TEMPLATE 
        value: "/home/runner/container-config/container-podspec.yaml" 
    volumeMounts: 
      - name: "container-podspec-volume" 
        mountPath: "/home/runner/container-config" 
      - name: azurefile 
        mountPath: /home/runner/.nuget/              
  volumes: 
    - name: "container-podspec-volume" 
      configMap: 
        name: hook-extension 
    - name: azurefile 
      persistentVolumeClaim: 
        claimName: azurefile

Neste exemplo, usamos uma versão personalizada do Kubernetes containerMode para incluir montagens de volume de partilhas de ficheiros do Azure nos pacotes NuGet e no volume efémero da pasta _work.

Os seguintes parâmetros não são obrigatórios para alterar:

storageClassName: Escolha entre "github-azurefile-premium" e "github-azurefile".
storage: Escolha o tamanho do armazenamento. Mínimo de 100 Gb para Premium.

Os outros parâmetros Helm são definidos no comando helm install usando a opção --set.

Para compatibilidade com o recurso de contentor de Workflow do GitHub, que permite executar contentores dentro do pipeline, montamos um container-podspec-volume com a especificação do pod para o pod de Workflow criado pela ARC ao executar workflows com o recurso de contentor. Esta especificação de pod é montada a partir de um mapa de configuração criado no arquivo arc-runners-set-container-pod-spec.yaml na pasta de instalação. Não são necessárias alterações.

kubectl apply -f ./install/arc-runners-set-container-pod-spec.yaml

Parâmetros do gráfico Helm do conjunto de corredores ARC

O gráfico Helm do conjunto de escala de corredores ARC fornece alguns parâmetros. Os seguintes parâmetros são os mais importantes ao instalar um conjunto de escala no AKS com um volume de partilha de ficheiros Azure montado:

githubConfigUrl: Sua organização ou repositório do GitHub.
githubConfigSecret: O segredo do aplicativo GitHub para acessar o GitHub a partir do corredor auto-hospedado.
minRunners: Número mínimo de corredores na escala definida aguardando novos trabalhos do GitHub.
maxRunners: Número máximo de corredores executando trabalhos ou aguardando novos trabalhos do GitHub.
runnerGroup: Grupo de corredores do GitHub usado pelo conjunto de corredores ARC.

Faça o download do gráfico Helm do conjunto de escala de corredores ARC.

Instale o gráfico Helm no AKS

Instale o gráfico Helm set de escala de corredores ARC no AKS usando o helm install comando.

helm install "${ARC_RUNNER_SCALESET_NAME}" \ 
    --namespace "${NAMESPACE_ARC_RUNNERS}" \ 
    --create-namespace \ 
    --values ./install/arc-runners-set-values.yaml \ 
    --set githubConfigUrl="${GITHUB_CONFIG_URL}" \ 
    --set githubConfigSecret="${ARC_RUNNER_GITHUB_SECRET_NAME}" \ 
    --set minRunners=1 \ 
    --set maxRunners=3 \ 
    --set runnerGroup=default \ 
    oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set

Atualizar uma instalação de conjunto de escala de corredor

Se quiser atualizar qualquer configuração no conjunto de escala de corredores ARC, você pode usar o helm upgrade --install comando com os mesmos parâmetros usados para instalar o conjunto de escalas. Por exemplo, se você quiser alterar o minRunners parâmetro de 1 para 2, você pode executar o seguinte comando:

helm upgrade --install "${ARC_RUNNER_SCALESET_NAME}" \
    --namespace "${NAMESPACE_ARC_RUNNERS}" \
    --create-namespace \
    --values ./install/arc-runners-set-values.yaml \
    --set githubConfigUrl="${GITHUB_CONFIG_URL}" \
    --set githubConfigSecret="${ARC_RUNNER_GITHUB_SECRET_NAME}" \
    --set minRunners=2 \
    --set maxRunners=3 \
    --set runnerGroup=default \
    oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set

Próximo passo

Implantar e testar Ações do GitHub de alta disponibilidade com Azure Files no AKS

Contribuidores

A Microsoft mantém este artigo. Os seguintes colaboradores escreveram-no originalmente:

Jorge Arterio | Advogado Sénior de Cloud
Jeff Patterson: Gerente de Produto Principal
Rena Shah | Gerente de Produto Senior
Shekhar Singh Sorot | Gerente de Produto 2
Erin Schaffer | Desenvolvedora de Conteúdo 2

Comentários

Esta página foi útil?

Last updated on 2025-07-22