AWS Batch
用户指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

作业定义参数

作业定义被拆分为四个基本部分:作业定义名称、作业定义的类型、参数替代占位符默认值以及作业的容器属性。

作业定义名称

jobDefinitionName

当您注册作业定义时,需要指定一个名称。最多能包含 128 个字母 (大写和小写字母)、数字、连字符和下划线。使用该名称注册的第一个作业定义被指定为修订 1。注册到该名称下的任何后续作业定义将被指定增量修订号。

类型:字符串

必需:是

类型

type

当您注册作业定义时,需要指定作业类型。有关多节点并行作业的更多信息,请参阅创建多节点并行作业定义

类型:字符串

有效值:container | multinode

必需:是

参数

parameters

当您提交任务时,您可以指定应替换占位符或覆盖默认作业定义参数的参数。作业提交请求中的参数优先于作业定义中的默认值。这样,您就可以对多个作业使用相同的任务定义,这些作业在提交时使用相同的格式以编程方式在命令中更改值。

类型:字符串到字符串映射

必需:否

当您注册作业定义时,可以在作业容器属性的 command 字段中使用参数替代占位符。例如:

"command": [ "ffmpeg", "-i", "Ref::inputfile", "-c", "Ref::codec", "-o", "Ref::outputfile" ]

在上面的示例中,命令中包含参数替代占位符 Ref::inputfileRef::codecRef::outputfile。使用作业定义中的 parameters 对象,您可以为这些占位符设置默认值。例如,要为 Ref::codec 占位符设置默认值,可以在作业定义中指定以下内容:

"parameters" : {"codec" : "mp4"}

在提交此作业定义以运行时,容器命令中的 Ref::codec 参数将被替换为默认值 mp4

容器属性

当您注册作业定义时,必须指定容器属性列表,在置放作业时,需要将这些容器属性传递给容器实例上的 Docker 守护程序。作业定义中允许使用以下容器属性。对于单节点作业,这些容器属性是在作业定义级别设置的。对于多节点并行作业,每个节点组的容器属性是在节点属性级别设置的。

command

传递给容器的命令。此参数将映射到 Docker Remote API创建容器部分中的 Cmd 以及 docker runCOMMAND 参数。有关 Docker CMD 参数的更多信息,请参阅 https://docs.docker.com/engine/reference/builder/#cmd

"command": ["string", ...]

类型:字符串数组

必需:否

environment

要传递给容器的环境变量。此参数将映射到 Docker Remote API创建容器部分中的 Env 以及 docker run--env 选项。

重要

建议不要对敏感信息 (如凭证数据) 使用纯文本环境变量。

类型:键/值对的数组

必需:否

name

环境变量的名称。

类型:字符串

必需:当使用 environment 时为必需。

value

环境变量的值。

类型:字符串

必需:当使用 environment 时为必需。

"environment" : [ { "name" : "string", "value" : "string" }, { "name" : "string", "value" : "string" } ]
image

用于启动容器的映像。此字符串将直接传递给 Docker 守护程序。默认情况下,Docker Hub 注册表中的映像可用。您也可以使用 repository-url/image:tag 指定其他存储库。允许最多 255 个字母 (大写和小写字母)、数字、连字符、下划线、冒号、句点、正斜杠和井号。此参数将映射到 Docker Remote API创建容器部分中的 Image 以及 docker runIMAGE 参数。

注意

Docker 映像架构必须与为它们安排的计算资源的处理器架构相匹配。例如,基于 ARM 的 Docker 映像只能在基于 ARM 的计算资源上运行。

  • Amazon ECR 存储库中的映像使用完整的 registry/repository:tag 命名约定。例如,aws_account_id.dkr.ecr.region.amazonaws.com/my-web-app:latest

  • Docker Hub 上的官方存储库中的映像使用一个名称(例如,ubuntumongo)。

  • Docker Hub 上其他存储库中的映像通过组织名称(例如,amazon/amazon-ecs-agent)进行限定。

  • 其他在线存储库中的映像由域名(例如,quay.io/assemblyline/ubuntu)进行进一步限定。

