為部署群組佈建代理程式

發行項
11/21/2024

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

部署群組是 Azure Pipelines 中傳統發行管線的部署目標機器邏輯群組。部署群組中的每個目標伺服器都需要安裝部署代理程式。本文說明如何在部署群組中的每個實體或虛擬機（VM）上安裝及布建部署代理程式。

您可以使用下列任一種方式，在目標電腦上安裝代理程式：

執行當您建立部署群組時所產生的腳稿。
在 VM 上安裝 Azure Pipelines Agent Azure VM 擴充功能。
在發行管線中使用 AzureResourceGroupDeploymentV2 工作，以動態方式建立部署群組和布建代理程式。

下列各節提供實作每個方法的步驟。

必要條件

Azure DevOps 組織與專案。若要建立組織或專案，請參閱在 Azure DevOps 中建立新的組織或建立專案。
至少有一部具有適當許可權的 Windows 或 Linux 部署目標機器的存取權。
針對 Azure Pipelines 代理程式安裝方法，Azure 帳戶和訂用帳戶具有建立和管理 Azure VM 的許可權。如果您沒有 Azure 帳戶，請註冊免費帳戶。

在目標伺服器上執行安裝文本

當您建立部署群組時，會產生可在每個目標計算機上執行的腳本，以註冊伺服器並安裝代理程式。若要使用產生的註冊腳本來安裝代理程式：

從您的 Azure DevOps 專案中，選取 [管線>部署群組]。
在 [ 部署群組 ] 畫面上，選取 [新增]，如果此部署群組是專案中的第一個部署群組，請選取 [新增] 或 [ 新增部署群組 ]。
輸入部署組名和選擇性 [描述]，然後選取 [建立]。
在下一個畫面上，針對要註冊的目標類型選取 [Windows] 或 [Linux]。會產生註冊腳本。
選取 [在腳本中使用個人存取令牌進行驗證]。如需詳細資訊，請參閱使用個人存取令牌。
選取 [ 將腳本複製到剪貼簿]。
在每個目標計算機上，使用具有系統管理許可權的帳戶登入。
執行複製的腳本來註冊計算機並安裝代理程式。針對 Windows 計算機，請使用提升許可權的 PowerShell 命令提示字元。

當文稿執行時：
- 若要將標籤指派給限制部署群組作業中特定伺服器的標籤，請在系統提示輸入標籤時輸入 Y，然後輸入此 VM 的標籤或標籤。
  
  卷標各限制為 256 個字元，不區分大小寫，而且您可以使用的標籤數目沒有限制。
- 當系統提示您輸入使用者帳戶時，請接受預設值。
注意

如果您在執行無法建立安全通道的文稿時收到錯誤，請在系統管理員 PowerShell 提示字元中執行下列命令：

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

設定每個目標伺服器之後，文稿應該會傳回訊息 Service vstsagent.{organization-name}.{computer-name} started successfully。

在 [Azure Pipelines 部署群組] 頁面的 [目標] 索引標籤上，您可以確認代理程式正在執行。如有必要，請重新整理頁面。

安裝 Azure Pipelines Agent Azure VM 擴充功能

如果您使用 Azure VM 作為部署機器，您可以在每個 VM 上安裝 Azure Pipelines 代理程式擴充功能。延伸模組會自動向 Azure DevOps 專案中的指定部署群組註冊代理程式。

若要使用擴充功能安裝代理程式，請先建立部署群組：

從您的 Azure DevOps 專案中，選取 [管線>部署群組]。
在 [ 部署群組 ] 畫面上，選取 [新增]，如果此部署群組是專案中的第一個部署群組，請選取 [新增] 或 [ 新增部署群組 ]。
輸入部署組名和選擇性 [描述]，然後選取 [建立]。

在 Azure 入口網站中，在每個目標 VM 上安裝 Azure Pipelines Agent 擴充功能：

在 VM 頁面上，選取左側導覽中的 [設定>擴充功能 + 應用程式]。
在 [ 擴充功能] 索引標籤上，選取 [ 新增]。
在 [ 安裝擴充功能 ] 頁面上，搜尋並選取 [Azure Pipelines 代理程式]，然後選取 [ 下一步]。
在 [ 設定 Azure Pipelines 代理程序擴充功能 ] 畫面上，指定下列資訊：
- Azure DevOps 組織 URL：輸入 Azure DevOps 組織的 URL，例如 https://dev.azure.com/contoso。
- Team Project：輸入您的項目名稱，例如 myProject。
- 部署群組：輸入您所建立之部署群組的名稱。
- 代理程式名稱：選擇性地輸入代理程序的名稱。如果您未輸入任何專案，代理程式就會命名為附加的 -DGVM 名稱。
- 個人存取令牌：輸入用於向 Azure Pipelines 進行驗證的個人存取令牌（PAT）。
- 標記：選擇性地指定要在代理程式上設定之標記的逗號分隔清單。卷標各限制為 256 個字元，不區分大小寫，而且您可以使用的標籤數目沒有限制。
選取 [檢閱 + 建立]，並在驗證通過時選取 [建立]。

使用 AzureResourceGroupDeploymentV2 工作

