Package: aws-cdk.aws-batch
AWS Batch Construct Library---AWS CDK v1 has reached End-of-Support on 2023-06-01.
This package is no longer being updated, and users should migrate to AWS CDK v2.For more information on how to migrate, see theMigrating to AWS CDK v2guide.This module is part of theAWS Cloud Development Kitproject.AWS Batch is a batch processing tool for efficiently running hundreds of thousands computing jobs in AWS. Batch can dynamically provision different types of compute resources based on the resource requirements of submitted jobs.AWS Batch simplifies the planning, scheduling, and executions of your batch workloads across a full range of compute services likeAmazon EC2andSpot Resources.Batch achieves this by utilizing queue processing of batch job requests. To successfully submit a job for execution, you need the following resources:Job Definition-Group various job properties (container image, resource requirements, env variables...) into a single definition. These definitions are used at job submission time.Compute Environment-the execution runtime of submitted batch jobsJob Queue-the queue where batch jobs can be submitted to via AWS SDK/CLIFor more information onAWS Batchvisit theAWS Docs for Batch.Compute EnvironmentAt the core of AWS Batch is the compute environment. All batch jobs are processed within a compute environment, which uses resource like OnDemand/Spot EC2 instances or Fargate.InMANAGEDmode, AWS will handle the provisioning of compute resources to accommodate the demand. Otherwise, inUNMANAGEDmode, you will need to manage the provisioning of those resources.Below is an example of each available type of compute environment:# vpc: ec2.Vpc# default is managedaws_managed_environment=batch.ComputeEnvironment(self,"AWS-Managed-Compute-Env",compute_resources=batch.ComputeResources(vpc=vpc))customer_managed_environment=batch.ComputeEnvironment(self,"Customer-Managed-Compute-Env",managed=False)Spot-Based Compute EnvironmentIt is possible to have AWS Batch submit spotfleet requests for obtaining compute resources. Below is an example of how this can be done:vpc=ec2.Vpc(self,"VPC")spot_environment=batch.ComputeEnvironment(self,"MySpotEnvironment",compute_resources=batch.ComputeResources(type=batch.ComputeResourceType.SPOT,bid_percentage=75,# Bids for resources at 75% of the on-demand pricevpc=vpc))Fargate Compute EnvironmentIt is possible to have AWS Batch submit jobs to be run on Fargate compute resources. Below is an example of how this can be done:vpc=ec2.Vpc(self,"VPC")fargate_spot_environment=batch.ComputeEnvironment(self,"MyFargateEnvironment",compute_resources=batch.ComputeResources(type=batch.ComputeResourceType.FARGATE_SPOT,vpc=vpc))Understanding Progressive Allocation StrategiesAWS Batch uses anallocation strategyto determine what compute resource will efficiently handle incoming job requests. By default,BEST_FITwill 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 vCPUJob Queue:
---------
| A | B |
---------

