How to Create a DevOps-Friendly Maintenance Page

August 7, 2017 by Lukasz Czerpak

In my previous blog post entitled "How to deliver code with zero downtime," I presented a working solution on delivering new code without any service interruption. However, there are situations where it's not possible to apply this pattern due to different reasons. Here are a few examples:

  • A new version requires a database upgrade; it can't be done gradually.
  • Dependencies on third parties require some delay to switch between versions.
  • Required downtime for a maintenance window.
  • Mission-critical security patching, where it's important to makes fixes without waiting for a pre-defined time window.

When the Site is Down...

In cases like this, you need to inform users and search engines so that they are aware that it is planned or temporary maintenance. So instead of seeing an error message...

they can be given more meaningful content along with appropriate response code to prevent a sorry page being indexed by search engines.

In this post I'll show you how complex, advanced-metadata-based maintenance page solutions can be self-serviceable, flexible, and DevOps friendly in a few easy steps.


Maintenance Page Requirements

Let's define requirements for the perfect maintenance page solution:


  • It can be activated on demand.
  • Activation/deactivation time in seconds.
  • The content is served outside of customer's backend.
  • The maintenance page can be controlled through an API.


Site Failover

Site failover is the most straightforward solution that can be easily implemented. When Origin throws an error (i.e.: 503) or is not available, alternate content is served from NetStorage:

Although Site Failover covers a lot of cases, it doesn't give any control as to when activate Maintenance mode. It evaluates for each request separately according to pre-defined rules in site delivery configuration.


Site Failover with Trigger File on NetStorage

Advanced and definitely more flexible solution uses single file on NetStorage to trigger Site Failover or not. Simply, when a certain file exists on NetStorage - Site Failover is always executed, otherwise regular content is served. This is fully Advanced Metadata solution that needs to be properly implemented by Akamai.


A Perfect fit for Phased Release Cloudlet

The Phased Release Cloudlet can be used for continuous deployment by shifting traffic gradually between origins (environments). But you can also use its functionality as a simple binary decision - go to the default origin or to a maintenance backup. Using the Phased Release Cloudlet in such a manner gives us the following:


  • A self-service solution, no advanced metadata anymore.
  • Activation/deactivation of Maintenance mode in seconds.
  • Full control through open API, therefore easy integration with devops workflow.

The following graph illustrates enabled Maintenance mode - in the cloudlet policy it's set 100% for the alternate origin which is NetStorage:

And corresponding rule in the cloudlet's policy:


Implementation Details

Now if thePhased Release Cloudlet and NetStorage are on the contract, then in the configuration file you have to add Phased Release Cloudlet behavior:

And then set NetStorage as Cloudlet Origin:

Please note that in Cloudlet Origin Definition rule we have not only Origin behavior but also caching rules, path rewrite (to point to the right file on NetStorage) and response code override (for SEO). Aforementioned origin and corresponding rules are applied only when "MAINTENANCE" origin is active in Phased Release cloudlet (as illustrated on previous screenshot).

In order to disable maintenance mode, an empty policy must be activated.


Enable/Disable in LUNA

Enabling or disabling Maintenance Mode is done through the Luna UI, in the Cloudlet Policy Manager. To make the life easier, policies can be pre-defined and only activated when needed:


Enable/Disable Using the API

You can also activate or deactivate the maintenance page using Akamai APIs, which gives more flexibility and it's faster. In order to enable or disable Maintenance Mode, a certain policy must be activate which can be done by issuing simple command in command-line:

After about 15 seconds, maintenance mode is active:


Integrating with DevOps

Integrating with a build/deployment process is as easy as executing single command or sending single JSON request.

For NodeJS, for example, it's a matter of defining additional commands in the packages.json file:

After that, you can invoke defined scripts to enable or disable Maintenance Mode. An example of that workflow follows:



The solution helps to react quickly on incidents and is convenient to use. Since all the control is feasible though Akamai APIs, the solution can be integrated with variety of systems like real-time monitoring or Continuous Integration tools and incorporated into a DevOps workflow.