教程：提交源代码时在云中运行多步骤容器工作流

项目
12/25/2023

除快速任务以外，ACR 任务还支持在向 Git 存储库提交源代码时可自动触发的多步骤多容器式工作流。

本教程介绍如何使用示例 YAML 文件来定义多步骤任务，以便在提交源代码时生成、运行一个或多个容器映像并将其推送到注册表。若要创建仅在提交代码时自动生成单个映像的任务，请参阅教程：提交源代码时在云中自动化容器映像生成。有关 ACR 任务的概述，请参阅使用 ACR 任务自动执行 OS 和框架修补。

本教程的内容：

使用 YAML 文件定义多步骤任务
创建任务
（可选）将凭据添加到该任务，以便能够访问注册表
测试任务
查看任务状态
使用代码提交触发任务

本教程假设你已完成前面教程中的任务。如果尚未完成，请先完成前面教程先决条件部分中的步骤，再继续操作。

必备条件

获取示例代码

本教程假设你已完成前面教程中的步骤，并且已经创建分支和克隆示例存储库。如果尚未完成，请先完成前面教程先决条件部分中的步骤，再继续操作。

容器注册表

Azure 订阅中必须具有 Azure 容器注册表才能完成此教程。如果需要注册表，请参阅快速入门：使用 Azure CLI 创建容器注册表。

创建 GitHub 个人访问令牌

若要在向 Git 存储库提交内容时触发任务，ACR 任务需要用于访问存储库的个人访问令牌 (PAT)。如果还没有 PAT，请按照以下步骤在 GitHub 中生成一个：

导航到 GitHub 上的 PAT 创建页面 https://github.com/settings/tokens/new
输入令牌的简短说明，例如“ACR 任务演示”
选择 ACR 的作用域以访问存储库。要像本教程一样访问公共存储库，请在“存储库”下方，启用“存储库:状态”和“public_repo”

注意

若要生成 PAT 以访问专用存储库，请选择完全存储库控制的作用域。
选择“生成令牌”按钮（可能会要求你确认密码）
将生成的令牌复制并保存到安全位置（在后续部分定义任务时会使用此令牌）

为 Azure CLI 准备环境

如需在本地运行 CLI 参考命令，请安装 Azure CLI。如果在 Windows 或 macOS 上运行，请考虑在 Docker 容器中运行 Azure CLI。有关详细信息，请参阅如何在 Docker 容器中运行 Azure CLI。
- 如果使用的是本地安装，请使用 az login 命令登录到 Azure CLI。若要完成身份验证过程，请遵循终端中显示的步骤。有关其他登录选项，请参阅使用 Azure CLI 登录。
- 出现提示时，请在首次使用时安装 Azure CLI 扩展。有关扩展详细信息，请参阅使用 Azure CLI 的扩展。
- 运行 az version 以查找安装的版本和依赖库。若要升级到最新版本，请运行 az upgrade。

注意

在可以在由世纪互联运营的 Microsoft Azure 中使用 Azure CLI 之前，请先运行 az cloud set -n AzureChinaCloud 来更改云环境。若要切换回 Azure 公有云，请再次运行 az cloud set -n AzureCloud。

创建多步骤任务

完成启用 ACR 任务以读取提交状态及在存储库中创建 Webhook 所需的步骤后，请创建一个用于触发容器映像生成、运行和推送的多步骤任务。

YAML 文件

在 YAML 文件中定义多步骤任务的步骤。本教程的第一个示例多步骤任务在 taskmulti.yaml 文件中定义，该文件位于克隆的 GitHub 存储库的根目录：

version: v1.1.0
steps:
# Build target image
- build: -t {{.Run.Registry}}/hello-world:{{.Run.ID}} -f Dockerfile .
# Run image 
- cmd: -t {{.Run.Registry}}/hello-world:{{.Run.ID}}
  id: test
  detach: true
  ports: ["8080:80"]
- cmd: docker stop test
# Push image
- push:
  - {{.Run.Registry}}/hello-world:{{.Run.ID}}

此多步骤任务执行以下操作：