您可以使用 AzureResourceGroupDeploymentV2 工作來部署 Azure Resource Manager （ARM）範本。範本可以在建立 Azure VM 時安裝 Azure Pipelines Agent 擴充功能，也可以更新資源群組，以在建立 VM 之後套用擴充功能。

或者，您可以使用 AzureResourceGroupDeployment 工作的進階部署選項來部署代理程式。

建立部署群組

首先建立部署群組：

從您的 Azure DevOps 專案中，選取 [管線>部署群組]。
在 [ 部署群組 ] 畫面上，選取 [新增]，如果此部署群組是專案中的第一個部署群組，請選取 [新增] 或 [ 新增部署群組 ]。
輸入部署組名和選擇性 [描述]，然後選取 [建立]。

使用 ARM 範本來安裝代理程式

ARM 範本是一個 JSON 檔案，會以宣告方式定義一組 Azure 資源。 Azure 會自動讀取範本並布建資源。您可以在單一範本中部署多個服務及其相依性。

若要使用 ARM 範本註冊及安裝部署代理程式，請在資源底下 Microsoft.Compute/virtualMachine 新增 resources 元素，如下列程式碼所示。

"resources": [
  {
    "name": "[concat(parameters('vmNamePrefix'),copyIndex(),'/TeamServicesAgent')]",
    "type": "Microsoft.Compute/virtualMachines/extensions",
    "location": "[parameters('location')]",
    "apiVersion": "2015-06-15",
    "dependsOn": [
        "[resourceId('Microsoft.Compute/virtualMachines/',
                      concat(parameters('vmNamePrefix'),copyindex()))]"
    ],
    "properties": {
      "publisher": "Microsoft.VisualStudio.Services",
      "type": "TeamServicesAgent",
      "typeHandlerVersion": "1.0",
      "autoUpgradeMinorVersion": true,
      "settings": {
        "VSTSAccountName": "[parameters('VSTSAccountName')]",
        "TeamProject": "[parameters('TeamProject')]",
        "DeploymentGroup": "[parameters('DeploymentGroup')]",
        "AgentName": "[parameters('AgentName')]",
        "AgentMajorVersion": "auto|2|3",
        "Tags": "[parameters('Tags')]"
      },
      "protectedSettings": {
      "PATToken": "[parameters('PATToken')]"
     }
   }
  }
]

注意

針對 Linux VM 程式 type 代碼中的下 properties 參數應該是 TeamServicesAgentLinux。

注意

在 Azure DevOps Server 2022.1 和更新版本中，允許的值為 AgentMajorVersion auto|2|3。在 Azure DevOps Server 2022.0 和更早版本中，允許的值為 AgentMajorVersion auto|N。

"resources": [
  {
    "name": "[concat(parameters('vmNamePrefix'),copyIndex(),'/TeamServicesAgent')]",
    "type": "Microsoft.Compute/virtualMachines/extensions",
    "location": "[parameters('location')]",
    "apiVersion": "2015-06-15",
    "dependsOn": [
        "[resourceId('Microsoft.Compute/virtualMachines/',
                      concat(parameters('vmNamePrefix'),copyindex()))]"
    ],
    "properties": {
      "publisher": "Microsoft.VisualStudio.Services",
      "type": "TeamServicesAgent",
      "typeHandlerVersion": "1.0",
      "autoUpgradeMinorVersion": true,
      "settings": {
        "VSTSAccountName": "[parameters('VSTSAccountName')]",
        "TeamProject": "[parameters('TeamProject')]",
        "DeploymentGroup": "[parameters('DeploymentGroup')]",
        "AgentName": "[parameters('AgentName')]",
        "AgentMajorVersion": "auto|N",
        "Tags": "[parameters('Tags')]"
      },
      "protectedSettings": {
      "PATToken": "[parameters('PATToken')]"
     }
   }
  }
]

在上述程式碼中：

VSTSAccountName 是要使用的 Azure Pipelines 組織。例如，如果您的 Azure DevOps URL 是 https://dev.azure.com/contoso，只要指定 contoso
TeamProject 是已定義部署群組的必要專案。
DeploymentGroup 是註冊代理程式的必要部署群組。
AgentName 是選擇性的代理程式名稱。如果未指定，代理程式會以附加的 VM 名稱 -DG 來指定。
Tags 是代理程式上要設定的選擇性逗號分隔標籤清單。卷標各限制為 256 個字元，不區分大小寫，而且您可以使用的標籤數目沒有限制。
PATToken 是向 Azure Pipelines 進行驗證以下載和設定代理程式的必要 PAT。

如需 ARM 範本的詳細資訊，請參閱在 Azure Resource Manager 範本中定義資源。

在發行管線中使用範本

建立發行管線：

從左側功能表中選取 [管線>發行]，然後選取 [新增>發行管線]。
在 Azure Pipelines 的 [發行] 索引標籤中，使用包含 ARM 範本部署工作的階段建立發行管線。
此範本會使用第 2 版的工作，因此在 Azure 資源群組部署 設定畫面上，將 [工作版本 ] 從 3.* 變更為 2.*。
提供工作所需的參數，例如 Azure 訂用帳戶、資源組名、位置、範本資訊和要採取的動作。
儲存發行管線，並從管線建立發行以安裝代理程式。

