site-failover

Site-failover defines an alternate response to serve when the edge server cannot contact the origin server. The response can be a 301 or 302 HTTP Redirect, or content retrieved from an alternate location.defined in the site-failover behavior.

If the fail-action retrieves content from an alternate origin, you can also configure special downstream caching rules to prevent the end client from caching the fail-action content. This Downstream-Caching behavior is explained below in this section.

Example Use Case

Imagine that you have configured their domain (www.example.com) to serve content from the origin server located at origin111.k5.com. Further imagine that the content at origin111.k5.com is mirrored at origin222.k5.com. Since the content can be retrieved from a second source, you might desire to use that source as the failover when the primary origin is not available.

To configure this, you would do the following:

  • Create a separate "alternate hostname" that will resolve to the Multi-Domain Config Edge Hostname used by www.example.com. For example, they could create failover. example.com and CNAME it to the same MDC hostname as www.example.com.
  • Create a rule for fail-over.example.com that sets the origin-server behavior to retrieve content from origin222.k5.com. (Optionally, you could add the special downstream-caching behavior to this rule.)
  • Add the site-failover behavior to the rule for www.example.com. This rule would set the alternateHostname element to fail-over.example.com.

Note: In case the customer does not have their own domain, the configuration that our 2 grant domains are created by the delivery settings and the cdn-edge domain B is changed to wording to failover.example.com and the cdn-edge domain A is changed to wording to example.com is allowed.

Preconditions and Exceptions

In all failover actions, it is assumed that you would have an alternate hostname and alternate origin where they have completely or partially mirrored the site's content. This alternate origin must be configured before the site-failover behavior is provisioned as a rule behavior. The alternate hostname might be served by a CDN platform in the region, in other region or elsewhere. If the alternate hostname is also not reachable, then there is no second level failover action.

Note: The alternative origin server can be deployed in another region of FJCS for OSS.

The setting that can be specified by the type parameter (required) is as follows.

  • serve-301 – Failover action is to "redirect" end client to the alternateHostname and alternatePath with the status code 301
  • serve-302 – Failover action is to "redirect" end client to the alternateHostname and alternatePath with the status code 302
  • serve-alternate – Failover action is to automatically send a request to the alternateHostname and alternatePath to retrieve alternate content.

The setting that can be specified by the params parameter (required) is as follows.

  • httpResponseStatus
    • A space separated list of HTTP status code(s) with integer ranges allowed.

      These are the status codes that would have been served to the client if no site-failover action had been declared. The status codes could have been received from the origin or generated by the edge server due to connection or read timeouts. For example: 500 503:504 For example: 500 503:504

  • alternateHostname
    • -: A hyphen assigns no alternate hostname. The original hostname will be used to construct the new URL
    • valid_domain.com: A valid domain which would serve as the alternate hostname for the failover request.

      For example: failover.example.com

  • alternatePath
    • -: A hyphen assigns no alternatePath. The original path (with filename) will be used with the alternateHostname to construct the new URL.
    • The value of alternatePath completely replaces the path and filename in the original request URL. The alternatePath may also contain a query string, in which case preserveQueryString should be set to false. /valid_path/ : Valid URI path that begins and ends with a forward slash "/" Example: /dir1/filename.ext
    • In this case, only the path portion of the original request URI is replaced with the alternatePath. The original filename is retained in the newly constructed URL. Example: /dir1/dir2/
  • preserveQueryString
    • true – The query string in the original request URL should be retained in the new URL for the redirect or alternate forward request.
    • false – The query string in the original URL request should be removed in the new URL for the redirect or forward request.


       { 
         "rules": [
           {
             "matches": [
               {
                 "name": "http-method",
                 "value": "GET"
               }
             ],
             "behaviors": [
               {
                 "name": "site-failover",
                 "type": "serve-301",
                 "params": {
                   "httpResponseStatus": "404 500:504",
                   "alternateHostname": "www.alternatehostname.com",
                   "alternatePath": "/newdir1/newdir2",
                   "preserveQueryString": true
                 }
               }
             ]
           }
         ]
       }

The definition of site-failover must not specify both alternateHostname and alternatePath as hyphen (-). This would lead to a failover back to the already failing origin.

If "preserveQueryString" is true, the alternatePath cannot have query parameters in it. If it does, this would be a JSON validation error. In short, new query strings cannot be added to existing query strings.

downstream-caching

You can use the downstream-caching behavior to control downstream caching of alternate content. (The only values supported currently are to bust the downstream cache.)

In the absence of this behavior in the "alternate hostname"'s policy, the default downstream caching behavior as specified in the base CDN default configuration for the "alternate hostname" will be used.

The setting for which value can be specified is as follows

  • no-store – the alternate response is served with an HTTP Cache-Control: no-store header.
  • no-cache – the alternate response is served with an HTTP Cache-Control: no-cache header.

In the example below, all GET requests for alternate content receive a downstreamcaching setting of no-store.


       {
         "rules": [ 
           {
             "matches": [
               {
                 "name": "http-method",
                 "value": "GET"
               }
             ],
             "behaviors": [
               {
                 "name": "downstream-caching",
                 "value": "no-store"
               }
             ]
           }
         ]
       }