Batch
Introduction
Section titled “Introduction”Batch is a cloud-based service provided by Amazon Web Services (AWS) that simplifies the process of running batch computing workloads on the AWS cloud infrastructure. Batch allows you to efficiently process large volumes of data and run batch jobs without the need to manage and provision underlying compute resources.
Under the hood, the local Docker engine is used to run the containers that simulate your Batch jobs.
LocalStack allows you to use the Batch APIs to automate and scale computational tasks in your local environment while handling batch workloads. Batch jobs are executed using the ECS runtime, allowing for support of managed compute environments and improved service compatibility.
The supported APIs are available on our API Coverage section, which provides information on the extent of Batch integration with LocalStack.
Getting started
Section titled “Getting started”This guide is designed for users new to AWS Batch and assumes basic knowledge of the AWS CLI and our awslocal
wrapper script.
Start your LocalStack container using your preferred method. We will demonstrate how you create and run a Batch job by following these steps:
- Creating a service role for the compute environment.
- Creating the compute environment.
- Creating a job queue using the compute environment.
- Creating a job definition.
- Submitting a job to the job queue.
Create a service role
Section titled “Create a service role”You can create a role using the CreateRole
API.
LocalStack requires the role to exist with a valid trust policy. When enforcing IAM policies, ensure that the policy is valid and the role is properly attached.
Run the following command to create a role for ECS task execution:
awslocal iam create-role \ --role-name myrole \ --assume-role-policy-document '{ "Version": "2025-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "ecs-tasks.amazonaws.com" }, "Action": "sts:AssumeRole" } ]}'
Then attach the ECS task execution policy:
awslocal iam attach-role-policy \ --role-name myrole \ --policy-arn arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy
Create the compute environment
Section titled “Create the compute environment”You can use the CreateComputeEnvironment
API to create a compute environment.
Run the following command using the role ARN above (arn:aws:iam::000000000000:role/myrole) to create a managed compute environment with FARGATE:
awslocal batch create-compute-environment \ --compute-environment-name myenv \ --type MANAGED \ --state ENABLED \ --compute-resources type=FARGATE,maxvCpus=128,subnets=subnet-12345678,securityGroupIds=sg-12345678 \ --service-role arn:aws:iam::000000000000:role/myrole
Create a job queue
Section titled “Create a job queue”You can fetch the ARN using the DescribeComputeEnvironments
API.
Run the following command to fetch the ARN of the compute environment:
awslocal batch describe-compute-environments --compute-environments myenv
{ "computeEnvironments": [ { "computeEnvironmentName": "myenv", "computeEnvironmentArn": "arn:aws:batch:us-east-1:000000000000:compute-environment/myenv", "ecsClusterArn": "arn:aws:ecs:us-east-1:000000000000:cluster/OnDemand_Batch_abc123", "type": "MANAGED", "status": "VALID", "statusReason": "Compute environment is available", "serviceRole": "arn:aws:iam::000000000000:role/myrole" } ]}
You can use the ARN to create the job queue using CreateJobQueue
API.
Run the following command to create the job queue:
awslocal batch create-job-queue \ --job-queue-name myqueue \ --priority 1 \ --compute-environment-order order=0,computeEnvironment=arn:aws:batch:us-east-1:000000000000:compute-environment/myenv \ --state ENABLED
Create a job definition
Section titled “Create a job definition”Now, you can define what occurs during a job run. In this example, you can execute the ‘busybox’ container from DockerHub and initiate the command: ‘sleep 30’. It’s important to note you can override this command when submitting the job.
Run the following command to create the job definition using the RegisterJobDefinition
API:
awslocal batch register-job-definition \ --job-definition-name myjobdefn \ --type container \ --platform-capabilities FARGATE \ --container-properties '{ "image": "busybox", "resourceRequirements": [ {"type": "VCPU", "value": "0.25"}, {"type": "MEMORY", "value": "512"} ], "command": ["sleep", "30"], "networkConfiguration": { "assignPublicIp": "ENABLED" }, "executionRoleArn": "arn:aws:iam::000000000000:role/myrole" }'
If you want to pass arguments to the command as parameters, you can use the Ref::
declaration to set placeholders for parameter substitution.
This allows the dynamic passing of values at runtime for specific job definitions.
awslocal batch register-job-definition \ --job-definition-name myjobdefn \ --type container \ --parameters '{"time":"10"}' \ --platform-capabilities FARGATE \ --container-properties '{ "image": "busybox", "resourceRequirements": [ {"type": "VCPU", "value": "0.25"}, {"type": "MEMORY", "value": "512"} ], "command": ["sleep", "Ref::time"], "networkConfiguration": { "assignPublicIp": "ENABLED" }, "executionRoleArn": "arn:aws:iam::000000000000:role/myrole" }'
Submit a job to the job queue
Section titled “Submit a job to the job queue”You can now run a compute job.
This command runs a job on the queue that you have set up previously, overriding the container command to run: sh -c "sleep 5; pwd"
.
This command simulates work being done in the container.
Run the following command to submit a job to the job queue using the SubmitJob
API:
awslocal batch submit-job \ --job-name myjob \ --job-queue myqueue \ --job-definition myjobdefn \ --container-overrides '{"command":["sh", "-c", "sleep 5; pwd"]}'
Current Limitations
Section titled “Current Limitations”LocalStack simulates the execution of ECS-based AWS Batch jobs using the local ECS runtime. No real infrastructure is created or managed.
Array jobs are supported in sequential mode only.
A subset of environment variables is supported, including:
AWS_BATCH_CE_NAME
AWS_BATCH_JOB_ARRAY_INDEX
AWS_BATCH_JOB_ARRAY_SIZE
AWS_BATCH_JOB_ATTEMPT
AWS_BATCH_JOB_ID
AWS_BATCH_JQ_NAME
The configuration variable ECS_DOCKER_FLAGS
can be used to pass additional Docker flags to the container runtime.
Setting ECS_TASK_EXECUTOR=kubernetes
is supported as an alternative backend, though Kubernetes execution is experimental and may not support all features.
API Coverage
Section titled “API Coverage”Operation ▲ | Implemented | Image |
---|