运行 build 步骤，以基于工作目录中的 Dockerfile 生成映像。该映像面向 Run.Registry（运行任务的注册表），并以唯一的 ACR 任务运行 ID 进行标记。
运行 cmd 步骤，以在临时容器中运行该映像。此示例在后台启动一个长时间运行的容器，返回容器 ID，然后停止该容器。在实际方案中，可以包含用于测试运行中容器的步骤，以确保该容器正常运行。
在 push 步骤中，将生成的映像推送到运行注册表。

任务命令

首先，使用适用于环境的值填充这些 shell 环境变量。此步骤并非必须执行的步骤，但它能让在此教程中执行多个 Azure CLI 命令更容易。如果未填充这些环境变量，则每当示例命令中出现每个值，都必须手动替换该值。

ACR_NAME=<registry-name>        # The name of your Azure container registry
GIT_USER=<github-username>      # Your GitHub user account name
GIT_PAT=<personal-access-token> # The PAT you generated in the previous section

现在，请执行以下 az acr task create 命令创建该任务：

az acr task create \
    --registry $ACR_NAME \
    --name example1 \
    --context https://github.com/$GIT_USER/acr-build-helloworld-node.git#main \
    --file taskmulti.yaml \
    --git-access-token $GIT_PAT

此任务指定，每当向 --context 指定的主分支存储库提交代码时，ACR 任务都要基于该分支中的代码运行该多步骤任务。存储库根目录中的 --file 指定的 YAML 文件将定义步骤。

成功的 az acr task create 命令的输出应如下所示：

{
  "agentConfiguration": {
    "cpu": 2
  },
  "creationDate": "2020-11-20T03:14:31.763887+00:00",
  "credentials": null,
  "id": "/subscriptions/<Subscription ID>/resourceGroups/myregistry/providers/Microsoft.ContainerRegistry/registries/myregistry/tasks/taskmulti",
  "location": "chinaeast2",
  "name": "example1",
  "platform": {
    "architecture": "amd64",
    "os": "linux",
    "variant": null
  },
  "provisioningState": "Succeeded",
  "resourceGroup": "myresourcegroup",
  "status": "Enabled",
  "step": {
    "baseImageDependencies": null,
    "contextAccessToken": null,
    "contextPath": "https://github.com/gituser/acr-build-helloworld-node.git#main",
    "taskFilePath": "taskmulti.yaml",
    "type": "FileTask",
    "values": [],
    "valuesFilePath": null
  },
  "tags": null,
  "timeout": 3600,
  "trigger": {
    "baseImageTrigger": {
      "baseImageTriggerType": "Runtime",
      "name": "defaultBaseimageTriggerName",
      "status": "Enabled"
    },
    "sourceTriggers": [
      {
        "name": "defaultSourceTriggerName",
        "sourceRepository": {
          "branch": "main",
          "repositoryUrl": "https://github.com/gituser/acr-build-helloworld-node.git#main",
          "sourceControlAuthProperties": null,
          "sourceControlType": "Github"
        },
        "sourceTriggerEvents": [
          "commit"
        ],
        "status": "Enabled"
      }
    ]
  },
  "type": "Microsoft.ContainerRegistry/registries/tasks"
}

测试多步骤工作流

若要测试多步骤任务，请执行 az acr task run 命令手动将其触发：

az acr task run --registry $ACR_NAME --name example1

默认情况下，执行此命令时，az acr task run 命令会将日志流式传输到控制台。输出显示每个任务步骤的运行进度。以下输出经过简化，只显示关键步骤。

