ACR 任务参考：YAMLACR Tasks reference: YAML

• 04/06/2020
• • 

ACR 任务中的多步骤任务定义提供注重于生成、测试和修补容器的，以容器为中心的计算基元。Multi-step task definition in ACR Tasks provides a container-centric compute primitive focused on building, testing, and patching containers. 本文介绍用于定义多步骤任务的 YAML 文件的命令、参数、属性和语法。This article covers the commands, parameters, properties, and syntax for the YAML files that define your multi-step tasks.

本文包含有关为 ACR 任务创建多步骤任务 YAML 文件的参考信息。This article contains reference for creating multi-step task YAML files for ACR Tasks. 如需 ACR 任务的简介，请参阅 ACR 任务概述。If you'd like an introduction to ACR Tasks, see the ACR Tasks overview.

acr-task.yaml 文件格式acr-task.yaml file format

ACR 任务支持采用标准 YAML 语法的多步骤任务声明。ACR Tasks supports multi-step task declaration in standard YAML syntax. 在 YAML 文件中定义任务的步骤。You define a task's steps in a YAML file. 然后，可以通过将该文件传递到 az acr run 命令来手动运行该任务。You can then run the task manually by passing the file to the az acr run command. 或者，运行 az acr task create 命令并使用该文件创建一个任务，每次执行 Git 提交或基础映像更新时，会自动触发该任务。Or, use the file to create a task with az acr task create that's triggered automatically on a Git commit or base image update. 尽管本文将 acr-task.yaml 称作包含步骤的文件，但 ACR 任务支持带有受支持扩展名的任何有效文件名。Although this article refers to acr-task.yaml as the file containing the steps, ACR Tasks supports any valid filename with a supported extension.

顶级 acr-task.yaml 基元为任务属性、步骤类型和步骤属性：The top-level acr-task.yaml primitives are task properties, step types, and step properties:

• 任务属性应用到整个任务执行中的所有步骤。Task properties apply to all steps throughout task execution. 有几个全局任务属性，包括：There are several global task properties, including:
  • version
  • stepTimeout
  • workingDirectory
• 任务步骤类型表示可在任务中执行的操作类型。Task step types represent the types of actions that can be performed in a task. 有三个步骤类型：There are three step types:
  • build
  • push
  • cmd
• 任务步骤属性是应用到单个步骤的参数。Task step properties are parameters that apply to an individual step. 有多个步骤属性，其中包括：There are several step properties, including:
  • startDelay
  • timeout
  • when
  • ...等等。...and many more.

acr-task.yaml 文件的基本格式（包括一些通用步骤属性）如下。The base format of an acr-task.yaml file, including some common step properties, follows. 尽管本文并未提供所有可用步骤属性或步骤类型用法的详尽表述，但提供了基本文件格式的简要概述。While not an exhaustive representation of all available step properties or step type usage, it provides a quick overview of the basic file format.

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.

支持的任务文件扩展名Supported task filename extensions

ACR 任务具有多个保留的文件扩展名（包括 .yaml），它将这些文件作为任务文件进行处理。ACR Tasks has reserved several filename extensions, including .yaml, that it will process as a task file. ACR 任务将以下列表中未列出的任何扩展名视为 Dockerfile：.yaml、.yml、.toml、.json、.sh、.bash、.zsh、.ps1、.ps、.cmd、.bat、.ts、.js、.php、.py、.rb、.luaAny extension not in the following list is considered by ACR Tasks to be a Dockerfile: .yaml, .yml, .toml, .json, .sh, .bash, .zsh, .ps1, .ps, .cmd, .bat, .ts, .js, .php, .py, .rb, .lua

YAML 是 ACR 任务目前支持的唯一一种文件格式。YAML is the only file format currently supported by ACR Tasks. 其他文件扩展名是保留的，将来可能受到支持。The other filename extensions are reserved for possible future support.

运行示例任务Run the sample tasks

本文的后续部分参考了多个示例任务文件。There are several sample task files referenced in the following sections of this article. 这些示例任务在公共 GitHub 存储库 Azure-Samples/acr-tasks 中提供。The sample tasks are in a public GitHub repository, Azure-Samples/acr-tasks. 可以使用 Azure CLI 命令 az acr run 运行这些任务。You can run them with the Azure CLI command az acr run. 示例命令如下所示：The sample commands are similar to:

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

