How to Implement Application Maintenance Mode on Elastic Beanstalk
How to create, and redirect end user requests to a temporary maintenance page while the site is undergoing development
This tutorial guides you on how to set up a maintenance page using AWS ElasticBeanstalk in a Load Balanced Environment.
For most developers, it is important to create, and redirect end user requests to a temporary maintenance page while the site is still undergoing development.
If you have ever used Heroku to host an application, this feature is available as a simple on or off toggle. When it is on, all incoming HTTP requests to your application are redirected to a maintenance page that gracefully informs your users that the app is not ready.
For our purposes, we would be using AWS Elastic Beanstalk to create a custom maintenance page for a sample web application and show how you can easily roll out your application when you are ready.
As a bit of context, AWS Elastic Beanstalk helps developers to deploy and scale web applications quickly. It is an easy-to-use service that only requires that you upload your code (supports Java, .NET, PHP, Node.js, Python, Ruby, Go, and Docker on familiar servers such as Apache, Nginx, Passenger, and IIS). AWS Elastic Beanstalk automatically handles deployment, capacity provisioning, load balancing, auto-scaling, as well as, application health monitoring for your application, and still lets you retain full control over the underlying AWS resources that power your application.
Prerequisites
- You should already have your application code. In this tutorial, we make use of the Elastic Beanstalk Sample application code.
- You also need to create an SSL certificate in AWS Certificate Manager. This is needed to serve your application with HTTPS.
If you have these, then let’s dive in.
- To create the environment for your application, go to the Elastic Beanstalk service page. Here, you can create a new web server environment by adding the required information for your web application like the Application name, and the platform for your code (e.g Python, Node.js). At this point, you are required to upload your code for AWS EB to create the application. We would be using the sample EB Node.js application code.
2. After your environment is set up, you would need to link a subdomain DNS record to the environment URL. We would be using Route53 to set up a subdomain for the application, e.g. test.vahiwe.com. This sub-domain makes your EB URL a bit more user-friendly, for instance, test.vahiwe.com instead of test-env.eba-irpegkis.us-east-1.elasticbeanstalk.com. It is also a requirement to use HTTPS with AWS Elastic Beanstalk.
3. Given that you want to serve your application with HTTPS, you need to provision an SSL certificate using the AWS Certificate Manager(ACM). Click on the Get started.
You can either request a public or private certificate, as well as, import existing certificates. We would be requesting a public certificate. You can add multiple domains to the certificate.
To validate the certificate, we use DNS validation. Although you can also use email validation, if you have access to update the domain records then DNS validation is preferred. You can move through the remaining steps without any input or changes.
When you use AWS Route53 as your DNS provider, ACM can automatically add the CNAME record to validate your certificate. Validating the record can take up to 30 minutes. In the event that your DNS provider is external to AWS, you would have to manually add the ACM CNAME record with your domain registrar.
Once the certificate has been successfully validated, take note of the ARN(Amazon Resource Name) of the certificate. This will be needed when setting up HTTPS on the elastic beanstalk environment. Once you apply the changes made, you can go on to setup your application with the necessary files for the maintenance page.
Folder Structure
We would be using a repository that contains all the necessary files. You can check it out here. Open the repository and check out the contents of the folders. In your project setup, you need to add the folder .ebextensions. The .ebextensions folder contains AWS Elastic Beanstalk configuration files that allows you to configure your environment and customize the AWS resources that it contains. Configuration files are YAML- or JSON-formatted documents with a .config file extension. Below is the folder structure:
├── .ebextensions
│ │── alb_http_to_https_redirect.config
│ └── listener_priority_options.config
├── .gitignore
├── EBSampleApp-Nodejs.iml
├── app.js
├── cron.yaml
├── index.html
├── package.json
├── .gitignore
├── EBSampleApp-Nodejs.iml
├── app.js
├── cron.yaml
├── index.html
└── package.jsonThe alb_http_to_https_redirect.config configures the elastic beanstalk to do a few things, namely:
- It redirects
httptohttpson the load balancer - It creates a
httpslistener and attaches the certificate created by ACM to the listener. Please check line 45 of this file and replace the CertificateArn with the ARN of the certificate created earlier on. - It creates 3 listener rules for the
httpslistener. The rules perform the following actions:
1.ListenerRule1allows you specify specific IP addresses to access your application. This is useful if the developers are testing a new feature and need specific individuals to have access to the application without opening up for end users. Remember to use this listener if you still need access from your IP address when the maintenance mode is switched on.
2.ListenerRule2returns the HTML maintenance page to anyone visiting your domain. This is how you prevent access to the application. Update the domain names in this listener rule with yours.
3.ListenerRule3grants access to the application to anyone visiting your domain. Update the domain names in this listener rule with yours. - The priority of the listener rules determines how they are evaluated. Reordering the priority of the listener rules allows us to switch on and off the maintenance mode.
The listener_priority_options.config allows us to update the priority of the listener rules. To switch on and off the maintenance mode, update the values on line 21–23 with the following values:
Note: Do not repeat a priority number already pointed to another listener rule except if it's for same ruleTo switch Maintenance Mode ON Set the priorities as below:
* ListenerOne : 1
* ListenerTwo : 2
* ListenerThree : 3To switch Maintenance Mode OFF Set the priorities as below:
* ListenerOne : 6
* ListenerTwo : 5
* ListenerThree : 4
With this you can always flip the switch by just updating this file and making a new deployment to elastic beanstalk.
Testing the functionality
These folders and files should be in the root of your project. Your source code can be uploaded to the environment by using eb-cli, uploading a zipped copy of the project on AWS console or AWS CodeDeploy. I’ll be zipping my repo files and uploading to ElasticBeanstalk. Once the deployment is done, the application will be served with https .
Now I’ll switch on maintenance mode by updating the priorities of the listener rules in listener_priority_options.config. I’ll be zipping my updated repo files and uploading to ElasticBeanstalk. Once the deployment is done, maintenance mode will be switched on.
You can see that it works. If you would still like to have access to the application even when the maintenance mode is on, you can input your IP address in the ListenerRule1. This will grant you access exclusively.
Conclusion
The configuration in this article is only applicable to load balanced web environments on ElasticBeanstalk. This should let you control user access to your web application. Goodluck!
Written by John Adedigba & Ahiwe Onyebuchi Valentine — May, 2021
References:
1. docs.amazonaws.cn/en_us/elasticbeanstalk/latest/dg/ebextensions.html
2. aws.amazon.com/elasticbeanstalk/
3. docs.aws.amazon.com/acm/latest/userguide/acm-overview.html
4. tackoverflow.com/questions/32343136/aws-load-balancer-and-maintenance-page
6. docs.aws.amazon.com/elasticloadbalancing/latest/application/listener-update-rules.html
