Maintenance mode

Maintenance mode directs a web service's public ingress to a maintenance responder. Use it when you need to stop normal public requests while preparing or checking an application change.

It does not itself suspend the service, stop background writers, or block private connections. The service's independent suspension and scaling settings still apply. For a database cutover, stop every relevant writer separately; see the migration procedure.

Prerequisites​

Bex supports maintenance mode for paid web services. Free web services and other service types are rejected. You need operate access to the service and an API bearer token for API calls.

The installation must have working public ingress and the shared maintenance responder. Saving the setting requests a routing change; verify the response from each public hostname before relying on it.

Enable the default response​

Set SERVICE_ID to the ID returned by Bex. This PATCH updates the serviceDetails.maintenanceMode object:

curl --fail-with-body --silent --show-error \
  -X PATCH "$BEX_API_URL/v1/services/$SERVICE_ID" \
  -H "Authorization: Bearer $BEX_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"serviceDetails":{"maintenanceMode":{"enabled":true,"uri":""}}}'

Supply both enabled and uri whenever you supply that object. An empty uri selects the built-in maintenance page. Omitting the whole object leaves the setting unchanged.

For a Blueprint-managed service, declare the setting in its service entry so the next sync preserves your intent:

maintenanceMode:
  enabled: true
  uri: ""

This is a fragment of an existing paid web service entry, not a complete manifest. Validate the complete manifest before applying it.

Verify public and private behavior​

Set PUBLIC_URL to a returned service URL or a configured custom-domain URL:

curl --silent --show-error --include "$PUBLIC_URL"

The built-in response uses 503 Service Unavailable and Cache-Control: no-store. Check the platform hostname and each custom domain you use. A stored enabled: true alone does not prove ingress has reconciled.

Where private access is configured, verify it separately from an authorized workload. Maintenance mode changes public routing, not private-network policy. Existing work or long-lived connections should not be treated as canceled by a routing change.

If public traffic still reaches the application, have the installation operator check ingress reconciliation and the maintenance responder before proceeding. Do not substitute suspension without considering its separate effects on the workload.

Use a custom page​

Set uri to an absolute HTTP or HTTPS URL served independently of this Bex installation. Bex rejects URLs pointing to the same service, reserved platform hosts, or another service's claimed hostname on the platform, to prevent fetch loops. A static site on the same Bex installation is therefore not a suitable custom-page host.

The responder fetches that page. A successful upstream response is served with maintenance status 503; upstream error statuses are preserved. A fetch or response-size failure returns 502, rather than silently selecting the default page. Test the actual public response, including body and status, before the maintenance window.

Restore normal traffic​

Send the same PATCH with {"enabled":false,"uri":""} inside serviceDetails.maintenanceMode. This disables maintenance and clears the custom URL. To retain a custom URL for later, send that URL with enabled: false. Update the Blueprint declaration too if it manages the setting.

Read the service back and verify normal responses on every public hostname. If traffic still fails, check readiness, suspension, scaling, and DNS; disabling maintenance does not repair an unhealthy application. Ordinary redeployment does not itself clear the maintenance setting.

Use audit logs to inspect maintenance changes and application logs to check application behavior after reopening.