类型:字符串

必需:是

jobRoleArn

当您注册作业定义时,可以指定 IAM 角色。该角色向作业容器提供权限,以便代表您调用在关联的策略中指定的 API 操作。有关更多信息,请参阅 Amazon Elastic Container Service Developer Guide 中的适用于任务的 IAM 角色

类型:字符串

必需:否

memory

要提供给容器的内存的硬限制(以 MiB 为单位)。如果您的容器尝试使用超出此处指定的内存,该容器将被终止。此参数将映射到 Docker Remote API创建容器部分中的 Memory 以及 docker run--memory 选项。您必须为任务指定至少 4 MiB 内存。

注意

如果您尝试通过为任务提供尽可能多的用于特定实例类型的内存来最大程度地利用资源,请参阅 Memory Management

类型:整数

必需:是

mountPoints

您的容器中数据卷的装载点。此参数将映射到 Docker Remote API创建容器 部分中的 Volumes 以及 docker run--volume 选项。

"mountPoints": [ { "sourceVolume": "string", "containerPath": "string", "readOnly": true|false } ]

类型:对象数组

必需:否

sourceVolume

要装载的卷的名称。

类型:字符串

必需:当使用 mountPoints 时为必需。

containerPath

要将主机卷装载到的容器上的路径。

类型:字符串

必需:当使用 mountPoints 时为必需。

readOnly

如果此值为 true,则容器具有对卷的只读访问权。如果此值为 false,则容器可对卷进行写入。默认值为 false

类型:布尔值

必需:否

privileged

当此参数为 true 时,将对此容器提供对主机容器实例的提升的特权(类似于 root 用户)。此参数将映射到 Docker Remote API创建容器 部分中的 Privilegeddocker run--privileged 选项。

"privileged": true|false

类型:布尔值

必需:否

readonlyRootFilesystem

当此参数为 true 时,将对此容器提供对其根文件系统的只读访问权。此参数将映射到 Docker Remote API创建容器部分中的 ReadonlyRootfs 以及 docker run--read-only 选项。

"readonlyRootFilesystem": true|false

类型:布尔值

必需:否

ulimits

要在容器中设置的 ulimits 值的列表。此参数将映射到 Docker Remote API创建容器部分中的 Ulimits 以及 docker run--ulimit 选项。

"ulimits": [ { "name": string, "softLimit": integer, "hardLimit": integer } ... ]

类型:对象数组

必需:否

name

ulimittype

类型:字符串

必需:当使用 ulimits 时为必需。

hardLimit

ulimit 类型的硬限制。

类型:整数

必需:当使用 ulimits 时为必需。

softLimit

ulimit 类型的软限制。

类型:整数

必需:当使用 ulimits 时为必需。

user

要在容器内使用的用户名。此参数将映射到 Docker Remote API创建容器部分中的 User 以及 docker run--user 选项。

"user": "string"

类型:字符串

必需:否

resourceRequirements

指示要为您的容器保留的 GPU 的数量。

"resourceRequirements" : [ { "type": "GPU", "value": "number" } ]

类型:对象数组

必需:否

type

GPU 是唯一受支持的值。

类型:字符串

必需:当使用 resourceRequirements 时为必需。

value

每个容器将需要的物理 GPU 的数量。

类型:字符串

必需:当使用 resourceRequirements 时为必需。

linuxParameters

特定于 Linux 的修改应用于容器的详细信息,如设备映射的详细信息。

"linuxParameters": { "devices": [ { "hostPath": "string", "containerPath": "string", "permissions": [ "READ", "WRITE", "MKNOD" ] } ] }

类型:LinuxParameters 对象

必需:否

devices

映射到容器的设备列表。

类型:设备对象的数组

必需:否

hostPath

主机中可用设备的路径。

类型:字符串

必需:是

containerPath

在容器中公开设备的路径。如果未指定,则设备将在与主机路径相同的路径上公开。

类型:字符串

必需:否

permissions

容器中设备的权限。如果未指定,则将权限设置为 READWRITEMKNOD

类型:字符串数组

必需:否