Queued a run with ID: cab
Waiting for an agent...
2020/11/20 00:03:31 Downloading source code...
2020/11/20 00:03:33 Finished downloading source code
2020/11/20 00:03:33 Using acb_vol_cfe6bd55-3076-4215-8091-6a81aec3d1b1 as the home volume
2020/11/20 00:03:33 Creating Docker network: acb_default_network, driver: 'bridge'
2020/11/20 00:03:34 Successfully set up Docker network: acb_default_network
2020/11/20 00:03:34 Setting up Docker configuration...
2020/11/20 00:03:34 Successfully set up Docker configuration
2020/11/20 00:03:34 Logging in to registry: myregistry.azurecr.cn
2020/11/20 00:03:35 Successfully logged into myregistry.azurecr.cn
2020/11/20 00:03:35 Executing step ID: acb_step_0. Working directory: '', Network: 'acb_default_network'
2020/11/20 00:03:35 Scanning for dependencies...
2020/11/20 00:03:36 Successfully scanned dependencies
2020/11/20 00:03:36 Launching container with name: acb_step_0
Sending build context to Docker daemon  24.06kB
[...]
Successfully built f669bfd170af
Successfully tagged myregistry.azurecr.cn/hello-world:cf19
2020/11/20 00:03:43 Successfully executed container: acb_step_0
2020/11/20 00:03:43 Executing step ID: acb_step_1. Working directory: '', Network: 'acb_default_network'
2020/11/20 00:03:43 Launching container with name: acb_step_1
279b1cb6e092b64c8517c5506fcb45494cd5a0bd10a6beca3ba97f25c5d940cd
2020/11/20 00:03:44 Successfully executed container: acb_step_1
2020/11/20 00:03:44 Executing step ID: acb_step_2. Working directory: '', Network: 'acb_default_network'
2020/11/20 00:03:44 Pushing image: myregistry.azurecr.cn/hello-world:cf19, attempt 1
[...]
2020/11/20 00:03:46 Successfully pushed image: myregistry.azurecr.cn/hello-world:cf19
2020/11/20 00:03:46 Step ID: acb_step_0 marked as successful (elapsed time in seconds: 7.425169)
2020/11/20 00:03:46 Populating digests for step ID: acb_step_0...
2020/11/20 00:03:47 Successfully populated digests for step ID: acb_step_0
2020/11/20 00:03:47 Step ID: acb_step_1 marked as successful (elapsed time in seconds: 0.827129)
2020/11/20 00:03:47 Step ID: acb_step_2 marked as successful (elapsed time in seconds: 2.112113)
2020/11/20 00:03:47 The following dependencies were found:
2020/11/20 00:03:47
- image:
    registry: myregistry.azurecr.cn
    repository: hello-world
    tag: cf19
    digest: sha256:6b981a8ca8596e840228c974c929db05c0727d8630465de536be74104693467a
  runtime-dependency:
    registry: registry.hub.docker.com
    repository: library/node
    tag: 15-alpine
    digest: sha256:8dafc0968fb4d62834d9b826d85a8feecc69bd72cd51723c62c7db67c6dec6fa
  git:
    git-head-revision: 1a3065388a0238e52865db1c8f3e97492a43444c

Run ID: cab was successful after 18s

使用命令触发生成

通过手动运行任务对其进行测试后，可通过更改源代码手动触发该任务。

首先，确保你位于包含存储库的本地克隆的目录中：

cd acr-build-helloworld-node

接下来执行以下命令，创建新文件，并将其提交和推送给你在 GitHub 上的存储库分支：

echo "Hello World!" > hello.txt
git add hello.txt
git commit -m "Testing ACR Tasks"
git push origin main

执行 git push 命令时可能需要提供 GitHub 凭据。提供 GitHub 用户名并输入之前为密码创建的个人访问令牌 (PAT)。

Username for 'https://github.com': <github-username>
Password for 'https://githubuser@github.com': <personal-access-token>

将提交内容推送到存储库后，ACR 任务创建的 Webhook 将在 Azure 容器注册表中触发并启动该任务。显示当前正在运行的任务的日志，以验证和监视生成进度：

az acr task logs --registry $ACR_NAME

输出结果类似于以下内容，显示当前执行（或最近执行）的任务：

Showing logs of the last created run.
Run ID: cad

[...]

Run ID: cad was successful after 37s

生成列表

若要查看 ACR 任务对注册表完成的任务运行列表，请运行 az acr task list-runs 命令：

az acr task list-runs --registry $ACR_NAME --output table

该命令产生的输出应如下所示。将显示 ACR 任务已执行的运行，并在最近执行的任务的 TRIGGER 列中显示“Git Commit”：

