Créer l’infrastructure pour le déploiement d’actions GitHub hautement disponibles sur Azure Kubernetes Service (AKS) à l’aide d’Azure Files

Dans cet article, vous allez créer l’infrastructure nécessaire pour déployer une infrastructure Arc (Actions Runner Controller) hautement disponible sur AKS à l’aide d’Azure Files et Helm.

Avant de commencer

Définir des variables d’environnement

Définissez les variables d’environnement suivantes à utiliser dans ce guide :

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

Veillez à remplacer les valeurs des variables requises suivantes :

  • AKS_AND_STORAGE_ACCOUNT_RG avec le nom du groupe de ressources utilisé par le compte de stockage et le cluster AKS.
  • AKS_CLUSTER_NAME avec le nom du cluster AKS.
  • STORAGE_ACCOUNT_NAME avec le nom du compte de stockage.
  • AKS_STORAGE_ACCOUNT_LOCATION avec le nom de la région dans laquelle créer les ressources. Dans cet exemple, nous les déployons dans la même région que le cluster AKS pour faciliter la gestion des performances et des coûts.
  • GITHUB_CONFIG_URL avec l’URL de l’organisation ou du dépôt GitHub.

Conservez les variables facultatives suivantes comme valeurs par défaut si possible :

  • NAMESPACE_ARC_CONTROLLER : nom de l’espace de noms Kubernetes pour exécuter le contrôleur de groupe identique des exécuteurs ARC.
  • ARC_CONTROLLER_NAME : nom du contrôleur de groupe identique des exécuteurs ARC.
  • NAMESPACE_ARC_RUNNERS: nom de l’espace de noms Kubernetes pour faire fonctionner des exécuteurs auto-hébergés ARC.
  • ARC_RUNNER_SCALESET_NAME : nom du groupe identique des exécuteurs ARC.
  • ARC_RUNNER_GITHUB_SECRET_NAME : nom du secret GitHub.

Installer les extensions requises

Les extensions aks-preview, k8s-extension et amg fournissent plus de fonctionnalités pour la gestion des clusters Kubernetes et l’interrogation des ressources Azure. Installez ces extensions en utilisant les commandes az extension add suivantes :

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

Créer un groupe de ressources

Créez un groupe de ressources à l’aide de la commande az group create. Ce groupe de ressources contiendra le cluster AKS et le compte de stockage Azure Files.

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

Créer un cluster AKS

Créez un cluster AKS avec la commande 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

Se connecter au cluster AKS

Pour gérer un cluster Kubernetes, utilisez kubectl, le client de ligne de commande Kubernetes. Kubectl est déjà installé si vous utilisez Azure Cloud Shell. Pour installer kubectl localement, utilisez la commande az aks install-cli.

  1. Configurez kubectl pour vous connecter au cluster Kubernetes en utilisant le az aks get-credentials command. Cette commande télécharge les informations d’identification et configure l’interface CLI Kubernetes pour les utiliser.

    az aks get-credentials --resource-group "${AKS_AND_STORAGE_ACCOUNT_RG}" --name "${AKS_CLUSTER_NAME}"

  2. Pour vérifier la connexion à votre cluster, exécutez la commande kubectl get nodes. Cette commande retourne une liste de nœuds dans votre cluster AKS.

    kubectl get nodes

Crée un partage de fichiers Azure

