Migrating your Elastic Beanstalk Linux application to Amazon Linux 2
Note
On July 18,2022, Elastic Beanstalk set the status of all platform branches based on Amazon Linux AMI (AL1) to retired. For more information, see Amazon Linux AMI (AL1) platform retirement FAQ.
If your Elastic Beanstalk application is based on an Amazon Linux AMI platform branch, use this page to learn how to migrate your application's environments to Amazon Linux 2.
Amazon Elastic Beanstalk uses Amazon Linux 2
Differences and Compatibility
The AL2 based platform branches aren't guaranteed to be backward compatible with your existing application. Furthermore, even if your application code
successfully deploys to the new platform version, it might behave or perform differently due to operating system and run time differences. Although Amazon Linux
AMI and Amazon Linux 2 share the same Linux kernel, they differ in their initialization system, libc
versions, the compiler tool chain, and
various packages.
For more information, see Amazon Linux 2 FAQs
Migration process
When you're ready to go to production, Elastic Beanstalk requires a blue/green deployment to perform the upgrade. Following the best practices that are recommended for migration with a blue/green deployment procedure, you'll create a new environment that's based on an Amazon Linux 2 platform branch and deploy your application code to it. Your existing production environment will remain active and unaffected, while you iterate through testing and making adjustments to the new environment. When your new environment is ready to go to production, you'll swap the CNAMEs of the two environments to redirect traffic to the new environment. For more information about the blue/green deployment best practice methods, see Blue/Green method. To reference the specific steps of the blue/green deployment procedure, see Blue/Green deployments.
The following references may be helpful in planning your migration.
-
Elastic Beanstalk supported platforms in Amazon Elastic Beanstalk Platforms
Considerations for all Linux platforms
The following table discusses considerations you should be aware of when planning an application migration to Amazon Linux 2. These considerations apply to any of the Elastic Beanstalk Linux platforms, regardless of specific programming languages or application servers.
Area | Changes and information |
---|---|
Configuration Files |
On Amazon Linux 2 platforms, you can use configuration files as before, and all sections work the same way. However, specific settings might not work the same as they did on previous Amazon Linux AMI platforms. For example:
We recommend using platform hooks to run custom code on your environment instances. You can still use commands and container commands in
You still need to use |
Platform hooks |
Amazon Linux 2 platforms introduce a new way to extend your environment's platform by adding executable files to hook directories on the environment's instances. With previous Linux platform versions, you might have used custom platform hooks. These hooks weren't designed for managed platforms and weren't supported, but could work in useful ways in some cases. With Amazon Linux 2 platform versions, custom platform hooks don't work. You should migrate any hooks to the new platform hooks. For details, expand the Platform Hooks section in Extending Elastic Beanstalk Linux platforms. |
Supported proxy servers |
Amazon Linux 2 platform versions support the same reverse proxy servers as each platform supported in its Amazon Linux AMI platform versions. All Amazon Linux 2 platform versions use nginx as their default reverse proxy server. The Tomcat, Node.js, PHP, and Python platform also support Apache HTTPD as an alternative. All platforms enable proxy server configuration in a uniform way, as described in this section. However, configuring the proxy server is slightly different than it was on Amazon Linux AMI. These are the differences for all platforms:
For platform-specific proxy configuration changes, see Platform specific considerations. For information about proxy configuration on Amazon Linux 2 platforms, expand the Reverse Proxy Configuration section in Extending Elastic Beanstalk Linux platforms. |
Proxy Configuration Changes |
There are proxy configuration changes that apply uniformly to all platforms in addition to proxy configuration changes that are specific to each platform. It's important to refer to both to accurately configure your environments.
|
Instance profile |
Amazon Linux 2 platforms require an instance profile to be configured. Environment creation might temporarily succeed without one, but the environment might show errors soon after creation when actions requiring an instance profile start failing. For details, see Managing Elastic Beanstalk instance profiles. |
Enhanced health |
Amazon Linux 2 platform versions enable enhanced health by default. This is a change if you don't use the Elastic Beanstalk console to create your environments. The console enables enhanced health by default whenever possible, regardless of platform version. For details, see Enhanced health reporting and monitoring. |
Custom AMI |
If your environment uses a custom AMI, create a new AMI based on Amazon Linux 2 for your new environment using an Elastic Beanstalk Amazon Linux 2 platform. |
Custom platforms |
The managed AMIs of Amazon Linux 2 platform versions don't support custom platforms. |
Platform specific considerations
This section discusses migration considerations specific to particular Elastic Beanstalk Linux platforms.
The Docker platform branch family based on Amazon Linux AMI (AL1) includes three platform branches. We recommend a specific migration path for each one.
AL1 Platform branch | Migration Path to Amazon Linux 2 | ||||||||
---|---|---|---|---|---|---|---|---|---|
Multi-container Docker managed by Amazon ECS running on Amazon Linux AMI (AL1) |
ECS based Docker AL2 platform branchThe ECS based Docker AL2 platform branch offers a straightforward migration path for environments running on the Multi-container Docker AL1 platform branch.
For more information about migrating your applications running on the Multi-container Docker Amazon Linux platform branch to the Amazon ECS running on Amazon Linux 2 platform branch, see Migrating Multi-container Docker running on Amazon Linux to ECS on Amazon Linux 2. |
||||||||
Docker running on Amazon Linux AMI (AL1) Preconfigured Docker (Glassfish 5.0) running Amazon Linux AMI (AL1) |
Docker Running on Amazon Linux 2 platform branchWe recommend that you migrate your applications running on environments based on Preconfigured Docker (Glassfish 5.0) or Docker running on Amazon Linux AMI (AL1) to environments that are based on the Docker Running on Amazon Linux 2 platform branch. If your environment is based on the Preconfigured Docker (Glassfish 5.0) platform branch, see Deploying a GlassFish application to the Docker platform: a migration path to Amazon Linux 2. The following table lists migration information specific to the platform branch Docker Running on Amazon Linux 2.
|
The following table lists migration information for the Amazon Linux 2 platform versions in the Go platform.
Area | Changes and information |
---|---|
Port passing |
On Amazon Linux 2 platforms, Elastic Beanstalk doesn't pass a port value to your application process through the |
The following table lists migration information for the Corretto platform branches in the Java SE platform.
Area | Changes and information |
---|---|
Corretto vs. OpenJDK |
To implement the Java Platform, Standard Edition (Java SE), Amazon Linux 2 platform branches use Amazon Corretto |
Build tools |
Amazon Linux 2 platforms have newer versions of the build tools: |
JAR file handling |
On Amazon Linux 2 platforms, if your source bundle (ZIP file) contains a single JAR file and no other files, Elastic Beanstalk no longer renames the JAR file
to |
Port passing |
On Amazon Linux 2 platforms, Elastic Beanstalk doesn't pass a port value to your application process through the |
Java 7 |
Elastic Beanstalk doesn't support an Amazon Linux 2 Java 7 platform branch. If you have a Java 7 application, migrate it to Corretto 8 or Corretto 11. |
The following table lists migration information for the Amazon Linux 2 platform versions in the Tomcat platform.
Area | Changes and information | ||||||
---|---|---|---|---|---|---|---|
Configuration options |
On Amazon Linux 2 platform versions, Elastic Beanstalk supports only a subset of the configuration options and option values in the
The |
||||||
Application path |
On Amazon Linux 2 platforms, the path to the application's directory on Amazon EC2 instances of your environment is
|
The following table lists migration information for the Amazon Linux 2 platform versions in the Node.js platform.
Area | Changes and information | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Installed Node.js versions |
On Amazon Linux 2 platforms, Elastic Beanstalk maintains several Node.js platform branches, and only installs the latest version of the Node.js major version corresponding with the platform branch on each platform version. For example, each platform version in the Node.js 12 platform branch only has Node.js 12.x.y installed by default. On Amazon Linux AMI platform versions, we installed the multiple versions of multiple Node.js versions on each platform version, and only maintained a single platform branch. Choose the Node.js platform branch that corresponds with the Node.js major version that your application needs. |
||||||||||
Apache HTTPD log file names |
On Amazon Linux 2 platforms, if you use the Apache HTTPD proxy server, the HTTPD log file names are For details about log file names and locations for all platforms, see How Elastic Beanstalk sets up CloudWatch Logs. |
||||||||||
Configuration options |
On Amazon Linux 2 platforms, Elastic Beanstalk doesn't support the configuration options in the
|
The following table lists migration information for the Amazon Linux 2 platform versions in the PHP platform.
Area | Changes and information |
---|---|
PHP file processing |
On Amazon Linux 2 platforms, PHP files are processed using PHP-FPM (a CGI process manager). On Amazon Linux AMI platforms we used mod_php (an Apache module). |
Proxy server |
Amazon Linux 2 PHP platform versions support both the nginx and the Apache HTTPD proxy servers. The default is nginx. Amazon Linux AMI PHP platform versions supported only Apache HTTPD. If you added custom Apache configuration files, you can set the
|
The following table lists migration information for the Amazon Linux 2 platform versions in the Python platform.
Area | Changes and information |
---|---|
WSGI server |
On Amazon Linux 2 platforms, Gunicorn Alternatively, you can use a |
Application path |
On Amazon Linux 2 platforms, the path to the application's directory on Amazon EC2 instances of your environment is
|
Proxy server |
Amazon Linux 2 Python platform versions support both the nginx and the Apache HTTPD proxy servers. The default is nginx. Amazon Linux AMI Python platform versions supported only Apache HTTPD. If you added custom Apache configuration files, you can set the
|
The following table lists migration information for the Amazon Linux 2 platform versions in the Ruby platform.
Area | Changes and information |
---|---|
Installed Ruby versions |
On Amazon Linux 2 platforms, Elastic Beanstalk only installs the latest version of a single Ruby version, corresponding with the platform branch, on each platform version. For example, each platform version in the Ruby 2.6 platform branch only has Ruby 2.6.x installed. On Amazon Linux AMI platform versions, we installed the latest versions of multiple Ruby versions, for example, 2.4.x, 2.5.x, and 2.6.x. If your application uses a Ruby version that doesn't correspond to the platform branch you're using, we recommend that you switch to a platform branch that has the correct Ruby version for your application. |
Application server |
On Amazon Linux 2 platforms, Elastic Beanstalk only installs the Puma application server on all Ruby platform versions. You can use a
On the Amazon Linux AMI platform, we supported two flavors of platform branches for each Ruby version—one with the Puma application server and the other with the Passenger application server. If your application uses Passenger, you can configure your Ruby environment to install and use Passenger. For more information and examples, see Using the Elastic Beanstalk Ruby platform. |