A container orchestrated by ECS that uses EC2 resources.

addUlimit

addVolume

EcsEc2ContainerDefinition

The number of physical GPUs to reserve for the container.

Make sure that the number of GPUs reserved for all containers in a job doesn't exceed
the number of available GPUs on the compute resource that the job is launched on.

When this parameter is true, the container is given elevated permissions on the host container instance (similar to the root user).

privileged

Limits to set for the user this docker container will run as.

ulimits

The number of vCPUs reserved for the container.

Each vCPU is equivalent to 1,024 CPU shares.
For containers running on EC2 resources, you must specify at least one vCPU.

image

The memory hard limit present to the container.

If your container attempts to exceed the memory specified, the container is terminated.
You must specify at least 4 MiB of memory for a job.

memory

The command that's passed to the container.

command

Determines whether execute command functionality is turned on for this task.

If true, execute command functionality is turned on all the containers in the task.

This allows you to use ECS Exec to access containers interactively.
When enabled, a job role with required SSM permissions will be created automatically if no job role is provided.
If a job role is alreadyprovided, the required permissions will be added to it.

enableExecuteCommand

The environment variables to pass to a container.

Cannot start with `AWS_BATCH`.
We don't recommend using plaintext environment variables for sensitive information, such as credential data.

environment

The role used by Amazon ECS container and AWS Fargate agents to make AWS API calls on your behalf.

executionRole

jobRole

Linux-specific modifications that are applied to the container, such as details for device mappings.

linuxParameters

logging

Gives the container readonly access to its root filesystem.

readonlyRootFilesystem

A map from environment variable names to the secrets for the container.

Allows your job definitions
to reference the secret by the environment variable name defined in this property.

secrets

The user name to use inside the container.

user

The volumes to mount to this container.

Automatically added to the job definition.

volumes

A container orchestrated by ECS that uses Fargate resources.

EcsFargateContainerDefinition

Indicates whether the job has a public IP address.

For a job that's running on Fargate resources in a private subnet to send outbound traffic to the internet
(for example, to pull container images), the private subnet requires a NAT gateway be attached to route requests to the internet.

assignPublicIp

ephemeralStorageSize

The vCPU architecture of Fargate Runtime.

fargateCpuArchitecture

The operating system for the compute environment.

fargateOperatingSystemFamily

Which version of Fargate to use when running this container.

fargatePlatformVersion

A JobDefinition that uses ECS orchestration.

Add a RetryStrategy to this JobDefinition.

addRetryStrategy

Grants the `batch:submitJob` permission to the identity on both this job definition and the `queue`.

[disable-awslint:no-grants]

grantSubmitJob

EcsJobDefinition

container

Whether to propagate tags from the JobDefinition to the ECS task that Batch spawns.

propagateTags

jobDefinitionName

The default parameters passed to the container These parameters can be referenced in the `command` that you give to the container.

parameters

The number of times to retry a job.

The job is retried on failure the same number of attempts as the value.

retryAttempts

retryStrategies

The priority of this Job.

Only used in Fairshare Scheduling
to decide which job to run first when there are multiple jobs
with the same share identifier.

schedulingPriority

Specifies whether the previous revision of the job definition is retained in an active status after UPDATE events for the resource.

When the property is set to false, the previous revision of the job definition is de-registered after a new revision is created.
When the property is set to true, the previous revision of the job definition is not de-registered.

skipDeregisterOnUpdate

The timeout time for jobs that are submitted with this job definition.

After the amount of time you specify passes,
Batch terminates your jobs if they aren't finished.

timeout

A container that can be run with EKS orchestration on EC2 resources.

Mount a Volume to this container.

Automatically added to the Pod.

EksContainerDefinition

An array of arguments to the entrypoint.