RUN ID    TASK            PLATFORM    STATUS     TRIGGER    STARTED               DURATION
--------  --------------  ---------- ---------   ---------  --------------------  ----------
cad       example1        linux       Succeeded  Commit     2020-11-20T00:22:15Z  00:00:35
cac       taskhelloworld  linux       Succeeded  Commit     2020-11-20T00:22:15Z  00:00:22
cab       example1        linux       Succeeded  Manual     2020-11-20T00:18:36Z  00:00:47

创建多注册表多步骤任务

默认情况下，ACR 任务有权从运行任务的注册表推送或提取映像。你可能想要运行一个除了面向运行注册表以外，还面向其他一个或多个注册表的多步骤任务。例如，你可能需要在一个注册表中生成映像，并在由生产系统访问的另一个注册表中存储具有不同标记的映像。此示例演示如何创建此类任务，并提供另一个注册表的凭据。

如果没有另一个注册表，请为此示例创建一个注册表。如果需要注册表，请参阅前面教程，或快速入门：使用 Azure CLI 创建容器注册表。

若要创建任务，需要注册表登录服务器的名称，其格式为“mycontainerregistrydate.azurecr.cn”（全小写）。此示例使用第二个注册表来存储按生成日期标记的映像。

YAML 文件

本教程的第二个示例多步骤任务在 taskmulti-multiregistry.yaml 文件中定义，该文件位于克隆的 GitHub 存储库的根目录：

version: v1.1.0
steps:
# Build target images
- build: -t {{.Run.Registry}}/hello-world:{{.Run.ID}} -f Dockerfile .
- build: -t {{.Values.regDate}}/hello-world:{{.Run.Date}} -f Dockerfile .
# Run image 
- cmd: -t {{.Run.Registry}}/hello-world:{{.Run.ID}}
  id: test
  detach: true
  ports: ["8080:80"]
- cmd: docker stop test
# Push images
- push:
  - {{.Run.Registry}}/hello-world:{{.Run.ID}}
  - {{.Values.regDate}}/hello-world:{{.Run.Date}}

此多步骤任务执行以下操作：

运行两个 build 步骤，以基于工作目录中的 Dockerfile 生成映像：
- 第一个映像面向 Run.Registry（运行任务的注册表），并以 ACR 任务运行 ID 进行标记。
- 第二个映像面向创建任务时设置的（或通过传递给 az acr task create 的外部 values.yaml 文件提供的）regDate 值标识的注册表。此映像以运行日期进行标记。
运行 cmd 步骤，以运行某个生成的容器。此示例在后台启动一个长时间运行的容器，返回容器 ID，然后停止该容器。在实际方案中，可以测试正在运行的容器，以确保该容器正常运行。
在 push 步骤中，将生成的第一个映像推送到运行注册表，将生成的第二个映像推送到 regDate 标识的注册表。

任务命令

使用前面定义的 shell 环境变量，通过执行以下 az acr task create 命令创建任务。请将 mycontainerregistrydate 替换为你的注册表名称。

az acr task create \
    --registry $ACR_NAME \
    --name example2 \
    --context https://github.com/$GIT_USER/acr-build-helloworld-node.git#main \
    --file taskmulti-multiregistry.yaml \
    --git-access-token $GIT_PAT \
    --set regDate=mycontainerregistrydate.azurecr.cn

添加任务凭据

若要将映像推送到 regDate 值标识的注册表，请使用 az acr task credential add 命令将该注册表的登录凭据添加到任务。

对于此示例，建议创建一个有权访问该注册表且范围为 AcrPush 角色的服务主体，以便能够推送映像。若要创建服务主体，请使用以下脚本：

#!/bin/bash
# This script requires Azure CLI version 2.25.0 or later. Check version with `az --version`.

# Modify for your environment.
# ACR_NAME: The name of your Azure Container Registry
# SERVICE_PRINCIPAL_NAME: Must be unique within your AD tenant
ACR_NAME=$containerRegistry
SERVICE_PRINCIPAL_NAME=$servicePrincipal

# Obtain the full registry ID
ACR_REGISTRY_ID=$(az acr show --name $ACR_NAME --query "id" --output tsv)
# echo $registryId

