Skip to main content
This step-by-step guide outlines how to create and maintain a custom maintenance page in Fastly, and how to enable and disable it either manually or during Upsun deployments. We need to add a dictionary in Fastly which we will use as an on / off switch to enable and disable the maintenance page as well as the content of maintenance page. We are going to use official Fastly CLI tool which you can download from Fastly CLI. You will need a Fastly API token with permissions to perform changes. We are going to use these two environment variables:
  • FASTLY_SERVICE_ID: Contains our Fastly service ID.
  • FASTLY_API_TOKEN: Contains our Fastly API token.

​
Create Fastly configuration

Please define these two local environment variables before starting, using the following command lines:
export FASTLY_SERVICE_ID=<YOUR-FASTLY-SERVICE-ID>
export FASTLY_API_TOKEN=<YOUR-FASTLY-API-TOKEN>
Let’s start with cloning the active configuration version: 
fastly service-version clone -t $FASTLY_API_TOKEN -s $FASTLY_SERVICE_ID --version active

SUCCESS: Cloned service $FASTLY_SERVICE_ID version X to version Y
From now on, we will work on our cloned version by referring to it with --version latest. Let’s create a dictionary which will be used as on & off switch to enable and disable the maintenance page: 
fastly dictionary create -t $FASTLY_API_TOKEN -s $FASTLY_SERVICE_ID --version latest --name maintenance

SUCCESS: Created dictionary maintenance (id zHpEamIhKjDt7B28bSyRw4, service $FASTLY_SERVICE_ID, version Y)
Make a note of the given dictionary ID and let’s store it on a variable: 
export FASTLY_MAINTENANCE_DICT=zHpEamIhKjDt7B28bSyRw4
Let’s add an entry in the new dictionary which will be the actual on/off switch: 
fastly dictionary-entry create -t $FASTLY_API_TOKEN -s $FASTLY_SERVICE_ID --dictionary-id $FASTLY_MAINTENANCE_DICT --key maintenance --value=false

SUCCESS: Created dictionary item maintenance (service $FASTLY_SERVICE_ID, dictionary $FASTLY_MAINTENANCE_DICT)
We need a VCL to check for the key in the dictionary to know whether to return the maintenance page or not. Save the following VCL snippet in maintenance_recv.vcl: 
if (table.lookup(maintenance, "maintenance", "false") == "true") {
   error 653 "maintenance";
}
Let’s upload this maintenance_recv.vcl VCL to Fastly: 
fastly vcl snippet create -t $FASTLY_API_TOKEN -s $FASTLY_SERVICE_ID --version latest --name maintenance_recv --type recv --priority 50 --content maintenance_recv.vcl