示例命令的格式假设已在 Azure CLI 中配置了默认注册表，因此省略了 --registry 参数。The formatting of the sample commands assumes you've configured a default registry in the Azure CLI, so they omit the --registry parameter. 若要配置默认注册表，请结合 --defaults 参数（接受 acr=REGISTRY_NAME 值）使用 az configure 命令。To configure a default registry, use the az configure command with the --defaults parameter, which accepts an acr=REGISTRY_NAME value.

例如，若要在 Azure CLI 中配置名为“myregistry”的默认注册表：For example, to configure the Azure CLI with a default registry named "myregistry":

az configure --defaults acr=myregistry

任务属性Task properties

任务属性通常显示在 acr-task.yaml 文件的顶部，是在整个任务步骤执行中应用的全局属性。Task properties typically appear at the top of an acr-task.yaml file, and are global properties that apply throughout the full execution of the task steps. 其中的某些全局属性可在单个步骤中重写。Some of these global properties can be overridden within an individual step.

secretsecret

secret 对象具有以下属性。The secret object has the following properties.

网络network

network 对象具有以下属性。The network object has the following properties.

步骤任务类型Task step types

ACR 任务支持三种步骤类型。ACR Tasks supports three step types. 每种步骤类型支持多个属性，每个步骤类型的相关部分中会予以详述。Each step type supports several properties, detailed in the section for each step type.

buildbuild

生成容器映像。Build a container image. build 步骤类型表示在云中以多租户的安全方式将 docker build 作为第一类基元运行。The build step type represents a multi-tenant, secure means of running docker build in the cloud as a first-class primitive.

语法：buildSyntax: build

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

build 步骤类型支持下表中的参数。The build step type supports the parameters in the following table. build 步骤类型还支持 docker build 命令的所有生成选项，例如 --build-arg 以设置生成时变量。The build step type also supports all build options of the docker build command, such as --build-arg to set build-time variables.

属性：buildProperties: build

build 步骤类型支持以下属性。The build step type supports the following properties. 可在本文的任务步骤属性部分找到这些属性的详细信息。Find details of these properties in the Task step properties section of this article.

示例：buildExamples: build

生成映像 - 根目录中的上下文Build image - context in root

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 .

生成映像 - 子目录中的上下文Build image - context in subdirectory

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

pushpush

将生成或重新标记的一个或多个映像推送到容器注册表。Push one or more built or retagged images to a container registry. 支持推送到 Azure 容器注册表等专用注册表，或推送到公共 Docker 中心。Supports pushing to private registries like Azure Container Registry, or to the public Docker Hub.

语法：pushSyntax: push

push 步骤类型支持映像集合。The push step type supports a collection of images. YAML 集合语法支持内联和嵌套格式。YAML collection syntax supports inline and nested formats. 推送单个映像的操作通常使用内联语法来表示：Pushing a single image is typically represented using inline syntax:

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

为方便阅读，请在推送多个映像时使用嵌套语法：For increased readability, use nested syntax when pushing multiple images:

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

属性：pushProperties: push

push 步骤类型支持以下属性。The push step type supports the following properties. 可在本文的任务步骤属性部分找到这些属性的详细信息。Find details of these properties in the Task step properties section of this article.

示例：pushExamples: push

推送多个映像Push multiple images

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

生成、推送和运行Build, push, and run

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

cmdcmd

cmd 步骤类型运行容器。The cmd step type runs a container.

语法：cmdSyntax: cmd

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

属性：cmdProperties: cmd

cmd 步骤类型支持以下属性：The cmd step type supports the following properties:

可在本文的任务步骤属性部分找到这些属性的详细信息。You can find details of these properties in the Task step properties section of this article.

示例：cmdExamples: cmd

运行 hello-world 映像Run hello-world image

此命令执行 hello-world.yaml 任务文件，此文件引用 Docker 中心内的 hello-world 映像。This command executes the hello-world.yaml task file, which references the hello-world image on Docker Hub.

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

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

运行 bash 映像并回显“hello world”Run bash image and echo "hello world"

此命令执行 bash-echo.yaml 任务文件，此文件引用 Docker 中心内的 bash 映像。This command executes the bash-echo.yaml task file, which references the bash image on Docker Hub.

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 映像标记Run specific bash image tag

若要运行特定的映像版本，请在 cmd 中指定标记。To run a specific image version, specify the tag in the cmd.

