为托管 DevOps 池映像配置预配脚本

托管 DevOps 池提供在将映像分配到代理以运行作业之前为池中的映像运行 PowerShell 脚本(Windows)或 Bash 脚本(Linux)的选项。 此功能支持安装受信任的根 CA 和设置环境变量等方案。

Important

预配脚本目前为预览版。 在正式发布之前,该功能可能会更改。

托管 DevOps 池使用与池关联的托管标识,将脚本从 Azure Blob 存储下载到代理,并上传预配脚本日志以便进行故障排除。 预配脚本在代理启动时运行,可以将代理配置为在脚本运行后重启。

若要配置托管 DevOps 池映像以运行预配脚本,请执行以下步骤:

  1. 在Blob 存储帐户中创建两个 blob 容器:一个用于预配脚本和支持文件,一个用于上传预配脚本日志。 将预配脚本和任何支持文件上传到脚本 Blob 容器。
  2. 将托管标识与托管 DevOps 池相关联,并将所需的角色分配给适当的范围内的托管标识,以便代理可以读取预配脚本并上传预配脚本日志。
  3. 将镜像配置为使用所需的预配脚本。

先决条件

创建 Blob 容器

托管 DevOps 池从 Blob 存储 帐户中的容器内的 Blob 对象下载预配脚本及其相关文件。 托管 DevOps 池需要存储帐户中的两个 Blob 容器:一个用于下载预配脚本和支持文件,一个用于上传预配脚本日志。

在Blob 存储帐户中创建以下两个 Blob 容器。

Blob 存储容器 Description
脚本 Blob 容器。 如果在将映像配置为运行预配脚本时未在 入口点 (provisioningScriptEntryPoint)中指定自定义名称,则默认名称为 provisioningscript。 包含预配脚本和任何支持文件。 对于 Windows 映像,预配脚本必须命名为 Setup.sh;对于 Linux 映像,则必须命名为 Setup.ps1。
预配脚本日志容器。 无法配置此容器名称;它必须是 mdpprovisioningscriptlogs。

托管 DevOps 池可以自动创建 mdpprovisioningscriptlogs Blob 容器,但为了实现最小权限访问,我们建议手动创建 mdpprovisioningscriptlogs 容器。 有关更多信息,请参阅 向托管标识分配 Azure 角色。
包含由stdout预配脚本stderr生成的日志,以及该脚本的副本。 Blob 名称中使用代理的计算机名称作为虚拟目录。

将预配脚本和任何支持文件上传到脚本 Blob 容器。 对于 Windows 映像,预配脚本必须命名为 Setup.sh;对于 Linux 映像,则必须命名为 Setup.ps1。 可以在 Blob 中包含脚本所需的任何支持文件。 代理启动时,这些文件将下载到代理的工作目录,并从该位置执行预配脚本。

将 Azure 角色分配给托管标识

托管 DevOps 池使用托管标识访问用于存放预配脚本及其日志的 Blob 容器。 必须将托管标识关联到你的托管 DevOps 池,并在本节所述的作用域内向该托管标识分配指定的角色。 如果托管 DevOps 池没有托管标识,请按照 为托管 DevOps 池配置托管标识中的步骤创建一个。

  • 如果托管 DevOps 池具有单个关联的托管标识,则该标识用于访问预配脚本和预配脚本日志容器。
  • 如果你的托管 DevOps 池具有多个关联的托管标识,请在将映像配置为使用预配脚本时,通过指定 托管标识客户端 ID(provisioningScriptManagedIdentityResourceId)属性,来指定供预配脚本使用的特定托管标识。

在指定作用域内,将下表中的角色分配给 Managed DevOps 池关联的托管标识,以使代理能够下载脚本并上传预配脚本的日志。 有关分配Azure角色的详细信息,请参阅分配Azure角色的步骤。

角色 Scope
存储 Blob 数据读者 编写 Blob 容器范围的脚本。 如果在将映像配置为运行预配脚本时未在 入口点 (provisioningScriptEntryPoint)中指定名称,则默认名称为 provisioningscript。
存储 blob 数据参与者 对于最小权限访问,请手动创建预配脚本日志容器(mdpprovisioningscriptlogs),并在该 Blob 容器作用域内将角色分配给托管标识。

