The AWS Batch API contains several data types that various actions use. This section describes each data type in detail.
NoteThe order of each element in a data type structure is not guaranteed. Applications should not assume a particular order.
The following data types are supported:
• ArrayProperties (p. 114)
• ArrayPropertiesDetail (p. 115)
• ArrayPropertiesSummary (p. 116)
• AttemptContainerDetail (p. 117)
• AttemptDetail (p. 119)
• ComputeEnvironmentDetail (p. 120)
• ComputeEnvironmentOrder (p. 123)
• ComputeResource (p. 124)
• ComputeResourceUpdate (p. 129)
• ContainerDetail (p. 131)
• ContainerOverrides (p. 136)
• ContainerProperties (p. 138)
• ContainerSummary (p. 143)
• Device (p. 144)
• Ec2Configuration (p. 145)
• EFSAuthorizationConfig (p. 146)
• EFSVolumeConfiguration (p. 147)
• EvaluateOnExit (p. 149)
• FairsharePolicy (p. 151)
• FargatePlatformConfiguration (p. 152)
• Host (p. 153)
• JobDefinition (p. 154)
• JobDependency (p. 157)
• JobDetail (p. 158)
• JobQueueDetail (p. 162)
• JobSummary (p. 164)
• JobTimeout (p. 166)
• KeyValuePair (p. 167)
• KeyValuesPair (p. 168)
• LaunchTemplateSpecification (p. 169)
• LinuxParameters (p. 171)
• LogConfiguration (p. 173)
• MountPoint (p. 175)
• NetworkConfiguration (p. 176)
• NetworkInterface (p. 177)
• NodeDetails (p. 178)
• NodeOverrides (p. 179)
• NodeProperties (p. 180)
• NodePropertiesSummary (p. 181)
• NodePropertyOverride (p. 182)
• NodeRangeProperty (p. 183)
• ResourceRequirement (p. 184)
• RetryStrategy (p. 187)
• SchedulingPolicyDetail (p. 188)
• SchedulingPolicyListingDetail (p. 189)
• Secret (p. 190)
• ShareAttributes (p. 191)
• Tmpfs (p. 192)
• Ulimit (p. 193)
• Volume (p. 194)
ArrayProperties
ArrayProperties
An object representing an AWS Batch array job.
Contents
size
The size of the array job.
Type: Integer Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3
ArrayPropertiesDetail
ArrayPropertiesDetail
An object representing the array properties of a job.
Contents
index
The job index within the array that's associated with this job. This parameter is returned for array job children.
Type: Integer Required: No size
The size of the array job. This parameter is returned for parent array jobs.
Type: Integer Required: No statusSummary
A summary of the number of array job children in each available job status. This parameter is returned for parent array jobs.
Type: String to integer map Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3
ArrayPropertiesSummary
ArrayPropertiesSummary
An object representing the array properties of a job.
Contents
index
The job index within the array that's associated with this job. This parameter is returned for children of array jobs.
Type: Integer Required: No size
The size of the array job. This parameter is returned for parent array jobs.
Type: Integer Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3
AttemptContainerDetail
AttemptContainerDetail
An object representing the details of a container that's part of a job attempt.
Contents
containerInstanceArn
The Amazon Resource Name (ARN) of the Amazon ECS container instance that hosts the job attempt.
Type: String Required: No exitCode
The exit code for the job attempt. A non-zero exit code is considered a failure.
Type: Integer Required: No logStreamName
The name of the CloudWatch Logs log stream associated with the container. The log group for AWS Batch jobs is /aws/batch/job. Each container attempt receives a log stream name when they reach the RUNNING status.
Type: String Required: No networkInterfaces
The network interfaces associated with the job attempt.
Type: Array of NetworkInterface (p. 177) objects Required: No
reason
A short (255 max characters) human-readable string to provide additional details about a running or stopped container.
Type: String Required: No taskArn
The Amazon Resource Name (ARN) of the Amazon ECS task that's associated with the job attempt.
Each container attempt receives a task ARN when they reach the STARTING status.
Type: String Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
See Also
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3
AttemptDetail
AttemptDetail
An object representing a job attempt.
Contents
container
Details about the container in this job attempt.
Type: AttemptContainerDetail (p. 117) object Required: No
startedAt
The Unix timestamp (in milliseconds) for when the attempt was started (when the attempt transitioned from the STARTING state to the RUNNING state).
Type: Long Required: No statusReason
A short, human-readable string to provide additional details about the current status of the job attempt.
Type: String Required: No stoppedAt
The Unix timestamp (in milliseconds) for when the attempt was stopped (when the attempt transitioned from the RUNNING state to a terminal state, such as SUCCEEDED or FAILED).
Type: Long Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3
ComputeEnvironmentDetail
ComputeEnvironmentDetail
An object representing an AWS Batch compute environment.
Contents
computeEnvironmentArn
The Amazon Resource Name (ARN) of the compute environment.
Type: String Required: Yes
computeEnvironmentName
The name of the compute environment. It can be up to 128 letters long. It can contain uppercase and lowercase letters, numbers, hyphens (-), and underscores (_).
Type: String Required: Yes computeResources
The compute resources defined for the compute environment. For more information, see Compute Environments in the AWS Batch User Guide.
Type: ComputeResource (p. 124) object Required: No
ecsClusterArn
The Amazon Resource Name (ARN) of the underlying Amazon ECS cluster used by the compute environment.
Type: String Required: Yes serviceRole
The service role associated with the compute environment that allows AWS Batch to make calls to AWS API operations on your behalf. For more information, see AWS Batch service IAM role in the AWS Batch User Guide.
Type: String Required: No state
The state of the compute environment. The valid values are ENABLED or DISABLED.
If the state is ENABLED, then the AWS Batch scheduler can attempt to place jobs from an associated job queue on the compute resources within the environment. If the compute environment is managed, then it can scale its instances out or in automatically, based on the job queue demand.
If the state is DISABLED, then the AWS Batch scheduler doesn't attempt to place jobs within the environment. Jobs in a STARTING or RUNNING state continue to progress normally. Managed compute environments in the DISABLED state don't scale out. However, they scale in to minvCpus value after instances become idle.
See Also
Type: String
Valid Values: ENABLED | DISABLED Required: No
status
The current status of the compute environment (for example, CREATING or VALID).
Type: String
Valid Values: CREATING | UPDATING | DELETING | DELETED | VALID | INVALID Required: No
statusReason
A short, human-readable string to provide additional details about the current status of the compute environment.
Type: String Required: No tags
The tags applied to the compute environment.
Type: String to string map
Map Entries: Maximum number of 50 items.
Key Length Constraints: Minimum length of 1. Maximum length of 128.
Value Length Constraints: Maximum length of 256.
Required: No type
The type of the compute environment: MANAGED or UNMANAGED. For more information, see Compute Environments in the AWS Batch User Guide.
Type: String
Valid Values: MANAGED | UNMANAGED Required: No
unmanagedvCpus
The maximum number of VCPUs expected to be used for an unmanaged compute environment.
Type: Integer Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS SDK for C++
See Also
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3
ComputeEnvironmentOrder
ComputeEnvironmentOrder
The order in which compute environments are tried for job placement within a queue. Compute environments are tried in ascending order. For example, if two compute environments are associated with a job queue, the compute environment with a lower order integer value is tried for job placement first. Compute environments must be in the VALID state before you can associate them with a job queue. All of the compute environments must be either EC2 (EC2 or SPOT) or Fargate (FARGATE or FARGATE_SPOT); EC2 and Fargate compute environments can't be mixed.
NoteAll compute environments that are associated with a job queue must share the same
architecture. AWS Batch doesn't support mixing compute environment architecture types in a single job queue.
Contents
computeEnvironment
The Amazon Resource Name (ARN) of the compute environment.
Type: String Required: Yes order
The order of the compute environment. Compute environments are tried in ascending order. For example, if two compute environments are associated with a job queue, the compute environment with a lower order integer value is tried for job placement first.
Type: Integer Required: Yes
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3
ComputeResource
ComputeResource
An object representing an AWS Batch compute resource. For more information, see Compute Environments in the AWS Batch User Guide.
Contents
allocationStrategy
The allocation strategy to use for the compute resource if not enough instances of the best fitting instance type can be allocated. This might be because of availability of the instance type in the Region or Amazon EC2 service limits. For more information, see Allocation Strategies in the AWS Batch User Guide.
NoteThis parameter isn't applicable to jobs that are running on Fargate resources, and shouldn't be specified.
BEST_FIT (default)
AWS Batch selects an instance type that best fits the needs of the jobs with a preference for the lowest-cost instance type. If additional instances of the selected instance type aren't available, AWS Batch waits for the additional instances to be available. If there aren't enough instances available, or if the user is reaching Amazon EC2 service limits then additional jobs aren't run until the currently running jobs have completed. This allocation strategy keeps costs lower but can limit scaling. If you are using Spot Fleets with BEST_FIT then the Spot Fleet IAM Role must be specified.
BEST_FIT_PROGRESSIVE
AWS Batch will select additional instance types that are large enough to meet the requirements of the jobs in the queue, with a preference for instance types with a lower cost per unit vCPU.
If additional instances of the previously selected instance types aren't available, AWS Batch will select new instance types.
SPOT_CAPACITY_OPTIMIZED
AWS Batch will select one or more instance types that are large enough to meet the
requirements of the jobs in the queue, with a preference for instance types that are less likely to be interrupted. This allocation strategy is only available for Spot Instance compute resources.
With both BEST_FIT_PROGRESSIVE and SPOT_CAPACITY_OPTIMIZED strategies, AWS Batch might need to go above maxvCpus to meet your capacity requirements. In this event, AWS Batch never exceeds maxvCpus by more than a single instance.
Type: String
Valid Values: BEST_FIT | BEST_FIT_PROGRESSIVE | SPOT_CAPACITY_OPTIMIZED Required: No
bidPercentage
The maximum percentage that a Spot Instance price can be when compared with the On-Demand price for that instance type before instances are launched. For example, if your maximum percentage is 20%, then the Spot price must be less than 20% of the current On-Demand price for that Amazon EC2 instance. You always pay the lowest (market) price and never more than your maximum
percentage. If you leave this field empty, the default value is 100% of the On-Demand price.
NoteThis parameter isn't applicable to jobs that are running on Fargate resources, and shouldn't be specified.
Contents
Type: Integer Required: No desiredvCpus
The desired number of Amazon EC2 vCPUS in the compute environment. AWS Batch modifies this value between the minimum and maximum values, based on job queue demand.
NoteThis parameter isn't applicable to jobs that are running on Fargate resources, and shouldn't be specified.
Type: Integer Required: No ec2Configuration
Provides information used to select Amazon Machine Images (AMIs) for EC2 instances in the compute environment. If Ec2Configuration isn't specified, the default is ECS_AL2.
One or two values can be provided.
NoteThis parameter isn't applicable to jobs that are running on Fargate resources, and shouldn't be specified.
Type: Array of Ec2Configuration (p. 145) objects Required: No
ec2KeyPair
The Amazon EC2 key pair that's used for instances launched in the compute environment. You can use this key pair to log in to your instances with SSH.
NoteThis parameter isn't applicable to jobs that are running on Fargate resources, and shouldn't be specified.
Type: String Required: No imageId
This member has been deprecated.
The Amazon Machine Image (AMI) ID used for instances launched in the compute environment. This parameter is overridden by the imageIdOverride member of the Ec2Configuration structure.
Note
This parameter isn't applicable to jobs that are running on Fargate resources, and shouldn't be specified.
Note
The AMI that you choose for a compute environment must match the architecture of the instance types that you intend to use for that compute environment. For example, if your compute environment uses A1 instance types, the compute resource AMI that you choose must support ARM instances. Amazon ECS vends both x86 and ARM versions of the Amazon ECS-optimized Amazon Linux 2 AMI. For more information, see Amazon ECS-optimized Amazon Linux 2 AMI in the Amazon Elastic Container Service Developer Guide.
Type: String
Contents
Required: No instanceRole
The Amazon ECS instance profile applied to Amazon EC2 instances in a compute environment.
You can specify the short name or full Amazon Resource Name (ARN) of an instance profile.
For example, ecsInstanceRole or arn:aws:iam::<aws_account_id>:instance-profile/ecsInstanceRole . For more information, see Amazon ECS Instance Role in the AWS Batch User Guide.
NoteThis parameter isn't applicable to jobs that are running on Fargate resources, and shouldn't be specified.
Type: String Required: No instanceTypes
The instances types that can be launched. You can specify instance families to launch any instance type within those families (for example, c5 or p3), or you can specify specific sizes within a family (such as c5.8xlarge). You can also choose optimal to select instance types (from the C4, M4, and R4 instance families) that match the demand of your job queues.
NoteThis parameter isn't applicable to jobs that are running on Fargate resources, and shouldn't be specified.
NoteWhen you create a compute environment, the instance types that you select for the compute environment must share the same architecture. For example, you can't mix x86 and ARM instances in the same compute environment.
NoteCurrently, optimal uses instance types from the C4, M4, and R4 instance families. In Regions that don't have instance types from those instance families, instance types from the C5, M5. and R5 instance families are used.
Type: Array of strings Required: No
launchTemplate
The launch template to use for your compute resources. Any other compute resource parameters that you specify in a CreateComputeEnvironment (p. 6) API operation override the same parameters in the launch template. You must specify either the launch template ID or launch template name in the request, but not both. For more information, see Launch Template Support in the AWS Batch User Guide.
Note
This parameter isn't applicable to jobs that are running on Fargate resources, and shouldn't be specified.
Type: LaunchTemplateSpecification (p. 169) object Required: No
maxvCpus
The maximum number of Amazon EC2 vCPUs that a compute environment can reach.
NoteWith both BEST_FIT_PROGRESSIVE and SPOT_CAPACITY_OPTIMIZED allocation
strategies, AWS Batch might need to exceed maxvCpus to meet your capacity requirements.
Contents
In this event, AWS Batch never exceeds maxvCpus by more than a single instance. For example, no more than a single instance from among those specified in your compute environment is allocated.
Type: Integer Required: Yes minvCpus
The minimum number of Amazon EC2 vCPUs that an environment should maintain (even if the compute environment is DISABLED).
Note
This parameter isn't applicable to jobs that are running on Fargate resources, and shouldn't be specified.
Type: Integer Required: No placementGroup
The Amazon EC2 placement group to associate with your compute resources. If you intend to submit multi-node parallel jobs to your compute environment, you should consider creating a cluster placement group and associate it with your compute resources. This keeps your multi-node parallel job on a logical grouping of instances within a single Availability Zone with high network flow potential. For more information, see Placement Groups in the Amazon EC2 User Guide for Linux Instances.
Note
This parameter isn't applicable to jobs that are running on Fargate resources, and shouldn't be specified.
Type: String Required: No securityGroupIds
The Amazon EC2 security groups associated with instances launched in the compute environment.
One or more security groups must be specified, either in securityGroupIds or using a launch template referenced in launchTemplate. This parameter is required for jobs that are running on Fargate resources and must contain at least one security group. Fargate doesn't support launch templates. If security groups are specified using both securityGroupIds and launchTemplate, the values in securityGroupIds are used.
Type: Array of strings Required: No
spotIamFleetRole
The Amazon Resource Name (ARN) of the Amazon EC2 Spot Fleet IAM role applied to a SPOT compute environment. This role is required if the allocation strategy set to BEST_FIT or if the allocation strategy isn't specified. For more information, see Amazon EC2 Spot Fleet Role in the AWS Batch User Guide.
NoteThis parameter isn't applicable to jobs that are running on Fargate resources, and shouldn't be specified.
Important
To tag your Spot Instances on creation, the Spot Fleet IAM role specified here must use the newer AmazonEC2SpotFleetTaggingRole managed policy. The previously recommended
See Also
AmazonEC2SpotFleetRole managed policy doesn't have the required permissions to tag Spot Instances. For more information, see Spot Instances not tagged on creation in the AWS Batch User Guide.
Type: String Required: No subnets
The VPC subnets where the compute resources are launched. These subnets must be within the same VPC. Fargate compute resources can contain up to 16 subnets. For more information, see VPCs and Subnets in the Amazon VPC User Guide.
Type: Array of strings Required: Yes tags
Key-value pair tags to be applied to EC2 resources that are launched in the compute environment.
For AWS Batch, these take the form of "String1": "String2", where String1 is the tag key and String2 is the tag value−for example, { "Name": "Batch Instance - C4OnDemand" }. This is helpful for recognizing your AWS Batch instances in the Amazon EC2 console. These tags can't be updated or removed after the compute environment is created. Any changes to these tags require that you create a new compute environment and remove the old compute environment. These tags aren't seen when using the AWS Batch ListTagsForResource API operation.
Note
This parameter isn't applicable to jobs that are running on Fargate resources, and shouldn't be specified.
Type: String to string map Required: No
type
The type of compute environment: EC2, SPOT, FARGATE, or FARGATE_SPOT. For more information, see Compute Environments in the AWS Batch User Guide.
If you choose SPOT, you must also specify an Amazon EC2 Spot Fleet role with the
spotIamFleetRole parameter. For more information, see Amazon EC2 Spot Fleet role in the AWS
spotIamFleetRole parameter. For more information, see Amazon EC2 Spot Fleet role in the AWS