SUCCESS: Created VCL snippet 'maintenance_recv' (service: $FASTLY_SERVICE_ID, version: Y, dynamic: false, snippet id: KdpZbSaxdj4bqP3kwKHt41, type: recv, priority: 50)
Save the maintenance page inside a VCL called maintenance_error.vcl like below. Note maintenance page goes within HTML tags: 
if (obj.status == 653) {
  set obj.status = 200;
  set obj.response = "OK";
  synthetic {"
    <html>
      <head>
      </head>
      <body>
        <h1>This site is under maintenance</h1>
      </body>
    </html>
  "};
  return(deliver);
}
Let’s create the maintenance_error.vcl VCL with the maintenance page in Fastly: 
fastly vcl snippet create -t $FASTLY_API_TOKEN -s $FASTLY_SERVICE_ID --version latest --name maintenance_error --type error --content maintenance_error.vcl

SUCCESS: Created VCL snippet 'maintenance_error' (service: $FASTLY_SERVICE_ID, version: Y, dynamic: false, snippet id: 3BcskRs1Z2Fo9GqidDwDf0, type: error, priority: 100)
We can now activate our changes: 
fastly service-version activate -t $FASTLY_API_TOKEN -s $FASTLY_SERVICE_ID --version latest

SUCCESS: Activated service $FASTLY_SERVICE_ID version Y

​
Testing

From now on, we can enable and disable our maintenance page in Fastly on demand by altering the key in the dictionary. We can enable it by setting the key value to true: 
fastly dictionary-entry update -t $FASTLY_API_TOKEN -s $FASTLY_SERVICE_ID --dictionary-id $FASTLY_MAINTENANCE_DICT --key maintenance --value=true

SUCCESS: Updated dictionary item (service $FASTLY_SERVICE_ID)

Dictionary ID: $FASTLY_MAINTENANCE_DICT
Item Key: maintenance
Item Value: true
Bear in mind it will take several seconds for Fastly to propagate the key value among their edge servers. You can browse to our website and check how the maintenance page is being served by Fastly. We can disable the maintenance page by altering the key to false in the dictionary: 
fastly dictionary-entry update -t $FASTLY_API_TOKEN -s $FASTLY_SERVICE_ID --dictionary-id $FASTLY_MAINTENANCE_DICT --key maintenance --value=false

SUCCESS: Updated dictionary item (service $FASTLY_SERVICE_ID)

Dictionary ID: $FASTLY_MAINTENANCE_DICT
Item Key: maintenance
Item Value: false
Maintenance page will disappear and the website will be live again.

​
Enable maintenance during deployment

If we want to display the maintenance page during deployment, we can do so by adding the variables and enable followed disable the page in the deployment hooks. We can add the variables to our project like below: 
upsun variable:create -p <PROJECT_ID> -e <PROD_ENVIRONMENT> --level environment --inheritable false --visible-build true --prefix env --no-wait --name FASTLY_SERVICE_ID --value $FASTLY_SERVICE_ID
upsun variable:create -p <PROJECT_ID> -e <PROD_ENVIRONMENT> --level environment --inheritable false --visible-build true --prefix env --no-wait --sensitive true --name FASTLY_API_TOKEN --value $ FASTLY_API_TOKEN
upsun variable:create -p <PROJECT_ID> -e <PROD_ENVIRONMENT> --level environment --inheritable false --visible-build true --prefix env --no-wait --name FASTLY_MAINTENANCE_DICT --value $FASTLY_MAINTENANCE_DICT
Note: Replace <PROJECT_ID> and <PROD_ENVIRONMENT> with your Upsun project info.Example:
  • <PROJECT_ID> = azertyuiop1234
  • <PROD_ENVIRONMENT> = main
We add enable and disable maintenance commands at the end of build and deploy hooks respectively: 
applications:
  app:
    hooks:
      build: |
        set -e
        #...
        brew install fastly/tap/fastly
        fastly dictionary-entry update -t $FASTLY_API_TOKEN -s $FASTLY_SERVICE_ID --dictionary-id $FASTLY_MAINTENANCE_DICT --key maintenance --value=true
    
      deploy: |
        set -e
        #...
        fastly dictionary-entry update -t $FASTLY_API_TOKEN -s $FASTLY_SERVICE_ID --dictionary-id $FASTLY_MAINTENANCE_DICT --key maintenance --value=false
Please note:The above commands can also be applied to Platform.sh projects by replacing upsun CLI by platform CLI in the call.

​
Updating maintenance page

What if we want to update the maintenance page in the future? For doing so, we update maintenance_error.vcl with our updated maintenance page within HTML tags. We create a new version, upload it and activate in Fastly: 
fastly service-version clone -t $FASTLY_API_TOKEN -s $FASTLY_SERVICE_ID --version active
fastly vcl snippet update -t $FASTLY_API_TOKEN -s $FASTLY_SERVICE_ID --version latest --name maintenance_error --type error --content maintenance_error.vcl
fastly service-version activate -t $FASTLY_API_TOKEN -s $FASTLY_SERVICE_ID --version latest

​
Adding allowed IPs while maintenance enabled

Let’s say that we want to allow some IP ranges to allow to reach the website when the maintenance page is enabled. This is useful when we need to perform tests and other tasks during mainteance window. In order to accomplish this, we will need to create an ACL with the excluded IP ranges and exclude this list when maintenance is enabled. Create a new version to make changes: 
fastly service-version clone -t $FASTLY_API_TOKEN -s $FASTLY_SERVICE_ID --version active
Create the ACL: 
$ fastly acl create -t $FASTLY_API_TOKEN -s $FASTLY_SERVICE_ID --version latest --name maintenance_ips
SUCCESS: Created ACL 'maintenance_ips' (id: yQImb1Ab1cIWaqBV42VWC2, service: $FASTLY_SERVICE_ID, version: 41)
Make a note of the given ACL ID and let’s store it on a variable: 
export FASTLY_MAINTENANCE_ACL=yQImb1Ab1cIWaqBV42VWC2
Let’s add an IP address and a network to it (these IP addresses are examples and add IP ranges you own instead): 
fastly acl-entry create -t $FASTLY_API_TOKEN -s $FASTLY_SERVICE_ID --acl-id $FASTLY_MAINTENANCE_ACL --ip 101.101.101.101 --comment VPN_IP
fastly acl-entry create -t $FASTLY_API_TOKEN -s $FASTLY_SERVICE_ID --acl-id $FASTLY_MAINTENANCE_ACL --ip 101.201.201.0 --subnet 24 --comment Office
Edit maintenance_recv.vcl VCL snippet like below: 
if (table.lookup(maintenance, "maintenance", "false") == "true") {
   if (!req.http.Fastly-Client-IP ~ maintenance_ips) {
      error 653 "maintenance";
   }
}
And upload it to Fastly: 
fastly vcl snippet update -t $FASTLY_API_TOKEN -s $FASTLY_SERVICE_ID --version latest --name maintenance_recv --type recv --content maintenance_recv.vcl
Active the new version to activate the changes: 
fastly service-version activate -t $FASTLY_API_TOKEN -s $FASTLY_SERVICE_ID --version latest
We will be able to browse to the website from IPs listed in the maintenance_ips ACL even after enabling the maintenance page.

​
Updating maintenance ACL IPs

We can add additional IPs to the maintenance ACL in the future without cloning the version. Just add them like this: 
fastly acl-entry create -t $FASTLY_API_TOKEN -s $FASTLY_SERVICE_ID --acl-id $FASTLY_MAINTENANCE_ACL --ip 55.55.55.55 --comment another_location

​
Summary

With your Fastly maintenance page configured, you can now automatically enable maintenance page in Fastly during deployments to Upsun. This setup provides: For more advanced configurations, explore Upsun’s API documentation to customize environment settings, manage resources, and integrate with your existing DevOps tools.
Create your Upsun account today.
Last modified on April 27, 2026