此命令执行 bash-echo-3.yaml 任务文件，此文件引用 Docker 中心内的 bash:3.0 映像。This command executes the bash-echo-3.yaml task file, which references the bash:3.0 image on Docker Hub.

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

运行自定义映像Run custom images

cmd 步骤类型使用标准的 docker run 格式引用映像。The cmd step type references images using the standard docker run format. 不是以注册表名称开头的映像被认为源自 dockerhub.azk8s.cn。Images not prefaced with a registry are assumed to originate from dockerhub.azk8s.cn. 下面是前一示例的同等表示形式：The previous example could equally be represented as:

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

使用标准的 docker run 映像引用约定，cmd 可以运行任何专用注册表或公共 Docker Hub 中的映像。By using the standard docker run image reference convention, cmd can run images from any private registry or the public Docker Hub. 如果引用执行 ACR 任务的同一注册表中的映像，则无需指定任何注册表凭据。If you're referencing images in the same registry in which ACR Task is executing, you don't need to specify any registry credentials.

• 运行 Azure 容器注册表中的映像。Run an image that's from an Azure container registry. 以下示例假设已有一个名为 myregistry 的注册表，以及一个自定义映像 myimage:mytag。The following example assumes you have a registry named myregistry, and a custom image myimage:mytag.

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

• 使用 Run 变量或别名通用化注册表引用Generalize the registry reference with a Run variable or alias

  不要在 acr-task.yaml 文件中将注册表名称硬编码，可以使用 Run 变量或别名来提高此名称的可移植性。Instead of hard-coding your registry name in an acr-task.yaml file, you can make it more portable by using a Run variable or alias. 在运行时，Run.Registry 变量或 $Registry 别名将扩展到执行任务的注册表的名称。The Run.Registry variable or $Registry alias expands at runtime to the name of the registry in which the task is executing.

  例如，若要通用化上述任务，使其可在任何 Azure 容器注册表中运行，请在映像名称中引用 $Registry 变量：For example, to generalize the preceding task so that it works in any Azure container registry, reference the $Registry variable in the image name:

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

任务步骤属性Task step properties

每个步骤类型支持适用于其类型的多个属性。Each step type supports several properties appropriate for its type. 下表定义了所有可用的步骤属性。The following table defines all of the available step properties. 并非所有步骤类型都支持所有属性。Not all step types support all properties. 若要查看其中的哪些属性可用于每个步骤类型，请参阅 cmd、build 和 push 步骤类型参考部分。To see which of these properties are available for each step type, see the cmd, build, and push step type reference sections.

示例:任务步骤属性Examples: Task step properties

示例：idExample: id

生成两个映像，并实例化功能测试映像。Build two images, instancing a functional test image. 每个步骤由任务中的其他步骤在其 when 属性中引用的唯一 id 进行标识。Each step is identified by a unique id which other steps in the task reference in their when property.

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"]

示例：whenExample: when

when 属性指定某个步骤对任务中其他一个或多个步骤的依赖。The when property specifies a step's dependency on other steps within the task. 它支持两个参数值：It supports two parameter values:

• when: ["-"] - 指示不依赖于其他步骤。when: ["-"] - Indicates no dependency on other steps. 指定 when: ["-"] 的步骤将立即执行，并启用并发步骤执行。A step specifying when: ["-"] will begin execution immediately, and enables concurrent step execution.
• when: ["id1", "id2"] - 指示该步骤依赖于使用 id“id1”和 id“id2”的步骤。when: ["id1", "id2"] - Indicates the step is dependent upon steps with id "id1" and id "id2". 在“id1”和“id2”步骤完成之前，此步骤不会执行。This step won't be executed until both "id1" and "id2" steps complete.

如果未在某个步骤中指定 when，则该步骤依赖于 acr-task.yaml 文件中上一个步骤的完成。If when isn't specified in a step, that step is dependent on completion of the previous step in the acr-task.yaml file.

在不指定 when 的情况下按顺序执行步骤：Sequential step execution without 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 的情况下按顺序执行步骤：Sequential step execution with 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"]

并行映像生成：Parallel images build:

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: ["-"]

并行映像生成和依赖测试：Parallel image build and dependent testing:

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 变量Run variables

