URL readiness check

A wake is finished for Hibernator when the workloads are ready. It is finished for your users when the application answers. The URL readiness check watches for the second moment. Every value named here is in the table in configuration.md, under config.urlReadinessCheck.

• What the check does
• What a default install gets
• Configuration
• How it works
• SSRF protections
• Proxy configuration
• Tuning

What the check does

While a wake runs, the frontend can have the API send GET requests to the origin URL. The requests find out whether the application serves traffic again. The API uses GET, not HEAD, because a CDN or proxy cache can answer HEAD with an old 200 while the origin is down. The results go to the UI over SSE, and the “Return to Application” button shows the state.

The probe starts when the wake starts, not when it ends, so it can report the application usable while workloads still start. It has no attempt limit. It runs until the URL answers consecutiveThreshold times in a row, or until its own 75-minute backstop. A limit counted in attempts would be too short: a wake that holds a database tier can take 20 minutes alone.

The probe also continues for 10 minutes after the wake settles. The moment every workload is Ready is not the moment the application answers. Behind an ingress that must register the backends again, the HTTP path can return 504 and 404 for minutes after the last pod started. A probe that stopped with the transition would report “not confirmed” and never ask again. The way back into the application would then look as confident as when the application is up.

A URL that comes up inside those 10 minutes is still announced. A URL that does not is reported as a give-up. A transition that replaces the transition of the probe ends the probe early.

The origin-URL probe also observes the release of a wake. wake-order.md says what release changes.

What a default install gets

The check is off by default. It needs no IAM permission and no additional infrastructure.

A default install gets nothing from this check. No probe runs when enabled is false. No probe runs either when a user starts the wake from the Hibernator UI, which has no origin URL to return to. The user then stays on the transition overlay until the wake settles. Hibernator has no other signal to use instead: a signal for a cluster that configured none would be a guess.

Early release comes only when both conditions are true:

• enabled is true.
• Users reach Hibernator through a redirect from the application, so they have an origin URL.

Configuration

config:
  urlReadinessCheck:
    enabled: true
    proxyURL: "http://proxy.example.com:8080"  # Optional: corporate proxy for outbound requests
    whitelist:                                   # Optional: restrict allowed hostnames
      - "*.example.com"
      - "app.example.org"
    intervalSeconds: 5                           # Optional: seconds between checks (default: 5)
    consecutiveThreshold: 3                      # Optional: consecutive successes required (default: 3)

How it works

1. A user starts a wake in the UI.
2. When the wake starts, the frontend sends the origin URL to POST /api/v1/url-readiness-check.
3. The API validates the URL (scheme, whitelist, private IP blocking). Then it sends a GET request every intervalSeconds (default 5 seconds).
4. After consecutiveThreshold (default 3) successful responses in a row (2xx or 3xx), the URL is ready.
5. The API streams each readiness update to the frontend over SSE, with a running attempt count. There is no maximum to count against.
6. When the transition ends without a confirmation, the wake is reported as unverified. That is the correct verdict on the wake. The probe continues for 10 more minutes.
7. A probe without a success at the end of that window, or at the 75-minute backstop, gives up and reports it.
8. The “Return to Application” button and the way back on the status card both show the readiness state. The states are checking, not confirmed yet, ready and gave up.

SSRF protections

• SSRF protection: DNS pinning prevents DNS rebinding attacks. Private, loopback and link-local addresses are blocked.
• Scheme restriction: only http and https URLs are allowed.
• Whitelist: an optional list of allowed hostnames, with wildcards (for example *.example.com). When it is empty, every hostname that is not private is allowed.
• Rate limiting: one readiness check at a time per user.

Proxy configuration

If outbound traffic must go through a proxy, set proxyURL. When it is empty, the check uses config.proxyURL. With a proxy, the proxy resolves the host names and DNS pinning is off, because the proxy makes the connection.

Tuning

The defaults (3 checks × 5 seconds = 15 seconds of confirmed availability) suit most applications. For an application that needs more time to warm up, increase consecutiveThreshold. For faster feedback, decrease intervalSeconds (minimum 1 second). The API reads at most 1 KB of each response body and discards it, so a large response cannot use up its memory.