# Create the service principal with rights scoped to the registry.
# Default permissions are for docker pull access. Modify the '--role'
# argument value as desired:
# acrpull:     pull only
# acrpush:     push and pull
# owner:       push, pull, and assign roles
PASSWORD=$(az ad sp create-for-rbac --name $SERVICE_PRINCIPAL_NAME --scopes $ACR_REGISTRY_ID --role acrpull --query "password" --output tsv)
USER_NAME=$(az ad sp list --display-name $SERVICE_PRINCIPAL_NAME --query "[].appId" --output tsv)

# Output the service principal's credentials; use these in your services and
# applications to authenticate to the container registry.
echo "Service principal ID: $USER_NAME"
echo "Service principal password: $PASSWORD"

在以下 az acr task credential add 命令中传递服务主体应用程序 ID 和密码。请确保用第二个注册表的名称更新登录服务器名称 mycontainerregistrydate：

az acr task credential add --name example2 \
    --registry $ACR_NAME \
    --login-server mycontainerregistrydate.azurecr.cn \
    --username <service-principal-application-id> \
    --password <service-principal-password>

该 CLI 会返回添加的注册表登录服务器的名称。

测试多步骤工作流

与在前面的示例中一样，若要测试多步骤任务，请执行 az acr task run 命令手动将其触发。若要通过向 Git 存储库提交代码来触发任务，请参阅通过提交触发生成部分。

az acr task run --registry $ACR_NAME --name example2

默认情况下，执行此命令时，az acr task run 命令会将日志流式传输到控制台。与前面一样，输出将显示每个任务步骤的运行进度。该输出已经过简化，只显示关键步骤。

输出：

