Maintenance Windows

Maintenance Windows in the Polycrate API: recurring policy templates for permitted maintenance slots, with time_slots, lead times, system default vs. scoped windows, interplay with maintenances, UI, API and RBAC.

Maintenance Windows

A Maintenance Window (MaintenanceWindow) is a policy template for permitted maintenance slots — for example "Every Sunday 02:00–04:00 Europe/Berlin". Maintenance windows describe when maintenances may take place (or typically take place), and with which lead times they have to be planned.

Core Fields

Field Meaning
name / display_name Name of the window, e.g. "Weekly maintenance window"
time_slots JSON list of entries {weekday, start, end, timezone}
lead_time_days Minimum lead time (in days) with which a maintenance must be announced
notice_required Boolean: Do maintenances in this window have to be announced?
is_system_default Boolean: global default window of the platform
organization / workspace Scope — who owns the policy (optional)

time_slots — Examples

[
  {"weekday": "sunday", "start": "02:00", "end": "04:00", "timezone": "Europe/Berlin"}
]

[
  {"weekday": "tuesday",  "start": "23:00", "end": "23:30", "timezone": "UTC"},
  {"weekday": "thursday", "start": "23:00", "end": "23:30", "timezone": "UTC"}
]

The slots are descriptive: Polycrate creates no automatic maintenances from them. They serve planning, display and validation.

What a Maintenance Window Is For

Planning frame

Teams see at a glance in which recurring slots maintenances are intended. The calendar view in the dashboard combines maintenance window slots with concrete maintenances.

Validation when creating a maintenance

If a workspace or an organization has a maintenance window, the UI checks when creating a maintenance whether the desired period lies within a slot. If it lies outside, a warning is shown (optionally a hard rejection if the policy requires it).

Lead time requirement

lead_time_days defines how far in advance a maintenance must be created. A maintenance that falls short of this is marked as "Emergency Maintenance".

Communication towards customers

An exportable maintenance window calendar serves as a service commitment: "We reserve these slots for upgrades; you can expect that things may get noisy there."

System Default vs. Own Windows

  • System default (is_system_default=true) — A global window that applies to all organizations if they have not defined their own. Maintained by: platform admins.
  • Organization or workspace windows — Override the system default for their scope. Multiple windows per scope are possible (e.g. "Standard" and "High-Risk").

Resolution order: workspace window → organization window → system default.

Interplay with Maintenances

Maintenance windows and maintenances are not linked by foreign key. A maintenance window:

  • creates no maintenances,
  • prevents no maintenances,
  • records the rule within which maintenances should ideally lie.

When a maintenance is created, the UI can give the following hints based on the applicable maintenance windows:

  • "Period lies outside a maintenance window"
  • "Lead time below the required lead_time_days → Emergency Maintenance"
  • "Overlap with an existing maintenance window slot → all good"

This gives teams a consistent checklist without taking away their freedom.

Representation in the UI

  • Maintenance window list per scope, with filtering by "active/inactive" and "default/override".
  • Detail view with all time_slots, lead_time_days, description, usage statistics (how many maintenances were scheduled in this window?).
  • Calendar: combined view that shows maintenance windows as background stripes and maintenances as colored blocks.
  • "Next slot" widget: shows the next available maintenance window slot per workspace.

API Endpoints

  • GET /api/v1/maintenance-windows/ — list
  • POST /api/v1/maintenance-windows/ — create (only for authorized admins)
  • PATCH /api/v1/maintenance-windows/{id}/ — edit (time_slots, lead_time_days)
  • GET /api/v1/maintenance-windows/{id}/applicability/ — "Does this period fit into a slot?" check

DRF router basename: maintenancewindow. (Not to be confused with maintenance for individual maintenances.)

RBAC

  • Read: All users of the scope see the maintenance window — transparent rule.
  • Edit: Organization admin for organization windows, platform admin for the system default.

Typical Use Cases

Standard slot for the Managed Platform

The platform defines a maintenance window "Sunday 02:00–04:00 Europe/Berlin" with lead_time_days=7 as the system default. This way every customer knows that interruptions are possible on Sunday mornings, and that announcements arrive at least one week before execution.

Customers with their own rules

A customer requires maintenances exclusively on Tuesday nights 23:00–23:30 UTC with 14 days lead time. A dedicated maintenance window is created for their organization, which overrides the system default.

Emergency Maintenance

For production-critical security patches, a maintenance is announced with less than lead_time_days. The UI marks it as "Emergency Maintenance" and notifies more broadly, so that the deviation from the rule is visible.

Related Topics