If this isn't specified, the CMD of the container image is used.
This corresponds to the args member in the Entrypoint portion of the Pod in Kubernetes.
Environment variable references are expanded using the container's environment.
If the referenced environment variable doesn't exist, the reference in the command isn't changed.
For example, if the reference is to "$(NAME1)" and the NAME1 environment variable doesn't exist,
the command string will remain "$(NAME1)." $$ is replaced with $, and the resulting string isn't expanded.
or example, $$(VAR_NAME) is passed as $(VAR_NAME) whether or not the VAR_NAME environment variable exists.

args

The entrypoint for the container.

This isn't run within a shell.
If this isn't specified, the `ENTRYPOINT` of the container image is used.
Environment variable references are expanded using the container's environment.
If the referenced environment variable doesn't exist, the reference in the command isn't changed.
For example, if the reference is to `"$(NAME1)"` and the `NAME1` environment variable doesn't exist,
the command string will remain `"$(NAME1)."` `$$` is replaced with `$` and the resulting string isn't expanded.
For example, `$$(VAR_NAME)` will be passed as `$(VAR_NAME)` whether or not the `VAR_NAME` environment variable exists.

The entrypoint can't be updated.

The hard limit of CPUs to present to this container. Must be an even multiple of 0.25.

If your container attempts to exceed this limit, it will be terminated.

At least one of `cpuReservation` and `cpuLimit` is required.
If both are specified, then `cpuLimit` must be at least as large as `cpuReservation`.

cpuLimit

The soft limit of CPUs to reserve for the container Must be an even multiple of 0.25.

The container will given at least this many CPUs, but may consume more.

At least one of `cpuReservation` and `cpuLimit` is required.
If both are specified, then `cpuLimit` must be at least as large as `cpuReservation`.

cpuReservation

The environment variables to pass to this container.

*Note*: Environment variables cannot start with "AWS_BATCH".
This naming convention is reserved for variables that AWS Batch sets.

The hard limit of GPUs to present to this container.

If your container attempts to exceed this limit, it will be terminated.

If both `gpuReservation` and `gpuLimit` are specified, then `gpuLimit` must be equal to `gpuReservation`.

gpuLimit

The soft limit of CPUs to reserve for the container Must be an even multiple of 0.25.

The container will given at least this many CPUs, but may consume more.

If both `gpuReservation` and `gpuLimit` are specified, then `gpuLimit` must be equal to `gpuReservation`.

gpuReservation

The image pull policy for this container.

imagePullPolicy

The amount (in MiB) of memory to present to the container.

If your container attempts to exceed the allocated memory, it will be terminated.

Must be larger that 4 MiB

At least one of `memoryLimit` and `memoryReservation` is required

*Note*: To maximize your resource utilization, provide your jobs with as much memory as possible
for the specific instance type that you are using.

memoryLimit

The soft limit (in MiB) of memory to reserve for the container.

Your container will be given at least this much memory, but may consume more.

Must be larger that 4 MiB

When system memory is under heavy contention, Docker attempts to keep the
container memory to this soft limit. However, your container can consume more
memory when it needs to, up to either the hard limit specified with the memory
parameter (if applicable), or all of the available memory on the container
instance, whichever comes first.

At least one of `memoryLimit` and `memoryReservation` is required.
If both are specified, then `memoryLimit` must be equal to `memoryReservation`

*Note*: To maximize your resource utilization, provide your jobs with as much memory as possible
for the specific instance type that you are using.

memoryReservation

name

If specified, gives this container elevated permissions on the host container instance.

The level of permissions are similar to the root user permissions.

This parameter maps to `privileged` policy in the Privileged pod security policies in the Kubernetes documentation.

*Note*: this is only compatible with Kubernetes < v1.25

If specified, gives this container readonly access to its root file system.

This parameter maps to `ReadOnlyRootFilesystem` policy in the Volumes and file systems pod security policies in the Kubernetes documentation.

*Note*: this is only compatible with Kubernetes < v1.25

If specified, the container is run as the specified group ID (`gid`).

If this parameter isn't specified, the default is the group that's specified in the image metadata.
This parameter maps to `RunAsGroup` and `MustRunAs` policy in the Users and groups pod security policies in the Kubernetes documentation.

