Show your own page when no origin answers

Replace the 502, 503, and 504 responses of a workload with your own page, served from a connector that reaches none of the failing origins.

Last updated

View as Markdown Agent setup

You replace the error a workload returns when no origin answers with a page of your own, from Azion Console or the API. To replace other status codes, such as a 404, refer to Customize an error page.

When no origin server can be selected, a request carries the upstream status 502. When an HTTPS origin refuses the TLS handshake, the client receives 502 with the page titled Azion - Default error page. A custom page set binds a status code to a page that a connector serves. A page for a code tagged Azion in the Console replaces the default Azion page.

  1. A request reaches the connector that the application’s Set Connector rule names.
  2. When an origin answers, the client receives its response.
  3. When no origin answers, the response carries a 502 or a 504, and the custom page set of the workload’s deployment holds a page for that code.
  4. Azion fetches the page from the page’s own connector, at the page’s path.
  5. The client receives the page in place, with no redirect, and with the page’s custom status code.

Prerequisites

  • A workload whose deployment names an application. To create one, refer to Workloads quickstart.
  • A connector that serves your error page at a path and reaches none of your origins, such as a connector of type storage that reads an Object Storage bucket. For its fields, refer to Connector settings.
  • Access to Azion Console, for the Console procedure. Refer to Access Azion Console.
  • A personal token for the API procedure, with the ID of the page’s connector, of the workload, of its deployment, and of the application the deployment names. If the deployment names a firewall, its ID too.

The examples serve the page at /errors/503.html on a connector named error-pages, for the domain www.example.com. Replace them with yours.

Create a set with a page for each code

The set binds 502, 503, and 504 to the same page. In the Custom page settings, 502 is a gateway that received an invalid response, 503 a server that is not ready, and 504 a gateway that received no response in time. Each page answers with 503, which marks a temporary condition.

The page comes from a connector that reaches none of your origins, because a page fetched from a failing origin fails with it. Response TTL sets how many seconds the page stays in cache, from 0 to 31,536,000. An error page is static and rarely changes, so a high value, such as 86400, one day, keeps requests away from the page’s connector.

To create the set in Azion Console:

Open the Custom Pages page

Access Azion Console > Custom Pages.

Start the set

Select Create Custom Page.

Name the set

In Name, enter a name that identifies the set, such as origin-down.

Select Create Custom Page Code
Select the status code

In Page Code, select 502.

Keep the connector page type

In Type, keep Page Connector.

Select the page's connector

In Connector, select error-pages.

Enter the page path

In Page Path (URI), enter /errors/503.html.

Set the cache time and the status

Enter 86400 in Response TTL and 503 in Response Custom Status Code.

Add the 503 and 504 codes

Select Create Custom Page Code again for Page Code 503 and 504, with the same connector, path, Response TTL, and Response Custom Status Code.

Select Create

The Page Codes table lists one row per page, with its Page Status Code, Page Path (URI), Custom Status Code, and Response TTL.

The set holds one page for each of the three codes. It serves nothing until a workload’s deployment names it.

Assign the set in the workload’s deployment

The deployment of a workload names its application, its firewall, and its custom page set. Only the custom page set changes here, so the application and the firewall keep the values the workload uses today. The Azion CLI sets the custom page set only when it creates a deployment, and a workload holds one deployment, so this task uses Azion Console or the API.

To assign the set in Azion Console:

Open the Workloads page

Access Azion Console > Workloads.

Open the workload

Select the workload that serves www.example.com.

Select the set

In Deployment Settings, select origin-down in Custom Page. Keep Application and Firewall as they are.

Select Save

Azion Console shows Your workload has been updated.

The deployment of the workload names the set. A deployment change takes several minutes to reach Azion’s distributed infrastructure, and requests can receive Azion’s default page until it does.

Confirm the page replaces the error

The check takes your origins out of service, so run it in a maintenance window.

To confirm the page:

Stop every origin of the application's connector

Stop the web server on each origin, or block the connections from Azion at its firewall.

Request your domain
curl -s -D - https://www.example.com/
Start the origins again

The response carries status 503, from the page’s Response Custom Status Code, and the body of /errors/503.html, not the page titled Azion - Default error page. It carries no Location header, so the client is not redirected. If the default page still arrives after the deployment change has spread, refer to Troubleshoot Workloads.

Next steps

Custom page settingsEvery field of a set and its pages, and the 22 status codes a page can replace.Add a backup origin to a connectorKeep a standby origin answering before the error page is needed.Customize an error pageReplace the error responses of other status codes, each page with its own cache time.Keep an application online when an origin failsA primary and a standby origin in one pool, with this page when both fail.