Erstellen der Infrastruktur für die Bereitstellung hoch verfügbarer GitHub-Aktionen auf Azure Kubernetes Service (AKS) mithilfe von Azure Files

In diesem Artikel erstellen Sie die Infrastruktur, die zum Bereitstellen einer hoch verfügbaren Actions Runner Controller (ARC)-Infrastruktur auf AKS mit Azure Files und Helm erforderlich ist.

Bevor Sie anfangen

Festlegen von Umgebungsvariablen

Legen Sie die folgenden Umgebungsvariablen für die Verwendung in dieser Anleitung fest:

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

Stellen Sie sicher, dass Sie die Werte für die folgenden erforderlichen Variablen ersetzen:

  • AKS_AND_STORAGE_ACCOUNT_RG mit dem Namen der Ressourcengruppe, die vom Speicherkonto und dem AKS-Cluster verwendet wird.
  • AKS_CLUSTER_NAME mit dem Namen des AKS-Clusters.
  • STORAGE_ACCOUNT_NAME mit dem Namen des Speicherkontos.
  • AKS_STORAGE_ACCOUNT_LOCATION mit dem Namen der Region, in der die Ressourcen erstellt werden sollen. In diesem Beispiel stellen wir sie in derselben Region wie der AKS-Cluster bereit, um die Leistungs- und Kostenverwaltung zu vereinfachen.
  • GITHUB_CONFIG_URL mit der URL zur GitHub-Organisation oder zum Repository.

Bitte behalten Sie die folgenden optionalen Variablen nach Möglichkeit als Standard bei:

  • NAMESPACE_ARC_CONTROLLER: Der Name des Kubernetes-Namespace zur Ausführung des ARC-Runners-Skalierungsgruppencontrollers.
  • ARC_CONTROLLER_NAME: Der Name des ARC-Runners-Skalierungsgruppencontrollers.
  • NAMESPACE_ARC_RUNNERS: Der Name des Kubernetes-Namespace zum Ausführen von selbst gehosteten ARC-Läufern.
  • ARC_RUNNER_SCALESET_NAME: Der Name der ARC-Runners-Skalierungsgruppe.
  • ARC_RUNNER_GITHUB_SECRET_NAME: Der Name des geheimen GitHub-Schlüssels.

Installieren der erforderlichen Erweiterungen

Die Aks-Preview-, k8s-Erweiterungs- und amg-Erweiterungen bieten mehr Funktionalität für die Verwaltung von Kubernetes-Clustern und Abfragen von Azure-Ressourcen. Installieren Sie diese Erweiterungen, indem Sie die folgenden az extension add-Befehle ausführen:

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

Erstellen einer Ressourcengruppe

Erstellen Sie eine Ressourcengruppe mit dem Befehl az group create. Diese Ressourcengruppe enthält den AKS-Cluster und das Azure Files-Speicherkonto.

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

Erstellen eines AKS-Clusters

Erstellen Sie mit dem Befehl az aks create einen AKS-Cluster.

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

Herstellen einer Verbindung mit dem AKS-Cluster

Um einen Kubernetes-Cluster zu verwalten, verwenden Sie den Kubernetes-Befehlszeilenclient kubectl. Bei Verwendung von Azure Cloud Shell ist kubectl bereits installiert. Um kubectl lokal zu installieren, verwenden Sie den Befehl az aks install-cli.

  1. Konfigurieren Sie kubectl für die Verbindung mit Ihrem Kubernetes-Cluster mithilfe der az aks get-credentials command. Mit diesem Befehl werden die Anmeldeinformationen heruntergeladen, und die Kubernetes-Befehlszeilenschnittstelle wird für deren Verwendung konfiguriert.

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

  2. Überprüfen Sie die Verbindung mit dem Cluster mithilfe des Befehls kubectl get nodes. Dieser Befehl gibt eine Liste der Knoten in Ihrem AKS-Cluster zurück.

    kubectl get nodes

Erstellen einer Azure-Dateifreigabe