ACR 任务包含一组在执行时可供任务步骤使用的默认变量。ACR Tasks includes a default set of variables that are available to task steps when they execute. 可以使用 {{.Run.VariableName}} 格式访问这些变量，其中，VariableName 是以下值之一：These variables can be accessed by using the format {{.Run.VariableName}}, where VariableName is one of the following:

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

变量名称通常是自释性的。The variable names are generally self-explanatory. 常用的变量会附带详细信息。Details follows for commonly used variables. 从 YAML 版本 v1.1.0 开始，可以使用缩写的预定义任务别名来代替大部分 run 变量。As of YAML version v1.1.0, you can use an abbreviated, predefined task alias in place of most run variables. 例如，可以使用 $Registry 别名来代替 {{.Run.Registry}}。For example, in place of {{.Run.Registry}}, use the $Registry alias.

Run.IDRun.ID

通过 az acr run 执行的，或者使用基于触发器的任务执行通过 az acr task create 创建的每个 Run 都有唯一的 ID。Each Run, through az acr run, or trigger based execution of tasks created through az acr task create, has a unique ID. 此 ID 表示当前正在执行的运行。The ID represents the Run currently being executed.

通常用于唯一标记某个映像：Typically used for a uniquely tagging an image:

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

Run.RegistryRun.Registry

注册表的完全限定服务器名称。The fully qualified server name of the registry. 通常用于泛式引用正在运行任务的注册表。Typically used to generically reference the registry where the task is being run.

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

Run.RegistryNameRun.RegistryName

容器注册表的名称。The name of the container registry. 通常在不需要完全限定的服务器名称的任务步骤中使用，例如，针对注册表运行 Azure CLI 命令的 cmd 步骤。Typically used in task steps that don't require a fully qualified server name, for example, cmd steps that run Azure CLI commands on registries.

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

Run.DateRun.Date

运行开始时的当前 UTC 时间。The current UTC time the run began.

Run.CommitRun.Commit

对于提交到 GitHub 存储库后触发的任务，值为提交标识符。For a task triggered by a commit to a GitHub repository, the commit identifier.

Run.BranchRun.Branch

对于提交到 GitHub 存储库后触发的任务，值为分支名称。For a task triggered by a commit to a GitHub repository, the branch name.

别名Aliases

从 v1.1.0 开始，ACR 任务在执行时支持适用于任务步骤的别名。As of v1.1.0, ACR Tasks supports aliases that are available to task steps when they execute. 别名在概念上类似于 bash 和其他一些命令 shell 中支持的别名（命令快捷方式）。Aliases are similar in concept to aliases (command shortcuts) supported in bash and some other command shells.

使用别名，只需输入一个单词即可启动任一命令或一组命令（包括选项和文件名）。With an alias, you can launch any command or group of commands (including options and filenames) by entering a single word.

ACR 任务支持多个预定义的别名以及创建的自定义别名。ACR Tasks supports several predefined aliases and also custom aliases you create.

预定义的别名Predefined aliases

可使用以下任务别名来代替 run 变量：The following task aliases are available to use in place of run variables:

在任务步骤中，请在别名的前面加上 $ 指令，如以下示例所示：In task steps, precede an alias with the $ directive, as in this example:

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

映像别名Image aliases

以下每个别名指向 Azure 容器注册表 (MCR) 中的一个稳定映像。Each of the following aliases points to a stable image in Azure Container Registry (MCR). 可以在任务文件的 cmd 节中引用其中的每个别名，而无需使用指令。You can refer to each of them in the cmd section of a Task file without using a directive.

自定义别名Custom alias

在 YAML 文件中定义自定义别名，并如以下示例所示使用它。Define a custom alias in your YAML file and use it as shown in the following example. 别名只能包含字母数字字符。An alias can contain only alphanumeric characters. 用于展开别名的默认指令是 $ 字符。The default directive to expand an alias is the $ character.

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

可以链接到自定义别名定义的远程或本地 YAML 文件。You can link to a remote or local YAML file for custom alias definitions. 以下示例链接到 Azure Blob 存储中的 YAML 文件：The following example links to a YAML file in Azure blob storage:

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

后续步骤Next steps

有关多步骤任务的概述，请参阅在 ACR 任务中运行多步骤生成、测试和修补任务。For an overview of multi-step tasks, see the Run multi-step build, test, and patch tasks in ACR Tasks.

有关单步骤生成，请参阅 ACR 任务概述。For single-step builds, see the ACR Tasks overview.