为部署组预配代理

项目
11/21/2024

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

部署组是 Azure Pipelines 中经典发布管道的部署目标计算机的逻辑组。部署组中的每个目标服务器都需要安装部署代理。本文介绍如何在部署组中的每个物理或虚拟机（VM）上安装和预配部署代理。

可以通过以下任一方式在目标计算机上安装代理：

运行在创建部署组时生成的脚本。
在 VM 上安装 Azure Pipelines 代理 Azure VM 扩展。
使用发布管道中的 AzureResourceGroupDeploymentV2 任务动态创建部署组和预配代理。

以下部分提供了实现每个方法的步骤。

先决条件

Azure DevOps 组织和项目。要创建组织或项目，请参阅创建新组织或在 Azure DevOps 中创建项目。
访问至少具有相应权限的一台 Windows 或 Linux 部署目标计算机。
对于 Azure Pipelines 代理安装方法，具有创建和管理 Azure VM 的权限的 Azure 帐户和订阅。如果还没有 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 代理 Azure VM 扩展

如果使用 Azure VM 作为部署计算机，可以在每个 VM 上安装 Azure Pipelines 代理扩展。该扩展会自动将代理注册到 Azure DevOps 项目中的指定部署组。

若要使用扩展安装代理，请先创建部署组：

从 Azure DevOps 项目中，选择“管道>部署”组。
在“部署组”屏幕上，选择“新建”，或者选择“添加部署组”（如果此部署组是项目中的第一个部署组）。
输入部署组名称和可选说明，然后选择“创建”。

在Azure 门户中，在每个目标 VM 上安装 Azure Pipelines 代理扩展：

在 VM 页上，选择左侧导航中的“设置>扩展 + 应用程序”。
在 “扩展 ”选项卡上，选择“ 添加”。
在“安装扩展”页上，搜索并选择“Azure Pipelines 代理”，然后选择“下一步”。
在 “配置 Azure Pipelines 代理扩展 ”屏幕上，指定以下信息：
- Azure DevOps 组织 URL：输入 Azure DevOps 组织的 URL，例如 https://dev.azure.com/contoso。
- 团队项目：输入项目名称，例如 myProject。
- 部署组：输入创建的部署组的名称。
- 代理名称：（可选）输入代理的名称。如果未输入任何内容，代理将命名为附加的 -DGVM 名称。
- 个人访问令牌：输入用于对 Azure Pipelines 进行身份验证的个人访问令牌（PAT ）。
- 标记：（可选）指定要在代理上配置的标记的逗号分隔列表。每个标记限制为 256 个字符，不区分大小写，对可以使用的标记数没有限制。
选择“查看 + 创建”，然后在验证通过后选择“创建”。

使用 AzureResourceGroupDeploymentV2 任务

可以使用 AzureResourceGroupDeploymentV2 任务部署 Azure 资源管理器（ARM）模板。该模板可以在创建 Azure VM 时安装 Azure Pipelines 代理扩展，也可以更新资源组，以在创建 VM 后应用扩展。

或者，可以使用 AzureResourceGroupDeployment 任务的高级部署选项来部署代理。

创建部署组

首先创建部署组：

从 Azure DevOps 项目中，选择“管道>部署”组。
在“部署组”屏幕上，选择“新建”，或者选择“添加部署组”（如果此部署组是项目中的第一个部署组）。
输入部署组名称和可选说明，然后选择“创建”。

使用 ARM 模板安装代理

ARM 模板是一个 JSON 文件，其以声明方式定义一组 Azure 资源。 Azure 会自动读取模板并预配资源。可以在单个模板中部署多个服务及其依赖项。

若要使用 ARM 模板注册和安装部署代理，请在资源下 Microsoft.Compute/virtualMachine 添加资源元素，如以下代码所示。

"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 是可选的代理名称。如果未指定，则向代理提供附加的 -DG VM 名称。
Tags 是一个可选的逗号分隔的标记列表，可在代理上设置。每个标记限制为 256 个字符，不区分大小写，对可以使用的标记数没有限制。
PATToken 是向 Azure Pipelines 进行身份验证以下载和配置代理所需的 PAT。

有关 ARM 模板的详细信息，请参阅在 Azure 资源管理器模板中定义资源。

在发布管道中使用模板

创建发布管道：

