Migrating your Elastic Beanstalk Linux application to Amazon Linux 2
AWS provides two versions of Amazon Linux: Amazon Linux 2
If your Elastic Beanstalk application is based on an Amazon Linux AMI platform branch,
and the platform has newer generation Amazon Linux 2 platform branch(es), use this
page to
learn how to migrate your application's environments to Amazon Linux 2. The two platform
generations 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. We've also updated platform
specific versions of runtime, build tools,
and other dependencies. Therefore we recommend that you take your time, test your
application thoroughly in a development environment, and make any
necessary adjustments.
When you're ready to go to production, Elastic Beanstalk requires a blue/green deployment to perform the upgrade. For details about platform update strategies, see Updating your Elastic Beanstalk environment's platform version.
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. |
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 following table lists migration information for the Amazon Linux 2 platform versions in the Docker platform.
Area | Changes and information |
---|---|
Storage |
Elastic Beanstalk configures Docker to use storage drivers With Amazon Linux AMI, if you used the |
Private repository authentication |
When you provide a Docker-generated authentication file to connect to a private repository, you no longer need to convert it to the older format that Amazon Linux AMI Docker platform versions required. Amazon Linux 2 Docker platform versions support the new format. For details, see Using images from a private repository. |
Proxy server |
Amazon Linux 2 Docker platform versions don't support standalone containers that don't
run behind a proxy server. On Amazon Linux AMI Docker platform
versions, this used to be possible through the |
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. |