ACR 任务参考:YAMLACR Tasks reference: YAML
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, a base image update, or a schedule. 尽管本文将 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、.lua Any 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
az configureacr=REGISTRY_NAME
命令。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.
propertiesProperty | 类型Type | 可选Optional | 说明Description | 支持的重写Override supported | 默认值Default value |
---|---|---|---|---|---|
version |
字符串string | 是Yes | ACR 任务服务分析的 acr-task.yaml 文件的版本。The version of the acr-task.yaml file as parsed by the ACR Tasks service. ACR 任务致力于保持向后兼容性,而此值能使 ACR 任务与某个定义的版本保持兼容。While ACR Tasks strives to maintain backward compatibility, this value allows ACR Tasks to maintain compatibility within a defined version. 如果未指定,则默认为最新版本。If unspecified, defaults to the latest version. |
否No | 无None |
stepTimeout |
整数(秒)int (seconds) | 是Yes | 步骤可以运行的最大秒数。The maximum number of seconds a step can run. 如果在任务中指定该属性,则会设置所有步骤的默认 timeout 属性。If the property is specified on a task, it sets the default timeout property of all the steps. 如果在步骤中指定 timeout 属性,则会替代任务提供的属性。If the timeout property is specified on a step, it overrides the property provided by the task. |
是Yes | 600(10 分钟)600 (10 minutes) |
workingDirectory |
字符串string | 是Yes | 运行时期间容器的工作目录。The working directory of the container during runtime. 如果在任务中指定该属性,则会设置所有步骤的默认 workingDirectory 属性。If the property is specified on a task, it sets the default workingDirectory property of all the steps. 如果在步骤中指定,则会替代任务提供的属性。If specified on a step, it overrides the property provided by the task. |
是Yes | 在 Windows 中为 c:\workspace ,在 Linux 中为 /workspace c:\workspace in Windows or /workspace in Linux |
env |
[字符串, 字符串, ...][string, string, ...] | 是Yes | 采用 key=value 格式的字符串数组,定义任务的环境变量。Array of strings in key=value format that define the environment variables for the task. 如果在任务中指定该属性,则会设置所有步骤的默认 env 属性。If the property is specified on a task, it sets the default env property of all the steps. 如果在步骤中指定,则会替代从任务继承的所有环境变量。If specified on a step, it overrides any environment variables inherited from the task. |
是Yes | 无None |
secrets |
[secret, secret, ...][secret, secret, ...] | 是Yes | secret 对象的数组。Array of secret objects. | 否No | 无None |
networks |
[network, network, ...][network, network, ...] | 是Yes | network 对象的数组。Array of network objects. | 否No | 无None |
volumes |
[volume, volume, ...][volume, volume, ...] | 是Yes | 卷对象的数组。Array of volume objects. 指定要装载到步骤的具有源内容的卷。Specifies volumes with source content to mount to a step. | 否No | 无None |
secretsecret
secret 对象具有以下属性。The secret object has the following properties.
propertiesProperty | 类型Type | 可选Optional | 说明Description | 默认值Default value |
---|---|---|---|---|
id |
stringstring | 否No | 机密的标识符。The identifier of the secret. | 无None |
keyvault |
stringstring | 是Yes | Azure Key Vault 机密 URL。The Azure Key Vault Secret URL. | 无None |
clientID |
stringstring | 是Yes | Azure 资源的用户分配的托管标识的客户端 ID。The client ID of the user-assigned managed identity for Azure resources. | 无None |
networknetwork
network 对象具有以下属性。The network object has the following properties.
propertiesProperty | 类型Type | 可选Optional | 说明Description | 默认值Default value |
---|---|---|---|---|
name |
stringstring | 否No | 网络的名称。The name of the network. | 无None |
driver |
stringstring | 是Yes | 用于管理网络的驱动程序。The driver to manage the network. | 无None |
ipv6 |
boolbool | 是Yes | IPv6 网络是否已启用。Whether IPv6 networking is enabled. | false |
skipCreation |
boolbool | 是Yes | 是否跳过网络创建过程。Whether to skip network creation. | false |
isDefault |
boolbool | 是Yes | 该网络是否是随 Azure 容器注册表一起提供的默认网络。Whether the network is a default network provided with Azure Container Registry. | false |
卷volume
卷对象具有以下属性。The volume object has the following properties.
propertiesProperty | 类型Type | 可选Optional | 说明Description | 默认值Default value |
---|---|---|---|---|
name |
stringstring | 否No | 要装载的卷的名称。The name of the volume to mount. 只能包含字母数字字符“-”和“”。Can contain only alphanumeric characters, '-', and ''. | 无None |
secret |
map[string]stringmap[string]string | 否No | 映射的每个密钥都是卷中创建和填充的文件的名称。Each key of the map is the name of a file created and populated in the volume. 每个值都是机密的字符串版本。Each value is the string version of the secret. 机密值必须经过 Base64 编码。Secret values must be Base64 encoded. | 无None |
步骤任务类型Task step types
ACR 任务支持三种步骤类型。ACR Tasks supports three step types. 每种步骤类型支持多个属性,每个步骤类型的相关部分中会予以详述。Each step type supports several properties, detailed in the section for each step type.
步骤类型Step type | 说明Description |
---|---|
build |
使用熟悉的 docker build 语法生成容器映像。Builds a container image using familiar docker build syntax. |
push |
执行 docker push ,将新生成或重新标记的映像推送到容器注册表。Executes a docker push of newly built or retagged images to a container registry. 支持 Azure 容器注册表、其他专用注册表和公共 Docker 中心。Azure Container Registry, other private registries, and the public Docker Hub are supported. |
cmd |
结合传递给容器的 [ENTRYPOINT] 的参数,以命令形式运行容器。Runs a container as a command, with parameters passed to the container's [ENTRYPOINT] . cmd 步骤类型支持 env 、detach 等参数和其他常见的 docker run 命令选项,可对并发容器执行启用单元测试和功能测试。The cmd step type supports parameters like env , detach , and other familiar docker run command options, enabling unit and functional testing with concurrent container execution. |
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.
参数Parameter | 说明Description | 可选Optional |
---|---|---|
-t | --image -t | --image |
定义所生成的映像的完全限定 image:tag 。Defines the fully qualified image:tag of the built image.由于映像可用于内部任务验证(例如功能测试),并非所有映像都需要通过 push 推送到注册表。As images may be used for inner task validations, such as functional tests, not all images require push to a registry. 但是,若要实例化任务执行中的某个映像,该映像确实需要引用某个名称。However, to instance an image within a Task execution, the image does need a name to reference.与 az acr build 不同,正在运行的 ACR 任务不提供默认的推送行为。Unlike az acr build , running ACR Tasks doesn't provide default push behavior. 使用 ACR 任务时,默认方案假设能够生成、验证再推送映像。With ACR Tasks, the default scenario assumes the ability to build, validate, then push an image. 请参阅 push,了解如何选择性地推送所生成的映像。See push for how to optionally push built images. |
是Yes |
-f | --file -f | --file |
指定要传递给 docker build 的 Dockerfile。Specifies the Dockerfile passed to docker build . 如果未指定,则假设使用上下文根目录中的默认 Dockerfile。If not specified, the default Dockerfile in the root of the context is assumed. 若要指定 Dockerfile,请传递相对于上下文根目录的文件名。To specify a Dockerfile, pass the filename relative to the root of the context. |
是Yes |
context |
传递给 docker build 的根目录。The root directory passed to docker build . 每个任务的根目录设置为某个共享的 workingDirectory,包括关联的 Git 克隆目录所在的根目录。The root directory of each task is set to a shared workingDirectory, and includes the root of the associated Git cloned directory. |
否No |
属性: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.
属性Properties | 类型Type | 必须Required |
---|---|---|
detach |
boolbool | 可选Optional |
disableWorkingDirectoryOverride |
boolbool | 可选Optional |
entryPoint |
stringstring | 可选Optional |
env |
[字符串, 字符串, ...][string, string, ...] | 可选Optional |
expose |
[字符串, 字符串, ...][string, string, ...] | 可选Optional |
id |
stringstring | 可选Optional |
ignoreErrors |
boolbool | 可选Optional |
isolation |
stringstring | 可选Optional |
keep |
boolbool | 可选Optional |
network |
对象 (object)object | 可选Optional |
ports |
[字符串, 字符串, ...][string, string, ...] | 可选Optional |
pull |
boolbool | 可选Optional |
repeat |
intint | 可选Optional |
retries |
intint | 可选Optional |
retryDelay |
整数(秒)int (seconds) | 可选Optional |
secret |
对象 (object)object | 可选Optional |
startDelay |
整数(秒)int (seconds) | 可选Optional |
timeout |
整数(秒)int (seconds) | 可选Optional |
volumeMount |
对象 (object)object | 可选Optional |
when |
[字符串, 字符串, ...][string, string, ...] | 可选Optional |
workingDirectory |
stringstring | 可选Optional |
示例: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.
propertiesProperty | 类型Type | 必须Required |
---|---|---|
env |
[字符串, 字符串, ...][string, string, ...] | 可选Optional |
id |
stringstring | 可选Optional |
ignoreErrors |
boolbool | 可选Optional |
startDelay |
整数(秒)int (seconds) | 可选Optional |
timeout |
整数(秒)int (seconds) | 可选Optional |
when |
[字符串, 字符串, ...][string, string, ...] | 可选Optional |
示例: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:
propertiesProperty | 类型Type | 必须Required |
---|---|---|
detach |
boolbool | 可选Optional |
disableWorkingDirectoryOverride |
boolbool | 可选Optional |
entryPoint |
stringstring | 可选Optional |
env |
[字符串, 字符串, ...][string, string, ...] | 可选Optional |
expose |
[字符串, 字符串, ...][string, string, ...] | 可选Optional |
id |
stringstring | 可选Optional |
ignoreErrors |
boolbool | 可选Optional |
isolation |
stringstring | 可选Optional |
keep |
boolbool | 可选Optional |
network |
对象 (object)object | 可选Optional |
ports |
[字符串, 字符串, ...][string, string, ...] | 可选Optional |
pull |
boolbool | 可选Optional |
repeat |
intint | 可选Optional |
retries |
intint | 可选Optional |
retryDelay |
整数(秒)int (seconds) | 可选Optional |
secret |
对象 (object)object | 可选Optional |
startDelay |
整数(秒)int (seconds) | 可选Optional |
timeout |
整数(秒)int (seconds) | 可选Optional |
volumeMount |
对象 (object)object | 可选Optional |
when |
[字符串, 字符串, ...][string, string, ...] | 可选Optional |
workingDirectory |
stringstring | 可选Optional |
可在本文的任务步骤属性部分找到这些属性的详细信息。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 namedmyregistry
, and a custom imagemyimage: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 anacr-task.yaml
file, you can make it more portable by using a Run variable or alias. 在运行时,Run.Registry
变量或$Registry
别名将扩展到执行任务的注册表的名称。TheRun.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
访问机密卷Access secret volumes
volumes
属性允许针对任务中的 build
和 cmd
步骤指定卷及其机密内容。The volumes
property allows volumes and their secret contents to be specified for build
and cmd
steps in a task. 在每个步骤中,可选的 volumeMounts
属性列出了在该步骤中要装载到容器中的卷和相应的容器路径。Inside each step, an optional volumeMounts
property lists the volumes and corresponding container paths to mount into the container at that step. 机密作为每个卷的装载路径中的文件提供。Secrets are provided as files at each volume's mount path.
执行任务并将两个机密装载到步骤:一个存储到密钥保管库,另一个在命令行中指定:Execute a task and mount two secrets to a step: one stored in a key vault and one specified on the command line:
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
任务步骤属性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.
propertiesProperty | 类型Type | 可选Optional | 说明Description | 默认值Default value |
---|---|---|---|---|
detach |
boolbool | 是Yes | 在运行时是否应分离容器。Whether the container should be detached when running. | false |
disableWorkingDirectoryOverride |
boolbool | 是Yes | 是否禁用 workingDirectory 重写功能。Whether to disable workingDirectory override functionality. 将此属性与 workingDirectory 结合使用可以全面控制容器的工作目录。Use this in combination with workingDirectory to have complete control over the container's working directory. |
false |
entryPoint |
stringstring | 是Yes | 重写步骤容器的 [ENTRYPOINT] 。Overrides the [ENTRYPOINT] of a step's container. |
无None |
env |
[字符串, 字符串, ...][string, string, ...] | 是Yes | 采用 key=value 格式的字符串数组,定义步骤的环境变量。Array of strings in key=value format that define the environment variables for the step. |
无None |
expose |
[字符串, 字符串, ...][string, string, ...] | 是Yes | 从容器公开的端口的数组。Array of ports that are exposed from the container. | 无None |
id |
stringstring | 是Yes | 唯一标识任务中的步骤。Uniquely identifies the step within the task. 任务中的其他步骤可以引用步骤的 id ,例如,使用 when 执行依赖项检查。Other steps in the task can reference a step's id , such as for dependency checking with when .id 也是正在运行的容器的名称。The id is also the running container's name. 例如,在任务的其他容器中运行的进程可以引用 id 作为其 DNS 主机名,或者通过 Docker 日志 [id] 来访问该步骤。Processes running in other containers in the task can refer to the id as its DNS host name, or for accessing it with docker logs [id], for example. |
acb_step_%d ,其中,%d 是 YAML 文件中的步骤的从 0 开始的索引(按从上到下的顺序排列)。acb_step_%d , where %d is the 0-based index of the step top-down in the YAML file |
ignoreErrors |
boolbool | 是Yes | 是否将步骤标记为成功(无论容器执行过程中是否发生了错误)。Whether to mark the step as successful regardless of whether an error occurred during container execution. | false |
isolation |
stringstring | 是Yes | 容器的隔离级别。The isolation level of the container. | default |
keep |
boolbool | 是Yes | 执行后是否应保留该步骤的容器。Whether the step's container should be kept after execution. | false |
network |
objectobject | 是Yes | 标识运行容器的网络。Identifies a network in which the container runs. | 无None |
ports |
[字符串, 字符串, ...][string, string, ...] | 是Yes | 从容器发布到主机的端口的数组。Array of ports that are published from the container to the host. | 无None |
pull |
boolbool | 是Yes | 在执行容器之前是否强制提取容器以防止任何缓存行为。Whether to force a pull of the container before executing it to prevent any caching behavior. | false |
privileged |
boolbool | 是Yes | 是否在特权模式下运行容器。Whether to run the container in privileged mode. | false |
repeat |
intint | 是Yes | 尝试重复执行容器的次数。The number of retries to repeat the execution of a container. | 00 |
retries |
intint | 是Yes | 容器执行失败时的重试次数。The number of retries to attempt if a container fails its execution. 仅当容器的退出代码非零时才重试。A retry is only attempted if a container's exit code is non-zero. | 00 |
retryDelay |
整数(秒)int (seconds) | 是Yes | 重试容器执行的间隔延迟(以秒为单位)。The delay in seconds between retries of a container's execution. | 00 |
secret |
objectobject | 是Yes | 标识 Azure Key Vault 机密或 Azure 资源的托管标识。Identifies an Azure Key Vault secret or managed identity for Azure resources. | 无None |
startDelay |
整数(秒)int (seconds) | 是Yes | 将容器执行延迟的秒数。Number of seconds to delay a container's execution. | 00 |
timeout |
整数(秒)int (seconds) | 是Yes | 步骤在终止之前可以执行的最大秒数。Maximum number of seconds a step may execute before being terminated. | 600600 |
when |
[字符串, 字符串, ...][string, string, ...] | 是Yes | 配置某个步骤对任务中其他一个或多个步骤的依赖。Configures a step's dependency on one or more other steps within the task. | 无None |
user |
stringstring | 是Yes | 容器的用户名或 UIDThe user name or UID of a container | 无None |
workingDirectory |
stringstring | 是Yes | 设置步骤的工作目录。Sets the working directory for a step. 默认情况下,ACR 任务会创建一个根目录作为工作目录。By default, ACR Tasks creates a root directory as the working directory. 但是,如果生成包含多个步骤,则前面的步骤可以通过指定相同的工作目录,来与后面的步骤共享项目。However, if your build has several steps, earlier steps can share artifacts with later steps by specifying the same working directory. | 在 Windows 中为 c:\workspace ,在 Linux 中为 /workspace c:\workspace in Windows or /workspace in Linux |
volumeMountvolumeMount
volumeMount 对象具有以下属性。The volumeMount object has the following properties.
propertiesProperty | 类型Type | 可选Optional | 说明Description | 默认值Default value |
---|---|---|---|---|
name |
stringstring | 否No | 要装载的卷的名称。The name of the volume to mount. 必须与 volumes 属性中的名称完全匹配。Must exactly match the name from a volumes property. |
无None |
mountPath |
stringstring | 否no | 在容器中装载文件的绝对路径。The absolute path to mount files in the container. | 无None |
示例:任务步骤属性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 specifyingwhen: ["-"]
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 withid
"id1" andid
"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 follow 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.SharedVolumeRun.SharedVolume
共享卷的唯一标识符,所有任务步骤均可对其进行访问。The unique identifier for a shared volume that is accessible by all task steps. 该卷在 Windows 中装载到 c:\workspace
,在 Linux 中装载到 /workspace
。The volume is mounted to c:\workspace
in Windows or /workspace
in Linux.
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:
AliasAlias | Run 变量Run variable |
---|---|
ID |
Run.ID |
SharedVolume |
Run.SharedVolume |
Registry |
Run.Registry |
RegistryName |
Run.RegistryName |
Date |
Run.Date |
OS |
Run.OS |
Architecture |
Run.Architecture |
Commit |
Run.Commit |
Branch |
Run.Branch |
在任务步骤中,请在别名的前面加上 $
指令,如以下示例所示: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
以下每个别名各指向 Microsoft 容器注册表 (MCR) 中的一个稳定映像。Each of the following aliases points to a stable image in Microsoft Container Registry (MCR). 可以在任务文件的 cmd
节中引用其中的每个别名,而无需使用指令。You can refer to each of them in the cmd
section of a Task file without using a directive.
AliasAlias | 映像Image |
---|---|
acr |
mcr.microsoft.com/acr/acr-cli:0.1 |
az |
mcr.microsoft.com/acr/azure-cli:a80af84 |
bash |
mcr.microsoft.com/acr/bash:a80af84 |
curl |
mcr.microsoft.com/acr/curl:a80af84 |
以下示例任务使用多个别名,来清除运行注册表中 samples/hello-world
存储库内超过 7 天的映像标记:The following example task uses several aliases to purge image tags older than 7 days in the repo samples/hello-world
in the run registry:
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
自定义别名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.