从左侧菜单中选择“管道>发布”，然后选择“新建>发布管道”。
在 Azure Pipelines 的“发布”选项卡中，创建包含 ARM 模板部署任务的阶段的发布管道。
此模板使用任务版本 2，因此在 Azure 资源组部署 设置屏幕上，将 任务版本 从 3.* 更改为 2.*。
提供任务所需的参数，例如 Azure 订阅、资源组名称、位置、模板信息和要执行的操作。
保存发布管道，并从管道创建发布以安装代理。

使用高级部署选项安装代理

或者，可以使用高级部署选项安装代理。按照前面的步骤操作，但在 Azure 资源组部署 设置屏幕上，展开 “虚拟机 的高级部署选项”部分。

在“启用先决条件”下，选择“使用部署组代理进行配置”。
提供以下必需的参数和设置：
- Azure Pipelines 服务连接：选择指向目标的现有服务连接。
  
  如果没有现有的服务连接，请选择“新建”并创建一个。有关详细信息，请参阅 “创建服务连接”。将服务连接配置为使用限制为部署组范围的 PAT。
- 团队项目：选择包含部署组的项目。
- 部署组：选择要将代理注册到的部署组。
- 选择“ 将 Azure VM 标记复制到代理 ”，将已在 Azure VM 上配置的任何标记复制到相应的部署组代理。
  
  默认情况下，使用格式复制所有 Azure 标记，例如Role: Web。Key: Value
保存管道，并创建发布以安装代理。

扩展疑难解答

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 扩展和 1.21.0.1 Linux 扩展的版本1.27.0.2开始，此计算机重启问题已修复。重新启动现在不会向状态文件添加任何内容。但是，如果在早期版本的扩展中出现此问题，并且扩展已自动更新为固定版本，则问题可以保留。较新版本的扩展仍可使用早期状态文件。

如果使用带有标志的早期版本的扩展来关闭次要版本自动更新，或者将大型状态文件从早期版本传递到固定版本，则可能会遇到此问题。如果是这样，可以通过卸载并重新安装扩展来解决该问题。卸载该扩展会清理整个扩展目录，并为最新版本的全新安装创建新的状态文件。

自定义数据问题

Python 2 已弃用，Azure Pipelines 代理扩展适用于 Python 3。如果仍然使用默认未安装 Python 3 的 OS 版本，若要运行扩展，应在 VM 上安装 Python 3，或者切换到默认安装了 Python 3 的 OS 版本。否则，切换 OS 版本时，VM 上的自定义数据位置可能会造成混淆。

在 Linux VM 上，对于早期代理版本，自定义数据会复制到 /var/lib/waagent/ovf-env.xml ，以及 更新版本的 /var/lib/waagent/CustomData 。如果仅硬编码这两个路径中的一个，则在切换 OS 版本时可能会遇到问题，因为新 OS 版本上不存在其中一个路径，尽管存在其他路径。若要避免中断 VM 预配，请考虑在模板中使用这两个路径，以便如果一个路径失败，另一个路径应成功。

帮助和支持

浏览故障排除提示。
获取有关 Stack Overflow 的建议。
在 Azure DevOps 开发人员社区中发布问题、搜索答案或建议功能。
获取 Azure DevOps 支持。

部署组作业
Self-hosted Windows agents（自托管 Windows 代理）
Self-hosted macOS agents（自托管 macOS 代理）
Self-hosted Linux agents（自托管 Linux 代理）
配置并行作业并支付费用
Azure DevOps 定价

通过

为部署组预配代理

先决条件

在目标服务器上运行安装脚本

安装 Azure Pipelines 代理 Azure VM 扩展

使用 AzureResourceGroupDeploymentV2 任务

创建部署组

使用 ARM 模板安装代理

在发布管道中使用模板

使用高级部署选项安装代理

扩展疑难解答

状态文件太大

自定义数据问题

帮助和支持

反馈

其他资源

通过

为部署组预配代理

先决条件

在目标服务器上运行安装脚本

安装 Azure Pipelines 代理 Azure VM 扩展

使用 AzureResourceGroupDeploymentV2 任务

创建部署组

使用 ARM 模板安装代理

在发布管道中使用模板

使用高级部署选项安装代理

扩展疑难解答

状态文件太大

自定义数据问题

帮助和支持

相关内容

反馈

其他资源