使用 Azure 檔案儲存體建立基礎結構，以在 Azure Kubernetes Service （AKS） 上部署高可用性 GitHub Actions

在本文中，您將使用 Azure 檔案儲存體和 Helm 建立所需的基礎結構，以在 AKS 上部署高可用性的 Actions Runner Controller (ARC) 基礎設施。

開始之前

設定環境變數

設定下列環境變數，以在整個指南中使用：

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

請務必取代下列 必要 變數的值：

  • AKS_AND_STORAGE_ACCOUNT_RG，具有儲存體帳戶和 AKS 叢集所使用之資源群組的名稱。
  • AKS_CLUSTER_NAME，具有 AKS 叢集的名稱。
  • STORAGE_ACCOUNT_NAME，具有儲存體帳戶的名稱。
  • AKS_STORAGE_ACCOUNT_LOCATION，具有要用來在其中建立資源的區域名稱。 在此範例中，我們會將它們部署在與 AKS 叢集相同的區域中，以促進效能和成本管理。
  • GITHUB_CONFIG_URL 附上 GitHub 組織或存放庫的 URL。

如果可能，請將下列 選用 變數保留為預設值：

  • NAMESPACE_ARC_CONTROLLER：要執行 ARC 執行器擴展集控制器的 Kubernetes 命名空間名稱。
  • ARC_CONTROLLER_NAME：ARC 執行器擴展集控制器的名稱。
  • NAMESPACE_ARC_RUNNERS：執行 ARC 自我裝載執行器的 Kubernetes 命名空間名稱。
  • ARC_RUNNER_SCALESET_NAME：ARC 執行器擴展集的名稱。
  • ARC_RUNNER_GITHUB_SECRET_NAME：GitHub 秘密的名稱。

安裝必要的延伸模組

aks-preview、k8s-extension 和 amg 延伸模組提供更多功能來管理 Kubernetes 叢集和查詢 Azure 資源。 使用下列 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

建立資源群組

使用 az group create 命令建立資源群組。 此資源群組會保留 AKS 叢集和 Azure 檔案儲存體帳戶。

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

建立 AKS 叢集

使用 az aks create 命令建立 AKS 叢集。

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

連線到 AKS 叢集

若要管理 Kubernetes 叢集，請使用 Kubernetes 命令列用戶端 kubectl。 如果您使用 Azure Cloud Shell，則已安裝 kubectl。 若要在本機安裝 kubectl，請使用 az aks install-cli 命令。

  1. 設定 kubectl 以使用 az aks get-credentials command 來連接到您的 Kubernetes 叢集。 此命令會下載認證，並設定 Kubernetes CLI 來使用這些認證。

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

  2. 使用 kubectl get nodes 命令確認叢集的連線。 此命令會傳回 AKS 叢集中的節點清單。

    kubectl get nodes

建立 Azure 檔案共用

在能使用 Azure 檔案儲存體的檔案共用作為 Kubernetes 磁碟區之前，您必須建立 Azure 儲存體帳戶與檔案共用。 在本指南中，我們使用 Azure 檔案共用 Premium SMB，這個服務支援中繼資料快取。 您建立的每個分區的最低容量為 100 Gb。

  1. 使用命令 az storage account create 建立儲存體帳戶。 下列命令會使用 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

  2. 使用命令 az storage account show-connection-string ，將連接字串匯出為環境變數，以建立檔案共用。

    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. 使用命令 az storage share create 建立 100 Gb 進階檔案共用。 在此範例中，我們使用 metadatacaching 作為共用名稱。 如果您變更此名稱，也必須變更 arc-runners-set-pv.yaml 檔案以反映此變更。

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

安裝 ARC 執行器擴展集控制器

使用下列 helm install 命令來安裝 ARC 執行器擴展集控制器。

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 秘密

Azure 檔案分享儲存金鑰機密

Azure 檔案儲存體會要求您使用用於從 AKS Pod 容器連線 Azure 檔案共用的儲存體金鑰在 AKS 上建立秘密。

  1. 使用命令 az storage account keys list 將儲存體帳戶金鑰匯出為環境變數。

    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. 建立 Kubernetes 命名空間，以使用命令 kubectl create namespace 執行 ARC 自我託管執行器。

    kubectl create namespace "${NAMESPACE_ARC_RUNNERS}"

  3. 使用 命令 kubectl create secret generic 建立 Kubernetes 秘密，以儲存 Azure 檔案共用儲存體金鑰。

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

GitHub 應用程式秘密

  1. 建立 GitHub 應用程式，以允許自我裝載執行器使用 註冊 GitHub 應用程式 指南存取您的 GitHub 組織或存放庫。 GitHub 建立程式會提供下列參數：

    • GITHUB_APP_ID：GitHub 應用程式的 ID。
    • GITHUB_APP_INSTALLATION_ID：GitHub 應用程式的安裝 ID。
    • github_app_private_key：GitHub 應用程式的私密金鑰。 您需要將 -----BEGIN RSA PRIVATE KEY----- 區段取代為您的私密金鑰。

  2. 使用命令 kubectl create secret generic 建立 Kubernetes 密碼以儲存 GitHub 應用程式認證。 確保將預留位置取代為您在 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>'