*Note*: this is only compatible with Kubernetes < v1.25

runAsGroup

If specified, the container is run as a user with a `uid` other than 0.

Otherwise, no such rule is enforced.
This parameter maps to `RunAsUser` and `MustRunAsNonRoot` policy in the Users and groups pod security policies in the Kubernetes documentation.

*Note*: this is only compatible with Kubernetes < v1.25

runAsRoot

If specified, this container is run as the specified user ID (`uid`).

This parameter maps to `RunAsUser` and `MustRunAs` policy in the Users and groups pod security policies in the Kubernetes documentation.

*Note*: this is only compatible with Kubernetes < v1.25

runAsUser

The Volumes to mount to this container.

Automatically added to the Pod.

A JobDefinition that uses Eks orchestration.

EksJobDefinition

The container this Job Definition will run.

The DNS Policy of the pod used by this Job Definition.

dnsPolicy

The name of the service account that's used to run the container.

service accounts are Kubernetes method of identification and authentication,
roughly analogous to IAM users.

serviceAccount

If specified, the Pod used by this Job Definition will use the host's network IP address.

Otherwise, the Kubernetes pod networking model is enabled.
Most AWS Batch workloads are egress-only and don't require the overhead of IP allocation for each pod for incoming connections.

useHostNetwork

Represents a Fairshare Scheduling Policy. Instructs the scheduler to allocate ComputeEnvironment vCPUs based on Job shareIdentifiers.

The Faireshare Scheduling Policy ensures that each share gets a certain amount of vCPUs.
The scheduler does this by deciding how many Jobs of each share to schedule *relative to how many jobs of
each share are currently being executed by the ComputeEnvironment*. The weight factors associated with
each share determine the ratio of vCPUs allocated; see the readme for a more in-depth discussion of
fairshare policies.

Add a share this to this Fairshare SchedulingPolicy.

addShare

FairshareSchedulingPolicy

Used to calculate the percentage of the maximum available vCPU to reserve for share identifiers not present in the Queue.

The percentage reserved is defined by the Scheduler as:
`(computeReservation/100)^ActiveFairShares` where `ActiveFairShares` is the number of active fair share identifiers.

For example, a computeReservation value of 50 indicates that AWS Batch reserves 50% of the
maximum available vCPU if there's only one fair share identifier.
It reserves 25% if there are two fair share identifiers.
It reserves 12.5% if there are three fair share identifiers.

A computeReservation value of 25 indicates that AWS Batch should reserve 25% of the
maximum available vCPU if there's only one fair share identifier,
6.25% if there are two fair share identifiers,
and 1.56% if there are three fair share identifiers.

computeReservation

schedulingPolicyName

The amount of time to use to measure the usage of each job.

The usage is used to calculate a fair share percentage for each fair share identifier currently in the Queue.
A value of zero (0) indicates that only current usage is measured.
The decay is linear and gives preference to newer jobs.

The maximum supported value is 604800 seconds (1 week).

shareDecay

The shares that this Scheduling Policy applies to.

*Note*: It is possible to submit Jobs to the queue with Share Identifiers that
are not recognized by the Scheduling Policy.

shares

A ManagedComputeEnvironment that uses ECS orchestration on Fargate instances.

FargateComputeEnvironment

VPC in which this Compute Environment will launch Instances.

The maximum vCpus this `ManagedComputeEnvironment` can scale up to. Each vCPU is equivalent to 1024 CPU shares.

*Note*: if this Compute Environment uses EC2 resources (not Fargate) with either `AllocationStrategy.BEST_FIT_PROGRESSIVE` or
`AllocationStrategy.SPOT_CAPACITY_OPTIMIZED`, or `AllocationStrategy.BEST_FIT` with Spot instances,
The scheduler may exceed this number by at most one of the instances specified in `instanceTypes`
or `instanceClasses`.

maxvCpus

Specifies whether this Compute Environment is replaced if an update is made that requires replacing its instances.

