教學課程:使用 Azure Container Apps 作業部署自我裝載 CI/CD 執行器和代理程式
GitHub Actions 和 Azure Pipelines 可讓您使用自我裝載的執行器和代理程式來執行 CI/CD 工作流程。 您可以使用事件驅動的 Azure Container Apps 作業來執行自我裝載的執行器和代理程式。
當您需要執行需要存取雲端裝載執行器無法使用的本機資源或工具的工作流程時,自我裝載執行器會很有用。 例如,Container Apps 作業中的自我裝載執行器可讓您的工作流程存取作業虛擬網路內無法存取雲端裝載執行器的資源。
以事件驅動作業身分執行自我裝載的執行器,可讓您利用 Azure Container Apps 的無伺服器本質。 作業會在觸發工作流程時自動執行,並在作業完成時結束。
您只需支付作業執行的時間。
在本教學課程中,您將瞭解如何執行 GitHub Actions 執行器作為 事件驅動容器應用程式作業。
- 建立 Container Apps 環境以部署自我裝載的執行器
- 建立 GitHub 存放庫以執行使用自我裝載執行器的工作流程
- 建置執行 GitHub Actions 執行器的容器映像
- 將執行器部署為作業至 Container Apps 環境
- 建立使用自我裝載執行器的工作流程,並確認其執行
重要
僅建議私人存放庫使用自我裝載的執行器。 將它們與公用存放庫搭配使用,可讓危險程式代碼在您的自我裝載執行器上執行。 如需詳細資訊,請參閱 自我裝載執行器安全性。
在本教學課程中,您將瞭解如何將 Azure Pipelines 代理程式當做 事件驅動容器應用程式作業來執行。
- 建立 Container Apps 環境以部署自我裝載的代理程式
- 建立 Azure DevOps 組織和專案
- 建置執行 Azure Pipelines 代理程式的容器映像
- 使用手動作業在 Container Apps 環境中建立佔位元代理程式
- 將代理程式部署為作業至 Container Apps 環境
- 建立使用自我裝載代理程式的管線,並確認其執行
重要
僅針對 私人 項目,建議使用自我裝載代理程式。 將它們與公用專案搭配使用,可讓危險程式代碼在您的自我裝載代理程式上執行。 如需詳細資訊,請參閱 自我裝載代理程序安全性。
注意
容器應用程式和作業不支援在容器中執行 Docker。 當您在 Container Apps 作業中的自我裝載執行器或代理程式上執行時,使用 Docker 命令的工作流程中的任何步驟都會失敗。
必要條件
- Azure DevOps 組織:如果您沒有具有作用中訂用帳戶的 DevOps 組織,您可以 免費建立一個。
如需限制清單,請參閱作業限制。
設定
若要從 CLI 登入 Azure,請執行下列命令,並遵循提示來完成驗證程序。
az login
若要確保您執行最新版的 CLI,請執行升級命令。
az upgrade
接下來,安裝或更新 CLI 的 Azure Container Apps 擴充功能。
az extension add --name containerapp --upgrade
現在已安裝目前的擴充功能或模組,請註冊 Microsoft.App
和 Microsoft.OperationalInsights
命名空間。
注意
Azure 容器應用程式資源已從 Microsoft.Web
命名空間移轉至 Microsoft.App
命名空間。 如需詳細資訊,請參閱 2022 年 3 月將命名空間從 Microsoft.Web 移轉至 Microsoft.App。
az provider register --namespace Microsoft.App
az provider register --namespace Microsoft.OperationalInsights
建立環境變數
現在,您的 Azure CLI 設定已完成,您可以定義本文中使用的環境變數。
RESOURCE_GROUP="jobs-sample"
LOCATION="northcentralus"
ENVIRONMENT="env-jobs-sample"
JOB_NAME="github-actions-runner-job"
RESOURCE_GROUP="jobs-sample"
LOCATION="northcentralus"
ENVIRONMENT="env-jobs-sample"
JOB_NAME="azure-pipelines-agent-job"
PLACEHOLDER_JOB_NAME="placeholder-agent-job"
建立容器應用程式環境
Azure Container Apps 環境可作為容器應用程式和作業的安全界限,讓它們可以共用相同的網路並彼此通訊。
注意
若要建立與現有虛擬網路整合的 Container Apps 環境,請參閱 將虛擬網路提供給內部 Azure Container Apps 環境。
使用下列命令建立資源群組。
az group create \ --name "$RESOURCE_GROUP" \ --location "$LOCATION"
使用下列命令建立 Container Apps 環境。
az containerapp env create \ --name "$ENVIRONMENT" \ --resource-group "$RESOURCE_GROUP" \ --location "$LOCATION"
建立 GitHub 存放庫以執行工作流程
若要執行工作流程,您必須建立包含工作流程定義的 GitHub 存放庫。
瀏覽至 GitHub 並登入。
輸入下列值來建立新的存放庫。
設定 值 負責人 選取您的 GitHub 用戶名稱。 儲存機制名稱 輸入存放庫的名稱。 能見度 選取 [私人]。 使用 初始化此存放庫 選取 [新增讀我檔案]。 保留其餘的值做為其預設選取專案。
選取 [建立存放庫]。
在新的存放庫中,選取 [ 動作]。
搜尋 [簡單工作流程 ] 範本,然後選取 [ 設定]。
選取 [ 認可變更 ] 以將工作流程新增至您的存放庫。
工作流程會在 ubuntu-latest
GitHub 裝載的執行器上執行,並將訊息列印至主控台。 稍後,您將 GitHub 裝載的執行器取代為自我裝載的執行器。
取得 GitHub 個人存取令牌
若要執行自我裝載的執行器,您必須在 GitHub 中建立個人存取權杖 (PAT)。 每次執行器啟動時,PAT 都會用來產生令牌,向 GitHub 註冊執行器。 GitHub Actions 執行器調整規模規則也會使用 PAT 來監視存放庫的工作流程佇列,並視需要啟動執行器。
在 GitHub 中,選取右上角的配置檔圖片,然後選取 [設定]。
選取 [開發人員設定]。
在 [個人存取令牌] 底下,選取 [細部令牌]。
選取 [產生新的權杖] 。
在 [ 新增精細的個人存取令牌 ] 畫面中,輸入下列值。
設定 值 權杖名稱 輸入令牌的名稱。 到期 選取 [30 天]。 存放庫存取 選取 [僅選取存放庫 ],然後選取您所建立的存放庫。 針對存放庫許可權輸入下列值。
設定 值 動作 選取 [只讀]。 系統管理 選取 [ 讀取和寫入]。 中繼資料 選取 [只讀]。 選取 [產生權杖]。
複製令牌值。
定義稍後用來設定執行器和縮放規則的變數。
GITHUB_PAT="<GITHUB_PAT>" REPO_OWNER="<REPO_OWNER>" REPO_NAME="<REPO_NAME>"
以下欄值取代佔位元:
預留位置 值 <GITHUB_PAT>
您產生的 GitHub PAT。 <REPO_OWNER>
您稍早建立之存放庫的擁有者。 此值通常是您的 GitHub 用戶名稱。 <REPO_NAME>
您稍早建立之存放庫的名稱。 此值與您在 [存放庫名稱 ] 字段中輸入的名稱相同。
建置 GitHub Actions 執行器容器映像
若要建立自我裝載的執行器,您需要建置執行器容器映像。 在本節中,您會建置容器映射,並將其推送至容器登錄。
注意
您在本教學課程中建置的映像包含適合作為容器應用程式作業執行的基本自我裝載執行器。 您可以自定義它,以包含工作流程所需的其他工具或相依性。
定義容器映像和登錄的名稱。
CONTAINER_IMAGE_NAME="github-actions-runner:1.0" CONTAINER_REGISTRY_NAME="<CONTAINER_REGISTRY_NAME>"
將取代
<CONTAINER_REGISTRY_NAME>
為建立容器登錄的唯一名稱。 容器登錄名稱在 Azure 內必須是唯一的,且長度必須介於 5 到 50 個字元之間,且長度只包含數位和小寫字母。建立容器登錄。
az acr create \ --name "$CONTAINER_REGISTRY_NAME" \ --resource-group "$RESOURCE_GROUP" \ --location "$LOCATION" \ --sku Basic \ --admin-enabled true
GitHub 上提供用來建立執行器映像的 Dockerfile。 執行下列命令以複製存放庫,並使用 命令在雲端
az acr build
中建置容器映射。az acr build \ --registry "$CONTAINER_REGISTRY_NAME" \ --image "$CONTAINER_IMAGE_NAME" \ --file "Dockerfile.github" \ "https://github.com/Azure-Samples/container-apps-ci-cd-runner-tutorial.git"
映像現在可在容器登錄中使用。
將自我裝載執行器部署為作業
您現在可以建立用來使用容器映像的作業。 在本節中,您會建立作業,以使用您稍早產生的 PAT 來執行自我裝載的執行器,並使用 GitHub 進行驗證。 作業會 github-runner
使用調整規則 ,根據暫止的工作流程執行數目來建立作業執行。
在 Container Apps 環境中建立作業。
az containerapp job create -n "$JOB_NAME" -g "$RESOURCE_GROUP" --environment "$ENVIRONMENT" \ --trigger-type Event \ --replica-timeout 1800 \ --replica-retry-limit 0 \ --replica-completion-count 1 \ --parallelism 1 \ --image "$CONTAINER_REGISTRY_NAME.azurecr.io/$CONTAINER_IMAGE_NAME" \ --min-executions 0 \ --max-executions 10 \ --polling-interval 30 \ --scale-rule-name "github-runner" \ --scale-rule-type "github-runner" \ --scale-rule-metadata "githubAPIURL=https://api.github.com" "owner=$REPO_OWNER" "runnerScope=repo" "repos=$REPO_NAME" "targetWorkflowQueueLength=1" \ --scale-rule-auth "personalAccessToken=personal-access-token" \ --cpu "2.0" \ --memory "4Gi" \ --secrets "personal-access-token=$GITHUB_PAT" \ --env-vars "GITHUB_PAT=secretref:personal-access-token" "GH_URL=https://github.com/$REPO_OWNER/$REPO_NAME" "REGISTRATION_TOKEN_API_URL=https://api.github.com/repos/$REPO_OWNER/$REPO_NAME/actions/runners/registration-token" \ --registry-server "$CONTAINER_REGISTRY_NAME.azurecr.io"
下表描述命令中使用的索引鍵參數。
參數 描述 --replica-timeout
復本可以執行的持續時間上限。 --replica-retry-limit
重試失敗複本的次數。 --replica-completion-count
在作業執行成功之前,要成功完成的複本數目。 --parallelism
每個作業執行要啟動的複本數目。 --min-executions
每個輪詢間隔執行的作業執行數目下限。 --max-executions
每個輪詢間隔要執行的作業執行數目上限。 --polling-interval
要評估縮放規則的輪詢間隔。 --scale-rule-name
縮放規則的名稱。 --scale-rule-type
要使用的縮放規則類型。 若要深入瞭解 GitHub 執行器調整程式,請參閱 KEDA 檔。 --scale-rule-metadata
縮放規則的元數據。 如果您使用 GitHub Enterprise,請使用其 API URL 進行更新 githubAPIURL
。--scale-rule-auth
調整規則的驗證。 --secrets
要用於作業的秘密。 --env-vars
要用於作業的環境變數。 --registry-server
要用於作業的容器登錄伺服器。 針對 Azure Container Registry,命令會自動設定驗證。 調整規則組態會定義要監視的事件來源。 它會在每個輪詢間隔上進行評估,並判斷要觸發的作業執行數目。 若要深入瞭解,請參閱 設定調整規則。
事件驅動作業現在會在 Container Apps 環境中建立。
執行工作流程並確認作業
作業設定為每隔 30 秒評估一次調整規則。 在每個評估期間,它會檢查需要自我裝載執行器且啟動暫止工作流程的新作業執行次數,最多設定最多10個執行。
若要確認作業已正確設定,您可以修改工作流程以使用自我裝載執行器並觸發工作流程執行。 然後,您可以檢視作業執行記錄,以查看工作流程執行。
在 GitHub 存放庫中,流覽至您稍早產生的工作流程。 這是目錄中的
.github/workflows
YAML 檔案。選取 [ 就地編輯]。
將
runs-on
屬性更新為self-hosted
:runs-on: self-hosted
選取 [ 認可變更...]。
選取 [認可變更]。
瀏覽至 [ 動作] 索引標籤。
新的工作流程現在已排入佇列。 在 30 秒內,作業執行將會啟動,工作流程會在不久之後完成。
等候動作完成,再繼續進行下一個步驟。
列出作業的執行,以確認作業執行已建立並順利完成。
az containerapp job execution list \ --name "$JOB_NAME" \ --resource-group "$RESOURCE_GROUP" \ --output table \ --query '[].{Status: properties.status, Name: name, StartTime: properties.startTime}'
建立 Azure DevOps 專案和存放庫
若要執行管線,您需要 Azure DevOps 專案和存放庫。
流覽至 Azure DevOps 並登入您的帳戶。
選取現有的組織或建立新的組織。
在 [組織概觀] 頁面中,選取 [新增專案 ],然後輸入下列值。
設定 值 專案名稱 輸入項目的名稱。 可視性 選取 [私人]。 選取 建立。
從側邊導覽中,選取 [存放庫]。
在 [使用自述檔或 .gitignore 初始化主要分支] 底下,選取 [新增自述檔]。
將其餘的值保留為預設值,然後選取 [ 初始化]。
建立新的代理程式集區
建立新的代理程式集區以執行自我裝載的執行器。
在您的 Azure DevOps 專案中,展開左側導覽列,然後選取 [ 項目設定]。
在 [項目設定] 導覽功能表的 [管線] 區段下,選取 [代理程式集區]。
選取 [新增集區 ],然後輸入下列值。
設定 值 要連結的集區 選取新增。 集區類型 選取 [自我裝載]。 名稱 輸入 container-apps。 授與所有管線的訪問許可權 選取此核取方塊。 選取 建立。
取得 Azure DevOps 個人存取令牌
若要執行自我裝載的執行器,您必須在 Azure DevOps 中建立個人存取令牌 (PAT)。 PAT 可用來向 Azure DevOps 驗證執行器。 調整規則也會使用此規則來判斷暫止管線執行的數目,並觸發新的作業執行。
在 Azure DevOps 中,選取 右上角配置檔圖片旁的 [用戶設定 ]。
選取 [個人存取權杖]。
在 [ 個人存取令牌 ] 頁面中,選取 [ 新增令牌 ],然後輸入下列值。
設定 值 名稱 輸入令牌的名稱。 組織 選取您稍早選擇或建立的組織。 範圍 選取 [ 自定義定義]。 顯示所有範圍 選取 [ 顯示所有範圍]。 代理程式集區 (讀取和管理) 選取 [代理程序集區] [讀取及管理]。 讓所有其他範圍保持未選取。
選取 建立。
將令牌值複製到安全的位置。
離開頁面之後,您無法擷取令牌。
定義稍後用來設定 Container Apps 作業的變數。
AZP_TOKEN="<AZP_TOKEN>" ORGANIZATION_URL="<ORGANIZATION_URL>" AZP_POOL="container-apps"
以下欄值取代佔位元:
預留位置 值 註解 <AZP_TOKEN>
您產生的 Azure DevOps PAT。 <ORGANIZATION_URL>
Azure DevOps 組織的 URL。 請確定 URL 結尾沒有尾端 /
。例如, https://dev.azure.com/myorg
或https://myorg.visualstudio.com
。
建置 Azure Pipelines 代理程式容器映像
若要建立自我裝載代理程式,您需要建置執行代理程式的容器映像。 在本節中,您會建置容器映射,並將其推送至容器登錄。
注意
您在本教學課程中建置的映像包含基本的自我裝載代理程式,適合以容器應用程式作業的形式執行。 您可以自定義它,以包含管線所需的其他工具或相依性。
回到終端機,為您的容器映像和登錄定義名稱。
CONTAINER_IMAGE_NAME="azure-pipelines-agent:1.0" CONTAINER_REGISTRY_NAME="<CONTAINER_REGISTRY_NAME>"
將取代
<CONTAINER_REGISTRY_NAME>
為建立容器登錄的唯一名稱。容器登錄名稱在 Azure 內必須是唯一的,且長度必須介於 5 到 50 個字元之間,且長度只包含數位和小寫字母。
建立容器登錄。
az acr create \ --name "$CONTAINER_REGISTRY_NAME" \ --resource-group "$RESOURCE_GROUP" \ --location "$LOCATION" \ --sku Basic \ --admin-enabled true
GitHub 上提供用來建立執行器映像的 Dockerfile。 執行下列命令以複製存放庫,並使用 命令在雲端
az acr build
中建置容器映射。az acr build \ --registry "$CONTAINER_REGISTRY_NAME" \ --image "$CONTAINER_IMAGE_NAME" \ --file "Dockerfile.azure-pipelines" \ "https://github.com/Azure-Samples/container-apps-ci-cd-runner-tutorial.git"
映像現在可在容器登錄中使用。
建立佔位元自我裝載代理程式
您必須先建立佔位元代理程式,才能在新代理程式集區中執行自我裝載代理程式。 佔位元代理程式可確保代理程式集區可供使用。 沒有佔位元代理程式時,使用代理程式集區的管線會失敗。
您可以執行手動作業來註冊離線佔位元代理程式。 作業會執行一次,而且可以刪除。 佔位元代理程式不會取用 Azure Container Apps 或 Azure DevOps 中的任何資源。
在 Container Apps 環境中建立手動作業,以建立佔位元代理程式。
az containerapp job create -n "$PLACEHOLDER_JOB_NAME" -g "$RESOURCE_GROUP" --environment "$ENVIRONMENT" \ --trigger-type Manual \ --replica-timeout 300 \ --replica-retry-limit 0 \ --replica-completion-count 1 \ --parallelism 1 \ --image "$CONTAINER_REGISTRY_NAME.azurecr.io/$CONTAINER_IMAGE_NAME" \ --cpu "2.0" \ --memory "4Gi" \ --secrets "personal-access-token=$AZP_TOKEN" "organization-url=$ORGANIZATION_URL" \ --env-vars "AZP_TOKEN=secretref:personal-access-token" "AZP_URL=secretref:organization-url" "AZP_POOL=$AZP_POOL" "AZP_PLACEHOLDER=1" "AZP_AGENT_NAME=placeholder-agent" \ --registry-server "$CONTAINER_REGISTRY_NAME.azurecr.io"
下表描述命令中使用的索引鍵參數。
參數 描述 --replica-timeout
復本可以執行的持續時間上限。 --replica-retry-limit
重試失敗複本的次數。 --replica-completion-count
在作業執行成功之前,要成功完成的複本數目。 --parallelism
每個作業執行要啟動的複本數目。 --secrets
要用於作業的秘密。 --env-vars
要用於作業的環境變數。 --registry-server
要用於作業的容器登錄伺服器。 針對 Azure Container Registry,命令會自動設定驗證。 設定環境變數會
AZP_PLACEHOLDER
設定代理程式容器,以註冊為離線佔位元元代理程式,而不需要執行作業。執行手動作業以建立佔位元代理程式。
az containerapp job start -n "$PLACEHOLDER_JOB_NAME" -g "$RESOURCE_GROUP"
列出作業的執行,以確認作業執行已建立並順利完成。
az containerapp job execution list \ --name "$PLACEHOLDER_JOB_NAME" \ --resource-group "$RESOURCE_GROUP" \ --output table \ --query '[].{Status: properties.status, Name: name, StartTime: properties.startTime}'
確認已在 Azure DevOps 中建立佔位元代理程式。
- 在 Azure DevOps 中,瀏覽至您的專案。
- 選取 [項目設定>代理程式集區>容器應用程式>代理程式]。
- 確認已列出名為
placeholder-agent
的佔位元代理程式,且其狀態為離線。
不需要再次作業。 您可以刪除它。
az containerapp job delete -n "$PLACEHOLDER_JOB_NAME" -g "$RESOURCE_GROUP"
建立自我裝載代理程式作為事件驅動作業
既然您有佔位元代理程式,您可以建立自我裝載代理程式。 在本節中,您會建立事件驅動作業,以在觸發管線時執行自我裝載代理程式。
az containerapp job create -n "$JOB_NAME" -g "$RESOURCE_GROUP" --environment "$ENVIRONMENT" \
--trigger-type Event \
--replica-timeout 1800 \
--replica-retry-limit 0 \
--replica-completion-count 1 \
--parallelism 1 \
--image "$CONTAINER_REGISTRY_NAME.azurecr.io/$CONTAINER_IMAGE_NAME" \
--min-executions 0 \
--max-executions 10 \
--polling-interval 30 \
--scale-rule-name "azure-pipelines" \
--scale-rule-type "azure-pipelines" \
--scale-rule-metadata "poolName=$AZP_POOL" "targetPipelinesQueueLength=1" \
--scale-rule-auth "personalAccessToken=personal-access-token" "organizationURL=organization-url" \
--cpu "2.0" \
--memory "4Gi" \
--secrets "personal-access-token=$AZP_TOKEN" "organization-url=$ORGANIZATION_URL" \
--env-vars "AZP_TOKEN=secretref:personal-access-token" "AZP_URL=secretref:organization-url" "AZP_POOL=$AZP_POOL" \
--registry-server "$CONTAINER_REGISTRY_NAME.azurecr.io"
下表描述 命令中使用的縮放規則參數。
參數 | 描述 |
---|---|
--min-executions |
每個輪詢間隔執行的作業執行數目下限。 |
--max-executions |
每個輪詢間隔要執行的作業執行數目上限。 |
--polling-interval |
要評估縮放規則的輪詢間隔。 |
--scale-rule-name |
縮放規則的名稱。 |
--scale-rule-type |
要使用的縮放規則類型。 若要深入瞭解 Azure Pipelines Scaler,請參閱 KEDA 檔。 |
--scale-rule-metadata |
縮放規則的元數據。 |
--scale-rule-auth |
調整規則的驗證。 |
調整規則組態會定義要監視的事件來源。 它會在每個輪詢間隔上進行評估,並判斷要觸發的作業執行數目。 若要深入瞭解,請參閱 設定調整規則。
事件驅動作業現在會在 Container Apps 環境中建立。
執行管線並確認作業
既然您已設定自我裝載代理程式作業,您可以執行管線並確認其運作正常。
在 Azure DevOps 專案的左側導覽中,流覽至 [管線]。
選取 [建立準銷售案源]。
選取 [Azure Repos Git] 做為程式碼的位置。
選取您稍早建立的存放庫。
選取 [入門管線]。
在管線 YAML 中,將從 變更
pool
vmImage: ubuntu-latest
為name: container-apps
。pool: name: container-apps
選取儲存並執行。
管線會執行並使用您在 Container Apps 環境中建立的自我裝載代理程序作業。
列出作業的執行,以確認作業執行已建立並順利完成。
az containerapp job execution list \ --name "$JOB_NAME" \ --resource-group "$RESOURCE_GROUP" \ --output table \ --query '[].{Status: properties.status, Name: name, StartTime: properties.startTime}'
提示
有問題嗎? 在 Azure 容器應用程式存放庫中提出問題,讓我們在 GitHub 上了解該問題。
清除資源
完成後,請執行下列命令來刪除包含您容器應用程式資源的資源群組。
警告
下列命令會刪除指定的資源群組和其中包含的所有資源。 如果本教學課程範圍以外的資源存在於指定的資源群組中,則也會一併刪除。
az group delete \
--resource-group $RESOURCE_GROUP
若要刪除 GitHub 存放庫,請參閱 刪除存放庫。