Overlays, cold restarts and restores¶
The Configuration view shows the session's baseline file and, under Changed from baseline, each setting in the current configuration that differs from the baseline.
Overlays, cold restarts and restores are exclusive actions.
Configuration overlays¶
An overlay is a partial fleet document that the service merges onto the current fleet configuration as a JSON merge patch (RFC 7386):
- An object merges key by key.
nullremoves a key, which returns the field to its default.- Any other value, arrays included, replaces the current value.
An overlay may change the slo, controller, serving and recovery sections, with the fields in Fleet schema, Serving and role control and Recovery and validation, plus keys that start with _.
For example, this overlay adds 10% of the TTFT target to the admission budget:
Apply an overlay¶
Applying an overlay requires the router_restart hook.
- Enter the overlay in the Configuration view.
- Select Check overlay. This dry run lists each setting the overlay changes, with its current and new value, or the validation errors.
- Select Apply overlay and confirm.
The service validates the merged configuration as narwhal config validate does, saves it in the session directory, and restarts the router with it through the router_restart hook.
Cold restart¶
Cold restart runs the cold_restart hook with the current fleet configuration file.
Restore the baseline¶
Restore baseline undoes the session's changes and leaves everything else running:
- If the configuration differs from the baseline, the service restarts the router with the baseline through the
router_restarthook. - It resumes each paused engine, starts each stopped engine and readmits each drained engine.
A session that changed nothing restores nothing. The session stays open.
Router readiness¶
After an overlay, a cold restart or a configuration restore, the service polls the router's GET /ready every second until it returns HTTP 200. When router.timeout_s passes first, the action fails with HTTP 504.
If the router_restart hook succeeds but the router misses that deadline, the overlay still applies to the session.