Configure Waiting and Maintenance Pages for HTTP Scaler

This guide explains how to configure Kedify’s HTTP Scaler to serve static waiting and maintenance pages during cold-starts or when your application is temporarily unavailable. This feature is particularly useful for providing a better user experience by displaying informative messages and re-routing the traffic away from your application when it’s not ready.

Custom Cold-Start Waiting Page

During cold-starts, the default behavior of Kedify’s HTTP Scaler is to hold the request for a configurable duration until the application is scaled out to at least one replica and is ready to serve traffic. If the application bootstrapping takes longer, this can lead to timeouts and a poor user experience. With the custom waiting page feature, you can configure Kedify to serve a static HTML page while the application is scaling up and have informative responses for the users served immediately. There is a 256 KiB limit on the size of the waiting page body.

Enabling Cold-Start Waiting Page

This feature is enabled per ScaledObject as part of kedify-http scaler with trigger metadata coldStartWaitingPageEnabled set to true:

spec:
  triggers:
    - type: kedify-http
      metadata:
        coldStartWaitingPageEnabled: 'true'

Then during the cold-start interceptor no longer holds the proxied request for this application but instead responds directly with static page and Retry-After response HTTP header. The HTTP metrics are still accounted for so the scaling is not disrupted.

The default status code is 503, retry header 10s, and HTTP body reads a simple message:

Service is starting, try again later.

Customizing Cold-Start Waiting Page with Global Defaults

These defaults can be configured globally in the Kedify HTTP Addon helm chart:

interceptor:
  coldStartWaitingPage:
    body: |-
      <html>
        <head>
          <title>Service is starting</title>
        </head>
        <body>
          <h1>Service is starting</h1>
          <p>Please try again later.</p>
        </body>
      </html>
    responseStatusCode: 503
    retryAfter: 30s

Example of Customizing Cold-Start Waiting Page with ConfigMap

As an alternative, it’s possible to define cold-start waiting page parameters per namespace in a ConfigMap with the same keys coldStartWaitingPageBody / coldStartWaitingPageStatusCode / coldStartWaitingPageRetryAfter and then setting coldStartWaitingPageConfigMapRef on trigger metadata.

spec:
  triggers:
    - type: kedify-http
      metadata:
        coldStartWaitingPageEnabled: 'true'
        coldStartWaitingPageConfigMapRef: waiting-page-cm

The ConfigMap example:

apiVersion: v1
kind: ConfigMap
metadata:
  name: waiting-page-cm
data:
  coldStartWaitingPageBody: |-
    <html>
      <head>
        <title>Service is starting</title>
      </head>
      <body>
        <h1>Service is starting</h1>
        <p>Please try again later.</p>
      </body>
    </html>
  coldStartWaitingPageStatusCode: '503'
  coldStartWaitingPageRetryAfter: '60s'

Example of Customizing Cold-Start Waiting Page with Inlined Configuration

The global and namespaced defaults can be further fine tuned by inlining directly on the ScaledObject as

spec:
  triggers:
    - type: kedify-http
      metadata:
        coldStartWaitingPageEnabled: 'true'
        coldStartWaitingPageBody: |-
          <html>
            <head>
              <title>Service is starting</title>
            </head>
            <body>
              <h1>Service is starting</h1>
              <p>Please try again later.</p>
            </body>
          </html>
        coldStartWaitingPageStatusCode: '503'
        coldStartWaitingPageRetryAfter: '60s'

Custom Maintenance Page

When you want to make the application temporarily unavailable for any reasons, e.g. scheduled maintenance, and prevent traffic reaching your service, you can configure Kedify to serve a static maintenance page instead of the default 503 Service Unavailable response. This allows you to inform users about the maintenance and provide an estimated time for when the service will be back online. There is a 256 KiB limit on the size of the maintenance page body.

This is also enabled per ScaledObject that has kedify-http scaler with trigger metadata maintenancePageEnabled set to true:

spec:
  triggers:
    - type: kedify-http
      metadata:
        maintenancePageEnabled: 'true'

The difference is that when maintenance page is enabled, the traffic for this particular ScaledObject is served directly by the interceptor always and http metrics for the target are discarded by the scaler. The /queue endpoint on the interceptor will still show the metrics as if they were accounted, but scaler discards the values and sets active status for particular application to false.

The default status code is 503, and HTTP body reads a simple message:

Service is temporarily under maintenance. Please try again later.

Customizing Maintenance Page with Global Defaults

These defaults can be configured globally in the Kedify HTTP Addon helm chart:

interceptor:
  maintenancePage:
    body: |-
      <html>
        <head>
          <title>Service is under maintenance</title>
        </head>
        <body>
          <h1>Service is under maintenance</h1>
          <p>Please try again later.</p>
        </body>
      </html>
    responseStatusCode: 503

Example of Customizing Maintenance Page with ConfigMap

As an alternative, it’s possible to define maintenance page parameters per namespace in a ConfigMap with the same keys maintenancePageBody / maintenancePageStatusCode and then setting maintenancePageConfigMapRef on trigger metadata.

spec:
  triggers:
    - type: kedify-http
      metadata:
        maintenancePageEnabled: 'true'
        maintenancePageConfigMapRef: maintenance-page-cm

The ConfigMap example:

apiVersion: v1
kind: ConfigMap
metadata:
  name: maintenance-page-cm
data:
  maintenancePageBody: |-
    <html>
    <head>
        <title>Service is under maintenance</title>
    </head>
    <body>
        <h1>Service is under maintenance</h1>
        <p>Please try again later.</p>
    </body>
    </html>
  maintenancePageStatusCode: '503'

Example of Customizing Maintenance Page with Inlined Configuration

The global and namespaced defaults can be further fine tuned by inlining directly on the ScaledObject as

spec:
  triggers:
    - type: kedify-http
      metadata:
        maintenancePageEnabled: 'true'
        maintenancePageBody: |-
          <html>
            <head>
              <title>Service is under maintenance</title>
            </head>
            <body>
              <h1>Service is under maintenance</h1>
              <p>Please try again later.</p>
            </body>
          </html>
        maintenancePageStatusCode: '503'

Configuration Precedence

Maintenance page and cold-start waiting page configurations follow this precedence (highest to lowest):

Inline configuration in ScaledObject
Namespace-scoped ConfigMap referenced by maintenancePageConfigMapRef or coldStartWaitingPageConfigMapRef
Global defaults configured on http-add-on chart

The ConfigMaps for maintenancePage and coldStartWaitingPage can be the same.