AWS Elastic Beanstalk
Developer Guide
AWS services or capabilities described in AWS documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with AWS services in China.

Updating Your Elastic Beanstalk Environment's Platform Version

Elastic Beanstalk regularly releases new platform versions to update all Linux-based and Windows Server-based platforms. New platform versions provide updates to existing software components and support for new features and configuration options. To learn about platforms and platform versions, see AWS Elastic Beanstalk Platforms Glossary.

You can use the Elastic Beanstalk console or the EB CLI to update your environment's platform version. Depending on the platform version you'd like to update to, Elastic Beanstalk recommends one of two methods for performing platform updates.

  • Method 1 – Update your Environment's Platform Version. We recommend this method when you're updating to the latest platform version, without a change in runtime, web server, or application server versions, and without a change in the major platform version. This is the most common and routine platform update.

  • Method 2 – Perform a Blue/Green Deployment. We recommend this method when you're updating to a different runtime, web server, or application server versions, or to a different major platform version. This is a good approach when you want to take advantage of new runtime capabilities or the latest Elastic Beanstalk functionality.

For more help with choosing the best platform update method, expand the section for your environment's platform.

Single Container Docker

Use Method 1 to perform platform updates.

Multicontainer Docker

Use Method 1 to perform platform updates.

Preconfigured Docker

Consider the following cases:

  • If you're migrating your application to another platform, for example from Go 1.4 (Docker) to Go 1.11 or from Python 3.4 (Docker) to Python 3.6, use Method 2.

  • If you're migrating your application to a different Docker container version, for example from Glassfish 4.1 (Docker) to Glassfish 5.0 (Docker), use Method 2.

  • If you're updating to a latest platform version with no change in container version or major version, use Method 1.

Go

Use Method 1 to perform platform updates.

Java SE

Consider the following cases:

  • If you're migrating your application to a different Java runtime version, for example from Java 7 to Java 8, use Method 2.

  • If you're updating to a latest platform version with no change in runtime version, use Method 1.

Java with Tomcat

Consider the following cases:

  • If you're migrating your application to a different Java runtime version or Tomcat application server version, for example from Java 7 with Tomcat 7 to Java 8 with Tomcat 8.5, use Method 2.

  • If you're migrating your application across major Java with Tomcat platform versions (v1.x.x, v2.x.x, and v3.x.x), use Method 2.

  • If you're updating to a latest platform version with no change in runtime version, application server version, or major version, use Method 1.

.NET on Windows Server with IIS

Consider the following cases:

  • If you're migrating your application to a different Windows operating system version, for example from Windows Server 2008 R2 to Windows Server 2016, use Method 2.

  • If you're migrating your application across major Windows Server platform versions, see Migrating from Earlier Major Versions of the Windows Server Platform, and use Method 2.

  • If your application is currently running on a Windows Server platform V2.x.x and you're updating to a latest platform version, use Method 1.

Note

Windows Server platform versions earlier than v2 aren't semantically versioned. You can only launch the latest version of each of these Windows Server major platform versions and can't roll back after an upgrade.

Node.js

Use Method 2 to perform platform updates.

PHP

Consider the following cases:

  • If you're migrating your application to a different PHP runtime version, for example from PHP 5.6 to PHP 7.2, use Method 2.

  • If you're migrating your application across major PHP platform versions (v1.x.x and v2.x.x), use Method 2.

  • If you're updating to a latest platform version with no change in runtime version or major version, use Method 1.

Python

Consider the following cases:

  • If you're migrating your application to a different Python runtime version, for example from Python 2.7 to Python 3.6, use Method 2.

  • If you're migrating your application across major Python platform versions (v1.x.x and v2.x.x), use Method 2.

  • If you're updating to a latest platform version with no change in runtime version or major version, use Method 1.

Ruby

Consider the following cases:

  • If you're migrating your application to a different Ruby runtime version or application server version, for example from Ruby 2.3 with Puma to Ruby 2.6 with Puma, use Method 2.

  • If you're migrating your application across major Ruby platform versions (v1.x.x and v2.x.x), use Method 2.

  • If you're updating to a latest platform version with no change in runtime version, application server version, or major version, use Method 1.

Method 1 – Update your Environment's Platform Version

Use this method to update to the latest version of your environment's platform. If you've previously created an environment using an older platform version, or upgraded your environment from an older version, you can also use this method to revert to a previous platform version.

To update your environment's platform version

  1. Navigate to the management page for your environment.

  2. In the Overview section, under Configuration, click Change.

    
            Elastic Beanstalk Newer Platform Available
  3. Choose a Platform Version. The newest platform version is selected automatically, but you can update to any version that you've used in the past.

    
            Elastic Beanstalk Update Platform Version Confirmation
  4. Choose Save.

To further simplify platform updates, Elastic Beanstalk can manage them for you. You can configure your environment to apply minor and patch version updates automatically during a configurable weekly maintenance window. Elastic Beanstalk applies managed updates with no downtime or reduction in capacity, and cancels the update immediately if instances running your application on the new version fail health checks. For details, see Managed Platform Updates.

Method 2 – Perform a Blue/Green Deployment

Use this method to update to a different runtime, web server, or application server versions, or to a different major platform version. This is typically necessary when you want to take advantage of new runtime capabilities or the latest Elastic Beanstalk functionality.

When you migrate across major platform versions or to platform versions with major component updates, there's a greater likelihood that your application, or some aspects of it, might not function as expected on the new platform version, and might require changes.

Before performing the migration, update your local development machine to the newer runtime versions and other components of the platform you plan on migrating to. Verify that your application still works as expected, and make any necessary code fixes and changes. Then use the following best practice procedure to safely migrate your environment to the new platform version.

To migrate your environment to a platform version with major updates

  1. Create a new environment, using the new target platform version, and deploy your application code to it. The new environment should be in the Elastic Beanstalk application that contains the environment you're migrating. Don't terminate the existing environment yet.

  2. Use the new environment to migrate your application. In particular:

    • Find and fix any application compatibility issues that you couldn't discover during the development phase.

    • Ensure that any customizations that your application makes using configuration files work correctly in the new environment. These might include option settings, additional installed packages, custom security policies, and script or configuration files installed on environment instances.

    • If your application uses a custom Amazon Machine Image (AMI), create a new custom AMI based on the AMI of the new platform version. To learn more, see Using a Custom Amazon Machine Image (AMI). Specifically, this is required if your application uses the Windows Server platform with a custom AMI, and you're migrating to a Windows Server V2 platform version. In this case, see also Migrating from Earlier Major Versions of the Windows Server Platform.

    Iterate on testing and deploying your fixes until you're satisfied with the application on the new environment.

  3. Turn the new environment into your production environment by swapping its CNAME with the existing production environment's CNAME. For details, see Blue/Green Deployments with Elastic Beanstalk.

  4. When you're satisfied with the state of your new environment in production, terminate the old environment. For details, see Terminate an Elastic Beanstalk Environment.