How do I migrate my Amazon EC2 instance that runs AL2 to AL2023?

Resolution

Important: AL2 will reach end of life on June 30, 2026. Make sure that you migrate before the end-of-support date. Before you start your migration, create a backup of your instance that you can use in case you encounter issues. Create an Amazon Machine Image (AMI) of your instance, or take a snapshot of the instance's Amazon Elastic Block Store (Amazon EBS) volume.

Check your current packages

Run the following command to list all installed packages on your AL2 instance:

yum list installed > al2-packages.txt

Run the following command to identify packages that are critical for your application:

rpm -qa --queryformat '%{NAME}
' | sort > al2-package-names.txt

Test the AL2023 environment

To create an AL2023 test environment, complete the following steps:

1. Launch an instance that runs AL2023.
2. Run the following command to install your required packages:

   sudo dnf install package-name

   Note: Replace package-name with your package name.
3. Document unavailable packages, and test the application functionality.

Update your existing commands

AL2023 uses dnf instead of yum. Existing yum commands still work as pointers to dnf. However, plugins that are specific to yum, such as yum-plugin-priorities or yum-cron, don't have dnf equivalents. It's a best practice to update your scripts and automations to use dnf to access to the latest features. To identify common package management commands to update, use the following table:

Function	AL2	AL2023
Install package	sudo yum install packagename	sudo dnf install packagename
Search package	sudo yum search packagename	sudo dnf search packagename
Remove package	sudo yum remove packagename	sudo dnf remove packagename
Update system	sudo yum update	sudo dnf upgrade
List repositories	yum repolist	dnf repolist all --verbose
Check updates	yum check-update	dnf check-update --releasever=latest
Clean cache	yum clean all	dnf clean all
Install security updates	sudo yum update --security	sudo dnf upgrade --security --sec-severity=Critical --sec-severity=Important --bugfix -y Note: The preceding command installs only Critical and Important security updates and bug fixes. The -y flag confirms the update without user review. To manually approve changes, remove the -y flag.

The system information retrieval command also changed. AL2023 doesn't use lsb_release.

To check your operating system (OS) name, version, ID, and other distribution details in AL2023, run the following command:

cat /etc/os-release

Note: To check your system information, add standard to the end of the preceding command.

Update your packages and kernel configuration

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

AL2 used kernel 4.14 and had kernel 5.10 available as an upgrade. AL2023 sources its kernel directly from kernel.org, starting with kernel 6.1.

To prevent issues during updates, AMIs that are based on AL2023 are locked to specific repository versions. To provide more predictable updates, AL2023 releases quarterly updates instead of the rolling update model of AL2.

AL2023 also removed the amazon-linux-extras package because you can access all packages in the core repository. You can't use Extra Packages for Enterprise Linux (EPEL) or 32-bit applications in AL2023.

To replace existing packages and commands in AL2 with features in AL2023, take the following actions:

• Instead of amazon-linux-extras, usestandard dnf repositories.
• Instead of awslogs, use the unified Amazon CloudWatch Logs agent.
• Instead of aws-apitools-*, use the AWS CLI.
• Instead of Python 2.7, use Python 3.x.
• Instead of OpenJDK 7, use Amazon Corretto 8+.
• Instead of 32-bit packages, use an AL2 container for 32-bit binaries.

For a complete list of removed packages, see Packages in Amazon Linux 2 not in Amazon Linux 2023.

Also, test your application's compatibility with Instance Metadata Service version 2 (IMDSv2). AL2023 defaults to IMDSv2 instead of IMDSv1. For more information, see Get the full benefits of IMDSv2 and disable IMDSv1 across your AWS infrastructure.

Important: Before you migrate, check your applications and scripts for dependencies on removed packages, and replace the dependencies with the updated packages.

Update missing packages

If there are packages missing after you migrate, then take the following actions to update the packages.

Use SPAL to replace EPEL

Supplementary Packages for Amazon Linux (SPAL) replaces EPEL on AL2023.

Configure the SPAL repository, and then run the following command to search for your required package:

dnf search package-name

Note: Replace package-name with the package name.

Run the following command to install packages from SPAL:

sudo dnf install package-name

Note: Replace package-name with the package name.

Check for later package versions in core repositories

If your application requires a specific package that isn't available in your version, then check whether a later version is available in the core repository.

For example, AL2023 changed from mod_php to PHP-FPM to process PHP files. You can't access the mod_php for PHP 8.1 or PHP 8.2 in the AL2023 repository. However, you can access the php8.3-modphp package. To use mod_php, run the following command to upgrade to PHP 8.3 and install the package:

sudo dnf install php8.3-modphp

Or, run the following command to search for available PHP packages in the repository:

dnf search php

Use containerization

For applications with complex dependencies or requirements for specific package versions, package your application with all required dependencies in a container image. You can use Amazon Elastic Container Service (Amazon ECS) or Amazon Elastic Kubernetes Service (Amazon EKS). To isolate application dependencies from the host OS, base your container on an image that includes the required packages.

Note: If you must access a package that isn't available in AL2023, then open an AWS Support case to request an update. In the support case, specify the package and version, and why it's required.

Troubleshoot cgroup issues after migration

By default, AL2023 uses Control Group (cgroup) v2 instead of the cgroup v1 that AL2 uses. Applications and scripts that rely on cgroup v1 syntax and structure might encounter compatibility issues.

As a result, you experience the following issues:

• Commands, such as cgset -r cpu.cfs_quota_us, fail with the "cgroup modify error: cgroup, requested group parameter does not exist" error.
• Scripts that directly access cgroup v1 filesystem paths, such as /sys/fs/cgroup/cpu/, can't find expected files.
• Resource management tools that are designed for cgroup v1 don't work correctly.

To resolve this issue, update your scripts and applications to use cgroup v2 syntax and interfaces. For more information about cgroup v2 on AL2023, see Unified Control Group hierarchy (cgroup v2).

Related information

Security and compliance in Amazon Linux 2023

AL2023 kernel hardening