ACR 任务参考：YAML

ACR 任务中的多步骤任务定义提供注重于生成、测试和修补容器的，以容器为中心的计算基元。 本文介绍用于定义多步骤任务的 YAML 文件的命令、参数、属性和语法。

本文包含有关为 ACR 任务创建多步骤任务 YAML 文件的参考信息。 如需 ACR 任务的简介，请参阅 ACR 任务概述。

acr-task.yaml 文件格式

ACR 任务支持采用标准 YAML 语法的多步骤任务声明。 在 YAML 文件中定义任务的步骤。 然后，可以通过将该文件传递到 az acr run 命令来手动运行该任务。 或者，运行 az acr task create 命令并使用该文件创建一个任务，每次执行 Git 提交、基础映像更新或计划时，会自动触发该任务。 尽管本文将 acr-task.yaml 称作包含步骤的文件，但 ACR 任务支持带有受支持扩展名的任何有效文件名。

顶级 acr-task.yaml 基元为任务属性、步骤类型和步骤属性：

• 任务属性应用到整个任务执行中的所有步骤。 有几个全局任务属性，包括：
  • version
  • stepTimeout
  • workingDirectory
• 任务步骤类型表示可在任务中执行的操作类型。 有三个步骤类型：
  • build
  • push
  • cmd
• 任务步骤属性是应用到单个步骤的参数。 有多个步骤属性，其中包括：
  • startDelay
  • timeout
  • when
  • ...等等。

acr-task.yaml 文件的基本格式（包括一些通用步骤属性）如下。 尽管本文并未提供所有可用步骤属性或步骤类型用法的详尽表述，但提供了基本文件格式的简要概述。

version: # acr-task.yaml format version.
stepTimeout: # Seconds each step may take.
steps: # A collection of image or container actions.
  - build: # Equivalent to "docker build," but in a multi-tenant environment
  - push: # Push a newly built or retagged image to a registry.
    when: # Step property that defines either parallel or dependent step execution.
  - cmd: # Executes a container, supports specifying an [ENTRYPOINT] and parameters.
    startDelay: # Step property that specifies the number of seconds to wait before starting execution.

支持的任务文件扩展名

ACR 任务具有多个保留的文件扩展名（包括 .yaml），它将这些文件作为任务文件进行处理。 ACR 任务将以下列表中未列出的任何扩展名视为 Dockerfile：.yaml、.yml、.toml、.json、.sh、.bash、.zsh、.ps1、.ps、.cmd、.bat、.ts、.js、.php、.py、.rb、.lua

YAML 是 ACR 任务目前支持的唯一一种文件格式。 其他文件扩展名是保留的，将来可能受到支持。

运行示例任务

本文的后续部分参考了多个示例任务文件。 这些示例任务在公共 GitHub 存储库 Azure-Samples/acr-tasks 中提供。 可以使用 Azure CLI 命令 az acr run 运行这些任务。 示例命令如下所示：

az acr run -f build-push-hello-world.yaml https://github.com/Azure-Samples/acr-tasks.git

示例命令的格式假设已在 Azure CLI 中配置了默认注册表，因此省略了 --registry 参数。 若要配置默认注册表，请结合 命令（接受 set 键值对）使用 defaults.acr=REGISTRY_NAME 命令。

例如，若要在 Azure CLI 中配置名为“myregistry”的默认注册表：

az config set defaults.acr=myregistry

任务属性

任务属性通常显示在 acr-task.yaml 文件的顶部，是在整个任务步骤执行中应用的全局属性。 其中的某些全局属性可在单个步骤中重写。

secret

secret 对象具有以下属性。

network

network 对象具有以下属性。

卷

卷对象具有以下属性。

步骤任务类型

ACR 任务支持三种步骤类型。 每种步骤类型支持多个属性，每个步骤类型的相关部分中会予以详述。

build

生成容器映像。 build 步骤类型表示在云中以多租户的安全方式将 docker build 作为第一类基元运行。

语法：build

version: v1.1.0
steps:
  - [build]: -t [imageName]:[tag] -f [Dockerfile] [context]
    [property]: [value]

运行 az acr run 命令获取 Docker 版本。

az acr run -r $ACR_NAME --cmd "docker version" /dev/null

在 yaml 文件中添加环境变量 DOCKER_BUILDKIT=1 以启用 buildkit，并将 secret 与 buildkit 结合使用。

build 步骤类型支持下表中的参数。 build 步骤类型还支持 docker build 命令的所有生成选项，例如 --build-arg 以设置生成时变量。

属性：build

build 步骤类型支持以下属性。 可在本文的任务步骤属性部分找到这些属性的详细信息。

示例：build

生成映像 - 根目录中的上下文

az acr run -f build-hello-world.yaml https://github.com/AzureCR/acr-tasks-sample.git

