Guide to Setup a Maintenance Page on AWS ALB via CloudFormation
In a recent DevOps endeavour, our team encountered the challenge of orchestrating a maintenance page during a critical MySQL version upgrade — from MySQL 5.7 to MySQL 8.0.33. To minimize downtime and ensure a seamless user experience, we leveraged CloudFormation templates and AWS Application Load Balancer (ALB) listener rules.
During the designated maintenance window, our strategy involved deploying CloudFormation stacks that efficiently set up AWS Application Load Balancer (ALB) listener rules. These rules directed traffic appropriately and delivered a fixed HTML response. This response, embedded with our carefully crafted maintenance page HTML, carried a response code signalling downtime to users — a crucial step in orchestrating a successful upgrade.
Step 1: Identifying Prerequisites
Before diving into the implementation process, ensure you have the following prerequisites ready:
- Obtain HttpAlbListenerARN and HttpsAlbListenerARN for the ALB listeners.
- Define HttpAlbListenerPriority and HttpsAlbListenerPriority for setting up listener rules.
- Prepare the HTML content for the maintenance page.
- Define Host Headers required for effective traffic routing.
Step 2: Understanding ALB Listener ARN and Listener Priority
Gain insights into the significance of ALB Listener ARN and Listener Priority in AWS ALB. Understand their roles and how they’re used to manage traffic routing and rule evaluation.
What is ALB Listener ARN?
An ALB (Application Load Balancer) Listener ARN (Amazon Resource Name) is a unique identifier for an ALB listener resource in AWS (Amazon Web Services). It follows the ARN format, which is used to uniquely identify AWS resources across different AWS services.
An ALB listener is a component of the Application Load Balancer that listens for incoming network traffic on a specific port and protocol (e.g., HTTP on port 80 or HTTPS on port 443). The ALB routes incoming requests to the appropriate target group based on the rules defined by the listener.
The ALB Listener ARN typically includes information such as the AWS region, AWS account ID, load balancer resource ID, and listener resource ID. It’s used for various purposes, including IAM (Identity and Access Management) policies and resource references in AWS.
Here’s a general format for an ALB Listener ARN:
arn:aws:elasticloadbalancing:region:account-id:listener/load-balancer-id/listener-id
ALB Listener Priority:
AWS (Amazon Web Services) Application Load Balancer (ALB), the “listener priority” refers to the order in which listener rules are evaluated when the ALB processes incoming requests. The listener priority determines the precedence or priority of a particular rule compared to other rules associated with the same listener.
Each listener of an ALB can have one or more listener rules that specify how incoming traffic should be routed. Listener rules are evaluated sequentially based on their priority. The rule with the lowest priority value is evaluated first, and subsequent rules are evaluated in ascending order of priority.
Here’s how listener priority works:
- Rule Evaluation Order: ALB evaluates listener rules based on their priority values upon receiving a request.
- Matching a Rule: Each rule’s conditions are compared with the incoming request’s attributes (e.g., path, host) to find the first matching rule.
- Action Execution: The corresponding action in the matched rule is executed, such as forwarding, redirecting, or providing a fixed response.
- No Match Scenario: If no rule matches the request, ALB performs a default action or returns an error response as specified.
- Listener Functionality: Listeners route traffic to different target groups or perform actions based on rule conditions. Unique priorities control rule evaluation order, enabling complex routing and handling logic within the ALB. Adjusting priorities controls rule behaviour within a listener.
It’s important to note that listener rule priorities must be unique within a listener. You can adjust the priorities to control the order of rule evaluation and, consequently, the behaviour of your ALB.
Step 3: Crafting a Sample Maintenance Page
Explore a modified sample maintenance page HTML code designed to fit within the 1024-character limit imposed by ALB Fixed response content. Customize this template to convey relevant information to users during maintenance. Below is a modified sample maintenance page inspired by GitHub, tailored for our specific use case.
<!doctype html>
<title>Site Maintenance</title>
<style>
body { text-align: center; padding: 150px; }
h1 { font-size: 50px; }
body { font: 20px Helvetica, sans-serif; color: #333; }
article { display: block; text-align: left; width: 650px; margin: 0 auto; }
a { color: #dc8100; text-decoration: none; }
a:hover { color: #333; text-decoration: none; }
</style>
<article>
<h1>We’ll be back soon!</h1>
<div>
<p>Sorry for the inconvenience but we’re performing some maintenance at the moment. If you need to you can always <a href="mailto:#">contact us</a>, otherwise we’ll be back online shortly!</p>
<p>— The Team</p>
</div>
</article>Step 4: Creating a CloudFormation Template
Follow a structured CloudFormation template to deploy the maintenance page on both HTTP and HTTPS ALB listeners:
AWSTemplateFormatVersion: "2010-09-09"
Description: Create ALB Listener Rule with Maintenance Page and Custom Headers For Production site.
Parameters:
HttpAlbListenerARN:
Type: String
Default: <ALB ARN>
Description: The ARN of the HTTP load balancer listener to attach to the ECS service.
HttpAlbListenerPriority:
Type: Number
Default: <Priority Number>
Description: The priority of the HTTP load balancer listener rule to attach to the ECS service.
HttpsAlbListenerARN:
Type: String
Default: <ALB ARN>
Description: The ARN of the HTTPS load balancer listener to attach to the ECS service.
HttpsAlbListenerPriority:
Type: Number
Default: <Priority Number>
Description: The priority of the HTTPS load balancer listener rule to attach to the ECS service.
MaintenancePageContent:
Type: String
Default: "<!doctype html><title>Site Maintenance</title><style>body { text-align: center; padding: 150px; }h1 { font-size: 50px; }body { font: 20px Helvetica, sans-serif; color: #333; }article { display: block; text-align: left; width: 650px; margin: 0 auto; }a { color: #dc8100; text-decoration: none; }a:hover { color: #333; text-decoration: none; }</style><article><h1>We’ll be back soon!</h1><div><p>Sorry for the inconvenience but we’re performing some maintenance at the moment. If you need to you can always <a href="mailto:#">contact us</a>, otherwise we’ll be back online shortly!</p><p>— The Team</p></div></article>"
Description: The HTML content for the maintenance page.
Resources:
HttpMaintenancePageRule:
Type: AWS::ElasticLoadBalancingV2::ListenerRule
Properties:
Actions:
- Type: fixed-response
FixedResponseConfig:
StatusCode: 503
ContentType: text/html
MessageBody: !Ref MaintenancePageContent
Conditions:
- Field: host-header
HostHeaderConfig:
Values:
- example.com
- prod.example.com
ListenerArn: !Ref HttpAlbListenerARN
Priority: !Ref HttpAlbListenerPriority
HttpsMaintenancePageRule:
Type: AWS::ElasticLoadBalancingV2::ListenerRule
Properties:
Actions:
- Type: fixed-response
FixedResponseConfig:
StatusCode: 503
ContentType: text/html
MessageBody: !Ref MaintenancePageContent
Conditions:
- Field: host-header
HostHeaderConfig:
Values:
- prod.example.com
- www.example.com
- www.prod.example.com
- example.com
ListenerArn: !Ref HttpsAlbListenerARN
Priority: !Ref HttpsAlbListenerPriority
Outputs:
HttpMaintenancePageRule:
Value: !Ref HttpMaintenancePageRule
Description: Rule for the HTTP maintenance page.
HttpsMaintenancePageRule:
Value: !Ref HttpsMaintenancePageRule
Description: Rule for the HTTPS maintenance page.Step 5: Incorporating HTTP and HTTPS Maintenance Page Rules
Understand the importance of including rules for both HTTP and HTTPS traffic to ensure a consistent user experience:
Inclusion Rationale:
- HTTP Rule: Ensures users accessing the site via plain HTTP receive the maintenance page.
- HTTPS Rule: Caters to users accessing the site securely through HTTPS.
Consistent User Experience:
- Uniform Message: Provides a consistent maintenance message for users irrespective of the protocol used.
- Handling Both Protocols: Deploys the maintenance page across both HTTP and HTTPS entries for consistency.
- Redirection Assurance: Ensures users are redirected to the appropriate maintenance content regardless of the access protocol used.
This concise overview emphasizes why implementing rules for both HTTP and HTTPS traffic is essential for a seamless and uniform user experience during maintenance.
Step 6: Deployment and Testing:
Deployment Steps:
- Deploy the CloudFormation stack with the specified ALB listener rules.
- Monitor the website response code, expecting a 503 code indicating successful activation of the maintenance page.
Testing Procedure:
- Verify the display of the maintenance page by accessing the website via HTTP and HTTPS.
- Ensure the page content aligns with the intended maintenance message.
Post-Upgrade Verification:
- After completing the MySQL version upgrade from the AWS RDS Console, confirm the restoration of normal site access by removing the CloudFormation stack.
Thank you for diving into the intricacies of setting up a maintenance page on AWS ALB via CloudFormation with us. We hope this guide proves valuable in your DevOps journey. Stay tuned for more insightful posts, as we continue to explore and share best practices for seamless operations in the world of AWS and beyond. Your curiosity drives us forward, and we look forward to bringing you more engaging content. Until then, happy deploying!