Job Requirements:
A => 4 vCPU - ALLOCATED TO m5.xlarge
B => 2 vCPU - WAITINGIn this situation, Batch will allocateJob Ato compute resource #1 because it is the most cost efficient resource that matches the vCPU requirement. However, with thisBEST_FITstrategy,Job Bwill 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 similarm5.xlargeresource to be provisioned.The alternative would be to use theBEST_FIT_PROGRESSIVEstrategy in order for the remaining job to be handled in larger containers regardless of vCPU requirement and costs.Launch template supportSimply define your Launch Template:// This example is only available in TypeScript
const myLaunchTemplate = new ec2.CfnLaunchTemplate(this, 'LaunchTemplate', {
  launchTemplateName: 'extra-storage-template',
  launchTemplateData: {
    blockDeviceMappings: [
      {
        deviceName: '/dev/xvdcz',
        ebs: {
          encrypted: true,
          volumeSize: 100,
          volumeType: 'gp2',
        },
      },
    ],
  },
});and use it:# vpc: ec2.Vpc# my_launch_template: ec2.CfnLaunchTemplatemy_compute_env=batch.ComputeEnvironment(self,"ComputeEnv",compute_resources=batch.ComputeResources(launch_template=batch.LaunchTemplateSpecification(launch_template_name=my_launch_template.launch_template_name),vpc=vpc),compute_environment_name="MyStorageCapableComputeEnvironment")Importing an existing Compute EnvironmentTo import an existing batch compute environment, callComputeEnvironment.fromComputeEnvironmentArn().Below is an example:compute_env=batch.ComputeEnvironment.from_compute_environment_arn(self,"imported-compute-env","arn:aws:batch:us-east-1:555555555555:compute-environment/My-Compute-Env")Change the baseline AMI of the compute resourcesOccasionally, you will need to deviate from the default processing AMI.ECS Optimized Amazon Linux 2 example:# vpc: ec2.Vpcmy_compute_env=batch.ComputeEnvironment(self,"ComputeEnv",compute_resources=batch.ComputeResources(image=ecs.EcsOptimizedAmi(generation=ec2.AmazonLinuxGeneration.AMAZON_LINUX_2),vpc=vpc))Custom based AMI example:# vpc: ec2.Vpcmy_compute_env=batch.ComputeEnvironment(self,"ComputeEnv",compute_resources=batch.ComputeResources(image=ec2.MachineImage.generic_linux({"[aws-region]":"[ami-ID]"}),vpc=vpc))Job QueueJobs are always submitted to a specific queue. This means that you have to create a queue before you can start submitting jobs. Each queue is mapped to at least one (and no more than three) compute environment. When the job is scheduled for execution, AWS Batch will select the compute environment based on ordinal priority and available capacity in each environment.# compute_environment: batch.ComputeEnvironmentjob_queue=batch.JobQueue(self,"JobQueue",compute_environments=[batch.JobQueueComputeEnvironment(# Defines a collection of compute resources to handle assigned batch jobscompute_environment=compute_environment,# Order determines the allocation order for jobs (i.e. Lower means higher preference for job assignment)order=1)])Priorty-Based Queue ExampleSometimes you might have jobs that are more important than others, and when submitted, should take precedence over the existing jobs. To achieve this, you can create a priority based execution strategy, by assigning each queue its own priority:# shared_compute_envs: batch.ComputeEnvironmenthigh_prio_queue=batch.JobQueue(self,"JobQueue",compute_environments=[batch.JobQueueComputeEnvironment(compute_environment=shared_compute_envs,order=1)],priority=2)low_prio_queue=batch.JobQueue(self,"JobQueue",compute_environments=[batch.JobQueueComputeEnvironment(compute_environment=shared_compute_envs,order=1)],priority=1)By making sure to use the same compute environments between both job queues, we will give precedence to thehighPrioQueuefor the assigning of jobs to available compute environments.Importing an existing Job QueueTo import an existing batch job queue, callJobQueue.fromJobQueueArn().Below is an example:job_queue=batch.JobQueue.from_job_queue_arn(self,"imported-job-queue","arn:aws:batch:us-east-1:555555555555:job-queue/High-Prio-Queue")Job DefinitionA Batch Job definition helps AWS Batch understand important details about how to run your application in the scope of a Batch Job. This involves key information like resource requirements, what containers to run, how the compute environment should be prepared, and more. Below is a simple example of how to create a job definition:importaws_cdk.aws_ecrasecrrepo=ecr.Repository.from_repository_name(self,"batch-job-repo","todo-list")batch.JobDefinition(self,"batch-job-def-from-ecr",container=batch.JobDefinitionContainer(image=ecs.EcrImage(repo,"latest")))Using a local Docker projectBelow is an example of how you can create a Batch Job Definition from a local Docker application.batch.JobDefinition(self,"batch-job-def-from-local",container=batch.JobDefinitionContainer(# todo-list is a directory containing a Dockerfile to build the applicationimage=ecs.ContainerImage.from_asset("../todo-list")))Providing custom log configurationYou can provide custom log driver and its configuration for the container.importaws_cdk.aws_ssmasssmbatch.JobDefinition(self,"job-def",container=batch.JobDefinitionContainer(image=ecs.EcrImage.from_registry("docker/whalesay"),log_configuration=batch.LogConfiguration(log_driver=batch.LogDriver.AWSLOGS,options={"awslogs-region":"us-east-1"},secret_options=[batch.ExposedSecret.from_parameters_store("xyz",ssm.StringParameter.from_string_parameter_name(self,"parameter","xyz"))])))Importing an existing Job DefinitionFrom ARNTo import an existing batch job definition from its ARN, callJobDefinition.fromJobDefinitionArn().Below is an example:job=batch.JobDefinition.from_job_definition_arn(self,"imported-job-definition","arn:aws:batch:us-east-1:555555555555:job-definition/my-job-definition")From NameTo import an existing batch job definition from its name, callJobDefinition.fromJobDefinitionName().
If name is specified without a revision then the latest active revision is used.Below is an example:# Without revisionjob1=batch.JobDefinition.from_job_definition_name(self,"imported-job-definition","my-job-definition")# With revisionjob2=batch.JobDefinition.from_job_definition_name(self,"imported-job-definition","my-job-definition:3")