version: v1.1.0
steps:
  - build: -t $Registry/hello-world -f hello-world.dockerfile .

生成映像 - 子目录中的上下文

version: v1.1.0
steps:
  - build: -t $Registry/hello-world -f hello-world.dockerfile ./subDirectory

ACR 任务中的动态变量传递

使用 Azure 容器注册表 (ACR) 任务时，可能会发现需要通过将 --set 标签与 az acr task run 命令一起使用，将不同的值传递给生成过程，而无需更改任务定义。

示例：在运行时设置图像标签

假设在 acr-task.yml 文件中定义了一个 ACR 任务，其中包含图像标签的占位符：

steps:
  - build: -t $Registry/hello-world:{{.Values.tag}}

可以使用以下 Azure CLI 命令在运行时触发任务并将 tag 变量设置为 v2：

az acr task run --registry myregistry --name mytask --set tag=v2

此命令将启动名为 mytask 的 ACR 任务，并使用 v2 标签生成图像，覆盖 acr-task.yml 文件中的占位符。

此方法允许在 CI/CD 管道中进行自定义，这样即可根据当前需求动态调整参数，而无需更改任务定义。

push

将生成或重新标记的一个或多个映像推送到容器注册表。 支持推送到 Azure 容器注册表等专用注册表，或推送到公共 Docker 中心。

语法：push

push 步骤类型支持映像集合。 YAML 集合语法支持内联和嵌套格式。 推送单个映像的操作通常使用内联语法来表示：

version: v1.1.0
steps:
  # Inline YAML collection syntax
  - push: ["$Registry/hello-world:$ID"]

为方便阅读，请在推送多个映像时使用嵌套语法：

version: v1.1.0
steps:
  # Nested YAML collection syntax
  - push:
    - $Registry/hello-world:$ID
    - $Registry/hello-world:latest

属性：push

push 步骤类型支持以下属性。 可在本文的任务步骤属性部分找到这些属性的详细信息。

示例：push

推送多个映像

az acr run -f build-push-hello-world.yaml https://github.com/Azure-Samples/acr-tasks.git

version: v1.1.0
steps:
  - build: -t $Registry/hello-world:$ID -f hello-world.dockerfile .
  - push: 
    - $Registry/hello-world:$ID

生成、推送和运行

az acr run -f build-run-hello-world.yaml https://github.com/Azure-Samples/acr-tasks.git

version: v1.1.0
steps:
  - build: -t $Registry/hello-world:$ID -f hello-world.dockerfile .
  - push:
    - $Registry/hello-world:$ID
  - cmd: $Registry/hello-world:$ID

cmd

cmd 步骤类型运行容器。

语法：cmd

version: v1.1.0
steps:
  - [cmd]: [containerImage]:[tag (optional)] [cmdParameters to the image]

属性：cmd

cmd 步骤类型支持以下属性：

可在本文的任务步骤属性部分找到这些属性的详细信息。

示例：cmd

运行 hello-world 映像

此命令执行 hello-world.yaml 任务文件，此文件引用 Docker 中心内的 hello-world 映像。

az acr run -f hello-world.yaml https://github.com/Azure-Samples/acr-tasks.git

version: v1.1.0
steps:
  - cmd: mcr.microsoft.com/hello-world

运行 bash 映像并回显“hello world”

此命令执行 bash-echo.yaml 任务文件，此文件引用 Docker 中心内的 bash 映像。

az acr run -f bash-echo.yaml https://github.com/Azure-Samples/acr-tasks.git

version: v1.1.0
steps:
  - cmd: bash echo hello world

运行特定的 bash 映像标记

若要运行特定的映像版本，请在 cmd 中指定标记。

此命令执行 bash-echo-3.yaml 任务文件，此文件引用 Docker 中心内的 bash:3.0 映像。

az acr run -f bash-echo-3.yaml https://github.com/Azure-Samples/acr-tasks.git

version: v1.1.0
steps:
  - cmd: bash:3.0 echo hello world

运行自定义映像

cmd 步骤类型使用标准的 docker run 格式引用映像。 不是以注册表名称开头的映像被认为源自 dockerhub.azk8s.cn。 下面是前一示例的同等表示形式：

version: v1.1.0
steps:
  - cmd: dockerhub.azk8s.cn/bash:3.0 echo hello world

使用标准的 docker run 映像引用约定，cmd 可以运行任何专用注册表或公共 Docker Hub 中的映像。 如果引用执行 ACR 任务的同一注册表中的映像，则无需指定任何注册表凭据。

• 运行 Azure 容器注册表中的映像。 以下示例假设已有一个名为 myregistry 的注册表，以及一个自定义映像 myimage:mytag。

  version: v1.1.0
  steps:
      - cmd: myregistry.azurecr.cn/myimage:mytag
  

