Criar a infraestrutura para implantar o GitHub Actions altamente disponível no AKS (Serviço de Kubernetes do Azure) usando arquivos do Azure

Neste artigo, você criará a infraestrutura necessária para implantar uma infraestrutura do Controlador de Execução de Ações (ARC) altamente disponível no AKS usando Arquivos do Azure e Helm.

Antes de começar

Examine 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=""

Substitua os valores das 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 do AKS.
AKS_CLUSTER_NAME com o nome do cluster do 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, os implantamos na mesma região que o cluster do AKS para facilitar o gerenciamento de custos e desempenho.
GITHUB_CONFIG_URL com a URL para a organização ou repositório GitHub.

Mantenha as seguintes variáveis opcionais como padrão, se possível:

NAMESPACE_ARC_CONTROLLER: o nome do namespace do Kubernetes para executar o controlador do conjunto de dimensionamento de executores do ARC.
ARC_CONTROLLER_NAME: o nome do controlador do conjunto de dimensionamento de executores do ARC.
NAMESPACE_ARC_RUNNERS: o nome do namespace do Kubernetes para executar os executores auto-hospedados do ARC.
ARC_RUNNER_SCALESET_NAME: o nome do conjunto de dimensionamento de executores do ARC.
ARC_RUNNER_GITHUB_SECRET_NAME: o nome do segredo do GitHub.

Instalar extensões necessárias

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

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. Esse grupo de recursos conterá o cluster do AKS e a conta de armazenamento dos Arquivos do Azure.

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

Criar um cluster AKS

Crie um cluster do 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

Conecte-se ao cluster do AKS

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

Configure o kubectl para se conectar ao cluster do Kubernetes usando o az aks get-credentials command. Este comando baixa as 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 com o cluster usando o comando kubectl get nodes. Esse comando retorna uma lista de nós no cluster do AKS.
```
kubectl get nodes
```

Antes de usar um compartilhamento de arquivos dos Arquivos do Azure como um volume do Kubernetes, você precisa criar uma conta de armazenamento do Azure e compartilhamento de arquivos. Neste guia, usamos o SMB Premium de compartilhamento de arquivos do Azure com suporte para cache de metadados. O mínimo é de 100 Gb para cada compartilhamento criado.

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

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 arquivo 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 precisará 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 dimensionamento de executores de ARC

Instale o controlador do conjunto de dimensionamento de executores de ARC usando o seguinte comando helm install.

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 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 do Kubernetes para executar os executores auto-hospedados do ARC usando o kubectl create namespace comando.
```
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 executor auto-hospedado acesse sua organização ou repositório GitHub usando o guia de registro de um aplicativo do GitHub . O processo de criação do GitHub fornece os seguintes parâmetros:
- GITHUB_APP_ID: A ID do aplicativo GitHub.
- GITHUB_APP_INSTALLATION_ID: a ID de instalação do aplicativo GitHub.
- github_app_private_key: a chave privada do aplicativo GitHub. Você precisa substituir a seção -----BEGIN RSA PRIVATE KEY----- por 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 placeholders pelos valores reais que você obteve 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 dos Arquivos do Azure 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 Kubernetes ARC. Usamos o compartilhamento de arquivos dos Arquivos do Azure das seguintes maneiras:

Como um compartilhamento de arquivo 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 dos Arquivos do Azure nos pods do conjunto de dimensionamento dos executores de ARC. Recomendamos o Azure File Premium para esta primeira opção. Personalize volumeAttributes e quaisquer parâmetros de namespaces em 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 executores do GitHub. 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, um novo pod executor é criado no Kubernetes e um novo compartilhamento de arquivos do Azure é criado e montado. O volume está ativo somente 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 qualquer classe que preferir. Tenha em mente que o Premium oferece um desempenho melhor. Você pode personalizar o arc-runners-storage-class-files.yaml arquivo, mas ele não é necessário.

Crie 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 
```

Instale o conjunto de dimensionamento de executores de ARC

O snippet de código a seguir é do arquivo arc-runners-set-values.yaml na pasta de instalação que você pode personalizar antes de instalar o gráfico do 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 montagem de volume de compartilhamento de arquivos do Azure para pacotes NuGet e para o volume de pastas de _work efêmero.

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

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 do Helm são definidos no helm install comando usando a opção --set .

Para compatibilidade com o recurso de contêiner do Fluxo de Trabalho do GitHub que permite executar contêineres dentro do pipeline, montamos um container-podspec-volume com a especificação de pod para o pod de fluxo de trabalho criado pelo ARC ao executar fluxos de trabalho com o recurso de contêiner. Essa especificação de pod é montada a partir de um mapa de configuração criado no arquivo arc-runners-set-container-pod-spec.yaml da pasta de instalação. Nenhuma alteração é necessária.

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

Parâmetros do gráfico de Helm do conjunto de dimensionamento de executores de ARC

O gráfico Helm do conjunto de escalonamento de corredores ARC fornece alguns parâmetros. Os seguintes parâmetros são os mais importantes ao instalar um conjunto de dimensionamento com a montagem do volume de compartilhamento de arquivos do Azure no AKS:

githubConfigUrl: sua organização ou repositório GitHub.
githubConfigSecret: o segredo do Aplicativo GitHub para acessar o GitHub do executor auto-hospedado.
minRunners: número mínimo de executores no conjunto de dimensionamento aguardando novos trabalhos do GitHub.
maxRunners: número máximo de executores executando trabalhos ou aguardando novos trabalhos do GitHub.
runnerGroup: grupo de executores do GitHub usado pelo conjunto de executores de ARC.

Baixe o gráfico de Helm do conjunto de dimensionamento de corredores ARC.

Instale o gráfico de Helm no AKS

Instale o gráfico de Helm do conjunto de dimensionamento de executores de ARC no AKS usando o comando helm install.

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

Atualize uma instalação do conjunto de dimensionamento de executores

Se você quiser atualizar qualquer configuração no conjunto de dimensionamento dos runners ARC, poderá usar o comando helm upgrade --install com os mesmos parâmetros usados para instalar o conjunto de dimensionamento. Por exemplo, se você quiser alterar o minRunners parâmetro de 1 para 2, poderá 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óxima etapa

Implantar e testar ações do GitHub altamente disponíveis com Azure Files no AKS

Contribuidores

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

Jorge Arterio | Consultor sênior de nuvem
Jeff Patterson | Gerente de Produto Principal
Rena Shah | Gerente de Produto Sênior
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-28