To enable more properties to be updated,
set this property to `false`. When changing the value of this property to false,
do not change any other properties at the same time.
If other properties are changed at the same time,
and the change needs to be rolled back but it can't,
it's possible for the stack to go into the UPDATE_ROLLBACK_FAILED state.
You can't update a stack that is in the UPDATE_ROLLBACK_FAILED state.
However, if you can continue to roll it back,
you can return the stack to its original settings and then try to update it again.

The properties which require a replacement of the Compute Environment are:

replaceComputeEnvironment

The security groups this Compute Environment will launch instances in.

securityGroups

Whether or not to use spot instances.

Spot instances are less expensive EC2 instances that can be
reclaimed by EC2 at any time; your job will be given two minutes
of notice before reclamation.

spot

Whether or not any running jobs will be immediately terminated when an infrastructure update occurs.

If this is enabled, any terminated jobs may be retried, depending on the job's
retry policy.

terminateOnUpdate

Only meaningful if `terminateOnUpdate` is `false`.

If so,
when an infrastructure update is triggered, any running jobs
will be allowed to run until `updateTimeout` has expired.

updateTimeout

Whether or not the AMI is updated to the latest one supported by Batch when an infrastructure update occurs.

If you specify a specific AMI, this property will be ignored.

Note: the CDK will never set this value by default, `false` will set by CFN.
This is to avoid a deployment failure that occurs when this value is set.

updateToLatestImageVersion

The VPC Subnets this Compute Environment will launch instances in.

vpcSubnets

computeEnvironmentName

Whether or not this ComputeEnvironment can accept jobs from a Queue.

Enabled ComputeEnvironments can accept jobs from a Queue and
can scale instances up or down.
Disabled ComputeEnvironments cannot accept jobs from a Queue or
scale instances up or down.

If you change a ComputeEnvironment from enabled to disabled while it is executing jobs,
Jobs in the `STARTED` or `RUNNING` states will not
be interrupted. As jobs complete, the ComputeEnvironment will scale instances down to `minvCpus`.

To ensure you aren't billed for unused capacity, set `minvCpus` to `0`.

enabled

The role Batch uses to perform actions on your behalf in your account, such as provision instances to run your jobs.

serviceRole

JobQueues can receive Jobs, which are removed from the queue when sent to the linked ComputeEnvironment(s) to be executed.

Jobs exit the queue in FIFO order unless a `SchedulingPolicy` is linked.

Add a `ComputeEnvironment` to this Queue.

The Queue will prefer lower-order `ComputeEnvironment`s.

addComputeEnvironment

JobQueue

The set of compute environments mapped to a job queue and their order relative to each other.

The job scheduler uses this parameter to determine which compute environment runs a specific job.
Compute environments must be in the VALID state before you can associate them with a job queue.
You can associate up to three compute environments 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.

*Note*: All 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.

computeEnvironments

If the job queue is enabled, it is able to accept jobs.

Otherwise, new jobs can't be added to the queue, but jobs already in the queue can finish.

The name of the job queue.

It can be up to 128 letters long.
It can contain uppercase and lowercase letters, numbers, hyphens (-), and underscores (_)

jobQueueName

The set of actions that AWS Batch perform on jobs that remain at the head of the job queue in the specified state longer than specified times.

jobStateTimeLimitActions

The priority of the job queue.

Job queues with a higher priority are evaluated first when associated with the same compute environment.
Priority is determined in descending order.
For example, a job queue with a priority of 10 is given scheduling preference over a job queue with a priority of 1.

priority

The SchedulingPolicy for this JobQueue.

Instructs the Scheduler how to schedule different jobs.

schedulingPolicy

Linux-specific options that are applied to the container.

Adds one or more host devices to a container.

addDevices

Specifies the container path, mount options, and size (in MiB) of the tmpfs mount for a container.

Only works with EC2 launch type.

addTmpfs

Renders the Linux parameters to the Batch version of this resource, which does not have 'capabilities' and requires tmpfs.containerPath to be defined.