Bevor Sie eine Azure Files-Dateifreigabe als Kubernetes-Volume verwenden können, müssen Sie ein Azure-Speicherkonto und eine Dateifreigabe erstellen. In diesem Leitfaden verwenden wir azure file share Premium SMB mit Unterstützung für die Metadatenzwischenspeicherung. Der Mindestwert beträgt 100 Gb für jede von Ihnen erstellte Freigabe.

  1. Erstellen Sie ein Speicherkonto mit dem Befehl az storage account create. Mit dem folgenden Befehl wird mithilfe der Premium_LRS-SKU ein Speicherkonto erstellt.

    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. Exportieren Sie die Verbindungszeichenfolge als Umgebungsvariable, die Sie zum Erstellen der Dateifreigabe verwenden, mithilfe des az storage account show-connection-string Befehls.

    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. Erstellen Sie die 100 GB Premium-Dateifreigabe mit dem az storage share create-Befehl. In diesem Beispiel verwenden wir metadatencaching als Freigabename. Wenn Sie diesen Namen ändern, müssen Sie auch die arc-runners-set-pv.yaml Datei ändern, um diese Änderung widerzuspiegeln.

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

Installieren des ARC-Runners-Skalierungsgruppencontrollers

Installieren Sie den ARC Runners Scale Set-Controller mit dem folgenden helm install Befehl.

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

Kubernetes-Geheimnisse erstellen

Schlüsselgeheimnis für Azure-Dateifreigabespeicher

Azure Files erfordert, dass Sie einen geheimen Schlüssel auf AKS mit dem Speicherschlüssel erstellen, der zum Verbinden der Azure-Dateifreigabe aus dem AKS-Pod-Container verwendet wird.

  1. Exportieren Sie den Speicherkontoschlüssel mithilfe des az storage account keys list Befehls als Umgebungsvariable.

    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. Erstellen Sie einen Kubernetes-Namespace, um selbst gehostete ARC-Läufer mit dem kubectl create namespace Befehl auszuführen.

    kubectl create namespace "${NAMESPACE_ARC_RUNNERS}"

  3. Erstellen Sie einen Kubernetes-Schlüssel zum Speichern des Azure-Dateifreigabespeicherschlüssels mithilfe des kubectl create secret generic Befehls.

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

GitHub-App-Geheimnis

  1. Erstellen Sie eine GitHub-App, damit der selbst gehostete Runner über das Registrieren eines GitHub-App-Leitfadens auf Ihre GitHub-Organisation oder Ihr Repository zugreifen kann. Der GitHub-Erstellungsprozess bietet Ihnen die folgenden Parameter:

    • GITHUB_APP_ID: Die ID der GitHub-App.
    • GITHUB_APP_INSTALLATION_ID: Die Installations-ID der GitHub-App.
    • github_app_private_key: Der private Schlüssel der GitHub-App. Sie müssen den Abschnitt -----BEGIN RSA PRIVATE KEY----- durch Ihren privaten Schlüssel ersetzen.

  2. Erstellen Sie einen Kubernetes-Geheimschlüssel, um die GitHub-App-Anmeldeinformationen mithilfe des kubectl create secret generic Befehls zu speichern. Stellen Sie sicher, dass Sie die Platzhalter durch die tatsächlichen Werte ersetzen, die Sie aus dem GitHub-App-Erstellungsprozess erhalten haben.

    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>'

Azure-Dateifreigabekonfigurationen

Sie können eine Azure Files-Dateifreigabe in mehreren Pods gleichzeitig bereitstellen, indem Sie AccessMode: ReadWriteMany verwenden, um dieselbe Dateifreigabe in allen Pods bereitzustellen, die vom ARC Kubernetes-Replikatenset erstellt wurden. Wir verwenden die Azure Files-Dateifreigabe auf folgende Weise:

  • Als persistente SMB-Dateifreigabe zum Zwischenspeichern von NuGet-Paketen, die von der .NET-Beispielanwendung verwendet werden. Die Datei arc-runners-set-pv-pvc.yaml erstellt die erforderliche PV- und PVC-Datei, um die Dateifreigabe von Azure Files in den ARC-Runners-Skalierungsgruppen-Pods bereitzustellen. Wir empfehlen Azure File Premium für diese erste Option. Bitte passen Sie volumeAttributes und beliebige Namespace-Parameter sowohl in PV- als auch in PVC-Manifesten an, wie im folgenden Beispiel gezeigt:

    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

  • Als ein temporäres Volume für den Arbeitsordner der GitHub Runners. Außerdem erstellen wir zwei Speicherklassen: Azure Files Standard (github-azurefile) und Azure File Premium (github-azurefile-premium). Mit diesen Klassen können Sie Volumes bei Bedarf erstellen und löschen. Wenn ein GitHub-Auftrag ausgeführt wird, wird ein neuer Runners-Pod auf Kubernetes erstellt und eine neue Azure-Dateifreigabe erstellt und bereitgestellt. Das Volume ist nur während der Ausführung des Auftrags verfügbar. Die Standardklasse ermöglicht jede Volumengröße, und Premium ermöglicht mindestens 100 Gb Volumen. Sie können auswählen, welche Klasse Sie bevorzugen. Denken Sie daran, dass Premium Ihnen eine bessere Leistung bietet. Sie können die arc-runners-storage-class-files.yaml Datei anpassen, aber sie ist nicht erforderlich.

