Maintenance examples

Sources live under examples/maintenance/.

Global always-on (status probe)

Hosts in maintenance.hosts with no window are active whenever the hostname matches. Use GET /_/ingress/status to probe maintenance state for a Host (returns {"status":"ok"} or {"status":"maintenance",...}).

version: v1
port: 8080

# Global maintenance for listed hosts within maintenance.hosts[].window.
# Probe: curl -sS -D - http://app.example.com/_/ingress/status
maintenance:
  hosts:
    - host: app.example.com
      window:
        start: "2026-01-01T00:00:00Z"
        end: "2026-12-31T23:59:59Z"
    - host: staging-*.example.com
      window:
        start: "2026-01-01T00:00:00Z"
        end: "2026-12-31T23:59:59Z"
  title: Site maintenance
  subtitle: We will be back shortly.
  retry_after: 3600

rules:
  - host: app.example.com
    backend:
      service:
        name: httpbin.org
        port: 443
        protocol: https
  - host: staging-api.example.com
    backend:
      service:
        name: httpbin.org
        port: 443
        protocol: https

curl -sS http://app.example.com/_/ingress/status
curl -sS -D - http://app.example.com/api   # 503 + X-Ingress-Maintenance: 1 when active

Global maintenance + bypass

version: v1
port: 8080

# Global maintenance with bypass: /healthz still reaches the handler; other paths get 503.
maintenance:
  hosts:
    - host: app.example.com
      window:
        start: "2026-01-01T00:00:00Z"
        end: "2026-12-31T23:59:59Z"
  title: Planned maintenance
  retry_after: 600
  bypass:
    paths:
      - /healthz
      - /metrics/*
    header:
      name: X-Maintenance-Bypass
      value: secret-token

rules:
  - host: app.example.com
    backend:
      service:
        name: httpbin.org
        port: 443
        protocol: https
    paths:
      - path: /healthz
        backend:
          type: handler
          handler:
            status_code: 200
            headers:
              Content-Type: application/json
            body: '{"ok":true}'

While maintenance is active, /healthz (handler) and requests with X-Maintenance-Bypass: secret-token pass through; other paths receive 503.

Route scope: all

version: v1
port: 8080

# Route-level maintenance: scope all blocks every host matched by the rule.
rules:
  - host: app.example.com
    backend:
      type: service
      service:
        name: httpbin.org
        port: 443
        protocol: https
        maintenance:
          enabled: true
          scope: all
          window:
            start: "2026-01-01T00:00:00Z"
            end: "2026-12-31T23:59:59Z"
          title: Application maintenance
          subtitle: Upgrading the app stack.
          retry_after: 1800

Route scope: listed + per-host windows

version: v1
port: 8080

# Route-level maintenance: scope listed applies only to maintenance.hosts on the rule.
rules:
  - host: "*.example.com"
    backend:
      type: service
      service:
        name: httpbin.org
        port: 443
        protocol: https
        maintenance:
          enabled: true
          scope: listed
          hosts:
            - host: legacy.example.com
              window:
                start: "2026-12-01T00:00:00Z"
                end: "2026-12-01T06:00:00Z"
            - host: beta.example.com
              window:
                start: "2026-12-01T00:00:00Z"
                end: "2026-12-01T06:00:00Z"
          title: Legacy stack maintenance

Custom maintenance response header

version: v1
port: 8080

# Custom maintenance response header (default is X-Ingress-Maintenance: 1).
maintenance:
  hosts:
    - host: app.example.com
      window:
        start: "2026-01-01T00:00:00Z"
        end: "2026-12-31T23:59:59Z"
  title: Planned maintenance
  response_header:
    name: X-Custom-Maintenance
    value: "yes"

rules:
  - host: app.example.com
    backend:
      type: service
      service:
        name: httpbin.org
        port: 443
        protocol: https

Custom status probe path

version: v1
port: 8080

# Custom JSON status probe path (default is /_/ingress/status).
maintenance:
  status_path: /internal/ingress-status
  hosts:
    - host: app.example.com
      window:
        start: "2026-01-01T00:00:00Z"
        end: "2026-12-31T23:59:59Z"
  title: Planned maintenance

rules:
  - host: app.example.com
    backend:
      type: service
      service:
        name: httpbin.org
        port: 443
        protocol: https

Custom status probe response body

version: v1
port: 8080

# Custom JSON body for the maintenance status probe (default is built-in status/title fields).
maintenance:
  hosts:
    - host: app.example.com
      window:
        start: "2026-01-01T00:00:00Z"
        end: "2026-12-31T23:59:59Z"
  title: Planned maintenance
  retry_after: 300
  status_response:
    ok: '{"ready":true,"host":"${host}"}'
    maintenance: '{"ready":false,"message":"${title}","retry_after":${retry_after}}'
    content_type: application/json; charset=utf-8

rules:
  - host: app.example.com
    backend:
      type: service
      service:
        name: httpbin.org
        port: 443
        protocol: https

Global + route-level combined

version: v1
port: 8080

# Combined global + route-level maintenance with per-host time windows and bypass.
maintenance:
  hosts:
    - host: app.example.com
      window:
        start: "2026-05-30T02:00:00+08:00"
        end: "2026-05-30T06:00:00+08:00"
    - host: staging-*.example.com
      window:
        start: "2026-05-30T02:00:00+08:00"
        end: "2026-05-30T18:00:00+08:00"
  title: Planned maintenance
  subtitle: We will be back shortly.
  retry_after: 3600
  bypass:
    paths:
      - /healthz
    header:
      name: X-Maintenance-Bypass
      value: secret-token

rules:
  - host: "*.example.com"
    backend:
      type: service
      service:
        name: httpbin.org
        port: 443
        protocol: https
        maintenance:
          enabled: true
          scope: listed
          hosts:
            - host: legacy.example.com
              window:
                start: "2026-05-31T00:00:00+08:00"
                end: "2026-05-31T01:00:00+08:00"
          title: Legacy stack maintenance

Validate

ingress validate -c examples/maintenance/global-always-on.yaml
ingress validate -c examples/maintenance/global-bypass.yaml
ingress validate -c examples/maintenance/route-scope-all.yaml
ingress validate -c examples/maintenance/route-scope-listed.yaml
ingress validate -c examples/maintenance/custom-response-header.yaml
ingress validate -c examples/maintenance/custom-status-path.yaml
ingress validate -c examples/maintenance/custom-status-response.yaml
ingress validate -c examples/maintenance/ingress.yaml

See Maintenance guide for semantics, response headers, and access-log fields.