有效值:READ | WRITE | MKNOD

vcpus

为容器预留的 vCPU 的数量。此参数将映射到 Docker Remote API创建容器部分中的 CpuShares 以及 docker run--cpu-shares 选项。每个 vCPU 相当于 1024 个 CPU 份额。您必须指定至少一个 vCPU。

类型:整数

必需:是

volumes

当您注册作业定义时,可以指定需传递给容器实例上的 Docker 守护程序的卷的列表。容器属性中允许以下参数:

[ { "name": "string", "host": { "sourcePath": "string" } } ]
name

卷的名称。最多能包含 255 个字母 (大写和小写字母)、数字、连字符和下划线。此名称已在容器定义 mountPointssourceVolume 参数中引用。

类型:字符串

必需:是

host

host 参数的内容确定您的数据卷是否一直保存在主机容器实例上以及存储它的位置上。如果 host 参数为空,则 Docker 守护程序将为您的数据卷分配一个主机路径。但是,在与该卷关联的容器停止运行后,不保证保存数据。

类型:对象

必需:否

sourcePath

向容器提供的主机容器实例上的路径。如果此参数为空,则 Docker 守护程序将为您分配一个主机路径。

如果 host 参数包含 sourcePath 文件位置,则数据卷将在主机容器实例上的指定位置保留,除非您手动将其删除。如果主机容器实例上不存在 sourcePath 值,则 Docker 守护程序将创建该值。如果该位置不存在,则将导出源路径文件夹的内容。

类型:字符串

必需:否

节点属性

nodeProperties

在注册多节点并行作业定义时,您必须指定节点属性列表,这些属性定义要在作业中使用的节点数、主节点索引和要使用的各种节点范围。作业定义中允许使用以下节点属性。有关更多信息,请参阅 多节点并行作业

类型:NodeProperties 对象

必需:否

mainNode

指定多节点并行作业的主节点的节点索引。

类型:整数

必需:是

numNodes

与多节点并行作业关联的节点数。

类型:整数

必需:是

nodeRangeProperties

与多节点并行作业关联的节点范围及其属性的列表。

类型:NodeRangeProperty 对象的数组

必需:是

targetNodes

节点范围(使用节点索引值)。范围 0:3 表示索引值为 0 到 3 的节点。如果省略起始范围值 (:n),则使用 0 来开始范围。如果省略结束范围值 (n:),则使用可能最高的节点索引来结束范围。您的累积节点范围必须考虑所有节点 (0:n)。您可以嵌套节点范围,例如 0:10 和 4:5,在此情况下,4:5 范围属性会覆盖 0:10 属性。

类型:字符串

必需:否

container

节点范围的容器详细信息。有关更多信息,请参阅 容器属性

类型:ContainerProperties 对象

必需:否

重试策略

retryStrategy

在注册作业定义时,针对使用此作业定义提交的失败作业,您可以选择性地指定要用于这些作业的重试策略。默认情况下,每个任务尝试一次。如果指定多次尝试,则在作业失败后 (例如,如果返回非零退出代码或者容器实例终止) 将会重试。有关更多信息,请参阅 自动作业重试

类型:RetryStrategy 对象

必需:否

attempts

让作业进入 RUNNABLE 状态的次数。您可以指定 1 到 10 之间的尝试次数。如果 attempts 大于 1,则当实例失败时将重试多次,直到它进入 RUNNABLE 状态。

"attempts": integer

类型:整数

必需:否

超时

timeout

您可以为任务配置超时时间,以便在某个任务运行的时间超过超时时间时让 AWS Batch 终止该任务。有关更多信息,请参阅作业超时。如果某个任务因超时而终止,它不会被重试。在 SubmitJob 操作期间指定的任何超时配置将覆盖此处定义的超时配置。有关更多信息,请参阅 作业超时

类型:JobTimeout 对象

必需:否

attemptDurationSeconds

以秒为单位的持续时间(根据作业尝试的 startedAt 时间戳测得),在此时间过后,AWS Batch 将终止未完成的作业。超时时间的最小值为 60 秒。

类型:整数

必需:否