# Compute environments for AWS Batch
Job queues are mapped to one or more compute environments. Compute environments contain the Amazon ECS container instances that are used to run containerized batch jobs. A specific compute environment can also be mapped to one or more than one job queue. Within a job queue, the associated compute environments each have an order that's used by the scheduler to determine where jobs that are ready to be run will run. If the first compute environment has a status of `VALID` and has available resources, the job is scheduled to a container instance within that compute environment. If the first compute environment has a status of `INVALID` or can't provide a suitable compute resource, the scheduler attempts to run the job on the next compute environment.
**Topics**
+ [Managed compute environments](managed_compute_environments.md)
+ [Unmanaged compute environments](unmanaged_compute_environments.md)
+ [Create a compute environment](create-compute-environment.md)
+ [Update a compute environment in AWS Batch](updating-compute-environments.md)
+ [Compute resource AMIs](compute_resource_AMIs.md)
+ [Use Amazon EC2 launch templates with AWS Batch](launch-templates.md)
+ [Instance Metadata Service (IMDS) configuration](imds-compute-environments.md)
+ [EC2 configurations](ec2-configurations.md)
+ [Instance type allocation strategies for AWS Batch](allocation-strategies.md)
+ [Compute resource memory management](memory-management.md)
+ [Fargate compute environments](fargate.md)
+ [Amazon EKS compute environments](eks.md)
# Managed compute environments
You can use a managed compute environment to have AWS Batch manage the capacity and instance types of the compute resources within the environment. This is based on the compute resource specifications that you define when you create the compute environment. You can choose either to use Amazon EC2 On-Demand Instances and Amazon EC2 Spot Instances. Or, you can alternatively use Fargate and Fargate Spot capacity in your managed compute environment. When using Spot Instances, you can optionally set a maximum price. This way, Spot Instances only launch when the Spot Instance price is under a specified percentage of the On-Demand price.
**Important**
Fargate Spot instances are not supported on Windows containers on AWS Fargate. A job queue will be blocked if a FargateWindows job is submitted to a job queue that only uses Fargate Spot compute environments.
**Important**
AWS Batch creates and manages multiple AWS resources on your behalf and within your account, including Amazon EC2 Launch Templates, Amazon EC2 Auto Scaling Groups, Amazon EC2 Spot Fleets, and Amazon ECS Clusters. These managed resources are configured specifically to ensure optimal AWS Batch operation. Manually modifying these AWS Batch-managed resources, unless explicitly stated in AWS Batch documentation, can result in unexpected behavior, including `INVALID` compute environments, suboptimal instance scaling behavior, delayed workload processing, or unexpected costs. These manual modifications can't be deterministically supported by the AWS Batch service. Always use the supported AWS Batch APIs or the AWS Batch console to manage your compute environments.
Unsupported manual modifications include running your own Amazon ECS tasks or services on AWS Batch-managed Amazon ECS clusters, or starting additional processes, daemons, or services directly on AWS Batch-managed instances. AWS Batch assumes full control of the compute resources in a managed compute environment and can terminate instances, stop tasks, or scale the cluster at any time. Any workloads you run outside of AWS Batch job submissions on these managed resources can be interrupted without warning. Running non-AWS Batch workloads on AWS Batch-managed clusters and instances can also interfere with AWS Batch job scheduling and instance scaling.
Managed compute environments launch Amazon EC2 instances into the VPC and subnets that you specify and then registers them with an Amazon ECS cluster. The Amazon EC2 instances need external network access to communicate with the Amazon ECS service endpoint. Some subnets don't provide Amazon EC2 instances with public IP addresses. If your Amazon EC2 instances don't have a public IP address, they must use network address translation (NAT) to gain this access. For more information, see [NAT gateways](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-nat-gateway.html) in the *Amazon VPC User Guide*. For more information about how to create a VPC, see [Create a virtual private cloud](create-public-private-vpc.md).
By default, AWS Batch managed compute environments use a recent, approved version of the Amazon ECS optimized AMI for compute resources. However, you might want to create your own AMI to use for your managed compute environments for various reasons. For more information, see [Compute resource AMIs](compute_resource_AMIs.md).
**Note**
AWS Batch doesn't automatically upgrade the AMIs in a compute environment after it's created. For example, it doesn't update the AMIs in your compute environment when a newer version of the Amazon ECS optimized AMI is released. You're responsible for the management of the guest operating system. This includes any updates and security patches. You're also responsible for any additional application software or utilities that you install on the compute resources. There are two ways to use a new AMI for your AWS Batch jobs. The original method is to complete these steps:
Create a new compute environment with the new AMI.
Add the compute environment to an existing job queue.
Remove the earlier compute environment from your job queue.
Delete the earlier compute environment.
In April 2022, AWS Batch added enhanced support for updating compute environments. For more information, see [Update a compute environment in AWS Batch](updating-compute-environments.md). To use the enhanced updating of compute environments to update AMIs, follow these rules:
Either don't set the service role ([https://docs.aws.amazon.com/batch/latest/APIReference/API_CreateComputeEnvironment.html#Batch-CreateComputeEnvironment-request-serviceRole](https://docs.aws.amazon.com/batch/latest/APIReference/API_CreateComputeEnvironment.html#Batch-CreateComputeEnvironment-request-serviceRole)) parameter or set it to the **AWSServiceRoleForBatch** service-linked role.
Set the allocation strategy ([https://docs.aws.amazon.com/batch/latest/APIReference/API_ComputeResource.html#Batch-Type-ComputeResource-allocationStrategy](https://docs.aws.amazon.com/batch/latest/APIReference/API_ComputeResource.html#Batch-Type-ComputeResource-allocationStrategy)) parameter to `BEST_FIT_PROGRESSIVE`, `SPOT_CAPACITY_OPTIMIZED` or `SPOT_PRICE_CAPACITY_OPTIMIZED`.
Set the update to latest image version ([https://docs.aws.amazon.com/batch/latest/APIReference/API_ComputeResourceUpdate.html#Batch-Type-ComputeResourceUpdate-updateToLatestImageVersion](https://docs.aws.amazon.com/batch/latest/APIReference/API_ComputeResourceUpdate.html#Batch-Type-ComputeResourceUpdate-updateToLatestImageVersion)) parameter to `true`.
Don't specify an AMI ID in [https://docs.aws.amazon.com/batch/latest/APIReference/API_ComputeResourceUpdate.html#Batch-Type-ComputeResourceUpdate-imageId](https://docs.aws.amazon.com/batch/latest/APIReference/API_ComputeResourceUpdate.html#Batch-Type-ComputeResourceUpdate-imageId), [https://docs.aws.amazon.com/batch/latest/APIReference/API_Ec2Configuration.html#Batch-Type-Ec2Configuration-imageIdOverride](https://docs.aws.amazon.com/batch/latest/APIReference/API_Ec2Configuration.html#Batch-Type-Ec2Configuration-imageIdOverride) (in [https://docs.aws.amazon.com/batch/latest/APIReference/API_Ec2Configuration.html](https://docs.aws.amazon.com/batch/latest/APIReference/API_Ec2Configuration.html)), or in the launch template ([https://docs.aws.amazon.com/batch/latest/APIReference/API_ComputeResourceUpdate.html#Batch-Type-ComputeResourceUpdate-launchTemplate](https://docs.aws.amazon.com/batch/latest/APIReference/API_ComputeResourceUpdate.html#Batch-Type-ComputeResourceUpdate-launchTemplate)). In that case, AWS Batch selects the latest Amazon ECS optimized AMI that's supported by AWS Batch at the time the infrastructure update is initiated. Alternatively, you can specify the AMI ID in the `imageId` or `imageIdOverride` parameters, or the launch template identified by the `LaunchTemplate` properties. Changing any of these properties starts an infrastructure update. If the AMI ID is specified in the launch template, it can't be replaced by specifying an AMI ID in either the `imageId` or `imageIdOverride` parameters. It can only be replaced by specifying a different launch template. Or, if the launch template version is set to `$Default` or `$Latest`, by setting either a new default version for the launch template (if it's `$Default`) or by adding a new version to the launch template (if it's `$Latest`).
If these rules are followed, any update that starts an infrastructure update will cause the AMI ID to be re-selected. If the [https://docs.aws.amazon.com/batch/latest/APIReference/API_LaunchTemplateSpecification.html#Batch-Type-LaunchTemplateSpecification-version](https://docs.aws.amazon.com/batch/latest/APIReference/API_LaunchTemplateSpecification.html#Batch-Type-LaunchTemplateSpecification-version) setting in the launch template ([https://docs.aws.amazon.com/batch/latest/APIReference/API_ComputeResourceUpdate.html#Batch-Type-ComputeResourceUpdate-launchTemplate](https://docs.aws.amazon.com/batch/latest/APIReference/API_ComputeResourceUpdate.html#Batch-Type-ComputeResourceUpdate-launchTemplate)) is set to `$Latest` or `$Default`, the latest or default version of the launch template are evaluated up at the time of the infrastructure update, even if the [https://docs.aws.amazon.com/batch/latest/APIReference/API_ComputeResourceUpdate.html#Batch-Type-ComputeResourceUpdate-launchTemplate](https://docs.aws.amazon.com/batch/latest/APIReference/API_ComputeResourceUpdate.html#Batch-Type-ComputeResourceUpdate-launchTemplate) was not updated.
## Consideration when creating multi-node parallel jobs
AWS Batch recommends creating dedicated compute environments for running multi-node parallel (MNP) jobs and non-MNP jobs. This is due to the way compute capacity is created in your managed compute environment. When creating a new managed compute environment, if you specify a `minvCpu` value greater than zero then AWS Batch creates an instance pool for use with non-MNP jobs only. If a multi-node parallel job is submitted, AWS Batch creates new instance capacity to run the multi-node parallel jobs. In cases where there are both single-node and multi-node parallel jobs running in the same compute environment where either a `minvCpus` or `maxvCpus` value is set, if the required compute resources are unavailable AWS Batch will wait for the current jobs to finish before creating the compute resources necessary to run the new jobs.
# Unmanaged compute environments
In an unmanaged compute environment, you manage your own compute resources. AWS Batch supports unmanaged compute environments for both Amazon ECS and Amazon EKS, allowing you to maintain control over your infrastructure while leveraging Batch's job scheduling capabilities.
**Note**
AWS Fargate resources aren't supported in unmanaged compute environments.
For unmanaged Amazon ECS compute environments, you must verify that the AMI you use for your compute resources meets the Amazon ECS container instance AMI specification. For more information, see [Compute resource AMI specification](batch-ami-spec.md) and [Tutorial: Create a compute resource AMI](create-batch-ami.md).
After you created your unmanaged compute environment, use the [DescribeComputeEnvironments](https://docs.aws.amazon.com/batch/latest/APIReference/API_DescribeComputeEnvironments.html) API operation to view the compute environment details. Find the Amazon ECS cluster that's associated with the environment and then manually launch your container instances into that Amazon ECS cluster.
The following AWS CLI command also provides the Amazon ECS cluster ARN.
```
$ aws batch describe-compute-environments \
--compute-environments unmanagedCE \
--query "computeEnvironments[].ecsClusterArn"
```
For more information, see [Launching an Amazon ECS container instance](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/launch_container_instance.html) in the *Amazon Elastic Container Service Developer Guide*. When you launch your compute resources, specify the Amazon ECS cluster ARN that the resources register with the following Amazon EC2 user data. Replace *ecsClusterArn* with the cluster ARN that you obtained with the previous command.
```
#!/bin/bash
echo "ECS_CLUSTER=ecsClusterArn" >> /etc/ecs/ecs.config
```
In an unmanaged Amazon EKS compute environment, you manage your own Kubernetes nodes while AWS Batch handles job scheduling and placement. It allows you to directly control your Kubernetes infrastructure for security, compliance, or operational requirements. You are responsible for provisioning and configuring your Amazon EKS nodes, while AWS Batch integrates with your existing Amazon EKS cluster to schedule and run jobs.
For more information, see [Tutorial: Create an unmanaged compute environment using Amazon EKS resources](https://docs.aws.amazon.com/batch/latest/userguide/create-compute-environment-unmanaged-eks.html).
# Create a compute environment
Before you can run jobs in AWS Batch, you need to create a compute environment. You can create a managed compute environment where AWS Batch manages the Amazon EC2 instances or AWS Fargate resources within the environment based on your specifications. Or, alternatively, you can create an unmanaged compute environment where you handle the Amazon EC2 instance configuration within the environment.
**Important**
Fargate Spot instances are not supported in the following scenarios:
Windows containers on AWS Fargate
A job queue will be blocked in these scenarios if a job is submitted to a job queue that only uses Fargate Spot compute environments.
**Topics**
+ [Tutorial: Create a managed compute environment using Fargate resources](create-compute-environment-fargate.md)
+ [Tutorial: Create a managed compute environment using Amazon EC2 resources](create-compute-environment-managed-ec2.md)
+ [Tutorial: Create an unmanaged compute environment using Amazon EC2 resources](create-compute-environment-unmanaged-ec2.md)
+ [Tutorial: Create a managed compute environment using Amazon EKS resources](create-compute-environment-managed-eks.md)
+ [Tutorial: Create an unmanaged compute environment using Amazon EKS resources](create-compute-environment-unmanaged-eks.md)
+ [Resource: Compute environment template](compute-environment-template.md)
+ [Instance type compute table](instance-type-compute-table.md)
# Tutorial: Create a managed compute environment using Fargate resources
Complete the following steps to create a managed compute environment using AWS Fargate resources.
1. Open the AWS Batch console at [https://console.aws.amazon.com/batch/](https://console.aws.amazon.com/batch/).
1. From the navigation bar, select the AWS Region to use.
1. In the navigation pane, choose **Compute environments**.
1. Choose **Create**.
1. Configure the compute environment.
**Note**
Compute environments for Windows containers on AWS Fargate jobs must at least one vCPU.
1. For **Compute environment configuration**, choose **Fargate**.
1. For **Name**, specify a unique name for your compute environment. The name can contain up to 128 characters in length. It can contain uppercase and lowercase letters, numbers, hyphens (-), and underscores (\$1).
1. For **Service role**, choose service-linked role that lets the AWS Batch service to make calls to the required AWS API operations on your behalf. For example, choose **AWSServiceRoleForBatch**. For more information, see [Using service-linked roles for AWS Batch](using-service-linked-roles.md).
1. (Optional) Expand **Tags**. To add a tag, choose **Add tag**. Then, enter a **Key** name and optional **Value**. Choose **Add tag**.
1. Choose **Next page**.
1. In the **Instance configuration** section:
1. (Optional) For **Use Fargate Spot capacity**, turn on Fargate Spot. For information about Fargate Spot, see [Using Amazon EC2 Spot and Fargate\$1SPOT](https://docs.aws.amazon.com/AmazonECS/latest/bestpracticesguide/ec2-and-fargate-spot.html).
1. For **Maximum vCPUs**, choose the maximum number of vCPUs that your compute environment can scale out to, regardless of job queue demand.
1. Choose **Next page**.
1. Configure networking.
**Important**
Compute resources need access to communicate with the Amazon ECS service endpoint. This can be through an interface VPC endpoint or through your compute resources having public IP addresses.
For more information about interface VPC endpoints, see [Amazon ECS Interface VPC Endpoints (AWS PrivateLink)](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/vpc-endpoints.html) in the *Amazon Elastic Container Service Developer Guide*.
If you do not have an interface VPC endpoint configured and your compute resources do not have public IP addresses, then they must use network address translation (NAT) to provide this access. For more information, see [NAT gateways](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-nat-gateway.html) in the *Amazon VPC User Guide*. For more information, see [Create a VPC](create-a-vpc.md).
1. For **Virtual Private Cloud (VPC) ID**, choose a VPC where you want to launch your instances.
1. For **Subnets**, choose the subnets to use. By default, all subnets within the selected VPC are available.
**Note**
AWS Batch on Fargate doesn't currently support Local Zones. For more information, see [ Amazon ECS clusters in Local Zones, Wavelength Zones, and AWS Outposts](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/cluster-regions-zones.html#clusters-local-zones) in the *Amazon Elastic Container Service Developer Guide*.
1. For **Security groups**, choose a security group to attach to your instances. By default, the default security group for your VPC is chosen.
1. Choose **Next page**.
1. For **Review**, review the configuration steps. If you need to make changes, choose **Edit**. When you're finished, choose **Create compute environment**.
# Tutorial: Create a managed compute environment using Amazon EC2 resources
Complete the following steps to create a managed compute environment using Amazon Elastic Compute Cloud (Amazon EC2) resources.
1. Open the AWS Batch console at [https://console.aws.amazon.com/batch/](https://console.aws.amazon.com/batch/).
1. From the navigation bar, select the AWS Region to use.
1. In the navigation pane, choose **Environments**.
1. Choose **Create environment** and then **Compute environment**.
1. Configure the environment.
1. For **Compute environment configuration**, choose **Amazon Elastic Compute Cloud (Amazon EC2)**.
1. For **Orchestration type**, choose **Managed**.
1. For **Name**, specify a unique name for your compute environment. The name can contain up to 128 characters in length. It can contain uppercase and lowercase letters, numbers, hyphens (-), and underscores (\$1).
1. For **Service role**, choose service-linked role that lets the AWS Batch service make calls to the required AWS API operations on your behalf. For example, choose **AWSServiceRoleForBatch**. For more information, see [Using service-linked roles for AWS Batch](using-service-linked-roles.md).
1. For **Instance role**, choose to create a new instance profile or use an existing instance profile that has the required IAM permissions attached. This instance profile allows the Amazon ECS container instances that are created for your compute environment to make calls to the required AWS API operations on your behalf. For more information, see [Amazon ECS instance role](instance_IAM_role.md). If you choose to create a new instance profile, the required role (`ecsInstanceRole`) is created for you.
1. (Optional) Expand **Tags**.
1. (Optional) For **EC2 tags**, choose **Add tag** to add a tag to resources that are launched in the compute environment. Then, enter a **Key** name and optional **Value**. Choose **Add tag**.
1. (Optional) For **Tags**, choose **Add tag**. Then, enter a **Key** name and optional **Value**. Choose **Add tag**.
For more information, see [Tag your AWS Batch resources](using-tags.md).
1. Choose **Next**.
1. In the **Instance configuration** section:
1. (Optional) For **Enable using Spot instances**, turn on Spot. For more information, see [Spot Instances](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-spot-instances.html).
1. (Spot only) For **Maximum % on-demand price**, choose 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 price is 20%, then the Spot price must be less than 20% of the current On-Demand price for that 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.
1. (Spot only) For **Spot fleet role**, choose an existing Amazon EC2 Spot Fleet IAM role to apply to your Spot compute environment. If you don't already have an existing Amazon EC2 Spot Fleet IAM role, you must create one first. For more information, see [Amazon EC2 spot fleet role](spot_fleet_IAM_role.md).
**Important**
To tag your Spot Instances on creation, your Amazon EC2 Spot Fleet IAM role must use the newer **AmazonEC2SpotFleetTaggingRole** managed policy. The **AmazonEC2SpotFleetRole** managed policy doesn't have the required permissions to tag Spot Instances. For more information, see [Spot Instances not tagged on creation](spot-instance-no-tag.md) and [Tag your resources](tag-resources.md).
1. For **Minimum vCPUs**, choose the minimum number of vCPUs that your compute environment maintains, regardless of job queue demand.
1. For **Desired vCPUs**, choose the number of vCPUs that your compute environment launches with. As your job queue demand increases, AWS Batch can increase the desired number of vCPUs in your compute environment and add EC2 instances, up to the maximum vCPUs. As demand decreases, AWS Batch can decrease the desired number of vCPUs in your compute environment and remove instances, down to the minimum vCPUs.
1. For **Maximum vCPUs**, choose the maximum number of vCPUs that your compute environment can scale out to, regardless of job queue demand.
1. (Optional) For **Scale down delay (minutes)**, choose the minimum time (in minutes) that AWS Batch keeps instances running in the compute environment after their jobs complete.
1. For **Allowed instance types**, choose the Amazon EC2 instance types that can be launched. You can specify instance families to launch any instance type within those families (for example, `c5`, `c5n`, or `p3`). Or, you can specify specific sizes within a family (such as `c5.8xlarge`). Metal instance types aren't in the instance families. For example, `c5` doesn't include `c5.metal`.
AWS Batch can select the instance type for you if you choose one of the following:
+ `optimal` to select instance types (from the `c4`, `m4`, `r4`, `c5`, `m5`, and `r5` instance families) that match the demand of your job queues.
+ `default_x86_64` to choose x86 based instance types (from the m6i, c6i, r6i, and c7i instance families) that matches the resource demands of the job queue.
+ `default_arm64` to choose x86 based instance types (from the m6g, c6g, r6g, and c7g instance families) that matches the resource demands of the job queue.
**Note**
Starting on 11/01/2025 the behavior of `optimal` is going to be changed to match `default_x86_64`. During the change your instance families could be updated to a newer generation. You do not need to perform any actions for the upgrade to happen. For more information about change, see [Optimal instance type configuration to receive automatic instance family updates](optimal-default-instance-troubleshooting.md).
**Note**
Instance family availability varies by AWS Region. For example, some AWS Regions may not have any fourth generation instance families but have fifth and sixth generation instance families.
When using `default_x86_64` or `default_arm64` instance bundles, AWS Batch selects instance families based on a balance of cost-effectiveness and performance. While newer generation instances often provide better price-performance, AWS Batch may choose an earlier generation instance family if it provides the optimal combination of availability, cost, and performance for your workload. For example, in an AWS Region where both c6i and c7i instances are available, AWS Batch might select c6i instances if they offer better cost-effectiveness for your specific job requirements. For more information on AWS Batch instance types and AWS Region availability, see [Instance type compute table](instance-type-compute-table.md).
AWS Batch periodically updates your instances in default bundles to newer, more cost-effective options. Updates happen automatically without requiring any action from you. Your workloads continue running during updates with no interruption.
**Note**
When 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.
**Note**
AWS Batch will scale GPUs based on the required amount in your job queues. To use GPU scheduling, the compute environment must include instance types from the `p3`, `p4`, `p5`, `p6`, `g3`, `g3s`, `g4`, `g5`, or `g6` families.
1. For **Allocation strategy**, choose the allocation strategy to use when selecting instance types from the list of allowed instance types. **BEST\$1FIT\$1PROGRESSIVE** is usually the better choice for EC2 On-Demand compute environments, **SPOT\$1CAPACITY\$1OPTIMIZED**, and **SPOT\$1PRICE\$1CAPACITY\$1OPTIMIZED** for EC2 Spot compute environments. For more information, see [Instance type allocation strategies for AWS Batch](allocation-strategies.md).
1. Expand **Additional configuration**.
1. (Optional) For **Placement group**, enter a placement group name to group resources in the compute environment.
1. (Optional) For **EC2 key pair**, choose a public and private key pair as security credentials when you connect to the instance. For more information about Amazon EC2 key pairs, see [Amazon EC2 key pairs and Linux instances](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html).
1. (Optional) For **EC2 configuration** choose **Image type** and **Image ID override** values to provide information for AWS Batch to select Amazon Machine Images (AMIs) for instances in the compute environment. If the **Image ID override** isn't specified for each **Image type**, AWS Batch selects a recent [Amazon ECS optimized AMI](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-optimized_AMI.html). If no **Image type** is specified, the default is a **Amazon Linux 2** for non-GPU, non AWS Graviton instance.
**Important**
To use a custom AMI, choose the image type and then enter the custom AMI ID in the **Image ID override** box.
[Amazon Linux 2](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-optimized_AMI.html#al2ami)
Default for all AWS Graviton-based instance families (for example, `C6g`, `M6g`, `R6g`, and `T4g`) and can be used for all non-GPU instance types.
[Amazon Linux 2 (GPU)](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-optimized_AMI.html#gpuami)
Default for all GPU instance families (for example `P4` and `G4`) and can be used for all non AWS Graviton-based instance types.
[Amazon Linux 2023](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-optimized_AMI.html)
AWS Batch supports Amazon Linux 2023.
Amazon Linux 2023 does not support `A1` instances.
[Amazon Linux 2023 (GPU)](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-optimized_AMI.html#gpuami)
Default for all GPU instance families (for example `P4` and `G4`) and can be used for all non AWS Graviton-based instance types.
**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](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-optimized_AMI.html#ecs-optimized-ami-linux-variants.html) in the *Amazon Elastic Container Service Developer Guide*.
1. (Optional) Expand **Launch templates**
1. For **Default launch template**, select an existing Amazon EC2 launch template to configure your compute resources. The default version of the template is automatically populated. For more information, see [Use Amazon EC2 launch templates with AWS Batch](launch-templates.md).
**Note**
In a launch template, you can specify a custom AMI that you created.
1. (Optional) For **Default version**, enter `$Default`, `$Latest`, or a specific version number to use.
**Note**
Note: If you use either substitution variable (\$1Default or \$1Latest), they will apply the current default or latest version number at the time that this configuration is saved. If the default or latest version changes in the future, you must update the information - it won't automatically update.
**Important**
If the version parameter of the launch template is `$Default` or `$Latest`, the default or latest version of the specified launch template is evaluated during an infrastructure update. If a different AMI ID is selected by the default or the latest version of the launch template is selected, that AMI ID is used in the update. For more information, see [AMI selection during infrastructure updates](infrastructure-updates.md#updating-compute-environments-ami).
1. (Optional) For **Override launch template** choose **Add override launch template**
1. (Optional) For **Launch template**, select an existing Amazon EC2 launch template to use for specific instance types and families.
1. (Optional) For **Default version**, enter a specific version number to use, `$Default`, or `$Latest`.
**Note**
If you use either the `$Default` or `$Latest` variable, AWS Batch will apply the current information at the time that the compute environment is created. If the default or latest version changes in the future, you must update the information through [UpdateComputeEnvironment](https://docs.aws.amazon.com/batch/latest/APIReference/API_UpdateComputeEnvironment.html) or through the AWS Management Console - AWS Batch.
1. (Optional) For **Target instance types**, select the instance type or family that you want to apply the override launch template.
**Note**
If you specify an override launch template, **Target instance types** is required. For more information, see [LaunchTemplateSpecificationOverride.targetInstanceTypes](https://docs.aws.amazon.com/batch/latest/APIReference/API_LaunchTemplateSpecificationOverride.html#Batch-Type-LaunchTemplateSpecificationOverride-targetInstanceTypes).
**Note**
If the instance type or family that you want to select doesn't appear in this list, review the selections you made in `Allowed instance types`.
1. Choose **Next**.
1. In the **Network configuration** section:
**Important**
Compute resources need access to communicate with the Amazon ECS service endpoint. This can be through an interface VPC endpoint or through your compute resources having public IP addresses.
For more information about interface VPC endpoints, see [Amazon ECS Interface VPC Endpoints (AWS PrivateLink)](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/vpc-endpoints.html) in the *Amazon Elastic Container Service Developer Guide*.
If you do not have an interface VPC endpoint configured and your compute resources do not have public IP addresses, then they must use network address translation (NAT) to provide this access. For more information, see [NAT gateways](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-nat-gateway.html) in the *Amazon VPC User Guide*. For more information, see [Create a VPC](create-a-vpc.md).
1. For **Virtual Private Cloud (VPC) ID**, choose a VPC where to launch your instances.
1. For **Subnets**, choose the subnets to use. By default, all subnets within the selected VPC are available.
**Note**
AWS Batch on Amazon EC2 supports Local Zones. For more information, see [ Local Zones](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html?icmpid=docs_ec2_console#concepts-local-zones) in the *Amazon EC2 User Guide* and [ Amazon ECS clusters in Local Zones, Wavelength Zones, and AWS Outposts](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/cluster-regions-zones.html#clusters-local-zones) in the *Amazon Elastic Container Service Developer Guide*.
1. (Optional) For **Security groups**, choose a security group to attach to your instances. By default, the default security group for your VPC is chosen.
**Note**
Note: If you use either substitution variable (\$1Default or \$1Latest), they will apply the current default or latest version number at the time that this configuration is saved. If the default or latest version changes in the future, you must update the information - it won't automatically update.
1. Choose **Next page**.
1. For **Review**, review the configuration steps. If you need to make changes, choose **Edit**. When you're finished, choose **Create compute environment**.
# Tutorial: Create an unmanaged compute environment using Amazon EC2 resources
Complete the following steps to create an unmanaged compute environment using Amazon Elastic Compute Cloud (Amazon EC2) resources.
****
1. Open the AWS Batch console at [https://console.aws.amazon.com/batch/](https://console.aws.amazon.com/batch/).
1. From the navigation bar, select the AWS Region to use.
1. On the **Compute Environments** page, choose **Create**.
1. Configure the environment.
1. For **Compute environment configuration**, choose **Amazon Elastic Compute Cloud (Amazon EC2)**.
1. For **Orchestration type**, choose **Unmanaged**.
1. For **Name**, specify a unique name for your compute environment. The name can be up to 128 characters in length. It can contain uppercase and lowercase letters, numbers, hyphens (-), and underscores (\$1).
1. For **Service role**, choose a role that lets the AWS Batch service make calls to the required AWS API operations on your behalf.
**Note**
You can't use `AWSServiceRoleForBatch` for unmanaged compute environments.
1. For **Maximum vCPUs**, choose the maximum number of vCPUs that your compute environment can scale out to, regardless of job queue demand.
1. (Optional) Expand **Tags**. To add a tag, choose **Add tag**. Then, enter a **Key** name and optional **Value**. Choose **Add tag**. For more information, see [Tag your AWS Batch resources](using-tags.md).
1. Choose **Next page**.
1. For **Review**, review the configuration steps. If you need to make changes, choose **Edit**. When you're finished, choose **Create compute environment**.
# Tutorial: Create a managed compute environment using Amazon EKS resources
Complete the following steps to create a managed compute environment using Amazon Elastic Kubernetes Service (Amazon EKS) resources.
1. Open the AWS Batch console at [https://console.aws.amazon.com/batch/](https://console.aws.amazon.com/batch/).
1. From the navigation bar, select the AWS Region to use.
1. In the navigation pane, choose **Compute environments**.
1. Choose **Create**.
1. For **Compute environment configuration**, choose **Amazon Elastic Kubernetes Service (Amazon EKS)**.
1. For **Name**, specify a unique name for your compute environment. The name can be up to 128 characters in length. It can contain uppercase and lowercase letters, numbers, hyphens (-), and underscores (\$1).
1. For **Instance role**, choose an existing instance profile that has the required IAM permissions attached.
**Note**
To create a compute environment in the AWS Batch console, choose an instance profile that has the `eks:ListClusters` and `eks:DescribeCluster` permissions.
1. For **EKS cluster**, choose an existing Amazon EKS cluster.
1. For **Namespace**, enter a Kubernetes namespace to group your AWS Batch processes in the cluster.
1. (Optional) Expand **Tags**. Choose **Add tag** and then enter a key-value pair.
1. Choose **Next page**.
1. (Optional) For **Use EC2 Spot Instances**, turn on **Enable using Spot instances** to use Amazon EC2 Spot Instances.
1. (Spot only) For **Maximum % on-demand price**, choose 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 price is 20%, then the Spot price must be less than 20% of the current On-Demand price for that 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.
1. (Spot only) For **Spot fleet role**, choose the Amazon EC2 Spot fleet IAM role for the `SPOT` compute environment.
**Important**
This role is required if the allocation strategy is set to `BEST_FIT` or not specified.
1. (Optional) For **Minimum vCPUs**, choose the minimum number of vCPUs that your compute environment maintains, regardless of job queue demand.
1. (Optional) For **Maximum vCPUs**, choose the maximum number of vCPUs that your compute environment can scale out to, regardless of job queue demand.
1. (Optional) For **Scale down delay (minutes)**, choose the minimum time (in minutes) that AWS Batch keeps instances running in the compute environment after their jobs complete.
1. For **Allowed instance types**, choose the Amazon EC2 instance types that can be launched. You can specify instance families to launch any instance type within those families (for example, `c5`, `c5n`, or `p3`). Or, you can specify specific sizes within a family (such as `c5.8xlarge`). Metal instance types aren't in the instance families. For example, `c5` doesn't include `c5.metal`.
AWS Batch can select the instance type for you if you choose one of the following:
+ `optimal` to select instance types (from the `c4`, `m4`, `r4`, `c5`, `m5`, and `r5` instance families) that match the demand of your job queues.
+ `default_x86_64` to choose x86 based instance types (from the m6i, c6i, r6i, and c7i instance families) that matches the resource demands of the job queue.
+ `default_arm64` to choose x86 based instance types (from the m6g, c6g, r6g, and c7g instance families) that matches the resource demands of the job queue.
**Note**
Starting on 11/01/2025 the behavior of `optimal` is going to be changed to match `default_x86_64`. During the change your instance families could be updated to a newer generation. You do not need to perform any actions for the upgrade to happen. For more information about change, see [Optimal instance type configuration to receive automatic instance family updates](optimal-default-instance-troubleshooting.md).
**Note**
Instance family availability varies by AWS Region. For example, some AWS Regions may not have any fourth generation instance families but have fifth and sixth generation instance families.
When using `default_x86_64` or `default_arm64` instance bundles, AWS Batch selects instance families based on a balance of cost-effectiveness and performance. While newer generation instances often provide better price-performance, AWS Batch may choose an earlier generation instance family if it provides the optimal combination of availability, cost, and performance for your workload. For example, in an AWS Region where both c6i and c7i instances are available, AWS Batch might select c6i instances if they offer better cost-effectiveness for your specific job requirements. For more information on AWS Batch instance types and AWS Region availability, see [Instance type compute table](instance-type-compute-table.md).
AWS Batch periodically updates your instances in default bundles to newer, more cost-effective options. Updates happen automatically without requiring any action from you. Your workloads continue running during updates with no interruption
**Note**
When 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.
**Note**
AWS Batch will scale GPUs based on the required amount in your job queues. To use GPU scheduling, the compute environment must include instance types from the `p3`, `p4`, `p5`, `p6`, `g3`, `g3s`, `g4`, `g5`, or `g6` families.
1. (Optional) Expand **Additional configuration**.
1. (Optional) For **Placement group**, enter a placement group name to group resources in the compute environment.
1. For **Allocation strategy**, choose **BEST\$1FIT\$1PROGRESSIVE**.
1. (Optional) For **Amazon Machine Images (AMIs) Configuration**, choose **Add amazon machine images (amis) configuration**.
You can use either an Amazon EKS-optimized Amazon Linux AMI or a custom AMI.
1. To use an [Amazon EKS-optimized Amazon Linux AMI](https://docs.aws.amazon.com/eks/latest/userguide/eks-optimized-ami.html):
1. For **Image type** choose one of the following:
+ [Amazon Linux 2](https://docs.aws.amazon.com/eks/latest/userguide/eks-optimized-ami.html): Default for all AWS Graviton-based instance families (for example, `C6g`, `M6g`, `R6g`, and `T4g`) and can be used for all non-GPU instance types.
+ [Amazon Linux 2 (accelerated)](https://docs.aws.amazon.com/eks/latest/userguide/eks-optimized-ami.html): Default for all GPU instance families (for example, `P4` and `G4`) and can be used for all non AWS Graviton-based instance types.
+ [Amazon Linux 2023](https://docs.aws.amazon.com/eks/latest/userguide/eks-optimized-ami.html): AWS Batch supports Amazon Linux 2023 (AL2023).
+ [Amazon Linux 2023 (accelerated)](https://docs.aws.amazon.com/eks/latest/userguide/eks-optimized-ami.html): GPU instance families and can be used for all non AWS Graviton-based instance types.
1. For **Kubernetes version** enter in a [Kubernetes version number](supported_kubernetes_version.md).
1. To use a custom AMI:
1. For **Image type** choose the AMI type that the custom AMI is based off of:
+ [Amazon Linux 2](https://docs.aws.amazon.com/eks/latest/userguide/eks-optimized-ami.html): Default for all AWS Graviton-based instance families (for example, `C6g`, `M6g`, `R6g`, and `T4g`) and can be used for all non-GPU instance types.
+ [Amazon Linux 2 (accelerated)](https://docs.aws.amazon.com/eks/latest/userguide/eks-optimized-ami.html): Default for all GPU instance families (for example, `P4` and `G4`) and can be used for all non AWS Graviton-based instance types.
+ [Amazon Linux 2023](https://docs.aws.amazon.com/eks/latest/userguide/eks-optimized-ami.html): AWS Batch supports AL2023.
+ [Amazon Linux 2023 (accelerated)](https://docs.aws.amazon.com/eks/latest/userguide/eks-optimized-ami.html): GPU instance families and can be used for all non AWS Graviton-based instance types.
1. For **Image ID override** enter the custom AMI ID.
1. For **Kubernetes version** enter in a [Kubernetes version number](supported_kubernetes_version.md).
1. (Optional) For **Launch template**, choose an existing [launch template](eks-launch-templates.md).
1. (Optional) For **Launch template version**, enter **\$1Default**, **\$1Latest**, or a version number.
1. (Optional) For **Override launch template**, to add an override choose **Add override Launch template**:
1. (Optional) For **Launch template** choose the launch template to add the override to.
1. (Optional) For **Launch template version** choose the version number of the launch template, `$Default`, or `$Latest`.
1. (Optional) For **Target instances types** choose the instance type or family that this override should be applied to. This can target only instance types and families that are included in **Allowed instance types**.
1. (Optional) For **userdataType** choose the EKS node initialization. Only use this field if you have an AMI specified in either the Launch Template or as a Launch Template Override. Choose **EKS\$1NODEADM** for custom AMIs based on `EKS_AL2023` or `EKS_AL2023_NVIDIA` or **EKS\$1BOOSTRAP\$1SH** for `EKS_AL2` and `EKS_AL_NVIDIA`. The default value is **EKS\$1BOOSTRAP\$1SH**.
You would use **userdataType** when you have a [mixed environment](mixed-ami-environments.md) where you're using both AL2 and AL2023-based custom AMIs in the same compute environment.
1. Choose **Next page**.
1. For **Virtual Private Cloud (VPC) ID**, choose a VPC where to launch the instances.
1. For **Subnets**, choose the subnets to use. By default, all subnets within the selected VPC are available.
**Note**
AWS Batch on Amazon EKS supports Local Zones. For more information, see [Amazon EKS and AWS Local Zones](https://docs.aws.amazon.com/eks/latest/userguide/local-zones.html) in the *Amazon EKS User Guide*.
1. (Optional) For **Security groups**, choose a security group to attach to your instances. By default, the default security group for your VPC is selected.
1. Choose **Next page**.
1. For **Review**, review the configuration steps. If you need to make changes, choose **Edit**. When you're finished, choose **Create compute environment**.
# Tutorial: Create an unmanaged compute environment using Amazon EKS resources
Complete the following steps to create an unmanaged compute environment using Amazon Elastic Kubernetes Service (Amazon EKS) resources.
1. Open the AWS Batch console at [https://console.aws.amazon.com/batch/](https://console.aws.amazon.com/batch/).
1. From the navigation bar on top of the page, select the AWS Region to use.
1. In the navigation pane, choose **Compute environments**.
1. Choose **Create**.
1. Configure the environment.
1. For **Compute environment configuration**, choose **Amazon Elastic Kubernetes Service (Amazon EKS)**.
1. For **Orchestration type**, choose **Unmanaged**.
1. For **Name**, specify a unique name for your compute environment. The name can be up to 128 characters in length. It can contain uppercase and lowercase letters, numbers, hyphens (-), and underscores (\$1).
1. For **EKS cluster**, choose an existing Amazon EKS cluster. To create a new EKS cluster, follow the steps on [Create an Amazon EKS cluster page](https://docs.aws.amazon.com/eks/latest/userguide/create-cluster.html).
1. For **Namespace**, enter a Kubernetes namespace to group your AWS Batch processes in the cluster.
1. (Optional) For **Maximum vCPUs**, specify the maximum number of vCPUs available for job scheduling from your provisioned capacity.
1. (Optional) Expand **Tags**. Choose **Add tag** and then enter a key-value pair.
1. Choose **Next page**.
1. For **Review**, review the configuration steps. If you need to make changes, choose **Edit**. When you're finished, choose **Create compute environment**.
**Assigning Amazon EKS cluster nodes to unmanaged compute environment**
After creating the unmanaged compute environment, you need to label your Amazon EKS nodes with the compute environment UUID.
First, get the compute environment UUID from the `DescribeComputeEnvironments` API result:
```
$ aws batch describe-compute-environments \
--compute-environments unmanagedEksCE \
--query "computeEnvironments[].{name: computeEnvironmentName, uuid: uuid}"
```
Get the node information:
```
kubectl get nodes -o name
```
Label the nodes with the AWS Batch compute environment UUID:
```
kubectl label batch.amazonaws.com/compute-environment-uuid=uuid
```
# Resource: Compute environment template
The following example shows an empty compute environment template. You can use this template to create your compute environment that can then be saved to a file and used with the AWS CLI `--cli-input-json` option. For more information about these parameters, see [CreateComputeEnvironment](https://docs.aws.amazon.com/batch/latest/APIReference/API_CreateComputeEnvironment.html) in the *AWS Batch API Reference*.
**Note**
You can generate a compute environment template with the following AWS CLI command.
```
$ aws batch create-compute-environment --generate-cli-skeleton
```
```
{
"computeEnvironmentName": "",
"type": "UNMANAGED",
"state": "DISABLED",
"unmanagedvCpus": 0,
"computeResources": {
"type": "EC2",
"allocationStrategy": "BEST_FIT_PROGRESSIVE",
"minvCpus": 0,
"maxvCpus": 0,
"desiredvCpus": 0,
"instanceTypes": [
""
],
"imageId": "",
"subnets": [
""
],
"securityGroupIds": [
""
],
"ec2KeyPair": "",
"instanceRole": "",
"tags": {
"KeyName": ""
},
"placementGroup": "",
"bidPercentage": 0,
"spotIamFleetRole": "",
"launchTemplate": {
"launchTemplateId": "",
"launchTemplateName": "",
"version": ""
},
"ec2Configuration": [
{
"imageType": "",
"imageIdOverride": "",
"imageKubernetesVersion": ""
}
]
},
"serviceRole": "",
"tags": {
"KeyName": ""
},
"eksConfiguration": {
"eksClusterArn": "",
"kubernetesNamespace": ""
}
}
```
# Instance type compute table
The following table lists the AWS Region, instance family keyword, and available instance families. AWS Batch will try to allocate an instance from the latest family but because instance family availability varies by AWS Region you may get an earlier instance family generation.
**default\$1x86\$164**
| Region | Instance families |
| --- | --- |
| All AWS Regions that support [AWS Batch](https://docs.aws.amazon.com/general/latest/gr/batch.html) | m6i, c6i, r6i c7i |
**default\$1arm64**
| Region | Instance families |
| --- | --- |
| All AWS Regions that support [AWS Batch](https://docs.aws.amazon.com/general/latest/gr/batch.html) | m6g, c6g, r6g c7g |
**Optimal**
| Region | Instance families |
| --- | --- |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/batch/latest/userguide/instance-type-compute-table.html) | m4, c4, r4 |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/batch/latest/userguide/instance-type-compute-table.html) | m5, c5, r5 |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/batch/latest/userguide/instance-type-compute-table.html) | m6, c6, r6 |
# Update a compute environment in AWS Batch
AWS Batch provides multiple strategies for updating compute environments, each designed for specific update scenarios and requirements. These approaches use the same underlying update API but represent different prescriptive methods for managing updates effectively. You can manage these updates using the AWS Batch console or the AWS CLI. Understanding these strategies helps you choose the most appropriate method for your needs while minimizing disruption to your workloads.
This topic provides an overview of the available update strategies and guidance on when to use each approach. For detailed procedures, see the individual sections for each update strategy.
**Important**
AWS Batch creates and manages multiple AWS resources on your behalf and within your account, including Amazon EC2 Launch Templates, Amazon EC2 Auto Scaling Groups, Amazon EC2 Spot Fleets, and Amazon ECS Clusters. These managed resources are configured specifically to ensure optimal AWS Batch operation. Manually modifying these AWS Batch-managed resources, unless explicitly stated in AWS Batch documentation, can result in unexpected behavior, including `INVALID` compute environments, suboptimal instance scaling behavior, delayed workload processing, or unexpected costs. These manual modifications can't be deterministically supported by the AWS Batch service. Always use the supported AWS Batch APIs or the AWS Batch console to manage your compute environments.
Unsupported manual modifications include running your own Amazon ECS tasks or services on AWS Batch-managed Amazon ECS clusters, or starting additional processes, daemons, or services directly on AWS Batch-managed instances. AWS Batch assumes full control of the compute resources in a managed compute environment and can terminate instances, stop tasks, or scale the cluster at any time. Any workloads you run outside of AWS Batch job submissions on these managed resources can be interrupted without warning. Running non-AWS Batch workloads on AWS Batch-managed clusters and instances can also interfere with AWS Batch job scheduling and instance scaling.
**Topics**
+ [Compute environment update strategies](#update-strategies)
+ [Choosing the right update strategy](#choosing-update-strategies)
+ [AMI update considerations](#ami-update-considerations)
+ [Perform scaling updates](scaling-updates.md)
+ [Perform infrastructure updates](infrastructure-updates.md)
+ [Perform blue/green updates for compute environments](blue-green-updates.md)
## Compute environment update strategies
When you use scaling or infrastructure updates your compute environment is updated in place. For the blue/green update strategy you are creating a new compute environment (green) and then migrating your workload from the old compute environment (blue) to the new compute environment (green).
AWS Batch provides three different strategies for compute environment updates:
Scaling updates
Scaling updates adjust the capacity of your compute environment by adding or removing instances without replacing existing instances. This is the fastest update scenario and requires no downtime. Use scaling updates when you need to change capacity settings (vCPUs). These updates typically complete within minutes.
Fargate updates are performed using the same procedures as scaling updates. For more information, see [Perform scaling updates](scaling-updates.md).
Infrastructure updates
Infrastructure updates replace instances in your compute environment with new instances that have updated settings. These updates require specific service role and allocation strategy configurations but provide minimal downtime, with running jobs potentially interrupted. Use infrastructure updates when you need to modify instance types, AMI configuration, networking settings, service role, environment state, or other infrastructure components. These updates typically complete in 10-30 minutes depending on job completion.
For more information, see [Perform infrastructure updates](infrastructure-updates.md).
Blue/green updates
Blue/green updates create a new compute environment alongside your existing environment, allowing gradual workload transition with zero downtime. This approach provides the safest update path but requires running two environments temporarily. Use blue/green updates when you need zero downtime, want to test changes before full deployment, require quick rollback capability, or are using unsupported configurations for infrastructure updates. The time to complete is variable and controlled by you.
For more information, see [Perform blue/green updates for compute environments](blue-green-updates.md).
## Choosing the right update strategy
Use this decision guide to select the most appropriate update strategy for your needs:
### Choose scaling updates when
Choose the scaling update strategy when you only need to adjust compute capacity (vCPUs). Scaling updates are ideal when you need quick updates with no downtime and no infrastructure configuration changes are needed.
For detailed procedures, see [Perform scaling updates](scaling-updates.md).
### Choose infrastructure updates when
Choose the infrastructure update strategy when you need to modify instance types, AMI settings, service role, environment state, or networking configuration. Your environment must use the *AWSServiceRoleForBatch* service-linked role and an allocation strategy of `BEST_FIT_PROGRESSIVE`, `SPOT_CAPACITY_OPTIMIZED`, or `SPOT_PRICE_CAPACITY_OPTIMIZED`. Infrastructure updates work well when some job interruption is acceptable during the update and you want automatic updates to the latest Amazon ECS-optimized AMI.
For detailed procedures, see [Perform infrastructure updates](infrastructure-updates.md).
### Choose blue/green updates when
Choose the blue/green update strategy when zero downtime is required for your workloads or you need to test changes before transitioning production workloads. This approach is essential when quick rollback capability is important, your environment uses `BEST_FIT` allocation strategy, or your environment doesn't use the *AWSServiceRoleForBatch* service-linked role. Blue/green updates are also the best choice when you're using custom AMIs that require manual updates or need to make major configuration changes.
For detailed procedures, see [Perform blue/green updates for compute environments](blue-green-updates.md).
## AMI update considerations
The approach for updating AMIs depends on your compute environment configuration.
### Updating the AWS Batch provided default AMI to latest
AWS Batch can update to the latest Amazon ECS-optimized AMI during [infrastructure](infrastructure-updates.md) updates when all of these conditions are met:
**Note**
After the infrastructure update has completed `updateToLatestImageVersion` is set to `false`. To initiate another update `updateToLatestImageVersion` has to be set to `true`.
+ The compute environment uses the *AWSServiceRoleForBatch* service-linked role.
+ The allocation strategy is set to `BEST_FIT_PROGRESSIVE`, `SPOT_CAPACITY_OPTIMIZED`, or `SPOT_PRICE_CAPACITY_OPTIMIZED`.
+ No AMI ID is explicitly specified in `imageId`, `imageIdOverride`, or launch template.
+ The `updateToLatestImageVersion` is set to `true`.
### AMI updates using blue/green deployment
You must use blue/green deployment to update AMIs in these scenarios:
+ When using a specific version of the Amazon ECS-optimized AMI.
+ When the AMI ID is specified in any of:
+ Launch template (must update the template or remove it).
+ The `imageId` parameter.
+ The `imageIdOverride` parameter in EC2 configuration.
+ When using the `BEST_FIT` allocation strategy (doesn't support infrastructure updates).
+ When not using the *AWSServiceRoleForBatch* [service-linked role](using-service-linked-roles-batch-general.md).
### AMI updates for a custom AMI
If you specify a custom AMI in the compute environment's launch template, the `imageId` parameter or the `imageIdOverride` parameter in EC2 configuration, AWS Batch will not automatically update your custom AMI during infrastructure updates. You can update a custom AMI id by specifying the new id in the parameter originally used during Compute Environment creation. If you wish to switch to using an AWS Batch-provided AMI, you can do so by removing the custom AMI ID in your compute environment update.
# Perform scaling updates
Scaling updates adjust the capacity of your compute environment by adding or removing instances. This is the fastest update strategy and doesn't require replacing existing instances. Scaling updates work with any service role type and allocation strategy, making them the most flexible update option.
## Changes that trigger a scaling update
When you modify only the following settings, AWS Batch performs a scaling update. If you modify any of these settings along with other compute environment settings, AWS Batch performs an [infrastructure update](infrastructure-updates.md) instead.
The following settings trigger scaling updates when modified exclusively:
+ `desiredvCpus` – Sets the target number of vCPUs for the environment.
+ `maxvCpus` – Defines the maximum number of vCPUs that can be launched.
+ `minvCpus` – Specifies the minimum number of vCPUs to maintain.
+ `minScaleDownDelayMinutes` – Specifies minimum time (in minutes) that AWS Batch keeps instances running in the compute environment after their jobs complete.
**Note**
`minScaleDownDelayMinutes` does not apply to instances being replaced during infrastructure updates.
For Fargate compute environments, you can also modify these settings for scaling updates:
+ `securityGroupIds` – Security group IDs for the compute environment.
+ `subnets` – Subnets for the compute environment.
**Note**
We recommend not using `desiredvCpus` to initiate a scaling update as AWS Batch will dynamically adjust `desiredvCpus`. Instead you should update `minvCpus`.
When updating `desiredvCpus`, the value must be between `minvCpus` and `maxvCpus`. The new value must be greater than or equal to the current `desiredvCpus`. For more information, see [Error message when you update the `desiredvCpus` setting](error-desired-vcpus-update.md).
**Important**
If you modify any of these scaling settings together with other compute environment settings (such as instance types, AMI IDs, or launch templates), AWS Batch performs an infrastructure update instead of a scaling update. Infrastructure updates take longer and may replace existing instances.
------
#### [ Performing scaling updates using the AWS Management Console ]
1. Open the AWS Batch console at [https://console.aws.amazon.com/batch/](https://console.aws.amazon.com/batch/).
1. In the navigation pane, choose **Environments** and then the **Compute environments** tab.
1. Select the compute environment to update.
1. Choose **Actions** and then **Edit**.
1. Modify one or more of the [settings that support scaling updates](#scaling-updates-triggers). For example:
+ For **Minimum vCPUs**, enter the minimum number of vCPUs.
+ For **Desired vCPUs**, enter the desired number of vCPUs.
+ For **Maximum vCPUs**, enter the maximum number of vCPUs.
1. Choose **Save changes**.
1. Monitor the compute environment status. The update should complete quickly since it only involves scaling operations.
------
#### [ Performing scaling updates using the AWS CLI ]
Use the **update-compute-environment** command to perform scaling updates. The following two examples demonstrate common scaling operations. You can modify one or more of the following [settings that support scaling updates](#scaling-updates-triggers)
+ This example updates the desired, minimum, and maximum vCPUs:
```
aws batch update-compute-environment \
--compute-environment your-compute-environment-name \
--compute-resources minvCpus=2,maxvCpus=8
```
------
## Monitoring scaling updates
Monitor your scaling updates using the AWS Batch console to view the compute environment status and check instance count and vCPU metrics. You can also use the AWS CLI with the **describe-compute-environments** command to check status and monitor instance counts and vCPU values.
# Perform infrastructure updates
Infrastructure updates replace the instances in your compute environment with new instances that have updated settings. This update strategy takes longer than scaling updates and requires specific service role and allocation strategy settings. Infrastructure updates provide a way to modify fundamental compute environment configurations while maintaining service availability.
**Important**
Infrastructure updates require the *AWSServiceRoleForBatch* service-linked role and an allocation strategy of `BEST_FIT_PROGRESSIVE`, `SPOT_CAPACITY_OPTIMIZED`, or `SPOT_PRICE_CAPACITY_OPTIMIZED`. If your environment doesn't meet these requirements, use blue/green updates instead.
## Changes that trigger infrastructure updates
When you modify any of the following settings, AWS Batch performs an infrastructure update. Infrastructure updates also occur when you modify these settings together with scaling update settings.
The following settings trigger infrastructure updates:
**Compute configuration**
+ `allocationStrategy` – Determines how AWS Batch selects instance types.
+ `instanceTypes` – Specifies which EC2 instance types to use.
+ `bidPercentage` – Maximum percentage of On-Demand price for Spot instances.
+ `type` – Compute environment type (`EC2` or `SPOT`).
**AMI and launch configuration**
+ `imageId` – Specific AMI to use for instances.
+ `ec2Configuration` – EC2 configuration including `imageIdOverride`.
+ `launchTemplate` – EC2 launch template settings.
+ `ec2KeyPair` – SSH key pair for instance access.
+ `updateToLatestImageVersion` – Automatic AMI updates setting.
**Networking and security**
+ `subnets` – VPC subnets where instances are launched (for EC2 compute environments).
+ `securityGroupIds` – Security groups for instances (for EC2 compute environments).
+ `placementGroup` – EC2 placement group configuration.
**Other settings**
+ `instanceRole` – IAM role for EC2 instances.
+ `tags` – Tags applied to EC2 instances.
**Important**
If you modify any infrastructure update settings together with scaling update settings (such as `desiredvCpus`, `maxvCpus`, or `minvCpus`), AWS Batch performs an infrastructure update. Infrastructure updates take longer than scaling updates.
## AMI selection during infrastructure updates
During an infrastructure update, the compute environment's AMI ID might change, depending on whether AMIs are specified in any of these three settings. AMIs are specified in the `imageId` (in `computeResources`), `imageIdOverride` (in `ec2Configuration`), or the launch template specified in `launchTemplate`. Suppose that no AMI IDs are specified in any of those settings and the `updateToLatestImageVersion` setting is `true`. Then, the latest Amazon ECS optimized AMI supported by AWS Batch is used for any infrastructure update.
If an AMI ID is specified in at least one of these settings, the update depends on which setting provided the AMI ID used before the update. When you create a compute environment, the priority for selecting an AMI ID is first the launch template, then the `imageId` setting, and finally the `imageIdOverride` setting. However, if the AMI ID that's used came from the launch template, updating either the `imageId` or `imageIdOverride` settings doesn't update the AMI ID. The only way to update an AMI ID selected from the launch template is to update the launch template. If the version parameter of the launch template is `$Default` or `$Latest`, the default or latest version of the specified launch template is evaluated. If a different AMI ID is selected by the default or the latest version of the launch template is selected, that AMI ID is used in the update.
If the launch template was not used to select the AMI ID, the AMI ID that's specified in the `imageId` or `imageIdOverride` parameters is used. If both are specified, the AMI ID specified in the `imageIdOverride` parameter is used.
Suppose that the compute environment uses an AMI ID specified by the `imageId`, `imageIdOverride`, or `launchTemplate` parameters, and you want to use the latest Amazon ECS optimized AMI supported by AWS Batch. Then, the update must remove the settings that provided AMI IDs. For `imageId`, this requires specifying an empty string for that parameter. For `imageIdOverride`, this requires specifying an empty string for the `ec2Configuration` parameter.
If the AMI ID came from the launch template, you can change to the latest Amazon ECS optimized AMI that's supported by AWS Batch by either one of the following ways:
+ Remove the launch template by specifying an empty string for the `launchTemplateId` or `launchTemplateName` parameter. This removes the entire launch template, rather than the AMI ID alone.
+ If the updated version of the launch template doesn't specify an AMI ID, the `updateToLatestImageVersion` parameter must be set to `true`.
## Job handling during updates
Configure how running jobs are handled during an infrastructure update using the update policy. When you set `terminateJobsOnUpdate=true`, running jobs are terminated immediately, the `jobExecutionTimeoutMinutes` setting is ignored, and the update proceeds as soon as instances can be replaced. When you set `terminateJobsOnUpdate=false`, running jobs continue for the specified timeout period with a default timeout of 30 minutes, and jobs are terminated if they exceed the timeout.
**Note**
To retry jobs that are terminated during an update, configure a job retry strategy. For more information, see [Automated job retries](job_retries.md).
------
#### [ Performing infrastructure updates using the AWS Management Console ]
**Note**
To just update to the latest AMI version in the console, see [Updating AMI versions](managing-ami-versions.md#updating-ami-versions).
1. Open the AWS Batch console at [https://console.aws.amazon.com/batch/](https://console.aws.amazon.com/batch/).
1. In the navigation pane, choose **Environments** then the **Compute environments** tab.
1. Select the compute environment to update.
1. Choose **Actions** and then **Edit**.
1. In the **Update behavior** section, configure how running jobs are handled:
+ Choose **Update AMI to latest version** to update the AMI to the latest version.
+ Choose **Terminate jobs immediately on update** to terminate jobs when the update process is run.
+ For **Job execution timeout** enter the number of minutes to wait before starting the update process.
1. Modify one or more of the [settings that require an infrastructure updates](#infrastructure-updates-triggers). For example:
+ **Instance role**
+ **Use EC2 Spot instances**
+ **Allowed instance types**
+ **Placement group**
+ **EC2 key pair**
+ **EC2 configuration**
+ **Launch templates**
+ **Subnets**
+ **Security groups**
1. Choose **Save changes**.
1. Monitor the compute environment status. The environment will show `UPDATING` during the update process.
------
#### [ Performing infrastructure updates using the AWS CLI ]
Use the **update-compute-environment** command with an change to one or more of the [settings that require an infrastructure updates](#infrastructure-updates-triggers). The following three examples are common infrastructure operations.
+ This example updates the instance types and configures the update policy:
```
aws batch update-compute-environment \
--compute-environment your-compute-environment-name \
--compute-resources instanceTypes=default_x86_64 \
--update-policy terminateJobsOnUpdate=false,jobExecutionTimeoutMinutes=30
```
+ This example updates the VPC subnets and security groups:
```
aws batch update-compute-environment \
--compute-environment your-compute-environment-name \
--compute-resources subnets=subnet-abcd1234,subnet-efgh5678 securityGroupIds=sg-abcd1234 \
--update-policy terminateJobsOnUpdate=true
```
+ This example enables automatic updates to the latest Amazon ECS optimized AMI:
```
aws batch update-compute-environment \
--compute-environment your-compute-environment-name \
--compute-resources updateToLatestImageVersion=true \
--update-policy terminateJobsOnUpdate=false,jobExecutionTimeoutMinutes=60
```
------
## Monitoring infrastructure updates
Monitor your infrastructure updates using the AWS Batch console to watch the compute environment status change to `UPDATING`, monitor instance replacement progress, and check for any failed updates. The update is successful once the compute environment state is `VAILD`. You can also use CloudWatch to track instance termination events and monitor job states during the update. With the AWS CLI, use the **describe-compute-environments** command to check status and monitor instance lifecycle events.
# Perform blue/green updates for compute environments
A blue/green update is an update strategy that reduces downtime and risk by creating a new compute environment (green) alongside your existing compute environment (blue). This approach allows you to gradually transition workloads to the new environment while keeping the existing environment operational. Blue/green updates provide the safest update path and work with any service role type or allocation strategy.
## Overview
Blue/green updates offer several advantages that make them ideal for production environments. They provide *zero downtime* by keeping your workloads running continuously during the update process. The approach enables *easy rollback* capabilities, allowing you to quickly revert to the original environment if issues arise. You can implement a *gradual transition* strategy, verifying the new environment's performance before fully switching over your production workloads. This method also provides excellent *risk mitigation* since the original environment remains unchanged and operational until you choose to remove it.
### When blue/green updates are required
You must use blue/green updates in the following situations:
+ When your compute environment uses `BEST_FIT` allocation strategy (doesn't support infrastructure updates).
+ When your compute environment doesn't use the *AWSServiceRoleForBatch* service-linked role.
+ When you need to transition between different service role types.
### When blue/green updates are recommended
We recommend blue/green updates for production environments where zero downtime is critical for your workloads. This approach works well when you need to test new configurations before transitioning production workloads, ensuring that changes meet your performance and reliability requirements. Choose blue/green updates when quick rollback capability is important for your operations, especially if you're updating custom AMIs with significant changes. This method is also ideal when you want to validate performance characteristics and behavior before fully committing to changes, providing confidence in your update process.
### Prerequisites
Before performing a blue/green update, ensure you have:
+ Appropriate [IAM permissions](IAM_policies.md) to create and manage compute environments.
+ Access to view and modify job queue settings.
+ Job retry strategies configured for your job definitions to handle potential failures during the transition. For more information, see [Automated job retries](job_retries.md).
+ The AMI ID for the new compute environment. This can be either:
+ A recent, approved version of the Amazon ECS optimized AMI (used by default).
+ A custom AMI that meets the Amazon ECS container instance AMI specification. When using a custom AMI, you can specify it in one of these ways:
+ Using the **Image ID override** field in the EC2 configuration.
+ Specifying it in a launch template.
For more information about creating custom AMIs, see [Tutorial: Create a compute resource AMI](create-batch-ami.md).
Before creating the new environment, you need to record the configuration of your existing compute environment. You can do this using either the AWS Management Console or the AWS CLI.
**Note**
The following procedures detail how to perform a blue/green update that only changes the AMI. You can update other settings for the new environment.
**Important**
When you remove the old (blue) compute environment, any currently running jobs on those instances will fail because the instances will be terminated. Configure job retry strategies in your job definitions to handle these failures automatically. For more information, see [Automated job retries](job_retries.md).
Once you're confident in the new environment:
Edit the job queue to remove the old compute environment.
Wait for any running jobs in the old environment to complete.
Delete the old compute environment.
------
#### [ Performing blue/green updates using the AWS Management Console ]
1. Clone your current compute environment
1. Open the AWS Batch console at [https://console.aws.amazon.com/batch/](https://console.aws.amazon.com/batch/).
1. Select your existing compute environment.
1. Choose **Actions** and then **Clone**.
1. For **Name**, enter a unique name for your new compute environment.
1. Choose **Next**.
1. In the **Instance configuration** section, update the AMI settings:
1. Expand **Additional configuration**.
1. For **EC2 configuration**, specify the new AMI type in **Image type** and AMI ID in the **Image ID override** field.
1. Choose **Next**.
1. For **Network configuration** choose **Next**.
1. Review the other settings which are automatically copied from your existing environment.
1. Choose **Create compute environment**.
1. Wait for the new compute environment status to become `VALID`.
1. Change the job queue order
1. In the navigation pane, choose **Job queues**.
1. Select the job queue associated with your existing compute environment.
1. Choose **Edit**.
1. Under **Connected Compute environment**, add the new compute environment:
+ Add the new compute environment with a higher order number than the existing environment to transition the workload.
+ Once you verify the new environment is working correctly, you can make it the primary environment by giving it a lower order number.
1. Choose **Update job queue**.
1. Clean up
1. Monitor job execution in the new environment to ensure everything is working as expected.
1. Once you're confident in the new environment:
1. Edit the job queue to remove the old compute environment.
1. Wait for any running jobs in the old environment to complete.
1. Delete the old compute environment.
------
#### [ Performing blue/green updates using the AWS CLI ]
1. To get the configuration using the AWS CLI, use the following command:
```
aws batch describe-compute-environments \
--compute-environments your-compute-environment-name
```
Save the output for reference when creating the new environment.
1. Create a new compute environment using the configuration from your existing environment, but with the new AMI. Here's an example command structure:
Replace the example values with your actual configuration from the previous step:
```
cat < ./blue-green-compute-environment.json
{
"computeEnvironmentName": "your-new-compute-environment-name",
"type": "MANAGED",
"state": "ENABLED",
"computeResources": {
"instanceRole": "arn:aws:iam::012345678901:instance-profile/ecsInstanceRole",
"type": "EC2",
"minvCpus": 2,
"desiredvCpus": 2,
"maxvCpus": 256,
"instanceTypes": [
"optimal"
],
"allocationStrategy": "BEST_FIT_PROGRESSIVE",
"ec2Configuration": [
{
"imageType": "ECS_AL2023",
"imageIdOverride": "ami-0abcdef1234567890"
}
],
"subnets": [,
"subnet-0abcdef1234567890"
],
"securityGroupIds": [
"sg-0abcdef1234567890"
]
}
}
EOF
```
```
$ aws batch create-compute-environment --cli-input-json file://./blue-green-compute-environment.json
```
1. Wait for the new environment to become available:
```
aws batch describe-compute-environments \
--compute-environments your-new-compute-environment-name \
--query 'computeEnvironments[].status'
```
1. Add the new compute environment to your job queue:
```
aws batch update-job-queue \
--job-queue your-job-queue \
--compute-environment-order order=1,computeEnvironment=your-existing-environment \
order=2,computeEnvironment=your-new-compute-environment-name
```
1. Once verified, update again to make the new environment primary:
```
aws batch update-job-queue \
--job-queue your-job-queue \
--compute-environment-order order=1,computeEnvironment=your-new-compute-environment-name
```
After all jobs complete in the old environment, disable and then delete it:
```
aws batch update-compute-environment \
--compute-environment your-existing-environment \
--state DISABLED
```
```
aws batch delete-compute-environment \
--compute-environment your-existing-environment
```
------
# Compute resource AMIs
By default, AWS Batch managed compute environments use a recent, approved version of the Amazon ECS optimized AMI for compute resources. However, you might want to create your own AMI to use for your managed and unmanaged compute environments. If you require any of the following, we recommend you create your own AMI:
+ Increasing the storage size of your AMI root or data volumes.
+ Adding instance storage volumes for supported Amazon EC2 instance types.
+ Customizing the Amazon ECS container agent.
+ Customizing Docker
+ Configuring a GPU workload AMI to allow containers to access GPU hardware on supported Amazon EC2 instance types
**Note**
After a compute environment is created, AWS Batch doesn't upgrade the AMIs in the compute environment. AWS Batch also doesn't update the AMIs in your compute environment when a newer version of the Amazon ECS optimized AMI is available. You're responsible for the management of the guest operating system. This includes any updates and security patches. You're also responsible for any additional application software or utilities that you install on the compute resources. To use a new AMI for your AWS Batch jobs, do the following:
Create a new compute environment with the new AMI.
Add the compute environment to an existing job queue.
Remove the earlier compute environment from your job queue.
Delete the earlier compute environment.
In April 2022, AWS Batch added enhanced support for updating compute environments. For more information, see [Update a compute environment in AWS Batch](updating-compute-environments.md). To use the enhanced updating of compute environments to update AMIs, follow these rules:
Either don't set the service role ([https://docs.aws.amazon.com/batch/latest/APIReference/API_CreateComputeEnvironment.html#Batch-CreateComputeEnvironment-request-serviceRole](https://docs.aws.amazon.com/batch/latest/APIReference/API_CreateComputeEnvironment.html#Batch-CreateComputeEnvironment-request-serviceRole)) parameter or set it to the **AWSServiceRoleForBatch** service-linked role.
Set the allocation strategy ([https://docs.aws.amazon.com/batch/latest/APIReference/API_ComputeResource.html#Batch-Type-ComputeResource-allocationStrategy](https://docs.aws.amazon.com/batch/latest/APIReference/API_ComputeResource.html#Batch-Type-ComputeResource-allocationStrategy)) parameter to `BEST_FIT_PROGRESSIVE`, `SPOT_CAPACITY_OPTIMIZED`, or `SPOT_PRICE_CAPACITY_OPTIMIZED`.
Set the update to latest image version ([https://docs.aws.amazon.com/batch/latest/APIReference/API_ComputeResourceUpdate.html#Batch-Type-ComputeResourceUpdate-updateToLatestImageVersion](https://docs.aws.amazon.com/batch/latest/APIReference/API_ComputeResourceUpdate.html#Batch-Type-ComputeResourceUpdate-updateToLatestImageVersion)) parameter to `true`.
Don't specify an AMI ID in [https://docs.aws.amazon.com/batch/latest/APIReference/API_ComputeResourceUpdate.html#Batch-Type-ComputeResourceUpdate-imageId](https://docs.aws.amazon.com/batch/latest/APIReference/API_ComputeResourceUpdate.html#Batch-Type-ComputeResourceUpdate-imageId), [https://docs.aws.amazon.com/batch/latest/APIReference/API_Ec2Configuration.html#Batch-Type-Ec2Configuration-imageIdOverride](https://docs.aws.amazon.com/batch/latest/APIReference/API_Ec2Configuration.html#Batch-Type-Ec2Configuration-imageIdOverride) (in [https://docs.aws.amazon.com/batch/latest/APIReference/API_Ec2Configuration.html](https://docs.aws.amazon.com/batch/latest/APIReference/API_Ec2Configuration.html)), or in the launch template ([https://docs.aws.amazon.com/batch/latest/APIReference/API_ComputeResourceUpdate.html#Batch-Type-ComputeResourceUpdate-launchTemplate](https://docs.aws.amazon.com/batch/latest/APIReference/API_ComputeResourceUpdate.html#Batch-Type-ComputeResourceUpdate-launchTemplate)). When you don't specify an AMI ID, AWS Batch selects the latest Amazon ECS optimized AMI that AWS Batch supports at the time the infrastructure update is initiated. Alternatively, you can specify the AMI ID in the `imageId` or `imageIdOverride` parameters. Or, you can specify the launch template that's identified by the `LaunchTemplate` properties. Changing any of these properties starts an infrastructure update. If the AMI ID is specified in the launch template, the AMI ID can't be replaced by specifying an AMI ID in either the `imageId` or `imageIdOverride` parameters. The AMI ID can only be replaced by specifying a different launch template. If the launch template version is set to `$Default` or `$Latest`, the AMI ID can be replaced by setting either a new default version for the launch template (if `$Default`) or by adding a new version to the launch template (if `$Latest`).
If these rules are followed, any update that starts an infrastructure update causes the AMI ID to be re-selected. If the [https://docs.aws.amazon.com/batch/latest/APIReference/API_LaunchTemplateSpecification.html#Batch-Type-LaunchTemplateSpecification-version](https://docs.aws.amazon.com/batch/latest/APIReference/API_LaunchTemplateSpecification.html#Batch-Type-LaunchTemplateSpecification-version) setting in the launch template ([https://docs.aws.amazon.com/batch/latest/APIReference/API_ComputeResourceUpdate.html#Batch-Type-ComputeResourceUpdate-launchTemplate](https://docs.aws.amazon.com/batch/latest/APIReference/API_ComputeResourceUpdate.html#Batch-Type-ComputeResourceUpdate-launchTemplate)) is set to `$Latest` or `$Default`, the latest or default version of the launch template is evaluated up at the time of the infrastructure update, even if the [https://docs.aws.amazon.com/batch/latest/APIReference/API_ComputeResourceUpdate.html#Batch-Type-ComputeResourceUpdate-launchTemplate](https://docs.aws.amazon.com/batch/latest/APIReference/API_ComputeResourceUpdate.html#Batch-Type-ComputeResourceUpdate-launchTemplate) wasn't updated.
**Topics**
+ [Compute resource AMI specification](batch-ami-spec.md)
+ [AMI selection order](ami-selection-order.md)
+ [Managing AMI versions in compute environments](managing-ami-versions.md)
+ [Tutorial: Create a compute resource AMI](create-batch-ami.md)
+ [Use a GPU workload AMI](batch-gpu-ami.md)
+ [Amazon Linux deprecation](al1-ami-deprecation.md)
+ [Amazon EKS Amazon Linux 2 AMI deprecation](eks-al2-ami-deprecation.md)
+ [Amazon ECS Amazon Linux 2 AMI deprecation](ecs-al2-ami-deprecation.md)
# Compute resource AMI specification
The basic AWS Batch compute resource AMI specification consists of the following:
Required
+ A modern Linux distribution that's running at least version 3.10 of the Linux kernel on an HVM virtualization type AMI. Windows containers aren't supported.
**Important**
Multi-node parallel jobs can only run on compute resources that were launched on an Amazon Linux instance with the `ecs-init` package installed. We recommend that you use the default Amazon ECS optimized AMI when you create your compute environment. You can do this by not specifying a custom AMI. For more information, see [Multi-node parallel jobs](multi-node-parallel-jobs.md).
+ The Amazon ECS container agent. We recommend that you use the latest version. For more information, see [Installing the Amazon ECS Container Agent](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-agent-install.html) in the *Amazon Elastic Container Service Developer Guide*.
+ The `awslogs` log driver must be specified as an available log driver with the `ECS_AVAILABLE_LOGGING_DRIVERS` environment variable when the Amazon ECS container agent is started. For more information, see [Amazon ECS Container Agent Configuration](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-agent-config.html) in the *Amazon Elastic Container Service Developer Guide*.
+ A Docker daemon that's running at least version 1.9, and any Docker runtime dependencies. For more information, see [Check runtime dependencies](https://docs.docker.com/engine/installation/binaries/#check-runtime-dependencies) in the Docker documentation.
**Note**
We recommend the Docker version that ships with and is tested with the corresponding Amazon ECS agent version that you're using. Amazon ECS provides a changelog for the Linux variant of the Amazon ECS-optimized AMI on GitHub. For more information, see [Changelog](https://github.com/aws/amazon-ecs-ami/blob/main/CHANGELOG.md).
Recommended
+ An initialization and nanny process to run and monitor the Amazon ECS agent. The Amazon ECS optimized AMI uses the `ecs-init` upstart process, and other operating systems might use `systemd`. For more information and examples, see [Example container instance User Data Configuration Scripts](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/example_user_data_scripts.html) in the *Amazon Elastic Container Service Developer Guide*. For more information about `ecs-init`, see the [`ecs-init` project](https://github.com/aws/amazon-ecs-init) on GitHub. At a minimum, managed compute environments require the Amazon ECS agent to start at boot. If the Amazon ECS agent isn't running on your compute resource, then it can't accept jobs from AWS Batch.
The Amazon ECS optimized AMI is preconfigured with these requirements and recommendations. We recommend that you use the Amazon ECS optimized AMI or an Amazon Linux AMI with the `ecs-init` package that's installed for your compute resources. Choose another AMI if your application requires a specific operating system or a Docker version that's not yet available in those AMIs. For more information, see [Amazon ECS-Optimized AMI](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-optimized_AMI.html) in the *Amazon Elastic Container Service Developer Guide*.
# AMI selection order
AWS Batch determines the Amazon Machine Image (AMI) for compute resources using the following priority order. Understanding this order helps you understand why AWS Batch chose a particular AMI for your compute environment:
1. **Launch template override AMI** - If a launch template override for the launched instance has an image, then its image is used.
1. **Compute resources image ID (deprecated)** - If set, this compute environment AMI is used. *Note: Deprecated field; use ec2Configuration.imageIdOverride instead.*
1. **EC2 configuration image ID override** - If specified, the image in this field is used.
1. **Launch template AMI** - If the compute environment has an associated launch template with an image, then this image will be used.
1. **AWS default AMI** - If none of the above are configured, AWS Batch selects a default AMI based on the specified imageType in the ec2Configuration.
**Note**
The ec2Configuration parameter is optional. When omitted, AWS Batch automatically selects an appropriate ec2Configuration and default AMI based on the instance types launched in the compute environment.
**Note**
This AMI selection order does not apply to Fargate compute environments.
## AMI selection order from highest to lowest priority
1. **Launch template override AMI** (highest precedence)
**API field:** `overrides[].launchTemplateId` with target instance types
**Reference:** [LaunchTemplateSpecification](https://docs.aws.amazon.com/batch/latest/APIReference/API_LaunchTemplateSpecification.html)
Override templates target specific instance types and provide more granular control than the default launch template. They take precedence over all other AMI specifications for matching instance types.
```
{
"computeResources": {
"launchTemplate": {
"launchTemplateId": "lt-default",
"overrides": [
{
"launchTemplateId": "lt-gpu-optimized",
"targetInstanceTypes": ["p3.2xlarge", "g4dn.xlarge"]
}
]
}
}
}
```
1. **Compute resources image ID**
**API field:** `computeResources.imageId`
**Reference:** [CreateComputeEnvironment](https://docs.aws.amazon.com/batch/latest/APIReference/API_CreateComputeEnvironment.html)
You can specify an AMI directly at the compute environment level. This takes precedence over EC2 configuration overrides and launch templates (except override templates).
In a compute environment with multiple EC2 configurations (e.g. for `ECS_AL2023` and `ECS_AL2023_NVIDIA`), the AMI ID specified here is used for all EC2 configurations.
**Important**
The `imageId` field is deprecated. Please use `ec2Configuration.imageIdOverride` instead.
```
{
"computeResources": {
"imageId": "ami-12345678",
"instanceTypes": ["m5.large", "m5.xlarge"]
}
}
```
1. **EC2 configuration image ID override**
**API field:** `computeResources.ec2Configuration[].imageIdOverride`
**Reference:** [Ec2Configuration](https://docs.aws.amazon.com/batch/latest/APIReference/API_Ec2Configuration.html)
EC2 configuration provides image type-specific overrides. This setting overrides the default AMI selection and launch template AMI for the specified image type.
```
{
"computeResources": {
"ec2Configuration": [
{
"imageType": "ECS_AL2",
"imageIdOverride": "ami-87654321"
}
]
}
}
```
1. **Launch template AMI**
**API field:** `ImageId` in the Amazon EC2 launch template
**Reference:** [Use Amazon EC2 launch templates with AWS Batch](launch-templates.md)
When you specify an AMI in the launch template, it takes precedence over the default AMI selection but is overridden by higher precedence settings.
```
// EC2 Launch Template content
{
"LaunchTemplateName": "my-batch-template",
"LaunchTemplateData": {
"ImageId": "ami-12345678"
}
}
```
Referenced by the AWS Batch launch template:
```
// Batch Launch Template content
{
"computeResources": {
"launchTemplate": {
"launchTemplateName": "my-batch-template",
"version": "$Latest"
}
}
}
```
1. **AWS default AMI** (lowest precedence)
**API field:** Determined by `computeResources.ec2Configuration[].imageType`
**Reference:** [Ec2Configuration imageType](https://docs.aws.amazon.com/batch/latest/APIReference/API_Ec2Configuration.html)
When no custom AMI is specified, AWS Batch automatically selects the latest approved Amazon Amazon ECS-optimized AMI based on the image type.
**Note**
The `ec2Configuration` is optional. AWS Batch will select an appropriate default AMI if no `ec2Configuration` is specified.
```
{
"computeResources": {
"ec2Configuration": [
{
"imageType": "ECS_AL2023"
}
]
}
}
```
# Managing AMI versions in compute environments
AWS Batch provides visibility into the Amazon Machine Images (AMIs) that your compute environments use.
## Viewing AMI status
You can view the status of AMIs used in your compute environments through the AWS Batch console or by using [describe-compute-environments](https://docs.aws.amazon.com/cli/latest/reference/batch/describe-compute-environments.html) command.
------
#### [ Console ]
In the AWS Batch console, AMI status information appears in two locations with the following status values:
+ **Latest** – Using the most recent AMI supported by AWS Batch.
+ **Update available** – An update is available.
**Note**
AMI status information appears only for AWS Batch-managed AMIs. The status does not appear when images are specified in `imageId` (deprecated), `imageIdOverride`, or in the default launch template. The status does not appear when the compute environment has a launch template override. For more information on AMI selection, see [AMI selection order](ami-selection-order.md).
The compute environments page displays a **Batch image status** column that shows the overall `batchImageStatus` for each compute environment. If a compute environment has multiple AMIs and any one AMI has **Update available**, the console shows **Update available** for the entire compute environment.
**Note**
The status appears after the compute environment has started scaling for any **Image type**.
On the compute environment detail page, the **Ec2 configuration** section of the **Compute resources** tab shows the **Batch image status** for each **Image type** in the compute environment. If an **Image type** has multiple AMIs and any one AMI has **Update available**, the console shows **Update available** for that **Image type**.
**Note**
The status appears for each **Image type** only after the compute environment has begun scaling instances for that specific **Image type**.
------
#### [ CLI ]
When you call [describe-compute-environments](https://docs.aws.amazon.com/cli/latest/reference/batch/describe-compute-environments.html), the response includes the `batchImageStatus` field that provides AMI visibility with the following values:
+ `LATEST` – Using the most recent AMI supported by AWS Batch.
+ `UPDATE_AVAILABLE` – An update is available.
**Note**
The `batchImageStatus` field appears only for AWS Batch-managed AMIs. It does not appear when custom AMIs are specified in `imageId` (deprecated), `imageIdOverride`, or in the default launch template. The status does not appear when the compute environment has a launch template override. For more information about how AWS Batch selects AMIs, see [AMI selection order](ami-selection-order.md).
The field appears independently for each `Ec2Configuration` and only after the compute environment has begun scaling instances using that `imageType`.
```
{
"computeEnvironments": [
{
"computeEnvironmentName": "my-compute-environment",
"computeResources": {
"ec2Configuration": [
{
"imageType": "ECS_AL2023"
},
{
"imageType": "ECS_AL2023_NVIDIA",
"batchImageStatus": "UPDATE_AVAILABLE"
}
]
}
}
]
}
```
------
## Updating AMI versions
When AWS Batch indicates that an AMI update is available, you can update your compute environment to use the newer AMIs by updating the compute environment with **Update AMI to latest version** set to true.
You don't need to specify new AMI IDs – AWS Batch automatically selects the latest supported AMIs when you set **Update AMI to latest version**.
**Important**
Updating AMIs triggers an [infrastructure update](infrastructure-updates.md), not a scaling update. This means AWS Batch replaces existing instances with new instances that use the updated AMI. The update process takes longer than a scaling update and may interrupt running jobs depending on your update policy configuration.
**Important**
If your allocation strategy is `BEST_FIT` then you have to perform a [blue/green update](blue-green-updates.md).
------
#### [ Console ]
To update AMIs using the AWS Batch console:
1. Open the AWS Batch console at [https://console.aws.amazon.com/batch/](https://console.aws.amazon.com/batch/).
1. In the navigation pane, choose **Environments**.
1. Select the compute environment that shows an AMI status with an update.
1. Choose **Update now** (by the AMI status) or **Actions** > **Edit** to open the update modal.
1. In the AMI update modal, review the current AMI versions and their statuses.
1. Choose **Confirm** or **Save** to begin the infrastructure update.
The compute environment status changes to `UPDATING` during the infrastructure update. You can monitor the progress in the console.
------
#### [ CLI ]
To update AMIs using the AWS CLI, use the `update-compute-environment` command.
```
aws batch update-compute-environment \
--compute-environment my-compute-environment \
--compute-resources updateToLatestImageVersion=true
```
This command triggers an infrastructure update that replaces instances with new instances using the latest AWS Batch-supported AMIs.
------
## Custom AMI considerations
If your compute environment uses custom AMIs, i.e. AMIs specified in `ComputeResources.imageId` (deprecated), `Ec2Configuration.imageIdOverride`, the default launch template or the launch template overrides, AWS Batch cannot provide status information for these AMIs.
+ **Status visibility** – Custom AMIs show "**-**" for their **Batch image status** in the console and do not include the `batchImageStatus` field in API responses.
+ **Manual management** – You are responsible for maintaining and updating custom AMIs. Stay informed of security and software patches from your AMI provider and update your custom AMIs accordingly.
+ **EC2 management** – Use the Amazon EC2 console or APIs to manage custom AMI lifecycle, including creating new versions and deprecating old ones.
For more information about managing custom AMIs, see [Compute resource AMIs](compute_resource_AMIs.md).
## Best practices for AMI updates
This section applies to both custom and default AMIs.
+ **Regular monitoring** – Regularly check the AMI status of your compute environments to identify when updates are available. For default AMIs, the `batchImageStatus` will show when an update is available. For custom AMIs, you'll need to use other resources like AWS security bulletins.
+ **Maintenance windows** – Schedule AMI updates during maintenance windows when job interruption is acceptable, as infrastructure updates replace existing instances.
+ **Job retry strategy** – Configure job retry strategies to handle jobs that may be interrupted during infrastructure updates. For more information, see [Automated job retries](job_retries.md).
+ **Update policy configuration** – Configure appropriate update policies to control how running jobs are handled during infrastructure updates. For more information, see [Perform infrastructure updates](infrastructure-updates.md).
+ **Testing** – Test AMI updates in development environments before applying them to production compute environments.
# Tutorial: Create a compute resource AMI
You can create your own custom compute resource AMI to use for your managed and unmanaged compute environments. For instructions, see the [Compute resource AMI specification](batch-ami-spec.md). Then, after you created a custom AMI, you can create a compute environment that uses that AMI that you can associate a job queue with. Last, start submitting jobs to that queue.
**To create a custom compute resource AMI**
1. Choose a base AMI to start from. The base AMI must use HVM virtualization. The base AMI can't be a Windows AMI.
**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](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-optimized_AMI.html#ecs-optimized-ami-linux-variants.html) in the *Amazon Elastic Container Service Developer Guide*.
The Amazon ECS optimized Amazon Linux 2 AMI is the default AMI for compute resources in managed compute environments. The Amazon ECS optimized Amazon Linux 2 AMI is preconfigured and tested on AWS Batch by AWS engineers. It's a minimal AMI that you can get started with and to get your compute resources that are running on AWS quickly. For more information, see [Amazon ECS Optimized AMI](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-optimized_AMI.html) in the *Amazon Elastic Container Service Developer Guide*.
Alternatively, you can choose another Amazon Linux 2 variant and install the `ecs-init` package with the following commands. For more information, see [Installing the Amazon ECS container agent on an Amazon Linux 2 EC2 instance ](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-agent-install.html#ecs-agent-install-al2) in the *Amazon Elastic Container Service Developer Guide*:
```
$ sudo amazon-linux-extras disable docker
$ sudo amazon-linux-extras install ecs-init
```
For example, if you want to run GPU workloads on your AWS Batch compute resources, you can start with the [Amazon Linux Deep Learning AMI](https://aws.amazon.com/marketplace/pp/B01M0AXXQB). Then, configure the AMI to run AWS Batch jobs. For more information, see [Use a GPU workload AMI](batch-gpu-ami.md).
**Important**
You can choose a base AMI that doesn't support the `ecs-init` package. However, if you do, you must configure a way to start the Amazon ECS agent at boot and keep it running. You can also view several example user data configuration scripts that use `systemd` to start and monitor the Amazon ECS container agent. For more information, see [Example container instance user data configuration scripts](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/example_user_data_scripts.html) in the *Amazon Elastic Container Service Developer Guide*.
1. Launch an instance from your selected base AMI with the appropriate storage options for your AMI. You can configure the size and number of attached Amazon EBS volumes, or instance storage volumes if the instance type you selected supports them. For more information, see [Launching an Instance](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/launching-instance.html) and [Amazon EC2 Instance Store](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/InstanceStorage.html) in the *Amazon EC2 User Guide*.
1. Connect to your instance with SSH and perform any necessary configuration tasks. This might include any or all of the following steps:
+ Installing the Amazon ECS container agent. For more information, see [Installing the Amazon ECS Container Agent](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-agent-install.html) in the *Amazon Elastic Container Service Developer Guide*.
+ Configuring a script to format instance store volumes.
+ Adding instance store volume or Amazon EFS file systems to the `/etc/fstab` file so that they're mounted at boot.
+ Configuring Docker options, such as enabling debugging or adjusting base image size.
+ Installing packages or copying files.
For more information, see [Connecting to Your Linux Instance Using SSH](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AccessingInstancesLinux.html) in the *Amazon EC2 User Guide*.
1. If you started the Amazon ECS container agent on your instance, you must stop it and remove any persistent data checkpoint files before creating your AMI. Otherwise, if you don't do this, the agent doesn't start on instances that are launched from your AMI.
1. Stop the Amazon ECS container agent.
+ Amazon ECS-optimized Amazon Linux 2 AMI:
```
sudo systemctl stop ecs
```
+ Amazon ECS-optimized Amazon Linux AMI:
```
sudo stop ecs
```
1. Remove the persistent data checkpoint files. By default, these files are located in the `/var/lib/ecs/data/` directory. Use the following command to remove these files, if there are any.
```
sudo rm -rf /var/lib/ecs/data/*
```
1. Create a new AMI from your running instance. For more information, see [Creating an Amazon EBS Backed Linux AMI](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/creating-an-ami-ebs.html) in the *Amazon EC2 User Guide* guide.
**To use your new AMI with AWS Batch**
1. After the new AMI is created, create a compute environment with the new AMI. To do this,choose the image type and enter the custom AMI ID in the **Image ID override** box when you create the AWS Batch compute environment. For more information, see [Tutorial: Create a managed compute environment using Amazon EC2 resources](create-compute-environment-managed-ec2.md).
**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](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-optimized_AMI.html#ecs-optimized-ami-linux-variants.html) in the *Amazon Elastic Container Service Developer Guide*.
1. Create a job queue and associate your new compute environment. For more information, see [Create a job queue](create-job-queue.md).
**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.
1. (Optional) Submit a sample job to your new job queue. For more information, see [Job definition examples](example-job-definitions.md), [Create a single-node job definition](create-job-definition.md), and [Tutorial: submit a job](submit_job.md).
# Use a GPU workload AMI
To run GPU workloads on your AWS Batch compute resources, you must use an AMI with GPU support. For more information, see [Working with GPUs on Amazon ECS](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-gpu.html) and [Amazon ECS-optimized AMIs](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-optimized_AMI.html) in *Amazon Elastic Container Service Developer Guide*.
In managed compute environments, if the compute environment specifies any `p3`, `p4`, `p5`, `p6`, `g3`, `g3s`, `g4`, `g5`, or `g6` instance types or instance families, then AWS Batch uses an Amazon ECS GPU optimized AMI.
In unmanaged compute environments, an Amazon ECS GPU-optimized AMI is recommended. You can use the AWS Command Line Interface or AWS Systems Manager Parameter Store [GetParameter](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetParameter.html), [GetParameters](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetParameters.html), and [GetParametersByPath](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetParametersByPath.html) operations to retrieve the metadata for the recommended Amazon ECS GPU-optimized AMIs.
**Note**
The `p5` instance family is only supported on versions equal or later than `20230912` of the Amazon ECS GPU-optimized AMI and they are incompatible with `p2` and `g2` instance types. If you need to use `p5` instances, ensure that your compute environment doesn't contain `p2` or `g2` instances and uses the latest default Batch AMI. Creating a new compute environment will use the latest AMI but If you are updating your compute environment to include `p5`, you can ensure you are using the latest AMI by setting [https://docs.aws.amazon.com/batch/latest/APIReference/API_ComputeResourceUpdate.html#Batch-Type-ComputeResourceUpdate-updateToLatestImageVersion](https://docs.aws.amazon.com/batch/latest/APIReference/API_ComputeResourceUpdate.html#Batch-Type-ComputeResourceUpdate-updateToLatestImageVersion) to `true` in `ComputeResource` properties. For more information on AMI compatibility with GPU instances, see [Working with GPUs on Amazon ECS](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-gpu.html) in *Amazon Elastic Container Service Developer Guide*.
The following examples show how to use the [GetParameter](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetParameter.html) command.
------
#### [ AWS CLI ]
```
$ aws ssm get-parameter --name /aws/service/ecs/optimized-ami/amazon-linux-2/gpu/recommended \
--region us-east-2 --output json
```
The output includes the AMI information in the `Value` parameter.
```
{
"Parameter": {
"Name": "/aws/service/ecs/optimized-ami/amazon-linux-2/gpu/recommended",
"LastModifiedDate": 1555434128.664,
"Value": "{\"schema_version\":1,\"image_name\":\"amzn2-ami-ecs-gpu-hvm-2.0.20190402-x86_64-ebs\",\"image_id\":\"ami-083c800fe4211192f\",\"os\":\"Amazon Linux 2\",\"ecs_runtime_version\":\"Docker version 18.06.1-ce\",\"ecs_agent_version\":\"1.27.0\"}",
"Version": 9,
"Type": "String",
"ARN": "arn:aws:ssm:us-east-2::parameter/aws/service/ecs/optimized-ami/amazon-linux-2/gpu/recommended"
}
}
```
------
#### [ Python ]
```
from __future__ import print_function
import json
import boto3
ssm = boto3.client('ssm', 'us-east-2')
response = ssm.get_parameter(Name='/aws/service/ecs/optimized-ami/amazon-linux-2/gpu/recommended')
jsonVal = json.loads(response['Parameter']['Value'])
print("image_id = " + jsonVal['image_id'])
print("image_name = " + jsonVal['image_name'])
```
The output only includes the AMI ID and AMI name:
```
image_id = ami-083c800fe4211192f
image_name = amzn2-ami-ecs-gpu-hvm-2.0.20190402-x86_64-ebs
```
------
The following examples demonstrate the use of [GetParameters](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetParameters.html).
------
#### [ AWS CLI ]
```
$ aws ssm get-parameters --names /aws/service/ecs/optimized-ami/amazon-linux-2/gpu/recommended/image_name \
/aws/service/ecs/optimized-ami/amazon-linux-2/gpu/recommended/image_id \
--region us-east-2 --output json
```
The output includes the full metadata for each of the parameters:
```
{
"InvalidParameters": [],
"Parameters": [
{
"Name": "/aws/service/ecs/optimized-ami/amazon-linux-2/gpu/recommended/image_id",
"LastModifiedDate": 1555434128.749,
"Value": "ami-083c800fe4211192f",
"Version": 9,
"Type": "String",
"ARN": "arn:aws:ssm:us-east-2::parameter/aws/service/ecs/optimized-ami/amazon-linux-2/gpu/recommended/image_id"
},
{
"Name": "/aws/service/ecs/optimized-ami/amazon-linux-2/gpu/recommended/image_name",
"LastModifiedDate": 1555434128.712,
"Value": "amzn2-ami-ecs-gpu-hvm-2.0.20190402-x86_64-ebs",
"Version": 9,
"Type": "String",
"ARN": "arn:aws:ssm:us-east-2::parameter/aws/service/ecs/optimized-ami/amazon-linux-2/gpu/recommended/image_name"
}
]
}
```
------
#### [ Python ]
```
from __future__ import print_function
import boto3
ssm = boto3.client('ssm', 'us-east-2')
response = ssm.get_parameters(
Names=['/aws/service/ecs/optimized-ami/amazon-linux-2/gpu/recommended/image_name',
'/aws/service/ecs/optimized-ami/amazon-linux-2/gpu/recommended/image_id'])
for parameter in response['Parameters']:
print(parameter['Name'] + " = " + parameter['Value'])
```
The output includes the AMI ID and AMI name, using the full path for the names.
```
/aws/service/ecs/optimized-ami/amazon-linux-2/gpu/recommended/image_id = ami-083c800fe4211192f
/aws/service/ecs/optimized-ami/amazon-linux-2/gpu/recommended/image_name = amzn2-ami-ecs-gpu-hvm-2.0.20190402-x86_64-ebs
```
------
The following examples show how to use the [GetParametersByPath](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetParametersByPath.html) command.
------
#### [ AWS CLI ]
```
$ aws ssm get-parameters-by-path --path /aws/service/ecs/optimized-ami/amazon-linux-2/gpu/recommended \
--region us-east-2 --output json
```
The output includes the full metadata for all of the parameters under the specified path.
```
{
"Parameters": [
{
"Name": "/aws/service/ecs/optimized-ami/amazon-linux-2/gpu/recommended/ecs_agent_version",
"LastModifiedDate": 1555434128.801,
"Value": "1.27.0",
"Version": 8,
"Type": "String",
"ARN": "arn:aws:ssm:us-east-2::parameter/aws/service/ecs/optimized-ami/amazon-linux-2/gpu/recommended/ecs_agent_version"
},
{
"Name": "/aws/service/ecs/optimized-ami/amazon-linux-2/gpu/recommended/ecs_runtime_version",
"LastModifiedDate": 1548368308.213,
"Value": "Docker version 18.06.1-ce",
"Version": 1,
"Type": "String",
"ARN": "arn:aws:ssm:us-east-2::parameter/aws/service/ecs/optimized-ami/amazon-linux-2/gpu/recommended/ecs_runtime_version"
},
{
"Name": "/aws/service/ecs/optimized-ami/amazon-linux-2/gpu/recommended/image_id",
"LastModifiedDate": 1555434128.749,
"Value": "ami-083c800fe4211192f",
"Version": 9,
"Type": "String",
"ARN": "arn:aws:ssm:us-east-2::parameter/aws/service/ecs/optimized-ami/amazon-linux-2/gpu/recommended/image_id"
},
{
"Name": "/aws/service/ecs/optimized-ami/amazon-linux-2/gpu/recommended/image_name",
"LastModifiedDate": 1555434128.712,
"Value": "amzn2-ami-ecs-gpu-hvm-2.0.20190402-x86_64-ebs",
"Version": 9,
"Type": "String",
"ARN": "arn:aws:ssm:us-east-2::parameter/aws/service/ecs/optimized-ami/amazon-linux-2/gpu/recommended/image_name"
},
{
"Name": "/aws/service/ecs/optimized-ami/amazon-linux-2/gpu/recommended/os",
"LastModifiedDate": 1548368308.143,
"Value": "Amazon Linux 2",
"Version": 1,
"Type": "String",
"ARN": "arn:aws:ssm:us-east-2::parameter/aws/service/ecs/optimized-ami/amazon-linux-2/gpu/recommended/os"
},
{
"Name": "/aws/service/ecs/optimized-ami/amazon-linux-2/gpu/recommended/schema_version",
"LastModifiedDate": 1548368307.914,
"Value": "1",
"Version": 1,
"Type": "String",
"ARN": "arn:aws:ssm:us-east-2::parameter/aws/service/ecs/optimized-ami/amazon-linux-2/gpu/recommended/schema_version"
}
]
}
```
------
#### [ Python ]
```
from __future__ import print_function
import boto3
ssm = boto3.client('ssm', 'us-east-2')
response = ssm.get_parameters_by_path(Path='/aws/service/ecs/optimized-ami/amazon-linux-2/gpu/recommended')
for parameter in response['Parameters']:
print(parameter['Name'] + " = " + parameter['Value'])
```
The output includes the values of all the parameter names at the specified path, using the full path for the names.
```
/aws/service/ecs/optimized-ami/amazon-linux-2/gpu/recommended/ecs_agent_version = 1.27.0
/aws/service/ecs/optimized-ami/amazon-linux-2/gpu/recommended/ecs_runtime_version = Docker version 18.06.1-ce
/aws/service/ecs/optimized-ami/amazon-linux-2/gpu/recommended/image_id = ami-083c800fe4211192f
/aws/service/ecs/optimized-ami/amazon-linux-2/gpu/recommended/image_name = amzn2-ami-ecs-gpu-hvm-2.0.20190402-x86_64-ebs
/aws/service/ecs/optimized-ami/amazon-linux-2/gpu/recommended/os = Amazon Linux 2
/aws/service/ecs/optimized-ami/amazon-linux-2/gpu/recommended/schema_version = 1
```
------
For more information, see [Retrieving Amazon ECS-Optimized AMI Metadata](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/retrieve-ecs-optimized_AMI.html) in the *Amazon Elastic Container Service Developer Guide*.
# Amazon Linux deprecation
The Amazon Linux AMI (also called Amazon Linux 1) reached its end of life on December 31, 2023. AWS Batch has ended support for Amazon Linux AMI as it will not receive any security updates or bug fixes starting January 1, 2024. For more information about the Amazon Linux end-of-life, see [AL FAQ](https://aws.amazon.com/amazon-linux-ami/faqs/).
We recommend that you update existing Amazon Linux based compute environments to Amazon Linux 2023 to prevent unforeseen workload interruptions, and continue to receive security and other updates.
Your compute environments using the Amazon Linux AMI may continue functioning beyond the December 31, 2023 end-of-life date. However, these compute environments will no longer receive any new software updates, security patches, or bug fixes from AWS. It is your responsibility to maintain these compute environments on the Amazon Linux AMI after end-of-life. We recommend migrating AWS Batch compute environments to Amazon Linux 2023 or Amazon Linux 2 to maintain optimal performance and security.
For help migrating AWS Batch from the Amazon Linux AMI to Amazon Linux 2023 or Amazon Linux 2, see [Updating compute environments - AWS Batch](https://docs.aws.amazon.com/batch/latest/userguide/updating-compute-environments.html).
# Amazon EKS Amazon Linux 2 AMI deprecation
AWS ended support for Amazon EKS optimized Amazon Linux 2 AMIs on November 26, 2025. On October 27, 2025, AWS Batch changed the default AMI for new Amazon EKS compute environments to Amazon Linux 2023. Amazon EKS optimized Amazon Linux 2 AMIs no longer receive software updates, security patches, or bug fixes from AWS.
**Important**
If you have AWS Batch Amazon EKS compute environments still using Amazon Linux 2, we strongly recommend migrating to Amazon Linux 2023. It is your responsibility to maintain Amazon EKS optimized Amazon Linux 2 compute environments after end-of-life.
For more information about the Amazon EKS AL2 end-of-life, see [Amazon EKS AMI deprecation FAQs](https://docs.aws.amazon.com/eks/latest/userguide/eks-ami-deprecation-faqs.html) in the *Amazon EKS User Guide*.
For help migrating AWS Batch Amazon EKS compute environments from Amazon Linux 2 to Amazon Linux 2023, see [How to upgrade from EKS AL2 to EKS AL2023](eks-migration-2023.md).
# Amazon ECS Amazon Linux 2 AMI deprecation
AWS is ending support for Amazon ECS Amazon Linux 2-optimized and accelerated AMIs on June 30, 2026. On January 12, 2026, AWS Batch changed the default AMI for new Amazon ECS compute environments from Amazon Linux 2 to Amazon Linux 2023. Effective June 30, 2026, AWS Batch will block creation of new Amazon ECS compute environments using Batch-provided Amazon Linux 2 AMIs. After this date, you can only create new Amazon ECS compute environments using Amazon Linux 2023 or customer-provided AMIs.
**Important**
We strongly recommend migrating your existing AWS Batch Amazon ECS compute environments to Amazon Linux 2023 prior to June 30, 2026. Existing compute environments will continue to operate after this date, but will no longer receive software updates, security patches, or bug fixes from AWS. It is your responsibility to maintain Amazon Linux 2 compute environments after end-of-life.
You can track the migration status of your affected Amazon ECS compute environments using AWS Health planned lifecycle events. For more information, see [AWS Health Planned lifecycle events](batch-planned-lifecycle-events.md).
For more information about the Amazon Linux 2 end-of-life, see [Amazon Linux 2 FAQs](https://aws.amazon.com/amazon-linux-2/faqs/).
For information about differences between Amazon Linux 2 and Amazon Linux 2023, see [Compare Amazon Linux 2023 and Amazon Linux 2](https://docs.aws.amazon.com/linux/al2023/ug/compare-with-al2.html) in the *Amazon Linux 2023 User Guide*.
For information about changes in Amazon Linux 2023 for Amazon ECS-optimized AMI, see [Migrating from an Amazon Linux 2 to an Amazon Linux 2023 Amazon ECS-optimized AMI](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/al2-to-al2023-ami-transition.html) in the *Amazon ECS User Guide*.
For help migrating AWS Batch Amazon ECS compute environments from Amazon Linux 2 to Amazon Linux 2023, see [How to migrate from ECS AL2 to ECS AL2023](ecs-migration-2023.md).
# Use Amazon EC2 launch templates with AWS Batch
AWS Batch supports using Amazon EC2 launch templates with your EC2 compute environments. With launch templates, you can modify the default configuration of your AWS Batch compute resources without needing to create customized AMIs.
Launch templates can specify AMIs that take precedence in the AMI selection order. For more information, see [AMI selection order](ami-selection-order.md).
**Note**
When you specify a custom launch template for a AWS Batch compute environment, AWS Batch doesn't directly attach your launch template to the underlying Auto Scaling group. Instead, AWS Batch creates a separate, Batch-managed launch template for the Auto Scaling group and incorporates the relevant settings from your custom launch template into it. As a result, the launch template that you see associated with the Auto Scaling group is different from the one you originally specified. This is expected behavior.
**Note**
Launch templates aren't supported on AWS Fargate resources.
You must create a launch template before you can associate it with a compute environment. You can create a launch template in the Amazon EC2 console. Or, you can use the AWS CLI or an AWS SDK. For example, the following JSON file represents a launch template that resizes the Docker data volume for the default AWS Batch compute resource AMI and also sets it to be encrypted.
```
{
"LaunchTemplateName": "increase-container-volume-encrypt",
"LaunchTemplateData": {
"BlockDeviceMappings": [
{
"DeviceName": "/dev/xvda",
"Ebs": {
"Encrypted": true,
"VolumeSize": 100,
"VolumeType": "gp2"
}
}
]
}
}
```
You can create the previous launch template by saving the JSON to a file that's called `lt-data.json` and running the following AWS CLI command.
```
aws ec2 --region create-launch-template --cli-input-json file://lt-data.json
```
For more information about launch templates, see [Launching an Instance from a Launch Template](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-launch-templates.html) in the *Amazon EC2 User Guide*.
If you use a launch template to create your compute environment, you can move the following existing compute environment parameters to your launch template:
**Note**
Suppose that any of these parameters (except the Amazon EC2 tags) are specified both in the launch template and in the compute environment configuration. Then, the compute environment parameters take precedence. Amazon EC2 tags are merged between the launch template and the compute environment configuration. If there's a collision on the tag's key, the value in the compute environment configuration takes precedence.
+ Amazon EC2 key pair
+ Amazon EC2 AMI ID
+ Security group IDs
+ Amazon EC2 tags
The following launch template parameters are **ignored** by AWS Batch:
+ Instance type (specify your desired instance types when you create your compute environment)
+ Instance role (specify your desired instance role when you create your compute environment)
+ Network interface subnets (specify your desired subnets when you create your compute environment)
+ Instance market options (AWS Batch must control Spot Instance configuration)
+ Disable API termination (AWS Batch must control instance lifecycle)
AWS Batch only updates the launch template with a new launch template version during infrastructure updates. For more information, see [Update a compute environment in AWS Batch](updating-compute-environments.md).
## Default and override launch templates
You can define a default launch template for the compute environment and an override launch template for specific instance types and families. This can be useful to you so that the default template is used for the majority of instance types in the compute environments.
The substitution variables `$Default` and `$Latest` can be used instead of naming a specific version. If you do not provide an override launch template, the default launch template is automatically applied.
If you use either the `$Default` or `$Latest` variable, AWS Batch will apply the current information at the time that the compute environment is created. If the default or latest version changes in the future, you must update the information through [UpdateComputeEnvironment](https://docs.aws.amazon.com/batch/latest/APIReference/API_UpdateComputeEnvironment.html) or through the AWS Management Console - AWS Batch.
To provide additional flexibility, you can define override launch templates are applied to specific compute instance types or families.
**Note**
You can specify up to ten (10) override launch templates per compute environment.
Use the `targetInstanceTypes` parameter to select the instance type or family that should use this override launch template. The instance type or family must be first identified by the [https://docs.aws.amazon.com/batch/latest/APIReference/API_ComputeResource.html#Batch-Type-ComputeResource-instanceTypes](https://docs.aws.amazon.com/batch/latest/APIReference/API_ComputeResource.html#Batch-Type-ComputeResource-instanceTypes) parameter.
If you define launch template overrides and decide to remove them later, you can pass an empty array to unset the [https://docs.aws.amazon.com/batch/latest/APIReference/API_LaunchTemplateSpecification.html#Batch-Type-LaunchTemplateSpecification-overrides](https://docs.aws.amazon.com/batch/latest/APIReference/API_LaunchTemplateSpecification.html#Batch-Type-LaunchTemplateSpecification-overrides) parameter in the [https://docs.aws.amazon.com/batch/latest/APIReference/API_LaunchTemplateSpecification.html](https://docs.aws.amazon.com/batch/latest/APIReference/API_LaunchTemplateSpecification.html) API operation. You can also choose to not include the `overrides` parameter when submitting the `UpdateComputeEnvironment` API operation. For more information see, [https://docs.aws.amazon.com/batch/latest/APIReference/API_LaunchTemplateSpecification.html#Batch-Type-LaunchTemplateSpecification-overrides](https://docs.aws.amazon.com/batch/latest/APIReference/API_LaunchTemplateSpecification.html#Batch-Type-LaunchTemplateSpecification-overrides)
For more information, see [https://docs.aws.amazon.com/batch/latest/APIReference/API_LaunchTemplateSpecificationOverride.html#Batch-Type-LaunchTemplateSpecificationOverride-targetInstanceTypes](https://docs.aws.amazon.com/batch/latest/APIReference/API_LaunchTemplateSpecificationOverride.html#Batch-Type-LaunchTemplateSpecificationOverride-targetInstanceTypes) in the AWS Batch API Reference guide.
## Amazon EC2 user data in launch templates
You can supply Amazon EC2 user data in your launch template that's run by [cloud-init](https://cloudinit.readthedocs.io/en/latest/index.html) when your instances launch. Your user data can perform common configuration scenarios, including but not limited to the following:
+ [Including users or groups](https://cloudinit.readthedocs.io/en/latest/topics/examples.html#including-users-and-groups)
+ [Installing packages](https://cloudinit.readthedocs.io/en/latest/topics/examples.html#install-arbitrary-packages)
+ [Creating partitions and file systems](https://cloudinit.readthedocs.io/en/latest/topics/examples.html#create-partitions-and-filesystems)
Amazon EC2 user data in launch templates must be in the [MIME multi-part archive](https://cloudinit.readthedocs.io/en/latest/topics/format.html#mime-multi-part-archive) format. This is because your user data is merged with other AWS Batch user data that's required to configure your compute resources. You can combine multiple user data blocks together into a single MIME multi-part file. For example, you might want to combine a cloud boothook that configures the Docker daemon with a user data shell script that writes configuration information for the Amazon ECS container agent.
If you're using AWS CloudFormation, the [AWS::CloudFormation::Init](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-init.html) type can be used with the [cfn-init](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-init.html) helper script to perform common configuration scenarios.
A MIME multi-part file consists of the following components:
+ The content type and part boundary declaration: `Content-Type: multipart/mixed; boundary="==BOUNDARY=="`
+ The MIME version declaration: `MIME-Version: 1.0`
+ One or more user data blocks that contain the following components:
+ The opening boundary that signals the beginning of a user data block: `--==BOUNDARY==`. You must keep the line before this boundary blank.
+ The content type declaration for the block: `Content-Type: text/cloud-config; charset="us-ascii"`. For more information about content types, see the [Cloud-Init documentation](https://cloudinit.readthedocs.io/en/latest/topics/format.html). You must keep the line after the content type declaration blank.
+ The content of the user data, such as a list of shell commands or `cloud-init` directives.
+ The closing boundary that signals the end of the MIME multi-part file: `--==BOUNDARY==--`. You must keep the line before the closing boundary blank.
**Note**
If you add user data to a launch template in the Amazon EC2 console, you can paste it in as plaintext. Or, you can upload it from a file. If you use the AWS CLI or an AWS SDK, you must first `base64` encode the user data and submit that string as the value of the `UserData` parameter when you call [CreateLaunchTemplate](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_CreateLaunchTemplate.html), as shown in this JSON file.
```
{
"LaunchTemplateName": "base64-user-data",
"LaunchTemplateData": {
"UserData": "ewogICAgIkxhdW5jaFRlbXBsYXRlTmFtZSI6ICJpbmNyZWFzZS1jb250YWluZXItdm9sdW..."
}
}
```
**Topics**
+ [Default and override launch templates](#default-lt-and-overrides)
+ [Amazon EC2 user data in launch templates](#lt-user-data)
+ [Reference: Amazon EC2 launch template examples](launch-template-examples.md)
# Reference: Amazon EC2 launch template examples
The following are example MIME multi-part files that you can use to create your own templates.
**Topics**
+ [Example: Mount an existing Amazon EFS file system](#example-mount-an-existing-amazon-efs-file-system)
+ [Example: Override default Amazon ECS container agent configuration](#example-override-default-amazon-ecs-container-agent-configuration)
+ [Example: Mount an existing Amazon FSx for Lustre file system](#example-mount-an-existing-amazon-fsx-for-lustre-file-system)
## Example: Mount an existing Amazon EFS file system
**Example**
This example MIME multi-part file configures the compute resource to install the `amazon-efs-utils` package and mount an existing Amazon EFS file system at `/mnt/efs`.
```
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="==MYBOUNDARY=="
--==MYBOUNDARY==
Content-Type: text/cloud-config; charset="us-ascii"
packages:
- amazon-efs-utils
runcmd:
- file_system_id_01=fs-abcdef123
- efs_directory=/mnt/efs
- mkdir -p ${efs_directory}
- echo "${file_system_id_01}:/ ${efs_directory} efs tls,_netdev" >> /etc/fstab
- mount -a -t efs defaults
--==MYBOUNDARY==--
```
## Example: Override default Amazon ECS container agent configuration
**Example**
This example MIME multi-part file overrides the default Docker image cleanup settings for a compute resource.
```
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="==MYBOUNDARY=="
--==MYBOUNDARY==
Content-Type: text/x-shellscript; charset="us-ascii"
#!/bin/bash
echo ECS_IMAGE_CLEANUP_INTERVAL=60m >> /etc/ecs/ecs.config
echo ECS_IMAGE_MINIMUM_CLEANUP_AGE=60m >> /etc/ecs/ecs.config
--==MYBOUNDARY==--
```
## Example: Mount an existing Amazon FSx for Lustre file system
**Example**
This example MIME multi-part file configures the compute resource to install the `lustre2.10` package from the Extras Library and mount an existing FSx for Lustre file system at `/scratch` and a mount name of `fsx`. This example is for Amazon Linux 2. For installation instructions for other Linux distributions, see [Installing the Lustre Client](https://docs.aws.amazon.com/fsx/latest/LustreGuide/install-lustre-client.html) in the *Amazon FSx for Lustre User Guide*. For more information, see [Mounting your Amazon FSx file system automatically](https://docs.aws.amazon.com/fsx/latest/LustreGuide/mount-fs-auto-mount-onreboot.html) in the *Amazon FSx for Lustre User Guide*.
```
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="==MYBOUNDARY=="
--==MYBOUNDARY==
Content-Type: text/cloud-config; charset="us-ascii"
runcmd:
- file_system_id_01=fs-0abcdef1234567890
- region=us-east-2
- fsx_directory=/scratch
- amazon-linux-extras install -y lustre2.10
- mkdir -p ${fsx_directory}
- mount -t lustre ${file_system_id_01}.fsx.${region}.amazonaws.com@tcp:fsx ${fsx_directory}
--==MYBOUNDARY==--
```
In the [volumes](https://docs.aws.amazon.com/batch/latest/APIReference/API_ContainerProperties.html#Batch-Type-ContainerProperties-volumes) and [mountPoints](https://docs.aws.amazon.com/batch/latest/APIReference/API_ContainerProperties.html#Batch-Type-ContainerProperties-mountPoints) members of the container properties the mount points must be mapped into the container.
```
{
"volumes": [
{
"host": {
"sourcePath": "/scratch"
},
"name": "Scratch"
}
],
"mountPoints": [
{
"containerPath": "/scratch",
"sourceVolume": "Scratch"
}
],
}
```
# Instance Metadata Service (IMDS) configuration
The Instance Metadata Service (IMDS) provides metadata about your EC2 instances to applications running on those instances. Use IMDSv2 for all new workloads and migrate existing workloads from IMDSv1 to IMDSv2 for improved security. For more information about IMDS and configuring IMDS, see [Use instance metadata to manage your EC2 instance](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html) and [Configure instance metadata options for new instances](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-IMDS-new-instances.html) in the *Amazon EC2 User Guide*.
## Configuration scenarios
Choose the appropriate configuration method based on your compute environment setup:
### Default AMI with no launch template
When you use the default AWS Batch AMI and don't specify a launch template, choose one of these options:
1. **Use Amazon Linux 2023 default AMI** – Amazon Linux 2023 requires IMDSv2 by default. When you create your compute environment, select **Amazon Linux 2023** as the image type.
1. **Set account-level IMDSv2 configuration** – Configure your AWS account to require IMDSv2 for all new instances. This setting affects all new instances that you launch in the account. For instructions, see [Set IMDSv2 as the default for the account](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-IMDS-new-instances.html#set-imdsv2-account-defaults) in the *Amazon EC2 User Guide*.
**Note**
Account-level IMDS configuration can be overridden by launch template or AMI configuration. Launch template settings take precedence over account-level settings.
### Custom AMI with no launch template
When you use a custom AMI without a launch template, choose one of these options:
1. **Use Amazon Linux 2023 as base** – Build your custom AMI using Amazon Linux 2023 as the base image. For information about creating custom AMIs for Batch, see [Tutorial: Create a compute resource AMI](create-batch-ami.md).
1. **Configure IMDSv2 in your custom AMI** – When you create your custom AMI, configure it to require IMDSv2. For instructions, see [Configure instance metadata options for custom AMI](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-IMDS-new-instances.html#configure-IMDS-new-instances-ami-configuration) in the *Amazon EC2 User Guide*.
1. **Set account-level IMDSv2 configuration** – Configure your AWS account to require IMDSv2 for all new instances. This setting affects all new instances that you launch in the account. For instructions, see [Set IMDSv2 as the default for the account](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-IMDS-new-instances.html#set-imdsv2-account-defaults) in the *Amazon EC2 User Guide*.
**Note**
Account-level IMDS configuration can be overridden by launch template or AMI configuration. Launch template settings take precedence over account-level settings.
### Using launch templates
When you use launch templates in your compute environment, add metadata options to your launch template to require IMDSv2. For more information about using launch templates with Batch, see [Use Amazon EC2 launch templates with AWS Batch](launch-templates.md).
```
{
"LaunchTemplateName": "batch-imdsv2-template",
"VersionDescription": "IMDSv2 only template for Batch",
"LaunchTemplateData": {
"MetadataOptions": {
"HttpTokens": "required"
}
}
}
```
Create the launch template using the AWS CLI:
```
aws ec2 create-launch-template --cli-input-json file://imds-template.json
```
# EC2 configurations
AWS Batch uses Amazon ECS optimized AMIs for EC2 and EC2 Spot compute environments. The default is [Amazon Linux 2](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-optimized_AMI.html#al2ami) (`ECS_AL2`). Starting in January 2026, the default will change to [AL2023](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-optimized_AMI.html#al2023ami) (`ECS_AL2023`).
AWS will end support for Amazon Linux 2. We recommend migrating AWS Batch Amazon ECS compute environments to Amazon Linux 2023 to maintain optimal performance and security. For more information, see [Amazon ECS Amazon Linux 2 AMI deprecation](ecs-al2-ami-deprecation.md).
We recommend that you update existing Amazon Linux based compute environments to Amazon Linux 2023 to prevent unforeseen workload interruptions, and continue to receive security and other updates.
For help migrating AWS Batch from the Amazon Linux AMI to Amazon Linux 2023, see [How to migrate from ECS AL2 to ECS AL2023](ecs-migration-2023.md)
**Topics**
+ [How to migrate from ECS AL2 to ECS AL2023](ecs-migration-2023.md)
# How to migrate from ECS AL2 to ECS AL2023
AL2023 is a Linux-based operating system designed to provide a secure, stable, and high-performance environment for your cloud applications. For more information about the differences between AL2 and AL2023 see [Compare Amazon Linux 2023 and Amazon Linux 2](https://docs.aws.amazon.com/linux/al2023/ug/compare-with-al2.html) in the *Amazon Linux 2023 User Guide*.
**Important**
Effective June 30, 2026, AWS Batch will block creation of new Amazon ECS compute environments using Batch-provided Amazon Linux 2 AMIs. We strongly recommend migrating your existing AWS Batch Amazon ECS compute environments to Amazon Linux 2023 prior to this date. For more information, see [Amazon ECS Amazon Linux 2 AMI deprecation](ecs-al2-ami-deprecation.md).
On January 12, 2026, AWS Batch changed the default AMI for new Amazon ECS compute environments from Amazon Linux 2 to Amazon Linux 2023 because AWS is [ending support for Amazon Linux 2](https://aws.amazon.com/amazon-linux-2/faqs/). The default AMI is used when you don't specify a value for the [imageType.Ec2Configuration](https://docs.aws.amazon.com/batch/latest/APIReference/API_Ec2Configuration.html) field when creating a new compute environment. We recommend migrating AWS Batch Amazon ECS compute environments to Amazon Linux 2023 to maintain optimal performance and security.
You can track the migration status of your affected Amazon ECS compute environments using AWS Health planned lifecycle events. For more information, see [AWS Health Planned lifecycle events](batch-planned-lifecycle-events.md).
Depending on how your compute environment is configured you can use one of the following upgrade paths from AL2 to AL2023.
**Upgrade using Ec2Configuration.ImageType**
+ If you are not using a launch template or launch template overrides then change [Ec2Configuration.ImageType](https://docs.aws.amazon.com/batch/latest/APIReference/API_Ec2Configuration.html#Batch-Type-Ec2Configuration-imageType) to `ECS_AL2023` (or `ECS_AL2023_NVIDIA` when using GPU instances) and then run [UpdateComputeEnvironment](https://docs.aws.amazon.com/batch/latest/APIReference/API_UpdateComputeEnvironment.html).
+ If you specify an [Ec2Configuration.ImageIdOverride](https://docs.aws.amazon.com/batch/latest/APIReference/API_Ec2Configuration.html#Batch-Type-Ec2Configuration-imageIdOverride) then [Ec2Configuration.ImageType](https://docs.aws.amazon.com/batch/latest/APIReference/API_Ec2Configuration.html#Batch-Type-Ec2Configuration-imageType) must match the AMI type specified in [Ec2Configuration.ImageIdOverride](https://docs.aws.amazon.com/batch/latest/APIReference/API_Ec2Configuration.html#Batch-Type-Ec2Configuration-imageIdOverride).
If you mismatch `ImageIdOverride` and `ImageType` then the compute environment may not function properly.
**Upgrade using launch templates**
+ If you use a launch template that specifies an AMI based on `ECS_AL2023`, ensure your launch template is compatible with Amazon Linux 2023. For information about changes in Amazon Linux 2023 for Amazon ECS-optimized AMI, see [Migrating from an Amazon Linux 2 to an Amazon Linux 2023 Amazon ECS-optimized AMI](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/al2-to-al2023-ami-transition.html) in the *Amazon ECS User Guide*.
+ For AL2023 AMIs, verify that any custom user data or initialization scripts are compatible with the AL2023 environment and package management system.
**Upgrade using CloudFormation**
+ If you use CloudFormation to manage your compute environments, update your template to change the `ImageType` property in the `Ec2Configuration` from `ECS_AL2` to `ECS_AL2023` (or `ECS_AL2023_NVIDIA` when using GPU instances):
```
ComputeEnvironment:
Type: AWS::Batch::ComputeEnvironment
Properties:
ComputeResources:
Ec2Configuration:
- ImageType: ECS_AL2023
```
Then update your CloudFormation stack to apply the changes.
+ If your CloudFormation template specifies a custom AMI using `ImageIdOverride`, ensure the AMI ID corresponds to an AL2023-based AMI and matches the `ImageType` setting.
## Migration considerations
When migrating from Amazon Linux 2 to Amazon Linux 2023, consider the following:
+ **Package management** – Amazon Linux 2023 uses `dnf` instead of `yum` for package management.
+ **System services** – Some system services and their configurations may differ between AL2 and AL2023.
+ **Container runtime** – Both AL2 and AL2023 support Docker, but AL2023 may have different default configurations.
+ **Security** – AL2023 includes enhanced security features and may require updates to security-related configurations.
+ **Instance Metadata Service Version 2 (IMDSv2)** – IMDSv2 is a session-oriented service that requires token-based authentication to access EC2 instance metadata, providing enhanced security. For more information about IMDS, see [How Instance Metadata Service Version 2 works](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html#instance-metadata-v2-how-it-works) in the *Amazon EC2 User Guide*.
For a comprehensive list of changes and migration considerations, see [Migrating from an Amazon Linux 2 to an Amazon Linux 2023 Amazon ECS-optimized AMI](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/al2-to-al2023-ami-transition.html) in the *Amazon ECS User Guide*.
# Instance type allocation strategies for AWS Batch
When a managed compute environment is created, AWS Batch selects instance types from the `[instanceTypes](https://docs.aws.amazon.com/batch/latest/APIReference/API_ComputeResource.html#Batch-Type-ComputeResource-instanceTypes)` specified that best fit the needs of the jobs. The allocation strategy defines behavior when AWS Batch needs additional capacity. This parameter isn't applicable to jobs that run on Fargate resources. Don't specify this parameter.
`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 the [Amazon EC2 service quotas](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-resource-limits.html), then additional jobs don't run until currently running jobs are complete. This allocation strategy keeps costs lower but can limit scaling. If you're using Spot Fleets with `BEST_FIT`, the Spot Fleet IAM Role must be specified. `BEST_FIT` isn't supported when updating compute environments. For more information, see [Update a compute environment in AWS Batch](updating-compute-environments.md).
AWS Batch manages AWS resources in your account. Compute environments with the BEST\$1FIT allocation strategy originally utilized launch configurations by default. However, the use of launch configurations with new AWS accounts will be restricted over time. Therefore, beginning in late April 2024, newly-created BEST\$1FIT compute environments will default to launch templates. If your service role lacks permissions to manage launch templates, AWS Batch may continue to utilize launch configurations. Existing compute environments will continue to use launch configurations.
`BEST_FIT_PROGRESSIVE`
AWS Batch selects additional instance types that are large enough to meet the requirements of the jobs in the queue. Instance types with a lower cost for each unit vCPU are preferred. If additional instances of the previously selected instance types aren't available, AWS Batch selects new instance types.
For [multi-node parallel jobs](multi-node-parallel-jobs.md) AWS Batch chooses the optimal instance type available. If the instance type becomes unavailable due to insufficient capacity, other instance types within the family are not launched.
`SPOT_CAPACITY_OPTIMIZED`
AWS Batch selects one or more instance types that are large enough to meet the requirements of the jobs in the queue. Instance types that are less likely to be interrupted are preferred. This allocation strategy is only available for Spot Instance compute resources.
`SPOT_PRICE_CAPACITY_OPTIMIZED`
The price and capacity optimized allocation strategy looks at both price and capacity to select the Spot Instance pools that are the least likely to be interrupted and have the lowest possible price. This allocation strategy is only available for Spot Instance compute resources.
We recommend that you use `SPOT_PRICE_CAPACITY_OPTIMIZED` rather than `SPOT_CAPACITY_OPTIMIZED` in most instances.
The `BEST_FIT_PROGRESSIVE` and `BEST_FIT` strategies use On-Demand or Spot Instances, and the `SPOT_CAPACITY_OPTIMIZED` and `SPOT_PRICE_CAPACITY_OPTIMIZED` strategies use Spot Instances. However, AWS Batch might need to exceed `maxvCpus` to meet your capacity requirements. In this event, AWS Batch never exceeds `maxvCpus` by more than a single instance.
# Compute resource memory management
When the Amazon ECS container agent registers a compute resource into a compute environment, the agent must determine how much memory the compute resource has available to reserve for your jobs. Because of platform memory overhead and memory occupied by the system kernel, this number is different than the installed memory amount for Amazon EC2 instances. For example, an `m4.large` instance has 8 GiB of installed memory. However, this doesn't always translate to exactly 8192 MiB of memory available for jobs when the compute resource registers.
Suppose that you specify 8192 MiB for the job, and none of your compute resources have 8192 MiB or greater of memory available to satisfy this requirement. Then, the job can't be placed in your compute environment. If you're using a managed compute environment, AWS Batch must launch a larger instance type to accommodate the request.
The default AWS Batch compute resource AMI also reserves 32 MiB of memory for the Amazon ECS container agent and other critical system processes. This memory isn't available for job allocation. For more information, see [Reserve system memory](ecs-reserved-memory.md).
The Amazon ECS container agent uses the Docker `ReadMemInfo()` function to query the total memory available to the operating system. Linux provides command line utilities to determine the total memory.
**Example - Determine Linux total memory**
The **free** command returns the total memory that's recognized by the operating system.
```
$ free -b
```
The following is example output for an `m4.large` instance that's running the Amazon ECS-optimized Amazon Linux AMI.
```
total used free shared buffers cached
Mem: 8373026816 348180480 8024846336 90112 25534464 205418496
-/+ buffers/cache: 117227520 8255799296
```
This instance has 8373026816 bytes of total memory. This means that there's 7985 MiB available for tasks.
**Topics**
+ [Reserve system memory](ecs-reserved-memory.md)
+ [Tutorial: View compute resource memory](viewing-memory.md)
+ [Memory and vCPU considerations for AWS Batch on Amazon EKS](memory-cpu-batch-eks.md)
# Reserve system memory
If you occupy all of the memory on a compute resource with your jobs, it's possible that your jobs contend with critical system processes for memory and possibly cause a system failure. The Amazon ECS container agent provides a configuration variable that's called `ECS_RESERVED_MEMORY`. You can use this configuration variable to remove a specified number of MiB of memory from the pool that's allocated to your jobs. This effectively reserves that memory for critical system processes.
The default AWS Batch compute resource AMI reserves 32 MiB of memory for the Amazon ECS container agent and other critical system processes. We recommend reserving a 5% memory buffer for Amazon ECS container agent and other critical system processes.
# Tutorial: View compute resource memory
You can view how much memory a compute resource registers with in the Amazon ECS console or with the [DescribeContainerInstances](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_DescribeContainerInstances.html) API operation. If you're trying to maximize your resource utilization by providing your jobs as much memory as possible for a particular instance type, you can observe the memory available for that compute resource and then assign your jobs that much memory.
**To view compute resource memory**
1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2).
1. Choose **Clusters**, and then choose the cluster that hosts your compute resources to view.
The cluster name for your compute environment begins with your compute environment name.
1. Choose **Infrastructure**.
1. Under **Container instances**, choose the container instance.
1. The **Resources and networking** section shows the registered and available memory for the compute resource.
The **Total capacity** memory value is what the compute resource registered with Amazon ECS when it was first launched, and the **Available** memory value is what hasn't already been allocated to jobs.
# Memory and vCPU considerations for AWS Batch on Amazon EKS
In AWS Batch on Amazon EKS, you can specify the resources that are made available to a container. For example, you can specify `requests` or `limits` values for vCPU and memory resources.
The following are constraints for specifying vCPU resources:
+ At least one vCPU `requests` or `limits` value must be specified.
+ One vCPU unit is equivalent to one physical or virtual core.
+ The vCPU value must be entered in whole numbers or in increments of 0.25.
+ The smallest valid vCPU value is 0.25.
+ If both are specified, the `requests` value must be less than or equal to the `limits` value. This way, you can configure both soft and hard vCPU configurations.
+ vCPU values can't be specified in milliCPU form. For example, `100m` isn't a valid value.
+ AWS Batch uses the `requests` value for scaling decisions. If a `requests` value isn't specified, the `limits` value is copied to the `requests` value.
The following are constraints for specifying memory resources:
+ At least one memory `requests` or `limits` value must be specified.
+ Memory values must be in mebibytes (MiBs).
+ If both are specified, the `requests` value must be equal to the `limits` value.
+ AWS Batch uses the `requests` value for scaling decisions. If a `requests` value is not specified, the `limits` value is copied to the `requests` value.
The following are constraints for specifying GPU resources:
+ If both are specified, the `requests` value must be equal to the `limits` value.
+ AWS Batch uses the `requests` value for scaling decisions. If a `requests` value isn't specified, the `limits` value is copied to the `requests` value.
## Example: job definitions
The following AWS Batch on Amazon EKS job definition configures soft vCPU shares. This lets AWS Batch on Amazon EKS use all of the vCPU capacity for the instance type. However, if there are other jobs running, the job is allocated a maximum of `2` vCPUs. Memory is limited to 2 GB.
```
{
"jobDefinitionName": "MyJobOnEks_Sleep",
"type": "container",
"eksProperties": {
"podProperties": {
"containers": [
{
"image": "public.ecr.aws/amazonlinux/amazonlinux:2",
"command": ["sleep", "60"],
"resources": {
"requests": {
"cpu": "2",
"memory": "2048Mi"
}
}
}
]
}
}
}
```
The following AWS Batch on Amazon EKS job definition has a `request` value of `1` and allocates a maximum of `4` vCPUs to the job.
```
{
"jobDefinitionName": "MyJobOnEks_Sleep",
"type": "container",
"eksProperties": {
"podProperties": {
"containers": [
{
"image": "public.ecr.aws/amazonlinux/amazonlinux:2",
"command": ["sleep", "60"],
"resources": {
"requests": {
"cpu": "1"
},
"limits": {
"cpu": "4",
"memory": "2048Mi"
}
}
}
]
}
}
}
```
The following AWS Batch on Amazon EKS job definition sets a vCPU `limits` value of `1` and a memory `limits` value of 1 GB.
```
{
"jobDefinitionName": "MyJobOnEks_Sleep",
"type": "container",
"eksProperties": {
"podProperties": {
"containers": [
{
"image": "public.ecr.aws/amazonlinux/amazonlinux:2",
"command": ["sleep", "60"],
"resources": {
"limits": {
"cpu": "1",
"memory": "1024Mi"
}
}
}
]
}
}
}
```
When AWS Batch translates an AWS Batch on Amazon EKS job into an Amazon EKS pod, AWS Batch copies the`limits` value to the `requests` value. This is if a `requests` value isn't specified. When you submit the preceding example job definition, the pod `spec` is as follows.
```
apiVersion: v1
kind: Pod
...
spec:
...
containers:
- command:
- sleep
- 60
image: public.ecr.aws/amazonlinux/amazonlinux:2
resources:
limits:
cpu: 1
memory: 1024Mi
requests:
cpu: 1
memory: 1024Mi
...
```
## Node CPU and memory reservations
AWS Batch relies on the default logic of the `bootstrap.sh` file for vCPU and memory reservations. For more information about the `bootstrap.sh` file, see [bootstrap.sh](https://github.com/awslabs/amazon-eks-ami/blob/main/templates/al2/runtime/bootstrap.sh). When you size your vCPU and memory resources, consider the examples that follow.
**Note**
If no instances are running, vCPU and memory reservations can initially affect AWS Batch scaling logic and decision making. After the instances are running, AWS Batch adjusts the initial allocations.
## Example: Node CPU reservation
The CPU reservation value is calculated in millicores using the total number of vCPUs that are available to the instance.
| vCPU number | Percentage reserved |
| --- | --- |
| 1 | 6% |
| 2 | 1% |
| 3-4 | 0.5% |
| 4 and above | 0.25% |
Using the preceding values, the following is true:
+ The CPU reservation value for a `c5.large` instance with 2 vCPUs is 70 m. This is calculated in the following way: *(1\$160) \$1 (1\$110) = 70 m*.
+ The CPU reservation value for a `c5.24xlarge` instance with 96 vCPUs is 310 m. This is calculated in the following way: (1\$160) \$1 (1\$110) \$1 (2\$15) \$1 (92\$12.5) = 310 m.
In this example, there are 1930 (calculated 2000-70) millicore vCPU units available to run jobs on a `c5.large` instance. Suppose your job requires `2` (2\$11000 m) vCPU units, the job doesn't fit on a single `c5.large` instance. However, a job that requires `1.75` vCPU units fits.
## Example: Node memory reservation
The memory reservation value is calculated in mebibytes using the following:
+ The instance capacity in mebibytes. For example, an 8 GB instance is 7,748 MiB.
+ The `kubeReserved` value. The `kubeReserved` value is the amount of memory to reserve for system daemons. The `kubeReserved` value is calculated in the following way: *((11 \$1 maximum number of pods that is supported by the instance type) \$1 255)*. For information about the maximum number of pods that's supported by an instance type, see [eni-max-pods.txt](https://github.com/awslabs/amazon-eks-ami/blob/main/nodeadm/internal/kubelet/eni-max-pods.txt)
+ The `HardEvictionLimit` value. When available memory falls below the `HardEvictionLimit` value, the instance attempts to evict pods.
The formula to calculate the allocatable memory is as follows: (*instance\$1capacity\$1in\$1MiB*) - (11 \$1 (*maximum\$1number\$1of\$1pods*)) - 255 - (*`HardEvictionLimit` value.*)).
A `c5.large` instance supports up to 29 pods. For an 8 GB `c5.large` instance with a `HardEvictionLimit` value of 100 MiB, the allocatable memory is 7074 MiB. This is calculated in the following way: *(7748 - (11 \$1 29) -255 -100) = 7074 MiB*. In this example, an 8,192 MiB job doesn't fit on this instance even though it's an 8 gibibyte (GiB) instance.
## DaemonSets
When you use DaemonSets, consider the following:
+ If no AWS Batch on Amazon EKS instances are running, DaemonSets can initially affect AWS Batch scaling logic and decision making. AWS Batch initially allocates 0.5 vCPU units and 500 MiB for expected DaemonSets. After the instances are running, AWS Batch adjusts the initial allocations.
+ If a DaemonSet defines vCPU or memory limits, AWS Batch on Amazon EKS jobs have fewer resources. We recommend that you keep the number of DaemonSets that are assigned to AWS Batch jobs as low as possible.
# Fargate compute environments
Fargate is a technology that you can use with AWS Batch to run [containers](https://aws.amazon.com/what-are-containers) without having to manage servers or clusters of Amazon EC2 instances. With Fargate, you no longer have to provision, configure, or scale clusters of virtual machines to run containers. This removes the need to choose server types, decide when to scale your clusters, or optimize cluster packing.
When you run your jobs with Fargate resources, you package your application in containers, specify the CPU and memory requirements, define networking and IAM policies, and launch the application. Each Fargate job has its own isolation boundary and does not share the underlying kernel, CPU resources, memory resources, or elastic network interface with another job.
Fargate is only available for AWS Batch compute environments that use Amazon ECS as the orchestrator. Fargate is not supported for AWS Batch on Amazon EKS compute environments. For more information, see [Amazon EKS compute environments](eks.md).
**Topics**
+ [When to use Fargate](when-to-use-fargate.md)
+ [Job definitions on Fargate](fargate-job-definitions.md)
+ [Job queues on Fargate](fargate-job-queues.md)
+ [Compute environments on Fargate](fargate-compute-environments.md)
# When to use Fargate
We recommend using Fargate in most scenarios. Fargate launches and scales the compute to closely match the resource requirements that you specify for the container. With Fargate, you don't need to over-provision or pay for additional servers. You also don't need to worry about the specifics of infrastructure-related parameters such as instance type. When the compute environment needs to be scaled up, jobs that run on Fargate resources can get started more quickly. Typically, it takes a few minutes to spin up a new Amazon EC2 instance. However, jobs that run on Fargate can be provisioned in about 30 seconds. The exact time required depends on several factors, including container image size and number of jobs.
However, we recommend that you use Amazon EC2 if your jobs require any of the following:
+ More than 16 vCPUs
+ More than 120 gibibytes (GiB) of memory
+ A GPU
+ A custom Amazon Machine Image (AMI)
+ Any of the [linuxParameters](job_definition_parameters.md#ContainerProperties-linuxParameters) parameters
If you have a large number of jobs, we recommend that you use Amazon EC2 infrastructure. For example, if the number of concurrently running jobs exceeds the Fargate throttling limits. This is because, with EC2, jobs can be dispatched at a higher rate to EC2 resources than to Fargate resources. Moreover, more jobs can run concurrently when you use EC2. For more information, see [Fargate service quotas](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/service-quotas.html#service-quotas-fargate) in the *Amazon Elastic Container Service Developer Guide*.
# Job definitions on Fargate
AWS Batch jobs on AWS Fargate don't support all of the job definition parameters that are available. Some parameters are not supported at all, and others behave differently for Fargate jobs.
The following list describes job definition parameters that are not valid or otherwise restricted in Fargate jobs.
`platformCapabilities`
Must be specified as `FARGATE`.
```
"platformCapabilities": [ "FARGATE" ]
```
`type`
Must be specified as `container`.
```
"type": "container"
```
Parameters in `containerProperties`
`executionRoleArn`
Must be specified for jobs running on Fargate resources. For more information, see [IAM Roles for Tasks](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html) in the *Amazon Elastic Container Service Developer Guide*.
```
"executionRoleArn": "arn:aws:iam::123456789012:role/ecsTaskExecutionRole"
```
`fargatePlatformConfiguration`
(Optional, only for Fargate job definitions). Specifies the Fargate platform version, or `LATEST` for a recent platform version. Possible values for `platformVersion` are `1.3.0`, `1.4.0`, and `LATEST` (default).
```
"fargatePlatformConfiguration": { "platformVersion": "1.4.0" }
```
`instanceType``ulimits`
Not applicable for jobs running on Fargate resources.
`memory``vcpus`
These settings must be specified in `resourceRequirements`
`privileged`
Either don't specify this parameter, or specify `false`.
```
"privileged": false
```
`resourceRequirements`
Both memory and vCPU requirements must be specified using [supported values](job_definition_parameters.md#ContainerProperties-resourceRequirements-Fargate-memory-vcpu). GPU resources aren't supported for jobs that run on Fargate resources.
If you use GuardDuty Runtime Monitoring, there is a slight memory overhead for the GuardDuty security agent. Therefore the memory limit must include the size of the GuardDuty security agent. For information about the GuardDuty security agent memory limits, see [CPU and memory limits](https://docs.aws.amazon.com/guardduty/latest/ug/prereq-runtime-monitoring-ecs-support.html#ecs-runtime-agent-cpu-memory-limits) in the *GuardDuty User Guide*. For information about the best practices, see [How do I remediate out of memory errors on my Fargate tasks after enabling Runtime Monitoring](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-guard-duty-troubleshooting.html#memory-error) in the *Amazon ECS Developer Guide*.
```
"resourceRequirements": [
{"type": "MEMORY", "value": "512"},
{"type": "VCPU", "value": "0.25"}
]
```
Parameters in `linuxParameters`
`devices``maxSwap``sharedMemorySize``swappiness``tmpfs`
Not applicable for jobs that run on Fargate resources.
Parameters in `logConfiguration`
`logDriver`
Only `awslogs` and `splunk` are supported. For more information, see [Use the awslogs log driver](using_awslogs.md).
Members in `networkConfiguration`
`assignPublicIp`
If the private subnet doesn't have a NAT gateway attached to send traffic to the Internet, `[assignPublicIp](https://docs.aws.amazon.com/batch/latest/APIReference/API_NetworkConfiguration.html#Batch-Type-NetworkConfiguration-assignPublicIp)` must be "`ENABLED`". For more information, see [AWS Batch IAM execution role](execution-IAM-role.md).
# Job queues on Fargate
AWS Batch job queues on AWS Fargate are essentially unchanged. The only restriction is that the compute environments that are listed in `computeEnvironmentOrder` must all be Fargate compute environments (`FARGATE` or `FARGATE_SPOT`). EC2 and Fargate compute environments can't be mixed.
# Compute environments on Fargate
AWS Batch compute environments on AWS Fargate don't support all of the compute environment parameters that are available. Some parameters are not supported at all. Others have specific requirements for Fargate.
The following list describes compute environment parameters that aren't valid or otherwise restricted in Fargate jobs.
`type`
This parameter must be `MANAGED`.
```
"type": "MANAGED"
```
Parameters in the `computeResources` object
`allocationStrategy``bidPercentage``desiredvCpus``imageId``instanceTypes``ec2Configuration``ec2KeyPair``instanceRole``launchTemplate``minvCpus``placementGroup``spotIamFleetRole`
These aren't applicable for Fargate compute environments and can't be provided.
`subnets`
If the subnets listed in this parameter don't have NAT gateways attached, the `assignPublicIp` parameter in the job definition must be set to `ENABLED`.
`tags`
This isn't applicable for Fargate compute environments and can't be provided. To specify tags for Fargate compute environments, use the `tags` parameter that's not in the `computeResources` object.
`type`
This must be either `FARGATE` or `FARGATE_SPOT`.
```
"type": "FARGATE_SPOT"
```
# Amazon EKS compute environments
[Getting started with AWS Batch on Amazon EKS](getting-started-eks.md) provides a short guide to creating EKS compute environments. This section provides more details on Amazon EKS compute environments.
![\[AWS Batch workflow diagram showing integration with Amazon EKS, ECS, Fargate, and EC2.\]](http://docs.aws.amazon.com/batch/latest/userguide/images/batch-on-eks.png)
AWS Batch simplifies your batch workloads on Amazon EKS clusters by providing managed batch capabilities. This includes queuing, dependency tracking, managed job retries and priorities, pod management, and node scaling. AWS Batch can handle multiple Availability Zones and multiple Amazon EC2 instance types and sizes. AWS Batch integrates several of the Amazon EC2 Spot best practices to run your workloads in a fault-tolerant manner, allowing for fewer interruptions. You can use AWS Batch to run a handful of overnight jobs or millions of mission-critical jobs with confidence.
![\[AWS Batch workflow on Amazon EKS, showing job queue, compute environment, and EC2 instances.\]](http://docs.aws.amazon.com/batch/latest/userguide/images/batch-on-eks-detail.png)
AWS Batch is a managed service that orchestrates batch workloads in your Kubernetes clusters that are managed by Amazon Elastic Kubernetes Service (Amazon EKS). AWS Batch conducts this orchestration external to your clusters using an "overlay" model. Since AWS Batch is a managed service, there are no Kubernetes components (for example, Operators or Custom Resources) to install or manage in your cluster. AWS Batch only needs your cluster to be configured with Role-Based Access Controls (RBAC) that allow AWS Batch to communicate with the Kubernetes API server. AWS Batch calls Kubernetes APIs to create, monitor, and delete Kubernetes pods and nodes.
AWS Batch has built-in scaling logic to scale Kubernetes nodes based on job queue load with optimizations in terms of job capacity allocations. When the job queue is empty, AWS Batch scales down the nodes to the minimum capacity that you set, which by default is zero. AWS Batch manages the full lifecycle of these nodes, and decorates the nodes with labels and taints. This way, other Kubernetes workloads aren't placed on the nodes managed by AWS Batch. The exception to this are `DaemonSets`, which can target AWS Batch nodes to provide monitoring and other functionality required for proper execution of the jobs. Additionally, AWS Batch doesn't run jobs, specifically pods, on nodes in your cluster that it doesn't manage. This way, you can use separate scaling logic and services for other applications on the cluster.
To submit jobs to AWS Batch, you interact directly with the AWS Batch API. AWS Batch translates jobs into `podspecs` and then creates the requests to place pods on nodes managed by AWS Batch in your Amazon EKS cluster. You can use tools such as `kubectl` to view running pods and nodes. When a pod has completed its execution, AWS Batch deletes the pod it created to maintain a lower load on the Kubernetes system.
You can get started by connecting a valid Amazon EKS cluster with AWS Batch. Then attach an AWS Batch job queue to it, and register an Amazon EKS job definition using `podspec` equivalent attributes. Last, submit jobs using the [SubmitJob](https://docs.aws.amazon.com/batch/latest/APIReference/API_SubmitJob.html) API operation referencing to the job definition. For more information, see [Getting started with AWS Batch on Amazon EKS](getting-started-eks.md).
AWS Batch on Amazon EKS supports Amazon EC2 instances (On-Demand and Spot) as compute resources. To use Fargate with AWS Batch, use an Amazon ECS compute environment instead. For more information, see [Fargate compute environments](fargate.md).
## Amazon EKS
**Topics**
+ [Amazon EKS](#compute-environments-eks)
+ [Amazon EKS default AMI](eks-ce-ami-selection.md)
+ [Mixed AMI environments](mixed-ami-environments.md)
+ [Supported Kubernetes versions](supported_kubernetes_version.md)
+ [Update the Kubernetes version of the compute environment](updating-k8s-version-ce.md)
+ [Shared responsibility of the Kubernetes nodes](eks-ce-shared-responsibility.md)
+ [Run a DaemonSet on AWS Batch managed nodes](daemonset-on-batch-eks-nodes.md)
+ [Customize Amazon EKS launch templates](eks-launch-templates.md)
+ [How to upgrade from EKS AL2 to EKS AL2023](eks-migration-2023.md)
# Amazon EKS default AMI
When you create an Amazon EKS compute environment, you don't need to specify an Amazon Machine Image (AMI). AWS Batch selects an Amazon EKS optimized AMI based on the Kubernetes version and instance types that are specified in your [CreateComputeEnvironment](https://docs.aws.amazon.com/batch/latest/APIReference/API_CreateComputeEnvironment.html) request. In general, we recommend that you use the default AMI selection. For information about AMI selection precedence, see [AMI selection order](ami-selection-order.md). For more information about Amazon EKS optimized AMIs, see [Amazon EKS optimized Amazon Linux AMIs](https://docs.aws.amazon.com/eks/latest/userguide/eks-optimized-ami.html) in the *Amazon EKS User Guide*.
**Important**
Amazon Linux 2023 AMIs are the default on AWS Batch for Amazon EKS.
AWS will end support for Amazon EKS AL2-optimized and AL2-accelerated AMIs, starting 11/26/25. You can continue using AWS Batch-provided Amazon EKS optimized Amazon Linux 2 AMIs on your Amazon EKS compute environments beyond the 11/26/25 end-of-support date, however these compute environments will no longer receive any new software updates, security patches, or bug fixes from AWS. For more information on upgrading from AL2 to AL2023, see [How to upgrade from EKS AL2 to EKS AL2023](eks-migration-2023.md) in the *AWS Batch User Guide*.
Run the following command to see which AMI type AWS Batch selected for your Amazon EKS compute environment. This following example is a non-GPU instance type.
```
# compute CE example: indicates Batch has chosen the AL2 x86 or ARM EKS 1.32 AMI, depending on instance types
$ aws batch describe-compute-environments --compute-environments My-Eks-CE1 \
| jq '.computeEnvironments[].computeResources.ec2Configuration'
[
{
"imageType": "EKS_AL2",
"imageKubernetesVersion": "1.32"
}
]
```
This following example is a GPU instance type.
```
# GPU CE example: indicates Batch has choosen the AL2 x86 EKS Accelerated 1.32 AMI
$ aws batch describe-compute-environments --compute-environments My-Eks-GPU-CE \
| jq '.computeEnvironments[].computeResources.ec2Configuration'
[
{
"imageType": "EKS_AL2_NVIDIA",
"imageKubernetesVersion": "1.32"
}
]
```
# Mixed AMI environments
You can use launch template overrides to create compute environments with both Amazon Linux 2 (AL2) and Amazon Linux 2023 (AL2023) AMIs. This is useful for using different AMIs for different architectures or during migration periods when transitioning from AL2 to AL2023.
**Note**
AWS will end support for Amazon EKS AL2-optimized and AL2-accelerated AMIs, starting 11/26/25. While you can continue using AWS Batch-provided Amazon EKS optimized Amazon Linux 2 AMIs on your Amazon EKS compute environments beyond the 11/26/25 end-of-support date, these compute environments will no longer receive any new software updates, security patches, or bug fixes from AWS. Mixed AMI environments can be useful during the transition period, allowing you to gradually migrate workloads to AL2023 while maintaining compatibility with existing AL2-based workloads.
Example configuration using both AMI types:
```
{
"computeResources": {
"launchTemplate": {
"launchTemplateId": "TemplateId",
"version": "1",
"userdataType": "EKS_BOOTSTRAP_SH",
"overrides": [
{
"instanceType": "c5.large",
"imageId": "ami-al2-custom",
"userdataType": "EKS_BOOTSTRAP_SH"
},
{
"instanceType": "c6a.large",
"imageId": "ami-al2023-custom",
"userdataType": "EKS_NODEADM"
}
]
},
"instanceTypes": ["c5.large", "c6a.large"]
}
}
```
# Supported Kubernetes versions
AWS Batch on Amazon EKS currently supports the following Kubernetes versions:
+ `1.34`
+ `1.33`
+ `1.32`
+ `1.31`
+ `1.30`
+ `1.29`
You might see an error message that resembles the following when you use the `CreateComputeEnvironment` API operation or `UpdateComputeEnvironment`API operation to create or update a compute environment. This issue occurs if you specify an unsupported Kubernetes version in `EC2Configuration`.
```
At least one imageKubernetesVersion in EC2Configuration is not supported.
```
To resolve this issue, delete the compute environment and then re-create it with a supported Kubernetes version.
You can perform a minor version upgrade on your Amazon EKS cluster. For example, you can upgrade the cluster from `1.xx` to `1.yy` even if the minor version isn't supported.
However, the compute environment status might change to `INVALID` after a major version update. For example, if you perform a major version upgrade from `1.xx` to `2.yy`. If the major version isn't supported by AWS Batch, you see an error message that resembles the following.
```
reason=CLIENT_ERROR - ... EKS Cluster version [2.yy] is unsupported
```
# Update the Kubernetes version of the compute environment
With AWS Batch, you can update the Kubernetes version of a compute environment to support Amazon EKS cluster upgrades. The Kubernetes version of a compute environment is the Amazon EKS AMI version for the Kubernetes nodes that AWS Batch launches to run jobs. You can perform a Kubernetes version upgrade on their Amazon EKS nodes before or after you update the version of Amazon EKS cluster's control-plane. We recommend that you update the nodes after upgrading the control plane. For more information, see [Updating an Amazon EKS cluster Kubernetes version](https://docs.aws.amazon.com/eks/latest/userguide/update-cluster.html) in the *Amazon EKS User Guide*.
To upgrade the Kubernetes version of a compute environment, use the [https://docs.aws.amazon.com/batch/latest/APIReference/API_UpdateComputeEnvironment.html](https://docs.aws.amazon.com/batch/latest/APIReference/API_UpdateComputeEnvironment.html) API operation.
```
$ aws batch update-compute-environment \
--compute-environment \
--compute-resources \
'ec2Configuration=[{imageType=EKS_AL2,imageKubernetesVersion=1.32}]'
```
# Shared responsibility of the Kubernetes nodes
Maintenance of the compute environments is a shared responsibility.
+ Don't change or remove AWS Batch nodes, labels, taints, namespaces, launch templates, or auto scaling groups. Don't add taints to AWS Batch managed nodes. If you make any of these changes, your compute environment cannot be supported and failures including idle instances occur.
+ Don't target your pods to AWS Batch managed nodes. If you target your pods to the managed nodes, broken scaling and stuck job queues occur. Run workloads that don't use AWS Batch on self-managed nodes or managed node groups. For more information, see [Managed node groups](https://docs.aws.amazon.com/eks/latest/userguide/managed-node-groups.html) in the *Amazon EKS User Guide*.
+ You can target a DaemonSet to run on AWS Batch managed nodes. For more information, see [Run a DaemonSet on AWS Batch managed nodes](daemonset-on-batch-eks-nodes.md).
AWS Batch doesn't automatically update compute environment AMIs. It's your responsibility to update them. Run the following command to update your AMIs to the latest AMI version.
```
$ aws batch update-compute-environment \
--compute-environment \
--compute-resources 'updateToLatestImageVersion=true'
```
AWS Batch doesn't automatically upgrade the Kubernetes version. Run the following command to update the Kubernetes version of your computer environment to *1.32*.
```
$ aws batch update-compute-environment \
--compute-environment \
--compute-resources \
'ec2Configuration=[{imageType=EKS_AL2,imageKubernetesVersion=1.32}]'
```
When updating to a more recent AMI or the Kubernetes version, you can specify whether to terminate jobs when they're updated (`terminateJobsOnUpdate`) and how long to wait for before an instance is replaced if running jobs don't finish (`jobExecutionTimeoutMinutes`.) For more information, see [Update a compute environment in AWS Batch](updating-compute-environments.md) and the infrastructure update policy ([https://docs.aws.amazon.com/batch/latest/APIReference/API_UpdatePolicy.html](https://docs.aws.amazon.com/batch/latest/APIReference/API_UpdatePolicy.html)) set in the [https://docs.aws.amazon.com/batch/latest/APIReference/API_UpdateComputeEnvironment.html](https://docs.aws.amazon.com/batch/latest/APIReference/API_UpdateComputeEnvironment.html) API operation.
# Run a DaemonSet on AWS Batch managed nodes
AWS Batch sets taints on AWS Batch managed Kubernetes nodes. You can target a DaemonSet to run on AWS Batch managed nodes with the following `tolerations`.
```
tolerations:
- key: "batch.amazonaws.com/batch-node"
operator: "Exists"
```
Another way to do this is with the following `tolerations`.
```
tolerations:
- key: "batch.amazonaws.com/batch-node"
operator: "Exists"
effect: "NoSchedule"
- key: "batch.amazonaws.com/batch-node"
operator: "Exists"
effect: "NoExecute"
```
# Customize Amazon EKS launch templates
AWS Batch on Amazon EKS supports launch templates. There are constraints on what your launch template can do.
**Important**
For EKS AL2 AMIs, AWS Batch runs `/etc/eks/bootstrap.sh`. Don't run `/etc/eks/bootstrap.sh` in your launch template or cloud-init user-data scripts. You can add additional parameters besides the `--kubelet-extra-args` parameter to [bootstrap.sh](https://github.com/awslabs/amazon-eks-ami/blob/main/templates/al2/runtime/bootstrap.sh). To do this, set the `AWS_BATCH_KUBELET_EXTRA_ARGS` variable in the `/etc/aws-batch/batch.config` file. See the following example for details.
For EKS AL2023, AWS Batch utilizes the [NodeConfigSpec](https://awslabs.github.io/amazon-eks-ami/nodeadm/doc/api/#nodeconfigspec) from EKS to make instances join the EKS cluster. AWS Batch populates [ClusterDetails](https://awslabs.github.io/amazon-eks-ami/nodeadm/doc/api/#clusterdetails) in [NodeConfigSpec](https://awslabs.github.io/amazon-eks-ami/nodeadm/doc/api/#nodeconfigspec) for the EKS cluster and you don't need to specify them.
**Note**
We recommend that you do not set any of the follow [https://awslabs.github.io/amazon-eks-ami/nodeadm/doc/api/#nodeconfigspec](https://awslabs.github.io/amazon-eks-ami/nodeadm/doc/api/#nodeconfigspec) settings in the launch template as AWS Batch will override your values. For more information, see [Shared responsibility of the Kubernetes nodes](eks-ce-shared-responsibility.md).
`Taints`
`Cluster Name`
`apiServerEndpoint`
`certificatAuthority`
`CIDR`
Do not create a labels with the prefix `batch.amazonaws.com/`
**Note**
If the launch template is changed after [CreateComputeEnvironment](https://docs.aws.amazon.com/batch/latest/APIReference/API_CreateComputeEnvironment.html) is called, [https://docs.aws.amazon.com/batch/latest/APIReference/API_UpdateComputeEnvironment.html](https://docs.aws.amazon.com/batch/latest/APIReference/API_UpdateComputeEnvironment.html) must be called to evaluate the version of the launch template for replacement.
**Topics**
+ [Add `kubelet` extra arguments](#kubelet-extra-args)
+ [Configure the container runtime](#change-container-runtime)
+ [Mount an Amazon EFS volume](#mounting-efs-volume)
+ [IPv6 support](#eks-ipv6-support)
## Add `kubelet` extra arguments
AWS Batch supports adding extra arguments to the `kubelet` command. For the list of supported parameters, see [https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet/](https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet/) in the *Kubernetes documentation*. In the following example for EKS AL2 AMIs, `--node-labels mylabel=helloworld` is added to the `kubelet` command line.
```
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="==MYBOUNDARY=="
--==MYBOUNDARY==
Content-Type: text/x-shellscript; charset="us-ascii"
#!/bin/bash
mkdir -p /etc/aws-batch
echo AWS_BATCH_KUBELET_EXTRA_ARGS=\"--node-labels mylabel=helloworld\" >> /etc/aws-batch/batch.config
--==MYBOUNDARY==--
```
For EKS AL2023 AMIs the file format is YAML. For the list of supported parameters, see [https://awslabs.github.io/amazon-eks-ami/nodeadm/doc/api/#nodeconfigspec](https://awslabs.github.io/amazon-eks-ami/nodeadm/doc/api/#nodeconfigspec) in the *Kubernetes documentation*. In the following example for EKS AL2023 AMIs, `--node-labels mylabel=helloworld` is added to the `kubelet` command line.
```
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="==MYBOUNDARY=="
--==MYBOUNDARY==
Content-Type: application/node.eks.aws
apiVersion: node.eks.aws/v1alpha1
kind: NodeConfig
spec:
kubelet:
flags:
- --node-labels=mylabel=helloworld
--==MYBOUNDARY==--
```
## Configure the container runtime
You can use the AWS Batch `CONTAINER_RUNTIME` environment variable to configure the container runtime on a managed node. The following example sets the container runtime to `containerd` when `bootstrap.sh` runs. For more information, see [https://kubernetes.io/docs/setup/production-environment/container-runtimes/#containerd](https://kubernetes.io/docs/setup/production-environment/container-runtimes/#containerd) in the *Kubernetes documentation*.
If you are using an optimized `EKS_AL2023` or `EKS_AL2023_NVIDIA` AMI you do not need to specify the container runtime as only **containerd** is supported.
**Note**
The `CONTAINER_RUNTIME` environment variable is equivalent to the `--container-runtime` option of `bootstrap.sh`. For more information, see [https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet/#options](https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet/#options) in the *Kubernetes documentation*.
```
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="==MYBOUNDARY=="
--==MYBOUNDARY==
Content-Type: text/x-shellscript; charset="us-ascii"
#!/bin/bash
mkdir -p /etc/aws-batch
echo CONTAINER_RUNTIME=containerd >> /etc/aws-batch/batch.config
--==MYBOUNDARY==--
```
## Mount an Amazon EFS volume
You can use launch templates to mount volumes to the node. In the following example, the `cloud-config` `packages` and `runcmd` settings are used. For more information, see [Cloud config examples](https://cloudinit.readthedocs.io/en/latest/topics/examples.html) in the *cloud-init documentation*.
```
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="==MYBOUNDARY=="
--==MYBOUNDARY==
Content-Type: text/cloud-config; charset="us-ascii"
packages:
- amazon-efs-utils
runcmd:
- file_system_id_01=fs-abcdef123
- efs_directory=/mnt/efs
- mkdir -p ${efs_directory}
- echo "${file_system_id_01}:/ ${efs_directory} efs _netdev,noresvport,tls,iam 0 0" >> /etc/fstab
- mount -t efs -o tls ${file_system_id_01}:/ ${efs_directory}
--==MYBOUNDARY==--
```
To use this volume in the job, it must be added in the [eksProperties](https://docs.aws.amazon.com/batch/latest/APIReference/API_EksProperties.html) parameter to [RegisterJobDefinition](https://docs.aws.amazon.com/batch/latest/APIReference/API_RegisterJobDefinition.html). The following example is a large portion of the job definition.
```
{
"jobDefinitionName": "MyJobOnEks_EFS",
"type": "container",
"eksProperties": {
"podProperties": {
"containers": [
{
"image": "public.ecr.aws/amazonlinux/amazonlinux:2",
"command": ["ls", "-la", "/efs"],
"resources": {
"limits": {
"cpu": "1",
"memory": "1024Mi"
}
},
"volumeMounts": [
{
"name": "efs-volume",
"mountPath": "/efs"
}
]
}
],
"volumes": [
{
"name": "efs-volume",
"hostPath": {
"path": "/mnt/efs"
}
}
]
}
}
}
```
In the node, the Amazon EFS volume is mounted in the `/mnt/efs` directory. In the container for the Amazon EKS job, the volume is mounted in the `/efs` directory.
## IPv6 support
AWS Batch supports Amazon EKS clusters that have IPv6 addresses. No customizations are required for AWS Batch support. However, before you begin, we recommend that you review the considerations and conditions that are outlined in [Assigning IPv6 addresses to pods and services](https://docs.aws.amazon.com/eks/latest/userguide/cni-ipv6.html) in the *Amazon EKS User Guide*.
# How to upgrade from EKS AL2 to EKS AL2023
The Amazon EKS optimized AMIs are available in two families based on Amazon Linux 2 (AL2) and Amazon Linux 2023 (AL2023). AL2023 is a Linux-based operating system designed to provide a secure, stable, and high-performance environment for your cloud applications. For more information about the differences between AL2 and AL2023 see [Upgrade from Amazon Linux 2 to Amazon Linux 2023](https://docs.aws.amazon.com/eks/latest/userguide/al2023.html) in the *Amazon EKS User Guide*.
**Important**
AWS ended support for Amazon EKS AL2-optimized and AL2-accelerated AMIs on November 26, 2025. AWS Batch Amazon EKS compute environments using Amazon Linux 2 no longer receive software updates, security patches, or bug fixes from AWS. We recommend migrating AWS Batch Amazon EKS compute environments to Amazon Linux 2023 to maintain optimal performance and security. It is your [responsibility to maintain](eks-ce-shared-responsibility.md) these compute environments on the Amazon EKS optimized Amazon Linux 2 AMI after end-of-life.
Depending on how your compute environment is configured you can use one of the following upgrade paths from AL2 to AL2023.
**Upgrade using Ec2Configuration.ImageType**
+ If you are not using a launch template or launch template overrides then change [Ec2Configuration.ImageType](https://docs.aws.amazon.com/batch/latest/APIReference/API_Ec2Configuration.html#Batch-Type-Ec2Configuration-imageType) to `EKS_AL2023` or `EKS_AL2023_NVIDIA` and then run [UpdateComputeEnvironment](https://docs.aws.amazon.com/batch/latest/APIReference/API_UpdateComputeEnvironment.html).
+ If you specify an [Ec2Configuration.ImageIdOverride](https://docs.aws.amazon.com/batch/latest/APIReference/API_Ec2Configuration.html#Batch-Type-Ec2Configuration-imageIdOverride) then [Ec2Configuration.ImageType](https://docs.aws.amazon.com/batch/latest/APIReference/API_Ec2Configuration.html#Batch-Type-Ec2Configuration-imageType) must match the AMI type specified in [Ec2Configuration.ImageIdOverride](https://docs.aws.amazon.com/batch/latest/APIReference/API_Ec2Configuration.html#Batch-Type-Ec2Configuration-imageIdOverride).
If you mismatch `ImageIdOverride` and `ImageType` then the node won't join the cluster.
**Upgrade using launch templates**
+ If you have any `kubelet` extra arguments defined in a launch template or launch template override, they need to be updated to the new [`kubelet` extra arguments format](eks-launch-templates.md#kubelet-extra-args).
If you mismatch the `kubelet` extra arguments format then the extra arguments aren't applied.
+ For AL2023 AMIs, **containerd** is the only supported container runtime. You do not need to specify container runtime for `EKS_AL2023` in the launch template.
You can't specify a customized container runtime with `EKS_AL2023`.
+ If you use a launch template or launch template override that specifies an AMI based on `EKS_AL2023` then you need to set [userdataType](https://docs.aws.amazon.com/batch/latest/APIReference/API_LaunchTemplateSpecification.html) to `EKS_NODEADM`.
If you mismatch the `userdataType` and AMI then the node won't join the EKS cluster.