Erstellen Sie das dauerhafte Volume und den dauerhaften Volumeanspruch

  1. Erstellen Sie den Anspruch für den dauerhaften Volume und dauerhaften Volumeanspruch mithilfe des kubectl apply-Befehls.

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

  2. Wenden Sie die Speicherklasse für Azure Files mithilfe des kubectl apply Befehls an.

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

Installieren Sie die ARC-Runners-Skalierungsgruppe

Der folgende Codeausschnitt stammt aus der arc-runners-set-values.yaml Datei im Installationsordner, die Sie anpassen können, bevor Sie das Runner set Helm-Diagramm installieren.

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

In diesem Beispiel verwenden wir eine angepasste Version von Kubernetes containerMode, um Azure File-Dateifreigabe-Volumes in NuGet-Pakete und in das temporäre _work-Ordner-Volume einzubinden.

Die folgenden Parameter müssen nicht geändert werden:

  • storageClassName: Wählen Sie zwischen "github-azurefile-premium" und "github-azurefile".
  • storage: Wählen Sie die Größe des Speichers aus. Mindestens 100 Gb für Premium.

Die anderen Helm-Parameter werden mithilfe des helm install Befehls und der --set Option festgelegt.

Aus Gründen der Kompatibilität mit dem GitHub-Workflow-Container-Feature, mit dem Sie Container in Ihrer Pipeline ausführen können, hängen wir eine container-podspec-volume mit der Podspezifikation für den Workflow-Pod ein, der von ARC erstellt wird, wenn Workflows mit dem Container-Feature ausgeführt werden. Diese Pod-Spezifikation wird aus einem ConfigMap eingehängt, der in der arc-runners-set-container-pod-spec.yaml-Datei im Installationsordner erstellt wurde. Es sind keine Änderungen erforderlich.

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

ARC-Runners-Skalierungsgruppen-Helm-Diagrammparameter

Das ARC-Runners-Skalierungsgruppen-Helm-Diagramm stellt einige Parameter bereit. Die folgenden Parameter sind die wichtigsten Parameter bei der Installation eines Skalierungssatzes mit azure File Share Volume Mount auf AKS:

  • githubConfigUrl: Ihre GitHub-Organisation oder Ihr Repository.
  • githubConfigSecret: Der geheime GitHub-App-Schlüssel für den Zugriff auf GitHub vom selbst gehosteten Runners.
  • minRunners: Mindestanzahl der Runner in der Skalierungsgruppe, die auf neue Aufträge von GitHub wartet.
  • maxRunners: Maximale Anzahl von Runnern, die Aufträge ausführen oder auf neue Aufträge von GitHub warten.
  • runnerGroup: GitHub-Runners-Gruppe, die von den ARC-Runnern verwendet wird.

Laden Sie das ARC Runners Scale Set Helm Chart herunter.

Helm-Chart auf AKS installieren

Installieren Sie das ARC Runners-Skalierungsgruppen-Helm-Diagramm auf AKS mithilfe des helm install Befehls.

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

Upgrade einer Runner Scale Set-Installation

Wenn Sie eine Konfiguration für die ARC-Läufer-Skalierungsgruppe aktualisieren möchten, können Sie den helm upgrade --install Befehl mit denselben Parametern verwenden, die Sie zum Installieren des Skalierungssatzes verwendet haben. Wenn Sie beispielsweise den minRunners Parameter von 1 in 2 ändern möchten, können Sie den folgenden Befehl ausführen:

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

Nächster Schritt

Bereitstellen und Testen hoch verfügbarer GitHub-Aktionen mit Azure Files auf AKS

Beitragende

Microsoft verwaltet diesen Artikel. Die folgenden Mitwirkenden haben es ursprünglich geschrieben:

  • Jorge Arterio | Senior Cloud Advocate
  • Jeff Patterson | Principal Product Manager
  • Rena Shah | Senior Product Manager
  • Shekhar Singh Sorot | Product Manager 2
  • Erin Schaffer | Inhaltsentwickler 2
  • Last updated on