如果希望 Managed DevOps Pools 创建该容器,请在存储帐户作用域内将该角色分配给托管身份。 如果在存储帐户范围内分配存储 Blob 数据参与者角色,则无需在脚本容器范围分配存储 Blob 数据读取者角色。

将映像配置为使用预配脚本

若要将预配脚本用于映像,请配置以下映像属性。

财产 Description
存储帐户资源 ID
provisioningScriptStorageAccountResourceId
必需。 包含脚本容器(默认名称为 provisioningscript)和 mdpprovisioningscriptlogs 容器的存储账户的资源 ID。
入口点
provisioningScriptEntryPoint
包含预配脚本和支持文件的 Blob 容器的名称。 如果未指定值,则默认值为 provisioningscript。
托管标识客户端 ID
provisioningScriptManagedIdentityClientId
必填(如果您的池与多个托管标识相关联)。 用于访问脚本和预配脚本日志容器中的 blob 的托管标识的客户端 ID。 如果你的托管 DevOps 池关联了多个托管标识,则必须在此处指定要使用哪一个。 如果该池只有一个身份,则此属性为可选项。
脚本执行后重启
provisioningScriptShouldRestart
在运行预配脚本以及将作业发送到代理之前,代理是否应重启。 如果未指定值,则默认值为 false。

脚本执行后重启会增加预配时间,并且仅当预配脚本进行更改时,才需要重启才能生效。

注释

预配脚本在 API 版本 2026-06-02 或更高版本中可用。

如果在配置预配脚本后使用以前的 API 版本更新池,则不会保留预配脚本设置。

若要配置映像的预配脚本设置,请转到池设置的 “映像 ”部分,然后选择 ...。>配置预配脚本。

显示“配置预配脚本”菜单选项的屏幕截图。

添加或更新映像的预配脚本设置,然后选择“ 保存”。

显示“配置预配脚本设置”的屏幕截图。

预配错误

下表列出了预配脚本错误代码和说明。

失败代码 Description
ProvisioningScriptDownloadFailed 预配期间无法将预配脚本下载到计算机。
ProvisioningScriptAccessFailed 预配过程无法访问预配脚本。 通常,此错误是由于检索脚本时出现访问或权限问题。
ProvisioningScriptExecutionFailed 预配脚本已下载,但在计算机上运行时失败。
ProvisioningScriptLogUploadFailed 预配过程生成了预配脚本日志,但无法上传这些日志。

预配脚本日志

预配脚本日志包含脚本生成的标准输出(stdout)和标准错误(stderr)。 Managed DevOps Pools 将这些日志写入你指定的存储帐户中的 mdpprovisioningscriptlogs Blob 容器。 Blob 组织在名称采用 mdp-{poolName}-{agentMachineName} 格式的虚拟目录下。 此虚拟目录包含output包含和stderr.logstdout.log文件的虚拟目录,以及script包含运行脚本副本的虚拟目录。

托管的 DevOps 池不管理这些日志,因此你必须使用 Azure Blob 存储生命周期管理策略来管理你的存储帐户中这些日志的保留期限。 以下名为 DeleteOldMDPLogs 的示例策略会在日志 blob 上次修改三天后将其删除。

{
  "rules": [
    {
      "enabled": true,
      "name": "DeleteOldMDPLogs",
      "type": "Lifecycle",
      "definition": {
        "actions": {
          "baseBlob": {
            "delete": {
              "daysAfterModificationGreaterThan": 3
            }
          }
        },
        "filters": {
          "blobTypes": [
            "blockBlob"
          ],
          "prefixMatch": [
            "mdpprovisioningscriptlogs/"
          ]
        }
      }
    }
  ]
}

可以从GitHub Copilot获取 AI 帮助,以生成Azure Blob 存储生命周期管理策略。 自定义以下提示以创建Azure Blob 存储生命周期管理策略。

Build an Azure Blob Storage lifecycle management policy named DeleteOldMDPLogs that deletes logs after three days.

若要获取有关Copilot生成的策略的更多详细信息,可以要求Copilot在提示中提供有关生成的策略的说明。

Copilot 由 AI 提供支持,因此可能会带来意外和错误。 有关详细信息,请参阅 Copilot 常规使用常见问题解答。

有关详细信息,请参阅Azure Blob 存储生命周期管理策略和配置生命周期管理策略。

另见