**Help improve this page**
To contribute to this user guide, choose the **Edit this page on GitHub** link that is located in the right pane of every page.
# Upgrade from Amazon Linux 2 to Amazon Linux 2023
**Warning**
Amazon EKS stopped publishing EKS-optimized Amazon Linux 2 (AL2) AMIs on November 26, 2025. AL2023 and Bottlerocket based AMIs for Amazon EKS are available for all supported Kubernetes versions including 1.33 and higher.
AL2023 is a Linux-based operating system designed to provide a secure, stable, and high-performance environment for your cloud applications. It’s the next generation of Amazon Linux from Amazon Web Services and is available across all supported Amazon EKS versions.
AL2023 offers several improvements over AL2. For a full comparison, see [Comparing AL2 and Amazon Linux 2023](https://docs.aws.amazon.com/linux/al2023/ug/compare-with-al2.html) in the *Amazon Linux 2023 User Guide*. Several packages have been added, upgraded, and removed from AL2. It’s highly recommended to test your applications with AL2023 before upgrading. For a list of all package changes in AL2023, see [Package changes in Amazon Linux 2023](https://docs.aws.amazon.com/linux/al2023/release-notes/compare-packages.html) in the *Amazon Linux 2023 Release Notes*.
In addition to these changes, you should be aware of the following:
+ AL2023 introduces a new node initialization process `nodeadm` that uses a YAML configuration schema. If you’re using self-managed node groups or an AMI with a launch template, you’ll now need to provide additional cluster metadata explicitly when creating a new node group. An [example](https://awslabs.github.io/amazon-eks-ami/nodeadm/) of the minimum required parameters is as follows, where `apiServerEndpoint`, `certificateAuthority`, and service `cidr` are now required:
```
---
apiVersion: node.eks.aws/v1alpha1
kind: NodeConfig
spec:
cluster:
name: my-cluster
apiServerEndpoint: https://example.com
certificateAuthority: Y2VydGlmaWNhdGVBdXRob3JpdHk=
cidr: 10.100.0.0/16
```
In AL2, the metadata from these parameters was discovered from the Amazon EKS `DescribeCluster` API call. With AL2023, this behavior has changed since the additional API call risks throttling during large node scale ups. This change doesn’t affect you if you’re using managed node groups without a launch template or if you’re using Karpenter. For more information on `certificateAuthority` and service `cidr`, see [https://docs.aws.amazon.com/eks/latest/APIReference/API_DescribeCluster.html](https://docs.aws.amazon.com/eks/latest/APIReference/API_DescribeCluster.html) in the *Amazon EKS API Reference*.
+ For AL2023, `nodeadm` also changes the format to apply parameters to the `kubelet` for each node using [https://awslabs.github.io/amazon-eks-ami/nodeadm/doc/api/#nodeconfigspec](https://awslabs.github.io/amazon-eks-ami/nodeadm/doc/api/#nodeconfigspec). In AL2, this was done with the `--kubelet-extra-args` parameter. This is commonly used to add labels and taints to nodes. An example below shows applying `maxPods` and `--node-labels` to the node.
```
---
apiVersion: node.eks.aws/v1alpha1
kind: NodeConfig
spec:
cluster:
name: test-cluster
apiServerEndpoint: https://example.com
certificateAuthority: Y2VydGlmaWNhdGVBdXRob3JpdHk=
cidr: 10.100.0.0/16
kubelet:
config:
maxPods: 110
flags:
- --node-labels=karpenter.sh/capacity-type=on-demand,karpenter.sh/nodepool=test
```
+ Amazon VPC CNI version `1.16.2` or greater is required for AL2023.
+ AL2023 requires `IMDSv2` by default. `IMDSv2` has several benefits that help improve security posture. It uses a session-oriented authentication method that requires the creation of a secret token in a simple HTTP PUT request to start the session. A session’s token can be valid for anywhere between 1 second and 6 hours. For more information on how to transition from `IMDSv1` to `IMDSv2`, see [Transition to using Instance Metadata Service Version 2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-metadata-transition-to-version-2.html) and [Get the full benefits of IMDSv2 and disable IMDSv1 across your AWS infrastructure](https://aws.amazon.com/blogs/security/get-the-full-benefits-of-imdsv2-and-disable-imdsv1-across-your-aws-infrastructure). If you would like to use `IMDSv1`, you can still do so by manually overriding the settings using instance metadata option launch properties.
**Note**
For `IMDSv2` with AL2023, the default hop count for managed node groups can vary:
When not using a launch template, the default is set to `1`. This means that containers won’t have access to the node’s credentials using IMDS. If you require container access to the node’s credentials, you can still do so by using a [custom Amazon EC2 launch template](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-ec2-launchtemplate-metadataoptions.html).
When using a custom AMI in a launch template, the default `HttpPutResponseHopLimit` is set to `2`. You can manually override the `HttpPutResponseHopLimit` in the launch template.
Alternatively, you can use [Amazon EKS Pod Identity](pod-identities.md) to provide credentials instead of `IMDSv2`.
+ AL2023 features the next generation of unified control group hierarchy (`cgroupv2`). `cgroupv2` is used to implement a container runtime, and by `systemd`. While AL2023 still includes code that can make the system run using `cgroupv1`, this isn’t a recommended or supported configuration. This configuration will be completely removed in a future major release of Amazon Linux.
+ `eksctl` version `0.176.0` or greater is required for `eksctl` to support AL2023.
For previously existing managed node groups, you can either perform an in-place upgrade or a blue/green upgrade depending on how you’re using a launch template:
+ If you’re using a custom AMI with a managed node group, you can perform an in-place upgrade by swapping the AMI ID in the launch template. You should ensure that your applications and any user data transfer over to AL2023 first before performing this upgrade strategy.
+ If you’re using managed node groups with either the standard launch template or with a custom launch template that doesn’t specify the AMI ID, you’re required to upgrade using a blue/green strategy. A blue/green upgrade is typically more complex and involves creating an entirely new node group where you would specify AL2023 as the AMI type. The new node group will need to then be carefully configured to ensure that all custom data from the AL2 node group is compatible with the new OS. Once the new node group has been tested and validated with your applications, Pods can be migrated from the old node group to the new node group. Once the migration is completed, you can delete the old node group.
If you’re using Karpenter and want to use AL2023, you’ll need to modify the `EC2NodeClass` `amiFamily` field with AL2023. By default, Drift is enabled in Karpenter. This means that once the `amiFamily` field has been changed, Karpenter will automatically update your worker nodes to the latest AMI when available.
## Additional Information About nodeadm
When utilizing an EKS-optimized Amazon Linux 2023 AMI or building a Custom EKS Amazon Linux 2023 AMI via the Packer scripts provided in the official amazon-eks-ami GitHub repository, you should avoid explicitly running nodeadm init within EC2 User Data or as part of your custom AMI.
If you want to generate dynamic NodeConfig in your user-data, you can write that configuration to a drop-in yaml or json file in `/etc/eks/nodeadm.d`. These configuration files will be merged and applied to your node when nodeadm init is automatically started later in the boot process. For example:
```
cat > /etc/eks/nodeadm.d/additional-node-labels.yaml << EOF
apiVersion: node.eks.aws/v1alpha1
kind: NodeConfig
spec:
kubelet:
flags:
- --node-labels=foo=bar
EOF
```
The EKS-optimized Amazon Linux 2023 AMIs automatically execute nodeadm init in two phases through separate systemd services: nodeadm-config runs before user data execution, while nodeadm-run executes afterward. The nodeadm-config service establishes baseline configurations for containerd and kubelet before user data runs. The nodeadm-run service runs select system daemons and completes any final configurations following user data execution. If the nodeadm init command is run an additional time, via user data or a custom AMI, it may break assumptions about execution ordering, leading to unexpected outcomes including misconfigured ENIs.