renderLinuxParameters

LinuxParameters

Specifies whether to run an init process inside the container that forwards signals and reaps processes.

initProcessEnabled

The total amount of swap memory a container can use.

This parameter
will be translated to the --memory-swap option to docker run.

This parameter is only supported when you are using the EC2 launch type.
Accepted values are positive integers.

maxSwap

The value for the size of the /dev/shm volume.

sharedMemorySize

This allows you to tune a container's memory swappiness behavior.

This parameter
maps to the --memory-swappiness option to docker run. The swappiness relates
to the kernel's tendency to swap memory. A value of 0 will cause swapping to
not happen unless absolutely necessary. A value of 100 will cause pages to
be swapped very aggressively.

This parameter is only supported when you are using the EC2 launch type.
Accepted values are whole numbers between 0 and 100. If a value is not
specified for maxSwap then this parameter is ignored.

swappiness

A ManagedComputeEnvironment that uses ECS orchestration on EC2 instances.

Add an instance class to this compute environment.

addInstanceClass

Add an instance type to this compute environment.

addInstanceType

ManagedEc2EcsComputeEnvironment

The allocation strategy to use if not enough instances of the best fitting instance type can be allocated.

allocationStrategy

Use batch's default instance types.

A simpler way to choose up-to-date instance classes based on region
instead of specifying exact instance classes.

defaultInstanceClasses

Configure which AMIs this Compute Environment can launch.

If you specify this property with only `image` specified, then the
`imageType` will default to `ECS_AL2` (or `ECS_AL2023` if the
`@aws-cdk/aws-batch:defaultToAL2023` feature flag is set).
*If your image needs GPU resources,
specify `ECS_AL2_NVIDIA` or `ECS_AL2023_NVIDIA`; otherwise, the instances
will not be able to properly join the ComputeEnvironment*.

images

The execution Role that instances launched by this Compute Environment will use.

instanceRole

The Launch Template that this Compute Environment will use to provision EC2 Instances.

*Note*: if `securityGroups` is specified on both your
launch template and this Compute Environment, **the
`securityGroup`s on the Compute Environment override the
ones on the launch template.

launchTemplate

The minimum vCPUs that an environment should maintain, even if the compute environment is DISABLED.

minvCpus

The EC2 placement group to associate with your compute resources.

If you intend to submit multi-node parallel jobs to this 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.

placementGroup

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%, the Spot price must be
less than 20% of the current On-Demand price for that Instance.
You always pay the lowest market price and never more than your maximum percentage.
For most use cases, Batch recommends leaving this field empty.

Implies `spot == true` if set

spotBidPercentage

The service-linked role that Spot Fleet needs to launch instances on your behalf.

spotFleetRole

Whether or not to use batch's optimal instance type.

The optimal instance type is equivalent to adding the
C4, M4, and R4 instance classes. You can specify other instance classes
(of the same architecture) in addition to the optimal instance classes.

useOptimalInstanceClasses

The instance classes that this Compute Environment can launch.

Which one is chosen depends on the `AllocationStrategy` used.
Batch will automatically choose the instance size.

instanceClasses

The instance types that this Compute Environment can launch.

Which one is chosen depends on the `AllocationStrategy` used.

AWS Batch

L2 Constructs13

EcsEc2ContainerDefinition

EcsFargateContainerDefinition

EcsJobDefinition

EksContainerDefinition

EksJobDefinition

FairshareSchedulingPolicy

FargateComputeEnvironment

JobQueue

LinuxParameters

ManagedEc2EcsComputeEnvironment

ManagedEc2EksComputeEnvironment

MultiNodeJobDefinition

UnmanagedComputeEnvironment

L1 Constructs7

CfnComputeEnvironment

CfnConsumableResource

CfnJobDefinition

CfnJobQueue

CfnQuotaShare

CfnSchedulingPolicy

CfnServiceEnvironment

Learn AWS the Practical Way

Quick Facts

Related Links