• 使用 Run 变量或别名通用化注册表引用

  不要在 acr-task.yaml 文件中将注册表名称硬编码，可以使用 Run 变量或别名来提高此名称的可移植性。 在运行时，Run.Registry 变量或 $Registry 别名将扩展到执行任务的注册表的名称。

  例如，若要通用化上述任务，使其可在任何 Azure 容器注册表中运行，请在映像名称中引用 $Registry 变量：

  version: v1.1.0
  steps:
    - cmd: $Registry/myimage:mytag
  

访问机密卷

volumes 属性允许针对任务中的 build 和 cmd 步骤指定卷及其机密内容。 在每个步骤中，可选的 volumeMounts 属性列出了在该步骤中要装载到容器中的卷和相应的容器路径。 机密作为每个卷的装载路径中的文件提供。

执行任务并将两个机密装载到步骤：一个存储到密钥保管库，另一个在命令行中指定：

az acr run -f mounts-secrets.yaml --set-secret mysecret=abcdefg123456 https://github.com/Azure-Samples/acr-tasks.git

# This template demonstrates mounting a custom volume into a container at a CMD step
secrets:
  - id: sampleSecret
    keyvault: https://myacbvault2.vault.azure.cn/secrets/SampleSecret # Replace with valid keyvault with access

volumes:
  - name: mysecrets
    secret:
      mysecret1: {{.Secrets.sampleSecret | b64enc}}
      mysecret2: {{.Values.mysecret | b64enc}}

steps:
  - cmd: bash cat /run/test/mysecret1 /run/test/mysecret2
    volumeMounts:
      - name: mysecrets
        mountPath: /run/test

任务步骤属性

每个步骤类型支持适用于其类型的多个属性。 下表定义了所有可用的步骤属性。 并非所有步骤类型都支持所有属性。 若要查看其中的哪些属性可用于每个步骤类型，请参阅 cmd、build 和 push 步骤类型参考部分。

volumeMount

volumeMount 对象具有以下属性。

示例：任务步骤属性

示例：id

生成两个映像，并实例化功能测试映像。 每个步骤由任务中的其他步骤在其 id 属性中引用的唯一 when 进行标识。

az acr run -f when-parallel-dependent.yaml https://github.com/Azure-Samples/acr-tasks.git

version: v1.1.0
steps:
  # build website and func-test images, concurrently
  - id: build-hello-world
    build: -t $Registry/hello-world:$ID -f hello-world.dockerfile .
    when: ["-"]
  - id: build-hello-world-test
    build: -t hello-world-test -f hello-world.dockerfile .
    when: ["-"]
  # run built images to be tested
  - id: hello-world
    cmd: $Registry/hello-world:$ID
    when: ["build-hello-world"]
  - id: func-tests
    cmd: hello-world-test
    env:
      - TEST_TARGET_URL=hello-world
    when: ["hello-world"]
  # push hello-world if func-tests are successful  
  - push: ["$Registry/hello-world:$ID"]
    when: ["func-tests"]

示例：when

when 属性指定某个步骤对任务中其他一个或多个步骤的依赖。 它支持两个参数值：

• when: ["-"] - 指示不依赖于其他步骤。 指定 when: ["-"] 的步骤将立即执行，并启用并发步骤执行。
• when: ["id1", "id2"] - 指示该步骤依赖于使用 id“id1”和 id“id2”的步骤。 在“id1”和“id2”步骤完成之前，此步骤不会执行。

如果未在某个步骤中指定 when，则该步骤依赖于 acr-task.yaml 文件中上一个步骤的完成。

在不指定 when 的情况下按顺序执行步骤：

az acr run -f when-sequential-default.yaml https://github.com/Azure-Samples/acr-tasks.git

version: v1.1.0
steps:
    - cmd: bash echo one
    - cmd: bash echo two
    - cmd: bash echo three

在指定 when 的情况下按顺序执行步骤：

az acr run -f when-sequential-id.yaml https://github.com/Azure-Samples/acr-tasks.git

version: v1.1.0
steps:
    - id: step1
      cmd: bash echo one
    - id: step2
      cmd: bash echo two
      when: ["step1"]
    - id: step3
      cmd: bash echo three
      when: ["step2"]

并行映像生成：

az acr run -f when-parallel.yaml https://github.com/Azure-Samples/acr-tasks.git

version: v1.1.0
steps:
  # build website and func-test images, concurrently
  - id: build-hello-world
    build: -t $Registry/hello-world:$ID -f hello-world.dockerfile .
    when: ["-"]
  - id: build-hello-world-test
    build: -t hello-world-test -f hello-world.dockerfile .
    when: ["-"]

并行映像生成和依赖测试：

