Upgrading Elastic Beanstalk environment from AWS Linux 1 to AWS Linux 2

Question

I have an Elastic Beanstalk environment running Python 3.6 on AWS Linux 1, and I want to switch it to Python 3.8 on Amazon Linux 2.

I know that I can upgrade environments using the aws CLI update-environment command:

aws elasticbeanstalk update-environment --environment-name  --solution-stack-name "64bit Amazon Linux 2 v3.3.7 running Python 3.8"

However, AWS Linux 2 uses different configuration parameters. I can't deploy the AWS Linux 2 config because it's invalid on AWS Linux 1 and I can't upgrade to AWS Linux 2 because my config is invalid.

How do I do the upgrade, and is there a way to do it in-place?

Zags · Accepted Answer

Differences in Configuration

AWS Linux 2 has changed a lot of how elastic beanstalk works and how it is configured. Regardless of whether you are doing an in-place upgrade or spinning up a new environment, here is a list of things that will be different to run through before making the upgrade. Most of the items here are things that are different in Elastic Beanstalk config that live in .ebextensions.

There are differences in sub-package dependencies between Python 3.6 and 3.8. You should test your requirements file on Python 3.8 and make sure it's compatible, especially if you use a generated requirements.txt.
AWS Linux 2 no longer allows you to write Apache config using a file directive in .ebextensions. These modifications now need to live in .platform/httpd/conf.
The virtual environment is no longer active while running container_commands. Any container commands that use your code need to have source $PYTHONPATH/activate run first.
Generated files now get wiped on config changes, so commands like django's collectstatic need to get moved to hooks.

Postgres client is no longer available normally though yum. To install it, you need to do:

packages:
    yum:
        amazon-linux-extras: []

commands:
    01_postgres_activate:
        command: sudo amazon-linux-extras enable postgresql10
    02_postgres_install:
        command: sudo yum install -y postgresql-devel

Apache is no longer the default web server (it is Nginx). To continue using it, you need to specify that as an option on your environment, such as:
```
option_settings:
  aws:elasticbeanstalk:environment:proxy:
    ProxyServer: apache
```
Modwsgi has been replaced with Gunicorn. Any modwsgi customizations you have will no longer work, and the WSGI path has a different format:
```
option_settings:
  aws:elasticbeanstalk:container:python:
    WSGIPath: config.wsgi:application
```

Static files config has a different format:

option_settings:
  aws:elasticbeanstalk:environment:proxy:staticfiles:
    /static: staticfiles

You will get opted-in to advanced health reporting. Adding an Elastic Beanstalk health check is strongly recommended:
```
option_settings:
  aws:elasticbeanstalk:application:
    Application Healthcheck URL: /health-check/
```
The application is now run on port 8000 on the server via Gunicorn and Apache/Nginx are just proxying requests to Gunicorn. This matters if you are doing apache customizations such as encrypting traffic between the load balancers and applications servers.
Apache is now run through systemctl rather than supervisord. If you are trying to restart Apache, the command is now sudo systemctl restart httpd
If you want to load your environment variables when sshed into the server, you need to parse them differently:
The environment variables live in a different place and have a different format. To get access to them when SSHed in, you need to add jq: [] to your yum installs. Then, either run the following commands or add them to the bashrc of the server (using a file directive in .ebextensions) to load environment variables and activate the python virtual environment:
```
source <(/opt/elasticbeanstalk/bin/get-config environment | jq -r 'to_entries | .[] | "export \(.key)=\"\(.value)\""')
source $PYTHONPATH/activate
cd /var/app/current
```

Upgrading by Launching a New Environment

To take this upgrade path, you need to not be using the Elastic Beanstalk data tier (i.e. you launched your RDS instance yourself, rather than through Elastic Beanstalk).

Create a code branch with your AWS Linux 2 config
Launch a new Elastic Beanstalk environment on AWS Linux 2.
Copy the environment variables from your previous environment.
Allow access to your database from the new environment (add the new environment's server security group as the target of an ingress rule on the database's security group)
Set up SSL on the new environment.
Deploy the AWS Linux 2 code branch to the new environment.
Test this new environment, ignoring browser certificate warnings (or set up a temporary DNS entry to test it).
Switch the DNS entry to point to your new environment or use AWS's CNAME swap feature on the two environemnts.
After your new environment has been running without problems for sufficient time, terminate your old environment.

Upgrading In-Place

There is a way to do the upgrade in-place, though there will be a few minutes where your site says "502 Bad Gateway". In order to do this, you need EB config that is compatible with both the AWS Linux 1 and AWS Linux 2 environments.

For Python, you can do this with a small Flask app and a four part deploy.

Part 1: deploy placeholder app that is compatible with both platforms

Add flask to your requirements.txt (if it's not already there).
Delete all files in .ebextensions

Make .ebextensions/01.config:

option_settings:
  aws:elasticbeanstalk:container:python:
    WSGIPath: wsgi_shim.py

make wsgi_shim.py:

from flask import Flask

application = Flask(__name__)

@application.route("/")
@application.route("//")
def hello_world(path=None):
    return "This site is currently down for maintenance"

[If using load balancer to application server encryption, change the load balancer to send all traffic to the server via HTTP.]
eb deploy

Part 2: upgrade platform to AWS Linux 2

[If you have any static routes configured in elastic beanstalk delete them.]

Upgrade your eb environment

# Get list of solution stacks
aws elasticbeanstalk list-available-solution-stacks --output=json --query 'SolutionStacks' --region us-east-1

# Use one of the above options here
aws elasticbeanstalk update-environment --environment-name  --solution-stack-name "64bit Amazon Linux 2 v3.3.7 running Python 3.8"

Part 3: deploy your main application to AWS Linux 2

Replace .ebextensions/01.config with your new AWS Linux 2 config.
Add .platform/httpd/conf.d/ssl_rewrite.conf:

RewriteEngine On RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI} [R,L]
eb deploy

Part 4: cleanup

[If using load balancer to application server encryption, change the load balancer back to sending traffic to the server via HTTPS.]
Delete wsgi_shim.py and remove flask from requirements.txt (unless it's a flask project).
eb deploy