Avant de pouvoir utiliser un partage de fichiers Azure Files en tant que volume Kubernetes, vous devez créer un compte de stockage Azure et un partage de fichiers. Dans ce guide, nous utilisons le partage de fichiers Azure Premium SMB avec prise en charge de la mise en cache des métadonnées. Le minimum est de 100 Go pour chaque partage que vous créez.

  1. Créer un compte de stockage à l’aide de la commande az storage account create. La commande suivante crée un compte de stockage à l’aide de la référence SKU 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

  2. Exportez la chaîne de connexion en tant que variable d’environnement, que vous utilisez pour créer le partage de fichiers, à l’aide de la az storage account show-connection-string commande.

    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)

  3. Créez le partage de fichiers Premium de 100 Go à l’aide de la az storage share create commande. Dans cet exemple, nous utilisons metadatacaching comme nom de partage. Si vous modifiez ce nom, vous devez également modifier le arc-runners-set-pv.yaml fichier pour refléter cette modification.

    az storage share create --name metadatacaching --quota 100 --connection-string "${AZURE_STORAGE_CONNECTION_STRING}"

Installer le contrôleur de groupe identique des exécuteurs ARC

Installez le contrôleur de groupe identique des exécuteurs ARC en utilisant la commande helm install suivante.

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

Créer des secrets Kubernetes

Secret de clé de stockage du partage de fichiers Azure

Azure Files nécessite de créer un secret sur AKS avec la clé de stockage utilisée pour connecter le partage de fichiers Azure à partir du conteneur de pod AKS.

  1. Exportez la clé du compte de stockage en tant que variable d’environnement à l’aide de la az storage account keys list commande.

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

  2. Créez un espace de noms Kubernetes pour exécuter des exécuteurs auto-hébergés ARC à l’aide de la kubectl create namespace commande.

    kubectl create namespace "${NAMESPACE_ARC_RUNNERS}"

  3. Créez un secret Kubernetes pour stocker la clé de stockage de partage de fichiers Azure à l’aide de la kubectl create secret generic commande.

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

Secret de l’application GitHub

  1. Créez une application GitHub pour permettre à l’exécuteur auto-hébergé d’accéder à votre organisation ou référentiel GitHub à l’aide du guide d’inscription d’une application GitHub . Le processus de création GitHub vous fournit les paramètres suivants :

    • GITHUB_APP_ID: ID de l’application GitHub.
    • GITHUB_APP_INSTALLATION_ID: ID d’installation de l’application GitHub.
    • github_app_private_key: clé privée de l’application GitHub. Vous devez remplacer la section -----BEGIN RSA PRIVATE KEY----- par votre clé privée.

  2. Créez un secret Kubernetes pour stocker les informations d’identification de l’application GitHub à l’aide de la kubectl create secret generic commande. Veillez à remplacer les variables par les valeurs obtenues lors de la création de l’application 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>'

Configurations de partage de fichiers Azure

Vous pouvez monter un partage de fichiers Azure Files dans plusieurs pods en même temps à l'aide de AccessMode: ReadWriteMany pour monter le même partage de fichiers dans tous les pods créés par l'ensemble de réplicas ARC Kubernetes. Nous utilisons le partage de fichiers Azure Files de la manière suivante :

  • En tant que partage de fichiers SMB persistant pour mettre en cache les packages NuGet utilisés par l’exemple d’application .NET. Le fichier arc-runners-set-pv-pvc.yaml crée le PV et le PVC requis pour monter le partage de fichiers Azure Files dans les pods de groupe identique des exécuteurs ARC. Nous vous recommandons Azure File Premium pour cette première option. Personnalisez volumeAttributes et les paramètres des espaces de noms sur les manifestes PV et PVC, comme indiqué dans l'exemple suivant :

    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

  • En tant que volume éphémère pour le dossier de travail des exécuteurs GitHub. Nous créons également deux classes de stockage : Azure Files Standard (github-azurefile) et Azure File Premium (github-azurefile-premium). Ces classes vous permettent de créer et de supprimer des volumes à la demande. Lorsqu’un travail GitHub s’exécute, un nouveau pod d’exécuteur est créé sur Kubernetes et un nouveau partage de fichiers Azure File est créé et monté. Le volume ne vit que pendant l’exécution du travail. La classe Standard autorise n’importe quelle taille de volume et Premium autorise un minimum de 100 Go de volume. Vous pouvez sélectionner la classe que vous préférez. Gardez à l’esprit que Premium vous offre une meilleure performance. Vous pouvez personnaliser le arc-runners-storage-class-files.yaml fichier, mais il n’est pas obligatoire.