使用進階部署選項安裝代理程式

或者，您可以使用進階部署選項來安裝代理程式。請遵循上述步驟，但在 [Azure 資源群組部署設定] 畫面上，展開 [虛擬機的進階部署選項] 區段。

在 [啟用必要條件] 底下，選取 [ 使用部署群組代理程序進行設定]。
提供下列必要參數和設定：
- Azure Pipelines 服務連線：選取指向目標的現有服務連線。
  
  如果您沒有現有的服務連線，請選取 [新增 ] 並建立一個。如需詳細資訊，請參閱建立服務連線。將服務連線設定為使用限制為部署群組範圍的 PAT。
- Team 專案：選取包含部署群組的專案。
- 部署群組：選取要註冊代理程式的部署群組。
- 選取 [ 將 Azure VM 標籤複製到代理程式 ]，將 Azure VM 上已設定的任何標籤複製到對應的部署群組代理程式。
  
  根據預設，所有 Azure 標籤都會使用 Key: Value 格式來複製，例如 Role: Web。
儲存管線，並建立發行以安裝代理程式。

針對延伸模組進行疑難解答

Azure Pipelines 代理程式擴充功能有一些已知問題。

狀態檔太大

此問題可能發生在 Windows VM 上。狀態檔包含 JSON 物件，描述延伸模組的目前狀態。對像是列出到目前為止所執行的作業的佔位元。

Azure 會讀取此狀態檔，並傳遞狀態對象作為 API 要求的回應。檔案的大小上限。如果大小超過最大值，Azure 就無法完整讀取它，並針對狀態提供錯誤。

即使擴充功能一開始可能會安裝，但每次機器重新啟動擴充功能時，都會執行附加至狀態檔的一些作業。如果機器重新啟動多次，狀態檔案大小可能會超過臨界值，導致錯誤 Handler Microsoft.VisualStudio.Services.TeamServicesAgent:1.27.0.2 status file 0.status size xxxxxx bytes is too big. Max Limit allowed: 131072 bytes。雖然擴充功能安裝可能會成功，但此錯誤會隱藏延伸模組的實際狀態。

從 Windows 擴充功能和 Linux 擴充1.21.0.1功能的版本1.27.0.2開始，已修正此電腦重新啟動問題。重新啟動現在不會將任何專案新增至狀態檔。不過，如果您在舊版的延伸模塊中發生此問題，且您的擴充功能已自動更新為固定版本，則問題可以保存。較新版本的延伸模組仍然可以使用先前的狀態檔。

如果您使用具有旗標的舊版延伸模組來關閉次要版本自動更新，或大型狀態檔案已從舊版傳送至固定版本，則可能會遇到此問題。若是如此，您可以卸載並重新安裝擴充功能來解決此問題。卸載延伸模組會清除整個延伸模組目錄，並建立新的狀態檔，以重新安裝最新版本。

自訂數據問題

Python 2 已被取代，且 Azure Pipelines 代理程式擴充功能可與 Python 3 搭配運作。如果您仍然使用預設未安裝 Python 3 的作業系統版本，若要執行擴充功能，您應該在 VM 上安裝 Python 3，或切換至預設已安裝 Python 3 的作業系統版本。否則，當您切換 OS 版本時，VM 上的自定義資料位置可能會造成混淆。

在Linux VM上，自定義數據會 複製到舊版的 /var/lib/waagent/ovf-env.xml ，以及更新 版本的 /var/lib/waagent/CustomData 。如果您只硬式編碼這兩個路徑的其中一個，則切換OS版本時可能會遇到問題，因為其中一個路徑不存在於新的OS版本上，但另一個路徑存在。若要避免中斷 VM 布建，請考慮在範本中使用這兩個路徑，讓其中一個路徑失敗，另一個路徑應該會成功。

說明與支援

探索疑難解答秘訣。
取得 Stack Overflow 的建議。
張貼您的問題、搜尋解答，或建議 Azure DevOps 開發人員社群中的功能。
取得 Azure DevOps 的支援。

共用方式為

為部署群組佈建代理程式

必要條件

在目標伺服器上執行安裝文本

安裝 Azure Pipelines Agent Azure VM 擴充功能

使用 AzureResourceGroupDeploymentV2 工作

建立部署群組

使用 ARM 範本來安裝代理程式

在發行管線中使用範本

使用進階部署選項安裝代理程式

針對延伸模組進行疑難解答

狀態檔太大

自訂數據問題

說明與支援

意見反應

其他資源

共用方式為

為部署群組佈建代理程式

必要條件

在目標伺服器上執行安裝文本

安裝 Azure Pipelines Agent Azure VM 擴充功能

使用 AzureResourceGroupDeploymentV2 工作

建立部署群組

使用 ARM 範本來安裝代理程式

在發行管線中使用範本

使用進階部署選項安裝代理程式

針對延伸模組進行疑難解答

狀態檔太大

自訂數據問題

說明與支援

相關內容

意見反應

其他資源