az acr run -f when-parallel-dependent.yaml https://github.com/Azure-Samples/acr-tasks.git

version: v1.1.0
steps:
  # build website and func-test images, concurrently
  - id: build-hello-world
    build: -t $Registry/hello-world:$ID -f hello-world.dockerfile .
    when: ["-"]
  - id: build-hello-world-test
    build: -t hello-world-test -f hello-world.dockerfile .
    when: ["-"]
  # run built images to be tested
  - id: hello-world
    cmd: $Registry/hello-world:$ID
    when: ["build-hello-world"]
  - id: func-tests
    cmd: hello-world-test
    env:
      - TEST_TARGET_URL=hello-world
    when: ["hello-world"]
  # push hello-world if func-tests are successful  
  - push: ["$Registry/hello-world:$ID"]
    when: ["func-tests"]

Run 变量

ACR 任务包含一组在执行时可供任务步骤使用的默认变量。 可以使用 {{.Run.VariableName}} 格式访问这些变量，其中，VariableName 是以下值之一：

• Run.ID
• Run.SharedVolume
• Run.Registry
• Run.RegistryName
• Run.Date
• Run.OS
• Run.Architecture
• Run.Commit
• Run.Branch
• Run.TaskName

变量名称通常是自释性的。 下面是常用变量的详细信息。 从 YAML 版本 v1.1.0 开始，可以使用缩写的预定义任务别名来代替大部分 run 变量。 例如，可以使用 {{.Run.Registry}} 别名来代替 $Registry。

Run.ID

通过 az acr run 执行的，或者使用基于触发器的任务执行通过 az acr task create 创建的每个 Run 都有唯一的 ID。 此 ID 表示当前正在执行的运行。

通常用于唯一标记某个映像：

version: v1.1.0
steps:
    - build: -t $Registry/hello-world:$ID .

Run.SharedVolume

共享卷的唯一标识符，所有任务步骤均可对其进行访问。 该卷在 Windows 中装载到 c:\workspace，在 Linux 中装载到 /workspace。

Run.Registry

注册表的完全限定服务器名称。 通常用于泛式引用正在运行任务的注册表。

version: v1.1.0
steps:
  - build: -t $Registry/hello-world:$ID .

Run.RegistryName

容器注册表的名称。 通常在不需要完全限定的服务器名称的任务步骤中使用，例如，针对注册表运行 Azure CLI 命令的 cmd 步骤。

version 1.1.0
steps:
# List repositories in registry
- cmd: az login --identity
- cmd: az acr repository list --name $RegistryName

Run.Date

运行开始时的当前 UTC 时间。

Run.Commit

对于提交到 GitHub 存储库后触发的任务，值为提交标识符。

Run.Branch

对于提交到 GitHub 存储库后触发的任务，值为分支名称。

别名

从 v1.1.0 开始，ACR 任务在执行时支持适用于任务步骤的别名。 别名在概念上类似于 bash 和其他一些命令 shell 中支持的别名（命令快捷方式）。

使用别名，只需输入一个单词即可启动任一命令或一组命令（包括选项和文件名）。

ACR 任务支持多个预定义的别名以及创建的自定义别名。

预定义的别名

可使用以下任务别名来代替 run 变量：

在任务步骤中，请在别名的前面加上 $ 指令，如以下示例所示：

version: v1.1.0
steps:
  - build: -t $Registry/hello-world:$ID -f hello-world.dockerfile .

映像别名

以下每个别名各指向 Microsoft 容器注册表 (MCR) 中的一个稳定映像。 可以在任务文件的 cmd 节中引用其中的每个别名，而无需使用指令。

以下示例任务使用多个别名，来清除运行注册表中 samples/hello-world 存储库内超过 7 天的映像标记：

version: v1.1.0
steps:
  - cmd: acr tag list --registry $RegistryName --repository samples/hello-world
  - cmd: acr purge --registry $RegistryName --filter samples/hello-world:.* --ago 7d

自定义别名

在 YAML 文件中定义自定义别名，并如以下示例所示使用它。 别名只能包含字母数字字符。 用于展开别名的默认指令是 $ 字符。

version: v1.1.0
alias:
  values:
    repo: myrepo
steps:
  - build: -t $Registry/$repo/hello-world:$ID -f Dockerfile .

可以链接到自定义别名定义的远程或本地 YAML 文件。 以下示例链接到 Azure Blob 存储中的 YAML 文件：

version: v1.1.0
alias:
  src:  # link to local or remote custom alias files
    - 'https://link/to/blob/remoteAliases.yml?readSasToken'
[...]

后续步骤

有关多步骤任务的概述，请参阅在 ACR 任务中运行多步骤生成、测试和修补任务。

有关单步骤生成，请参阅 ACR 任务概述。