Queued a run with ID: cf1g
Waiting for an agent...
2020/11/20 04:33:39 Downloading source code...
2020/11/20 04:33:41 Finished downloading source code
2020/11/20 04:33:42 Using acb_vol_4569b017-29fe-42bd-83b2-25c45a8ac807 as the home volume
2020/11/20 04:33:42 Creating Docker network: acb_default_network, driver: 'bridge'
2020/11/20 04:33:43 Successfully set up Docker network: acb_default_network
2020/11/20 04:33:43 Setting up Docker configuration...
2020/11/20 04:33:44 Successfully set up Docker configuration
2020/11/20 04:33:44 Logging in to registry: mycontainerregistry.azurecr.cn
2020/11/20 04:33:45 Successfully logged into mycontainerregistry.azurecr.cn
2020/11/20 04:33:45 Logging in to registry: mycontainerregistrydate.azurecr.cn
2020/11/20 04:33:47 Successfully logged into mycontainerregistrydate.azurecr.cn
2020/11/20 04:33:47 Executing step ID: acb_step_0. Working directory: '', Network: 'acb_default_network'
2020/11/20 04:33:47 Scanning for dependencies...
2020/11/20 04:33:47 Successfully scanned dependencies
2020/11/20 04:33:47 Launching container with name: acb_step_0
Sending build context to Docker daemon  25.09kB
[...]
Successfully tagged mycontainerregistry.azurecr.cn/hello-world:cf1g
2020/11/20 04:33:55 Successfully executed container: acb_step_0
2020/11/20 04:33:55 Executing step ID: acb_step_1. Working directory: '', Network: 'acb_default_network'
2020/11/20 04:33:55 Scanning for dependencies...
2020/11/20 04:33:56 Successfully scanned dependencies
2020/11/20 04:33:56 Launching container with name: acb_step_1
Sending build context to Docker daemon  25.09kB
[...]
Successfully tagged mycontainerregistrydate.azurecr.cn/hello-world:20190503-043342z
2020/11/20 04:33:57 Successfully executed container: acb_step_1
2020/11/20 04:33:57 Executing step ID: acb_step_2. Working directory: '', Network: 'acb_default_network'
2020/11/20 04:33:57 Launching container with name: acb_step_2
721437ff674051b6be63cbcd2fa8eb085eacbf38d7d632f1a079320133182101
2020/11/20 04:33:58 Successfully executed container: acb_step_2
2020/11/20 04:33:58 Executing step ID: acb_step_3. Working directory: '', Network: 'acb_default_network'
2020/11/20 04:33:58 Launching container with name: acb_step_3
test
2020/11/20 04:34:09 Successfully executed container: acb_step_3
2020/11/20 04:34:09 Executing step ID: acb_step_4. Working directory: '', Network: 'acb_default_network'
2020/11/20 04:34:09 Pushing image: mycontainerregistry.azurecr.cn/hello-world:cf1g, attempt 1
The push refers to repository [mycontainerregistry.azurecr.cn/hello-world]
[...]
2020/11/20 04:34:12 Successfully pushed image: mycontainerregistry.azurecr.cn/hello-world:cf1g
2020/11/20 04:34:12 Pushing image: mycontainerregistrydate.azurecr.cn/hello-world:20190503-043342z, attempt 1
The push refers to repository [mycontainerregistrydate.azurecr.cn/hello-world]
[...]
2020/11/20 04:34:19 Successfully pushed image: mycontainerregistrydate.azurecr.cn/hello-world:20190503-043342z
2020/11/20 04:34:19 Step ID: acb_step_0 marked as successful (elapsed time in seconds: 8.125744)
2020/11/20 04:34:19 Populating digests for step ID: acb_step_0...
2020/11/20 04:34:21 Successfully populated digests for step ID: acb_step_0
2020/11/20 04:34:21 Step ID: acb_step_1 marked as successful (elapsed time in seconds: 2.009281)
2020/11/20 04:34:21 Populating digests for step ID: acb_step_1...
2020/11/20 04:34:23 Successfully populated digests for step ID: acb_step_1
2020/11/20 04:34:23 Step ID: acb_step_2 marked as successful (elapsed time in seconds: 0.795440)
2020/11/20 04:34:23 Step ID: acb_step_3 marked as successful (elapsed time in seconds: 11.446775)
2020/11/20 04:34:23 Step ID: acb_step_4 marked as successful (elapsed time in seconds: 9.734973)
2020/11/20 04:34:23 The following dependencies were found:
2020/11/20 04:34:23
- image:
    registry: mycontainerregistry.azurecr.cn
    repository: hello-world
    tag: cf1g
    digest: sha256:75354e9edb995e8661438bad9913deed87a185fddd0193811f916d684b71a5d2
  runtime-dependency:
    registry: registry.hub.docker.com
    repository: library/node
    tag: 15-alpine
    digest: sha256:8dafc0968fb4d62834d9b826d85a8feecc69bd72cd51723c62c7db67c6dec6fa
  git:
    git-head-revision: 9d9023473c46a5e2c315681b11eb4552ef0faccc
- image:
    registry: mycontainerregistrydate.azurecr.cn
    repository: hello-world
    tag: 20190503-043342z
    digest: sha256:75354e9edb995e8661438bad9913deed87a185fddd0193811f916d684b71a5d2
  runtime-dependency:
    registry: registry.hub.docker.com
    repository: library/node
    tag: 15-alpine
    digest: sha256:8dafc0968fb4d62834d9b826d85a8feecc69bd72cd51723c62c7db67c6dec6fa
  git:
    git-head-revision: 9d9023473c46a5e2c315681b11eb4552ef0faccc

Run ID: cf1g was successful after 46s

后续步骤

在本教程中，你已了解如何创建一个在向 Git 存储库提交源代码时可自动触发的多个步骤多容器式任务。有关多步骤任务的高级功能，包括并行和依赖性步骤执行，请参阅 ACR 任务 YAML 参考。请转到下一教程来了解如何创建任务，用于在更新容器映像的基础映像时触发生成。

在更新基础映像时自动生成

教程：提交源代码时在云中运行多步骤容器工作流

必备条件

获取示例代码

容器注册表

创建 GitHub 个人访问令牌

为 Azure CLI 准备环境

创建多步骤任务

YAML 文件

任务命令

测试多步骤工作流

使用命令触发生成

生成列表

创建多注册表多步骤任务

YAML 文件

任务命令

添加任务凭据

测试多步骤工作流

后续步骤

其他资源