Créer le volume persistant et la revendication de volume persistant

  1. Créez le volume persistant et la revendication de volume persistant en tirant parti de la commande kubectl apply.

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

  2. Appliquez la classe de stockage pour Azure Files à l’aide de la kubectl apply commande.

    kubectl apply -f ./install/arc-runners-storage-class-files.yaml --wait

Installer le groupe identique des exécuteurs ARC

L’extrait de code suivant provient du arc-runners-set-values.yaml fichier du dossier d’installation que vous pouvez personnaliser avant d’installer le graphique Helm du groupe d’exécuteurs.

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

Dans cet exemple, nous utilisons une version personnalisée de Kubernetes containerMode pour inclure des montages de volume de partage de fichiers Azure sur des packages NuGet et dans le volume de dossier éphémère _work.

Les paramètres suivants ne sont pas obligatoires pour changer :

  • storageClassName: Choisissez entre « github-azurefile-premium » et « github-azurefile ».
  • storage: choisissez la taille du stockage. 100 Go minimum pour Premium.

Les autres paramètres Helm sont définis sur la commande helm install à l'aide de l'option --set.

Pour la compatibilité avec la fonctionnalité de conteneur de workflow GitHub qui vous permet d’exécuter des conteneurs à l’intérieur de votre pipeline, nous montons un container-podspec-volume avec la spécification de pod pour le pod de workflow créé par ARC lors de l’exécution des workflows avec la fonctionnalité de conteneur. Cette spécification de pod est montée à partir d’un mappage de configuration créé sur un fichier arc-runners-set-container-pod-spec.yaml dans le dossier d’installation. Aucune modification n’est requise.

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

Paramètres du graphique Helm du groupe identique des exécuteurs ARC

Le graphique Helm du groupe identique des exécuteurs ARC fournit quelques paramètres. Les paramètres suivants sont les plus importants lors de l’installation d’un groupe identique avec le montage de volume de partage de fichiers Azure sur AKS :

  • githubConfigUrl: votre organisation ou référentiel GitHub.
  • githubConfigSecret : secret de l’application GitHub pour accéder à GitHub à partir de l’exécuteur auto-hébergé.
  • minRunners : nombre minimal d’exécuteurs sur le groupe identique en attente de nouveaux travaux à partir de GitHub.
  • maxRunners: nombre maximal d’exécuteurs exécutant des travaux ou en attente de nouveaux travaux à partir de GitHub.
  • runnerGroup : groupe d’exécuteurs GitHub utilisé par les exécuteurs ARC définis.

Téléchargez le graphique Helm du groupe identique des exécuteurs ARC.

Installer le graphique Helm sur AKS

Installez le graphique Helm du groupe identique des exécuteurs ARC sur AKS en utilisant la commande 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

Mettre à niveau une installation de groupe identique d’exécuteur

Si vous souhaitez mettre à niveau une configuration sur le groupe identique d’exécuteurs ARC, vous pouvez utiliser la commande helm upgrade --install avec les mêmes paramètres que ceux que vous avez utilisés pour installer le groupe identique. Par exemple, si vous souhaitez modifier le minRunners paramètre de 1 à 2, vous pouvez exécuter la commande suivante :

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

Étape suivante

Déployer et tester des actions GitHub hautement disponibles avec Azure Files sur AKS

Contributeurs

Microsoft gère cet article. Il a été écrit initialement par les contributeurs suivants.

  • Jorge Arterio | Avocat principal du cloud
  • Jeff Patterson | Chef de produit principal
  • Rena Shah | Chef de produit senior
  • Shekar Singh Sorot | Product Manager 2
  • Erin Schaffer | Développeuse de contenu 2
  • Dernière mise à jour :