Skip to main content
Version: 0.4 · current

Plan a maintenance window

How-to guideReviewed October 11, 2026
Applies to:Excubius 0.4Roles: Operator, Editor, Entity admin
PlansFree · Core · Pro · EnterpriseDeploymentSelf-hosted

A maintenance window covers a period in which resources are expected to misbehave: a patch night, a failover test, a migration. During the window Excubius keeps watching and recording, but it does not notify anyone. This guide shows the three ways to create one, from the console and from the API.

Before you begin​

  • You need the Operator role or higher on the entity. Viewers can see windows but not create them.
  • Decide the scope: a whole entity (everything in it and below it) or some resources (and everything discovered under them, such as an instance's availability groups and databases).

Choose how to start​

NeedUse
The work starts right nowStart maintenance now: from 1 minute to 7 days
A planned nightSchedule a window › Once: start and end in your browser's time, up to a year long
A routine slotSchedule a window › Every week: weekdays, local start time, duration and time zone

Schedule a weekly window​

  1. Open Settings › Maintenance windows and choose the entity in the picker, for example Ciguapa Inc. › Production.
  2. Select Schedule a window.
  3. Write the Reason. It is internal: it appears in the console, in alert timelines and in the audit log, never on the status page.
  4. Choose Every week.
  5. Pick the Days, the Local start time, the Duration (minutes) and the Time zone, for example Saturday at 23:00 for 180 minutes in America/Santo_Domingo.
  6. Under Covers, keep All of Production, which names the entity you chose, or choose Only some resources and pick them.
  7. Optionally select Announce on the status page and give it a Public title and a Public description. Only those two texts are published.
  8. Select Save window. The window appears under Next 14 days.

For a one-off window, choose Once in step 4 and enter when it Starts and Ends, in your browser's time.

Start maintenance now​

  1. Open Settings › Maintenance windows and choose the entity.
  2. Under Start maintenance now, enter For (minutes) and the Reason, for example 45 minutes and Patching sql-ventas-02 (change CHG-2231).
  3. Under Covers, keep the whole entity, for example All of Production, or choose Only some resources and pick them.
  4. Select Start now.

The window appears under Active now with its end time. When the work finishes early, select End now on it.

What a window covers​

ScopeCovers
The entityEvery resource of the entity and of every entity below it, as the tree is at each moment: resources added or moved into the branch later are covered too
Some resourcesThe resources picked, of the entity or below it, and everything discovered under them: an instance's availability groups, databases and linked servers

An alert raised on an instance about one of its databases or linked servers is covered when that child is covered. A window on one database quiets that database's alerts and not the rest of the instance's.

What happens during the window​

  • Covered resources show the state Maintenance instead of their health, on dashboard cards, in resource lists and on the resource page.
  • Checks keep running and metrics keep being stored, so history stays complete and the true state is back the moment the window ends.
  • An alert that opens is marked with the window and nothing is sent. Its timeline says it opened during maintenance.
  • An alert that clears before the end resolves silently, since nothing was announced.
  • An alert still open when the window ends is announced then, as if it had just opened, through the usual routing, quiet period and silences.
  • The resource's timeline records when each window started and ended, and whether someone ended it early.
note

A maintenance window is not a silence. A silence quiets one existing alert for a while; a window quiets everything about a set of resources for a period, including alerts that do not exist yet.

Weekly windows and daylight saving time​

  • When clocks go forward, a start time that does not exist starts just after the jump.
  • When clocks go back, a start time that happens twice uses the first one.
  • The duration is elapsed time, so a window that spans a change ends one hour earlier or later on the wall clock.
  • A window may cross midnight or the end of the week: Sunday at 23:00 for three hours ends on Monday at 02:00. An occurrence lasts up to a week.
  • End now on a weekly window cuts only the current occurrence; the next ones happen as planned. Editing the schedule clears that.

Change or delete a window​

All windows lists the entity's own windows, those of the entities below it, and those inherited from its ancestors, marked From and the entity's name. Each has edit and delete actions.

Deleting an active window ends it first, and its timeline keeps the start and the end. Alerts it had marked keep their timeline entry but lose the link to the deleted window.

Roles and audit​

ActionRole on the window's entity
See windows, active and upcomingViewer
Create, start, edit, end or deleteOperator

Every change is written to the audit log: maintenance.create, maintenance.start_now, maintenance.update, maintenance.end and maintenance.delete.

From the API​

$BASE is https://<your server>/api/v1 and $TOKEN is your access token; see Quickstart: add a SQL Server instance with the API.

# a two-hour weekly slot for the whole Production branch
curl -sS -X POST "$BASE/maintenance-windows" -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{
"entity_id": "'"$PROD"'", "kind": "weekly", "reason": "Weekly index maintenance",
"weekly": {"days": ["sun"], "start_time": "02:00", "duration_minutes": 120,
"timezone": "America/Santo_Domingo"}}'

# sql-ventas-02 is being patched now, for 45 minutes
curl -sS -X POST "$BASE/maintenance-windows/now" -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{
"entity_id": "'"$PROD"'", "resource_ids": ["'"$SQL02"'"], "minutes": 45,
"reason": "Patching sql-ventas-02 (change CHG-2231)"}'

# done early
curl -sS -X POST "$BASE/maintenance-windows/$WINDOW/end" -H "Authorization: Bearer $TOKEN"
RequestPurpose
GET /maintenance-windows?entity={id}The windows of an entity, with those below it and those inherited; filter with state=active,scheduled,ended
GET /maintenance-windows/active and /upcomingWhat is in maintenance now, and what comes next
POST /maintenance-windowsCreate a window: kind is once (with starts_at and ends_at) or weekly (with weekly); scope is entity or resources (with resource_ids)
POST /maintenance-windows/nowStart one now for minutes, on the entity or on resource_ids
PATCH /maintenance-windows/{id}Change any field
POST /maintenance-windows/{id}/endEnd the active occurrence now
DELETE /maintenance-windows/{id}Delete a window; an active one is ended first

To announce a window on the status page, add "public": true with public_title and, optionally, public_description. A weekly window can be bounded with optional starts_at and ends_at: only occurrences that start between them count. A one-off window can record the time zone it was planned in with timezone.