Azure 檔案共用設定

您可以使用 AccessMode: ReadWriteMany 在多個 Pod 中同時掛接 Azure 檔案儲存體的檔案共用，以便在 ARC Kubernetes 複本集建立的所有 Pod 中掛接相同的檔案共用。 我們會以下列方式使用 Azure Files 檔案共用：

  • 作為持續性 SMB 檔案共用，以用於快取 .NET 範例應用程式所使用的 NuGet 套件。 arc-runners-set-pv-pv.yaml 檔案會建立必要的 PV 和 PVC，以在 ARC 執行器擴展集 Pod 中掛接 Azure 檔案儲存體的檔案共用。 我們建議針對第一個選項使用 Azure 檔案進階版。 請自訂 volumeAttributes 和 PV 及 PVC 配置檔中的任何命名空間參數，如下列範例所示：

    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

  • 作為 GitHub 執行器工作資料夾的暫時磁碟區。 我們也會建立兩個儲存體類別：Azure 檔案儲存體標準 （github-azurefile） 和 Azure 檔案儲存體進階 （github-azurefile-premium）。 這些類別可讓您視需要建立及刪除磁碟區。 當 GitHub 作業執行時，會在 Kubernetes 上建立新的 Runner Pod，並建立並掛接新的 Azure 檔案共用。 該磁碟區僅在作業執行期間有效。 標準類別允許任何磁碟區大小，而進階類別則允許至少 100 Gb 磁碟區。 您可以選擇您喜歡的任何課程。 請記住，高級版為您提供更好的性能。 您可以自訂 arc-runners-storage-class-files.yaml 檔案，但不是必要條件。

建立永續性磁碟區和永續性磁碟區宣告

  1. 使用 kubectl apply 指令，建立持久性磁碟區和持久性磁碟區宣告。

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

  2. 使用 kubectl apply 命令來套用 Azure Files 的儲存體類別。

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

安裝 ARC 執行器擴展集

以下程式碼片段來自安裝資料夾中的 arc-runners-set-values.yaml 檔案，您可以在安裝執行器集 Helm 圖表之前自訂該檔案。

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

在此範例中，我們使用自訂版本的 Kubernetes containerMode，以將 Azure 檔案儲存體的檔案共用磁碟區掛接到 NuGet 套件和暫時 _work 資料夾磁碟區中。

下列參數不是必須變更的：

  • storageClassName：在 “github-azurefile-premium” 和 “github-azurefile” 之間進行選擇。
  • storage：選擇儲存空間的大小。 進階版至少 100 Gb。

其他 Helm 參數是透過在helm install命令中使用--set選項來設定的。

為了與允許您在管線內執行容器的 GitHub 工作流程容器功能相容，我們在使用容器功能執行工作流程時，使用 ARC 建立的工作流程 Pod 的 Pod 規格掛接了一個 container-podspec-volume。 此 Pod 規格是從在安裝資料夾中的 arc-runners-set-container-pod-spec.yaml 檔案上建立的組態對應掛接的。 無需更改。

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

ARC 執行器擴展集 Helm 圖表參數

ARC 執行器擴展集 Helm 圖表提供一些參數。 在 AKS 上安裝具有 Azure 檔案儲存體的共用磁碟區掛接的擴展集時，下列參數是最重要的：

  • githubConfigUrl：您的 GitHub 組織或存放庫。
  • githubConfigSecret：用於從自我裝載執行器存取 GitHub 的 GitHub 應用程式秘密。
  • minRunners：在擴展集上等待來自 GitHub 的新作業的執行器的最小數目。
  • maxRunners：正在執行作業或等待來自 GitHub 的新作業的執行器的最大數目。
  • runnerGroup：ARC 執行器集使用的 GitHub 執行器群組。

下載 ARC 執行器擴展集 Helm 圖表。

在 AKS 上安裝 Helm 圖表

使用 helm install 命令在 AKS 上安裝 ARC 執行器擴展集 Helm 圖表。

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

升級執行器擴展集安裝

如果您想要升級 ARC 執行器擴展集上的任何設定，您可以使用 helm upgrade --install 命令，並搭配您用來安裝擴展集的相同參數。 例如，如果您想要將 minRunners 參數從 1 變更為 2，您可以執行下列指令：

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

後續步驟

使用 AKS 上的 Azure 檔案儲存體部署和測試高可用性 GitHub Actions

貢獻者們

本文由 Microsoft 維護。 原始撰寫此內容的貢獻者如下：

  • 豪爾赫·阿特里奧 |資深雲端倡導者
  • 傑夫·帕特森 |首席產品經理
  • 蕾娜·沙阿 |資深產品經理
  • 謝卡爾·辛格·索羅特 |產品經理 2
  • Erin Schaffer |內容開發人員 2
  • 上次更新時間：