Package software.amazon.awscdk.services.batch
AWS Batch Construct Library
This module is part of the AWS Cloud Development Kit project.
AWS Batch is a batch processing tool for efficiently running hundreds of thousands computing jobs in AWS. Batch can dynamically provision Amazon EC2 Instances to meet the resource requirements of submitted jobs and simplifies the planning, scheduling, and executions of your batch workloads. Batch achieves this through four different resources:
- ComputeEnvironments: Contain the resources used to execute Jobs
- JobDefinitions: Define a type of Job that can be submitted
- JobQueues: Route waiting Jobs to ComputeEnvironments
- SchedulingPolicies: Applied to Queues to control how and when Jobs exit the JobQueue and enter the ComputeEnvironment
ComputeEnvironment
s can be managed or unmanaged. Batch will automatically provision EC2 Instances in a managed ComputeEnvironment
and will
not provision any Instances in an unmanaged ComputeEnvironment
. Managed ComputeEnvironment
s can use ECS, Fargate, or EKS resources to spin up
EC2 Instances in (ensure your EKS Cluster has been configured
to support a Batch ComputeEnvironment before linking it). You can use Launch Templates and Placement Groups to configure exactly how these resources
will be provisioned.
JobDefinition
s can use either ECS resources or EKS resources. ECS JobDefinition
s can use multiple containers to execute distributed workloads.
EKS JobDefinition
s can only execute a single container. Submitted Jobs use JobDefinition
s as templates.
JobQueue
s must link at least one ComputeEnvironment
. Jobs exit the Queue in FIFO order unless a SchedulingPolicy
is specified.
SchedulingPolicy
s tell the Scheduler how to choose which Jobs should be executed next by the ComputeEnvironment.
Use Cases & Examples
Cost Optimization
Spot Instances
Spot instances are significantly discounted EC2 instances that can be reclaimed at any time by AWS.
Workloads that are fault-tolerant or stateless can take advantage of spot pricing.
To use spot spot instances, set spot
to true
on a managed Ec2 or Fargate Compute Environment:
Vpc vpc = new Vpc(this, "VPC"); FargateComputeEnvironment.Builder.create(this, "myFargateComputeEnv") .vpc(vpc) .spot(true) .build();
Batch allows you to specify the percentage of the on-demand instance that the current spot price
must be to provision the instance using the spotBidPercentage
.
This defaults to 100%, which is the recommended value.
This value cannot be specified for FargateComputeEnvironment
s
and only applies to ManagedEc2EcsComputeEnvironment
s.
The following code configures a Compute Environment to only use spot instances that
are at most 20% the price of the on-demand instance price:
Vpc vpc = new Vpc(this, "VPC"); ManagedEc2EcsComputeEnvironment.Builder.create(this, "myEc2ComputeEnv") .vpc(vpc) .spot(true) .spotBidPercentage(20) .build();
For stateful or otherwise non-interruption-tolerant workflows, omit spot
or set it to false
to only provision on-demand instances.
Choosing Your Instance Types
Batch allows you to choose the instance types or classes that will run your workload.
This example configures your ComputeEnvironment
to use only the M5AD.large
instance:
Vpc vpc = new Vpc(this, "VPC"); ManagedEc2EcsComputeEnvironment.Builder.create(this, "myEc2ComputeEnv") .vpc(vpc) .instanceTypes(List.of(InstanceType.of(InstanceClass.M5AD, InstanceSize.LARGE))) .build();
Batch allows you to specify only the instance class and to let it choose the size, which you can do like this:
IManagedEc2EcsComputeEnvironment computeEnv; Vpc vpc = new Vpc(this, "VPC"); computeEnv.addInstanceClass(InstanceClass.M5AD); // Or, specify it on the constructor: // Or, specify it on the constructor: ManagedEc2EcsComputeEnvironment.Builder.create(this, "myEc2ComputeEnv") .vpc(vpc) .instanceClasses(List.of(InstanceClass.R4)) .build();
Unless you explicitly specify useOptimalInstanceClasses: false
, this compute environment will use 'optimal'
instances,
which tells Batch to pick an instance from the C4, M4, and R4 instance families.
Note: Batch does not allow specifying instance types or classes with different architectures.
For example, InstanceClass.A1
cannot be specified alongside 'optimal'
,
because A1
uses ARM and 'optimal'
uses x86_64.
You can specify both 'optimal'
alongside several different instance types in the same compute environment:
IVpc vpc; ManagedEc2EcsComputeEnvironment computeEnv = ManagedEc2EcsComputeEnvironment.Builder.create(this, "myEc2ComputeEnv") .instanceTypes(List.of(InstanceType.of(InstanceClass.M5AD, InstanceSize.LARGE))) .useOptimalInstanceClasses(true) // default .vpc(vpc) .build(); // Note: this is equivalent to specifying computeEnv.addInstanceType(InstanceType.of(InstanceClass.M5AD, InstanceSize.LARGE)); computeEnv.addInstanceClass(InstanceClass.C4); computeEnv.addInstanceClass(InstanceClass.M4); computeEnv.addInstanceClass(InstanceClass.R4);
Configure AMIs
You can configure Amazon Machine Images (AMIs). This example configures your ComputeEnvironment
to use Amazon Linux 2023.
IVpc vpc; ManagedEc2EcsComputeEnvironment.Builder.create(this, "myEc2ComputeEnv") .vpc(vpc) .images(List.of(EcsMachineImage.builder() .imageType(EcsMachineImageType.ECS_AL2023) .build())) .build();
Allocation Strategies
| Allocation Strategy | Optimized for | Downsides | | ----------------------- | ------------- | ----------------------------- | | BEST_FIT | Cost | May limit throughput | | BEST_FIT_PROGRESSIVE | Throughput | May increase cost | | SPOT_CAPACITY_OPTIMIZED | Least interruption | Only useful on Spot instances | | SPOT_PRICE_CAPACITY_OPTIMIZED | Least interruption + Price | Only useful on Spot instances |
Batch provides different Allocation Strategies to help it choose which instances to provision.
If your workflow tolerates interruptions, you should enable spot
on your ComputeEnvironment
and use SPOT_PRICE_CAPACITY_OPTIMIZED
(this is the default if spot
is enabled).
This will tell Batch to choose the instance types from the ones you’ve specified that have
the most spot capacity available to minimize the chance of interruption and have the lowest price.
To get the most benefit from your spot instances,
you should allow Batch to choose from as many different instance types as possible.
If you only care about minimal interruptions and not want Batch to optimize for cost, use
SPOT_CAPACITY_OPTIMIZED
. SPOT_PRICE_CAPACITY_OPTIMIZED
is recommended over SPOT_CAPACITY_OPTIMIZED
for most use cases.
If your workflow does not tolerate interruptions and you want to minimize your costs at the expense
of potentially longer waiting times, use AllocationStrategy.BEST_FIT
.
This will choose the lowest-cost instance type that fits all the jobs in the queue.
If instances of that type are not available,
the queue will not choose a new type; instead, it will wait for the instance to become available.
This can stall your Queue
, with your compute environment only using part of its max capacity
(or none at all) until the BEST_FIT
instance becomes available.
If you are running a workflow that does not tolerate interruptions and you want to maximize throughput,
you can use AllocationStrategy.BEST_FIT_PROGRESSIVE
.
This is the default Allocation Strategy if spot
is false
or unspecified.
This strategy will examine the Jobs in the queue and choose whichever instance type meets the requirements
of the jobs in the queue and with the lowest cost per vCPU, just as BEST_FIT
.
However, if not all of the capacity can be filled with this instance type,
it will choose a new next-best instance type to run any jobs that couldn’t fit into the BEST_FIT
capacity.
To make the most use of this allocation strategy,
it is recommended to use as many instance classes as is feasible for your workload.
This example shows a ComputeEnvironment
that uses BEST_FIT_PROGRESSIVE
with 'optimal'
and InstanceClass.M5
instance types:
IVpc vpc; ManagedEc2EcsComputeEnvironment computeEnv = ManagedEc2EcsComputeEnvironment.Builder.create(this, "myEc2ComputeEnv") .vpc(vpc) .instanceClasses(List.of(InstanceClass.M5)) .build();
This example shows a ComputeEnvironment
that uses BEST_FIT
with 'optimal'
instances:
IVpc vpc; ManagedEc2EcsComputeEnvironment computeEnv = ManagedEc2EcsComputeEnvironment.Builder.create(this, "myEc2ComputeEnv") .vpc(vpc) .allocationStrategy(AllocationStrategy.BEST_FIT) .build();
Note: allocationStrategy
cannot be specified on Fargate Compute Environments.
Controlling vCPU allocation
You can specify the maximum and minimum vCPUs a managed ComputeEnvironment
can have at any given time.
Batch will always maintain minvCpus
worth of instances in your ComputeEnvironment, even if it is not executing any jobs,
and even if it is disabled. Batch will scale the instances up to maxvCpus
worth of instances as
jobs exit the JobQueue and enter the ComputeEnvironment. If you use AllocationStrategy.BEST_FIT_PROGRESSIVE
,
AllocationStrategy.SPOT_PRICE_CAPACITY_OPTIMIZED
, or AllocationStrategy.SPOT_CAPACITY_OPTIMIZED
,
batch may exceed maxvCpus
; it will never exceed maxvCpus
by more than a single instance type. This example configures a
minvCpus
of 10 and a maxvCpus
of 100:
IVpc vpc; ManagedEc2EcsComputeEnvironment.Builder.create(this, "myEc2ComputeEnv") .vpc(vpc) .instanceClasses(List.of(InstanceClass.R4)) .minvCpus(10) .maxvCpus(100) .build();
Tagging Instances
You can tag any instances launched by your managed EC2 ComputeEnvironments by using the CDK Tags
API:
IVpc vpc; ManagedEc2EcsComputeEnvironment tagCE = ManagedEc2EcsComputeEnvironment.Builder.create(this, "CEThatMakesTaggedInstnaces") .vpc(vpc) .build(); Tags.of(tagCE).add("super", "salamander");
Unmanaged ComputeEnvironment
s do not support maxvCpus
or minvCpus
because you must provision and manage the instances yourself;
that is, Batch will not scale them up and down as needed.
Sharing a ComputeEnvironment between multiple JobQueues
Multiple JobQueue
s can share the same ComputeEnvironment
.
If multiple Queues are attempting to submit Jobs to the same ComputeEnvironment
,
Batch will pick the Job from the Queue with the highest priority.
This example creates two JobQueue
s that share a ComputeEnvironment
:
IVpc vpc; FargateComputeEnvironment sharedComputeEnv = FargateComputeEnvironment.Builder.create(this, "spotEnv") .vpc(vpc) .spot(true) .build(); JobQueue lowPriorityQueue = JobQueue.Builder.create(this, "JobQueue") .priority(1) .build(); JobQueue highPriorityQueue = JobQueue.Builder.create(this, "JobQueue") .priority(10) .build(); lowPriorityQueue.addComputeEnvironment(sharedComputeEnv, 1); highPriorityQueue.addComputeEnvironment(sharedComputeEnv, 1);
React to jobs stuck in RUNNABLE state
You can react to jobs stuck in RUNNABLE state by setting a jobStateTimeLimitActions
in JobQueue
.
Specifies actions that AWS Batch will take after the job has remained at the head of the queue in the
specified state for longer than the specified time.
JobQueue.Builder.create(this, "JobQueue") .jobStateTimeLimitActions(List.of(JobStateTimeLimitAction.builder() .action(JobStateTimeLimitActionsAction.CANCEL) .maxTime(Duration.minutes(10)) .reason(JobStateTimeLimitActionsReason.INSUFFICIENT_INSTANCE_CAPACITY) .state(JobStateTimeLimitActionsState.RUNNABLE) .build())) .build();
Fairshare Scheduling
Batch JobQueue
s execute Jobs submitted to them in FIFO order unless you specify a SchedulingPolicy
.
FIFO queuing can cause short-running jobs to be starved while long-running jobs fill the compute environment.
To solve this, Jobs can be associated with a share.
Shares consist of a shareIdentifier
and a weightFactor
, which is inversely correlated with the vCPU allocated to that share identifier.
When submitting a Job, you can specify its shareIdentifier
to associate that particular job with that share.
Let's see how the scheduler uses this information to schedule jobs.
For example, if there are two shares defined as follows:
| Share Identifier | Weight Factor | | ---------------- | ------------- | | A | 1 | | B | 1 |
The weight factors share the following relationship:
A_{vCpus} / A_{Weight} = B_{vCpus} / B_{Weight}
where BvCpus
is the number of vCPUs allocated to jobs with share identifier 'B'
, and B_weight
is the weight factor of B
.
The total number of vCpus allocated to a share is equal to the amount of jobs in that share times the number of vCpus necessary for every job.
Let's say that each A job needs 32 VCpus (A_requirement
= 32) and each B job needs 64 vCpus (B_requirement
= 64):
A_{vCpus} = A_{Jobs} * A_{Requirement}
B_{vCpus} = B_{Jobs} * B_{Requirement}
We have:
A_{vCpus} / A_{Weight} = B_{vCpus} / B_{Weight}
A_{Jobs} * A_{Requirement} / A_{Weight} = B_{Jobs} * B_{Requirement} / B_{Weight}
A_{Jobs} * 32 / 1 = B_{Jobs} * 64 / 1
A_{Jobs} * 32 = B_{Jobs} * 64
A_{Jobs} = B_{Jobs} * 2
Thus the scheduler will schedule two 'A'
jobs for each 'B'
job.
You can control the weight factors to change these ratios, but note that weight factors are inversely correlated with the vCpus allocated to the corresponding share.
This example would be configured like this:
FairshareSchedulingPolicy fairsharePolicy = new FairshareSchedulingPolicy(this, "myFairsharePolicy"); fairsharePolicy.addShare(Share.builder() .shareIdentifier("A") .weightFactor(1) .build()); fairsharePolicy.addShare(Share.builder() .shareIdentifier("B") .weightFactor(1) .build()); JobQueue.Builder.create(this, "JobQueue") .schedulingPolicy(fairsharePolicy) .build();
Note: The scheduler will only consider the current usage of the compute environment unless you specify shareDecay
.
For example, a shareDecay
of 5 minutes in the above example means that at any given point in time, twice as many 'A'
jobs
will be scheduled for each 'B'
job, but only for the past 5 minutes. If 'B'
jobs run longer than 5 minutes, then
the scheduler is allowed to put more than two 'A'
jobs for each 'B'
job, because the usage of those long-running
'B'
jobs will no longer be considered after 5 minutes. shareDecay
linearly decreases the usage of
long running jobs for calculation purposes. For example if share decay is 60 seconds,
then jobs that run for 30 seconds have their usage considered to be only 50% of what it actually is,
but after a whole minute the scheduler pretends they don't exist for fairness calculations.
The following code specifies a shareDecay
of 5 minutes:
FairshareSchedulingPolicy fairsharePolicy = FairshareSchedulingPolicy.Builder.create(this, "myFairsharePolicy") .shareDecay(Duration.minutes(5)) .build();
If you have high priority jobs that should always be executed as soon as they arrive,
you can define a computeReservation
to specify the percentage of the
maximum vCPU capacity that should be reserved for shares that are not in the queue.
The actual reserved percentage is defined by Batch as:
(\frac{computeReservation}{100}) ^ {ActiveFairShares}
where ActiveFairShares
is the number of shares for which there exists
at least one job in the queue with a unique share identifier.
This is best illustrated with an example.
Suppose there are three shares with share identifiers A
, B
and C
respectively
and we specify the computeReservation
to be 75%. The queue is currently empty,
and no other shares exist.
There are no active fair shares, since the queue is empty. Thus (75/100)^0 = 1 = 100% of the maximum vCpus are reserved for all shares.
A job with identifier A
enters the queue.
The number of active fair shares is now 1, hence
(75/100)^1 = .75 = 75% of the maximum vCpus are reserved for all shares that do not have the identifier A
;
for this example, this is B
and C
,
(but if jobs are submitted with a share identifier not covered by this fairshare policy, those would be considered just as B
and C
are).
Now a B
job enters the queue. The number of active fair shares is now 2,
so (75/100)^2 = .5625 = 56.25% of the maximum vCpus are reserved for all shares that do not have the identifier A
or B
.
Now a second A
job enters the queue. The number of active fair shares is still 2,
so the percentage reserved is still 56.25%
Now a C
job enters the queue. The number of active fair shares is now 3,
so (75/100)^3 = .421875 = 42.1875% of the maximum vCpus are reserved for all shares that do not have the identifier A
, B
, or C
.
If there are no other shares that your jobs can specify, this means that 42.1875% of your capacity will never be used!
Now, A
, B
, and C
can only consume 100% - 42.1875% = 57.8125% of the maximum vCpus.
Note that the this percentage is not split between A
, B
, and C
.
Instead, the scheduler will use their weightFactor
s to decide which jobs to schedule;
the only difference is that instead of competing for 100% of the max capacity, jobs compete for 57.8125% of the max capacity.
This example specifies a computeReservation
of 75% that will behave as explained in the example above:
FairshareSchedulingPolicy.Builder.create(this, "myFairsharePolicy") .computeReservation(75) .shares(List.of(Share.builder().weightFactor(1).shareIdentifier("A").build(), Share.builder().weightFactor(0.5).shareIdentifier("B").build(), Share.builder().weightFactor(2).shareIdentifier("C").build())) .build();
You can specify a priority
on your JobDefinition
s to tell the scheduler to prioritize certain jobs that share the same share identifier.
Configuring Job Retry Policies
Certain workflows may result in Jobs failing due to intermittent issues. Jobs can specify retry policies to respond to different failures with different actions. There are three different ways information about the way a Job exited can be conveyed;
exitCode
: the exit code returned from the process executed by the container. Will only match non-zero exit codes.reason
: any middleware errors, like your Docker registry being down.statusReason
: infrastructure errors, most commonly your spot instance being reclaimed.
For most use cases, only one of these will be associated with a particular action at a time.
To specify common exitCode
s, reason
s, or statusReason
s, use the corresponding value from
the Reason
class. This example shows some common failure reasons:
EcsJobDefinition jobDefn = EcsJobDefinition.Builder.create(this, "JobDefn") .container(EcsEc2ContainerDefinition.Builder.create(this, "containerDefn") .image(ContainerImage.fromRegistry("public.ecr.aws/amazonlinux/amazonlinux:latest")) .memory(Size.mebibytes(2048)) .cpu(256) .build()) .retryAttempts(5) .retryStrategies(List.of(RetryStrategy.of(Action.EXIT, Reason.CANNOT_PULL_CONTAINER))) .build(); jobDefn.addRetryStrategy(RetryStrategy.of(Action.EXIT, Reason.SPOT_INSTANCE_RECLAIMED)); jobDefn.addRetryStrategy(RetryStrategy.of(Action.EXIT, Reason.CANNOT_PULL_CONTAINER)); jobDefn.addRetryStrategy(RetryStrategy.of(Action.EXIT, Reason.custom(CustomReason.builder() .onExitCode("40*") .onReason("some reason") .build())));
When specifying a custom reason,
you can specify a glob string to match each of these and react to different failures accordingly.
Up to five different retry strategies can be configured for each Job,
and each strategy can match against some or all of exitCode
, reason
, and statusReason
.
You can optionally configure the number of times a job will be retried,
but you cannot configure different retry counts for different strategies; they all share the same count.
If multiple conditions are specified in a given retry strategy,
they must all match for the action to be taken; the conditions are ANDed together, not ORed.
Running single-container ECS workflows
Batch can run jobs on ECS or EKS. ECS jobs can be defined as single container or multinode.
This example creates a JobDefinition
that runs a single container with ECS:
IFileSystem myFileSystem; Role myJobRole; myFileSystem.grantRead(myJobRole); EcsJobDefinition jobDefn = EcsJobDefinition.Builder.create(this, "JobDefn") .container(EcsEc2ContainerDefinition.Builder.create(this, "containerDefn") .image(ContainerImage.fromRegistry("public.ecr.aws/amazonlinux/amazonlinux:latest")) .memory(Size.mebibytes(2048)) .cpu(256) .volumes(List.of(EcsVolume.efs(EfsVolumeOptions.builder() .name("myVolume") .fileSystem(myFileSystem) .containerPath("/Volumes/myVolume") .useJobRole(true) .build()))) .jobRole(myJobRole) .build()) .build();
For workflows that need persistent storage, batch supports mounting Volume
s to the container.
You can both provision the volume and mount it to the container in a single operation:
IFileSystem myFileSystem; EcsJobDefinition jobDefn; jobDefn.container.addVolume(EcsVolume.efs(EfsVolumeOptions.builder() .name("myVolume") .fileSystem(myFileSystem) .containerPath("/Volumes/myVolume") .build()));
Running an ECS workflow with Fargate container
EcsJobDefinition jobDefn = EcsJobDefinition.Builder.create(this, "JobDefn") .container(EcsFargateContainerDefinition.Builder.create(this, "myFargateContainer") .image(ContainerImage.fromRegistry("public.ecr.aws/amazonlinux/amazonlinux:latest")) .memory(Size.mebibytes(2048)) .cpu(256) .ephemeralStorageSize(Size.gibibytes(100)) .fargateCpuArchitecture(CpuArchitecture.ARM64) .fargateOperatingSystemFamily(OperatingSystemFamily.LINUX) .build()) .build();
Secrets
You can expose SecretsManager Secret ARNs or SSM Parameters to your container as environment variables.
The following example defines the MY_SECRET_ENV_VAR
environment variable that contains the
ARN of the Secret defined by mySecret
:
ISecret mySecret; EcsJobDefinition jobDefn = EcsJobDefinition.Builder.create(this, "JobDefn") .container(EcsEc2ContainerDefinition.Builder.create(this, "containerDefn") .image(ContainerImage.fromRegistry("public.ecr.aws/amazonlinux/amazonlinux:latest")) .memory(Size.mebibytes(2048)) .cpu(256) .secrets(Map.of( "MY_SECRET_ENV_VAR", Secret.fromSecretsManager(mySecret))) .build()) .build();
Running Kubernetes Workflows
Batch also supports running workflows on EKS. The following example creates a JobDefinition
that runs on EKS:
EksJobDefinition jobDefn = EksJobDefinition.Builder.create(this, "eksf2") .container(EksContainerDefinition.Builder.create(this, "container") .image(ContainerImage.fromRegistry("amazon/amazon-ecs-sample")) .volumes(List.of(EksVolume.emptyDir(EmptyDirVolumeOptions.builder() .name("myEmptyDirVolume") .mountPath("/mount/path") .medium(EmptyDirMediumType.MEMORY) .readonly(true) .sizeLimit(Size.mebibytes(2048)) .build()))) .build()) .build();
You can mount Volume
s to these containers in a single operation:
EksJobDefinition jobDefn; jobDefn.container.addVolume(EksVolume.emptyDir(EmptyDirVolumeOptions.builder() .name("emptyDir") .mountPath("/Volumes/emptyDir") .build())); jobDefn.container.addVolume(EksVolume.hostPath(HostPathVolumeOptions.builder() .name("hostPath") .hostPath("/sys") .mountPath("/Volumes/hostPath") .build())); jobDefn.container.addVolume(EksVolume.secret(SecretPathVolumeOptions.builder() .name("secret") .optional(true) .mountPath("/Volumes/secret") .secretName("mySecret") .build()));
Running Distributed Workflows
Some workflows benefit from parallellization and are most powerful when run in a distributed environment,
such as certain numerical calculations or simulations. Batch offers MultiNodeJobDefinition
s,
which allow a single job to run on multiple instances in parallel, for this purpose.
Message Passing Interface (MPI) is often used with these workflows.
You must configure your containers to use MPI properly,
but Batch allows different nodes running different containers to communicate easily with one another.
You must configure your containers to use certain environment variables that Batch will provide them,
which lets them know which one is the main node, among other information.
For an in-depth example on using MPI to perform numerical computations on Batch,
see this blog post
In particular, the environment variable that tells the containers which one is the main node can be configured on your MultiNodeJobDefinition
as follows:
MultiNodeJobDefinition multiNodeJob = MultiNodeJobDefinition.Builder.create(this, "JobDefinition") .instanceType(InstanceType.of(InstanceClass.R4, InstanceSize.LARGE)) // optional, omit to let Batch choose the type for you .containers(List.of(MultiNodeContainer.builder() .container(EcsEc2ContainerDefinition.Builder.create(this, "mainMPIContainer") .image(ContainerImage.fromRegistry("yourregsitry.com/yourMPIImage:latest")) .cpu(256) .memory(Size.mebibytes(2048)) .build()) .startNode(0) .endNode(5) .build())) .build(); // convenience method multiNodeJob.addContainer(MultiNodeContainer.builder() .startNode(6) .endNode(10) .container(EcsEc2ContainerDefinition.Builder.create(this, "multiContainer") .image(ContainerImage.fromRegistry("amazon/amazon-ecs-sample")) .cpu(256) .memory(Size.mebibytes(2048)) .build()) .build());
If you need to set the control node to an index other than 0, specify it in directly:
MultiNodeJobDefinition multiNodeJob = MultiNodeJobDefinition.Builder.create(this, "JobDefinition") .mainNode(5) .instanceType(InstanceType.of(InstanceClass.R4, InstanceSize.LARGE)) .build();
Pass Parameters to a Job
Batch allows you define parameters in your JobDefinition
, which can be referenced in the container command. For example:
EcsJobDefinition.Builder.create(this, "JobDefn") .parameters(Map.of("echoParam", "foobar")) .container(EcsEc2ContainerDefinition.Builder.create(this, "containerDefn") .image(ContainerImage.fromRegistry("public.ecr.aws/amazonlinux/amazonlinux:latest")) .memory(Size.mebibytes(2048)) .cpu(256) .command(List.of("echo", "Ref::echoParam")) .build()) .build();
Understanding Progressive Allocation Strategies
AWS Batch uses an allocation strategy to determine what compute resource will efficiently handle incoming job requests. By default, BEST_FIT will pick an available compute instance based on vCPU requirements. If none exist, the job will wait until resources become available. However, with this strategy, you may have jobs waiting in the queue unnecessarily despite having more powerful instances available. Below is an example of how that situation might look like:
Compute Environment: 1. m5.xlarge => 4 vCPU 2. m5.2xlarge => 8 vCPU
Job Queue: --------- | A | B | --------- Job Requirements: A => 4 vCPU - ALLOCATED TO m5.xlarge B => 2 vCPU - WAITING
In this situation, Batch will allocate Job A to compute resource #1 because it is the most cost efficient resource that matches the vCPU requirement. However, with this BEST_FIT
strategy, Job B will not be allocated to our other available compute resource even though it is strong enough to handle it. Instead, it will wait until the first job is finished processing or wait a similar m5.xlarge
resource to be provisioned.
The alternative would be to use the BEST_FIT_PROGRESSIVE
strategy in order for the remaining job to be handled in larger containers regardless of vCPU requirement and costs.
Permissions
You can grant any Principal the batch:submitJob
permission on both a job definition and a job queue like this:
IVpc vpc; EcsJobDefinition ecsJob = EcsJobDefinition.Builder.create(this, "JobDefn") .container(EcsEc2ContainerDefinition.Builder.create(this, "containerDefn") .image(ContainerImage.fromRegistry("public.ecr.aws/amazonlinux/amazonlinux:latest")) .memory(Size.mebibytes(2048)) .cpu(256) .build()) .build(); JobQueue queue = JobQueue.Builder.create(this, "JobQueue") .computeEnvironments(List.of(OrderedComputeEnvironment.builder() .computeEnvironment(ManagedEc2EcsComputeEnvironment.Builder.create(this, "managedEc2CE") .vpc(vpc) .build()) .order(1) .build())) .priority(10) .build(); User user = new User(this, "MyUser"); ecsJob.grantSubmitJob(user, queue);
-
ClassDescriptionThe Action to take when all specified conditions in a RetryStrategy are met.Determines how this compute environment chooses instances to spawn.The
AWS::Batch::ComputeEnvironment
resource defines your AWS Batch compute environment.A fluent builder forCfnComputeEnvironment
.Details about the compute resources managed by the compute environment.A builder forCfnComputeEnvironment.ComputeResourcesProperty
An implementation forCfnComputeEnvironment.ComputeResourcesProperty
Provides information used to select Amazon Machine Images (AMIs) for instances in the compute environment.A builder forCfnComputeEnvironment.Ec2ConfigurationObjectProperty
An implementation forCfnComputeEnvironment.Ec2ConfigurationObjectProperty
Configuration for the Amazon EKS cluster that supports the AWS Batch compute environment.A builder forCfnComputeEnvironment.EksConfigurationProperty
An implementation forCfnComputeEnvironment.EksConfigurationProperty
An object that represents a launch template that's associated with a compute resource.An implementation forCfnComputeEnvironment.LaunchTemplateSpecificationProperty
Specifies the infrastructure update policy for the compute environment.A builder forCfnComputeEnvironment.UpdatePolicyProperty
An implementation forCfnComputeEnvironment.UpdatePolicyProperty
Properties for defining aCfnComputeEnvironment
.A builder forCfnComputeEnvironmentProps
An implementation forCfnComputeEnvironmentProps
TheAWS::Batch::JobDefinition
resource specifies the parameters for an AWS Batch job definition.The authorization configuration details for the Amazon EFS file system.A builder forCfnJobDefinition.AuthorizationConfigProperty
An implementation forCfnJobDefinition.AuthorizationConfigProperty
A fluent builder forCfnJobDefinition
.Container properties are used for Amazon ECS based job definitions.A builder forCfnJobDefinition.ContainerPropertiesProperty
An implementation forCfnJobDefinition.ContainerPropertiesProperty
An object that represents a container instance host device.A builder forCfnJobDefinition.DeviceProperty
An implementation forCfnJobDefinition.DeviceProperty
An object that contains the properties for the Amazon ECS resources of a job.A builder forCfnJobDefinition.EcsPropertiesProperty
An implementation forCfnJobDefinition.EcsPropertiesProperty
The properties for a task definition that describes the container and volume definitions of an Amazon ECS task.A builder forCfnJobDefinition.EcsTaskPropertiesProperty
An implementation forCfnJobDefinition.EcsTaskPropertiesProperty
This is used when you're using an Amazon Elastic File System file system for job storage.A builder forCfnJobDefinition.EfsVolumeConfigurationProperty
An implementation forCfnJobDefinition.EfsVolumeConfigurationProperty
An environment variable.A builder forCfnJobDefinition.EksContainerEnvironmentVariableProperty
An implementation forCfnJobDefinition.EksContainerEnvironmentVariableProperty
EKS container properties are used in job definitions for Amazon EKS based job definitions to describe the properties for a container node in the pod that's launched as part of a job.A builder forCfnJobDefinition.EksContainerProperty
An implementation forCfnJobDefinition.EksContainerProperty
The volume mounts for a container for an Amazon EKS job.A builder forCfnJobDefinition.EksContainerVolumeMountProperty
An implementation forCfnJobDefinition.EksContainerVolumeMountProperty
An object that contains the properties for the Kubernetes resources of a job.A builder forCfnJobDefinition.EksPropertiesProperty
An implementation forCfnJobDefinition.EksPropertiesProperty
Specifies the configuration of a Kubernetessecret
volume.A builder forCfnJobDefinition.EksSecretProperty
An implementation forCfnJobDefinition.EksSecretProperty
Specifies an Amazon EKS volume for a job definition.A builder forCfnJobDefinition.EksVolumeProperty
An implementation forCfnJobDefinition.EksVolumeProperty
Example:A builder forCfnJobDefinition.EmptyDirProperty
An implementation forCfnJobDefinition.EmptyDirProperty
The Environment property type specifies environment variables to use in a job definition.A builder forCfnJobDefinition.EnvironmentProperty
An implementation forCfnJobDefinition.EnvironmentProperty
The amount of ephemeral storage to allocate for the task.A builder forCfnJobDefinition.EphemeralStorageProperty
An implementation forCfnJobDefinition.EphemeralStorageProperty
Specifies an array of up to 5 conditions to be met, and an action to take (RETRY
orEXIT
) if all conditions are met.A builder forCfnJobDefinition.EvaluateOnExitProperty
An implementation forCfnJobDefinition.EvaluateOnExitProperty
The platform configuration for jobs that are running on Fargate resources.A builder forCfnJobDefinition.FargatePlatformConfigurationProperty
An implementation forCfnJobDefinition.FargatePlatformConfigurationProperty
Example:A builder forCfnJobDefinition.HostPathProperty
An implementation forCfnJobDefinition.HostPathProperty
References a Kubernetes secret resource.A builder forCfnJobDefinition.ImagePullSecretProperty
An implementation forCfnJobDefinition.ImagePullSecretProperty
Linux-specific modifications that are applied to the container, such as details for device mappings.A builder forCfnJobDefinition.LinuxParametersProperty
An implementation forCfnJobDefinition.LinuxParametersProperty
Log configuration options to send to a custom log driver for the container.A builder forCfnJobDefinition.LogConfigurationProperty
An implementation forCfnJobDefinition.LogConfigurationProperty
Metadata about the Kubernetes pod.A builder forCfnJobDefinition.MetadataProperty
An implementation forCfnJobDefinition.MetadataProperty
Details for a Docker volume mount point that's used in a job's container properties.A builder forCfnJobDefinition.MountPointsProperty
An implementation forCfnJobDefinition.MountPointsProperty
The network configuration for jobs that are running on Fargate resources.A builder forCfnJobDefinition.NetworkConfigurationProperty
An implementation forCfnJobDefinition.NetworkConfigurationProperty
An object that represents the node properties of a multi-node parallel job.A builder forCfnJobDefinition.NodePropertiesProperty
An implementation forCfnJobDefinition.NodePropertiesProperty
This is an object that represents the properties of the node range for a multi-node parallel job.A builder forCfnJobDefinition.NodeRangePropertyProperty
An implementation forCfnJobDefinition.NodeRangePropertyProperty
The properties for the pod.A builder forCfnJobDefinition.PodPropertiesProperty
An implementation forCfnJobDefinition.PodPropertiesProperty
The repository credentials for private registry authentication.A builder forCfnJobDefinition.RepositoryCredentialsProperty
An implementation forCfnJobDefinition.RepositoryCredentialsProperty
The type and amount of a resource to assign to a container.A builder forCfnJobDefinition.ResourceRequirementProperty
An implementation forCfnJobDefinition.ResourceRequirementProperty
Example:A builder forCfnJobDefinition.ResourcesProperty
An implementation forCfnJobDefinition.ResourcesProperty
The retry strategy that's associated with a job.A builder forCfnJobDefinition.RetryStrategyProperty
An implementation forCfnJobDefinition.RetryStrategyProperty
An object that represents the compute environment architecture for AWS Batch jobs on Fargate.A builder forCfnJobDefinition.RuntimePlatformProperty
An implementation forCfnJobDefinition.RuntimePlatformProperty
An object that represents the secret to expose to your container.A builder forCfnJobDefinition.SecretProperty
An implementation forCfnJobDefinition.SecretProperty
Example:A builder forCfnJobDefinition.SecurityContextProperty
An implementation forCfnJobDefinition.SecurityContextProperty
A list of containers that this task depends on.A builder forCfnJobDefinition.TaskContainerDependencyProperty
An implementation forCfnJobDefinition.TaskContainerDependencyProperty
Container properties are used for Amazon ECS-based job definitions.A builder forCfnJobDefinition.TaskContainerPropertiesProperty
An implementation forCfnJobDefinition.TaskContainerPropertiesProperty
An object that represents a job timeout configuration.A builder forCfnJobDefinition.TimeoutProperty
An implementation forCfnJobDefinition.TimeoutProperty
The container path, mount options, and size of thetmpfs
mount.A builder forCfnJobDefinition.TmpfsProperty
An implementation forCfnJobDefinition.TmpfsProperty
Theulimit
settings to pass to the container.A builder forCfnJobDefinition.UlimitProperty
An implementation forCfnJobDefinition.UlimitProperty
Determine whether your data volume persists on the host container instance and where it's stored.A builder forCfnJobDefinition.VolumesHostProperty
An implementation forCfnJobDefinition.VolumesHostProperty
A list of volumes that are associated with the job.A builder forCfnJobDefinition.VolumesProperty
An implementation forCfnJobDefinition.VolumesProperty
Properties for defining aCfnJobDefinition
.A builder forCfnJobDefinitionProps
An implementation forCfnJobDefinitionProps
TheAWS::Batch::JobQueue
resource specifies the parameters for an AWS Batch job queue definition.A fluent builder forCfnJobQueue
.The order that compute environments are tried in for job placement within a queue.A builder forCfnJobQueue.ComputeEnvironmentOrderProperty
An implementation forCfnJobQueue.ComputeEnvironmentOrderProperty
Specifies an action that AWS Batch will take after the job has remained at the head of the queue in the specified state for longer than the specified time.A builder forCfnJobQueue.JobStateTimeLimitActionProperty
An implementation forCfnJobQueue.JobStateTimeLimitActionProperty
Properties for defining aCfnJobQueue
.A builder forCfnJobQueueProps
An implementation forCfnJobQueueProps
TheAWS::Batch::SchedulingPolicy
resource specifies the parameters for an AWS Batch scheduling policy.A fluent builder forCfnSchedulingPolicy
.The fair share policy for a scheduling policy.A builder forCfnSchedulingPolicy.FairsharePolicyProperty
An implementation forCfnSchedulingPolicy.FairsharePolicyProperty
Specifies the weights for the fair share identifiers for the fair share policy.A builder forCfnSchedulingPolicy.ShareAttributesProperty
An implementation forCfnSchedulingPolicy.ShareAttributesProperty
Properties for defining aCfnSchedulingPolicy
.A builder forCfnSchedulingPolicyProps
An implementation forCfnSchedulingPolicyProps
Props common to all ComputeEnvironments.A builder forComputeEnvironmentProps
An implementation forComputeEnvironmentProps
The corresponding Action will only be taken if all of the conditions specified here are met.A builder forCustomReason
An implementation forCustomReason
A container instance host device.A builder forDevice
An implementation forDevice
Permissions for device access.The DNS Policy for the pod used by the Job Definition.Props to configure an EcsContainerDefinition.A builder forEcsContainerDefinitionProps
An implementation forEcsContainerDefinitionProps
A container orchestrated by ECS that uses EC2 resources.A fluent builder forEcsEc2ContainerDefinition
.Props to configure an EcsEc2ContainerDefinition.A builder forEcsEc2ContainerDefinitionProps
An implementation forEcsEc2ContainerDefinitionProps
A container orchestrated by ECS that uses Fargate resources.A fluent builder forEcsFargateContainerDefinition
.Props to configure an EcsFargateContainerDefinition.A builder forEcsFargateContainerDefinitionProps
An implementation forEcsFargateContainerDefinitionProps
A JobDefinition that uses ECS orchestration.A fluent builder forEcsJobDefinition
.Props for EcsJobDefinition.A builder forEcsJobDefinitionProps
An implementation forEcsJobDefinitionProps
A Batch MachineImage that is compatible with ECS.A builder forEcsMachineImage
An implementation forEcsMachineImage
Maps the image to instance types.Represents a Volume that can be mounted to a container that uses ECS.Options to configure an EcsVolume.A builder forEcsVolumeOptions
An implementation forEcsVolumeOptions
A Volume that uses an AWS Elastic File System (EFS);A fluent builder forEfsVolume
.Options for configuring an EfsVolume.A builder forEfsVolumeOptions
An implementation forEfsVolumeOptions
A container that can be run with EKS orchestration on EC2 resources.A fluent builder forEksContainerDefinition
.Props to configure an EksContainerDefinition.A builder forEksContainerDefinitionProps
An implementation forEksContainerDefinitionProps
A JobDefinition that uses Eks orchestration.A fluent builder forEksJobDefinition
.Props for EksJobDefinition.A builder forEksJobDefinitionProps
An implementation forEksJobDefinitionProps
A Batch MachineImage that is compatible with EKS.A builder forEksMachineImage
An implementation forEksMachineImage
Maps the image to instance types.A Volume that can be mounted to a container supported by EKS.Options to configure an EksVolume.A builder forEksVolumeOptions
An implementation forEksVolumeOptions
What medium the volume will live in.A Kubernetes EmptyDir volume.A fluent builder forEmptyDirVolume
.Options for a Kubernetes EmptyDir volume.A builder forEmptyDirVolumeOptions
An implementation forEmptyDirVolumeOptions
Represents a Fairshare Scheduling Policy.A fluent builder forFairshareSchedulingPolicy
.Fairshare SchedulingPolicy configuration.A builder forFairshareSchedulingPolicyProps
An implementation forFairshareSchedulingPolicyProps
A ManagedComputeEnvironment that uses ECS orchestration on Fargate instances.A fluent builder forFargateComputeEnvironment
.Props for a FargateComputeEnvironment.A builder forFargateComputeEnvironmentProps
An implementation forFargateComputeEnvironmentProps
A Kubernetes HostPath volume.A fluent builder forHostPathVolume
.Options for a kubernetes HostPath volume.A builder forHostPathVolumeOptions
An implementation forHostPathVolumeOptions
Creates a Host volume.A fluent builder forHostVolume
.Options for configuring an ECS HostVolume.A builder forHostVolumeOptions
An implementation forHostVolumeOptions
Represents a ComputeEnvironment.Internal default implementation forIComputeEnvironment
.A proxy class which represents a concrete javascript instance of this type.A container that can be run with ECS orchestration.Internal default implementation forIEcsContainerDefinition
.A proxy class which represents a concrete javascript instance of this type.A container orchestrated by ECS that uses EC2 resources.Internal default implementation forIEcsEc2ContainerDefinition
.A proxy class which represents a concrete javascript instance of this type.A container orchestrated by ECS that uses Fargate resources and is orchestrated by ECS.Internal default implementation forIEcsFargateContainerDefinition
.A proxy class which represents a concrete javascript instance of this type.A container that can be run with EKS orchestration on EC2 resources.Internal default implementation forIEksContainerDefinition
.A proxy class which represents a concrete javascript instance of this type.A JobDefinition that uses Eks orchestration.Internal default implementation forIEksJobDefinition
.A proxy class which represents a concrete javascript instance of this type.Represents a Fairshare Scheduling Policy.Internal default implementation forIFairshareSchedulingPolicy
.A proxy class which represents a concrete javascript instance of this type.A ManagedComputeEnvironment that uses ECS orchestration on Fargate instances.Internal default implementation forIFargateComputeEnvironment
.A proxy class which represents a concrete javascript instance of this type.Represents a JobDefinition.Internal default implementation forIJobDefinition
.A proxy class which represents a concrete javascript instance of this type.Represents a JobQueue.Internal default implementation forIJobQueue
.A proxy class which represents a concrete javascript instance of this type.Determines when the image is pulled from the registry to launch a container.Represents a Managed ComputeEnvironment.Internal default implementation forIManagedComputeEnvironment
.A proxy class which represents a concrete javascript instance of this type.A ManagedComputeEnvironment that uses ECS orchestration on EC2 instances.Internal default implementation forIManagedEc2EcsComputeEnvironment
.A proxy class which represents a concrete javascript instance of this type.Represents a Scheduling Policy.Internal default implementation forISchedulingPolicy
.A proxy class which represents a concrete javascript instance of this type.Represents an UnmanagedComputeEnvironment.Internal default implementation forIUnmanagedComputeEnvironment
.A proxy class which represents a concrete javascript instance of this type.Props common to all JobDefinitions.A builder forJobDefinitionProps
An implementation forJobDefinitionProps
JobQueues can receive Jobs, which are removed from the queue when sent to the linked ComputeEnvironment(s) to be executed.A fluent builder forJobQueue
.Props to configure a JobQueue.A builder forJobQueueProps
An implementation forJobQueueProps
Specifies an action that AWS Batch will take after the job has remained at the head of the queue in the specified state for longer than the specified time.A builder forJobStateTimeLimitAction
An implementation forJobStateTimeLimitAction
The action to take when a job is at the head of the job queue in the specified state for the specified period of time.The reason to log for the action being taken.The state of the job needed to trigger the action.Linux-specific options that are applied to the container.A fluent builder forLinuxParameters
.The properties for defining Linux-specific options that are applied to the container.A builder forLinuxParametersProps
An implementation forLinuxParametersProps
Props for a ManagedComputeEnvironment.A builder forManagedComputeEnvironmentProps
An implementation forManagedComputeEnvironmentProps
A ManagedComputeEnvironment that uses ECS orchestration on EC2 instances.A fluent builder forManagedEc2EcsComputeEnvironment
.Props for a ManagedEc2EcsComputeEnvironment.A builder forManagedEc2EcsComputeEnvironmentProps
An implementation forManagedEc2EcsComputeEnvironmentProps
A ManagedComputeEnvironment that uses ECS orchestration on EC2 instances.A fluent builder forManagedEc2EksComputeEnvironment
.Props for a ManagedEc2EksComputeEnvironment.A builder forManagedEc2EksComputeEnvironmentProps
An implementation forManagedEc2EksComputeEnvironmentProps
Runs the container on nodes [startNode, endNode].A builder forMultiNodeContainer
An implementation forMultiNodeContainer
A JobDefinition that uses Ecs orchestration to run multiple containers.A fluent builder forMultiNodeJobDefinition
.Props to configure a MultiNodeJobDefinition.A builder forMultiNodeJobDefinitionProps
An implementation forMultiNodeJobDefinitionProps
Not a real instance type!Assigns an order to a ComputeEnvironment.A builder forOrderedComputeEnvironment
An implementation forOrderedComputeEnvironment
Common job exit reasons.Define how Jobs using this JobDefinition respond to different exit conditions.A secret environment variable.Specifies the configuration of a Kubernetes secret volume.A fluent builder forSecretPathVolume
.Options for a Kubernetes SecretPath Volume.A builder forSecretPathVolumeOptions
An implementation forSecretPathVolumeOptions
Specify the secret's version id or version stage.A builder forSecretVersionInfo
An implementation forSecretVersionInfo
Represents a group of Job Definitions.A builder forShare
An implementation forShare
The details of a tmpfs mount for a container.A builder forTmpfs
An implementation forTmpfs
The supported options for a tmpfs mount for a container.Sets limits for a resource withulimit
on linux systems.A builder forUlimit
An implementation forUlimit
The resources to be limited.Unmanaged ComputeEnvironments do not provision or manage EC2 instances on your behalf.A fluent builder forUnmanagedComputeEnvironment
.Represents an UnmanagedComputeEnvironment.A builder forUnmanagedComputeEnvironmentProps
An implementation forUnmanagedComputeEnvironmentProps