Maintenances

Maintenances in the Polycrate API: concrete, scheduled events with start and end time, their core fields, scope, affected resources, lifecycle, notifications, UI representation and API endpoints.

Maintenances

A Maintenance (Maintenance) is a concrete, scheduled event with a start and end time — for example "PostgreSQL 15 → 16 upgrade on 2026-04-22 02:00 to 04:00 UTC". Maintenances inform users proactively, appear in the Activity Timeline and the Downtime Timeline and distinguish announced outages from unplanned disruptions.

Core Fields

Field Meaning
name / display_name Title of the maintenance
message / embedded note Description / notice to those affected
scheduled_start / scheduled_end Planned period
progress_status Lifecycle — draft, scheduled, running, completed, cancelled
draft Boolean: true suppresses notifications (preparation)
organization Optional — null = system-wide maintenance (visible platform-wide)
workspace Optional — scope to one workspace (only with organization)
pop Primary PoP (display)
affected_pops M2M — all affected PoPs (canonical set)
affected_hosts M2M — affected hosts
affected_volumes M2M — affected K8sVolumes
provider Optional — linked provider (e.g. from a status feed)
reference_url Optional — link to the change ticket, playbook or similar

Scope

Scope organization workspace
System-wide null null
Organization set null
Workspace set set (must belong to the org)

Affected Resources

In addition to workspace and PoP scope, concrete resources can be linked:

  • affected_pops — multiple PoPs; pop remains the primary display PoP
  • affected_hosts / affected_volumes — finer-grained assignment for impact and filters in workspace/PoP/provider tabs
  • Automatic linking is possible via provider status ingestion and AI detection — see Incidents

Lifecycle

┌────────┐  publish  ┌───────────┐  scheduled_start  ┌─────────┐
│ draft  │──────────▶│ scheduled │──────────────────▶│ running │
└────────┘           └─────┬─────┘                   └────┬────┘
                           │                              │
                           │   cancel                     │ scheduled_end
                           ▼                              │ or end manually
                      ┌──────────┐                        ▼
                      │ cancelled│                  ┌───────────┐
                      └──────────┘                  │ completed │
                                                    └───────────┘
  • draft — created, not yet visible to recipients; no notifications
  • scheduled — published; notifications and timeline entries are created
  • running — scheduled_start reached
  • completed — scheduled_end reached or ended manually ahead of time (end=now)
  • cancelled — cancelled before execution

Notifications

Activity When
maintenance_scheduled On publishing from draft
maintenance_started When scheduled_start is reached
maintenance_ended When scheduled_end is reached or on manual end

Recipients are derived from contacts at organization/workspace level and their notification preferences. Every sent notification additionally creates an Activity entry.

Representation in the UI

  • List — filter by status, PoP, host, volume, period; active maintenances with in_progress badge
  • Detail — metadata, embedded note, tabs for affected hosts / volumes / PoPs, activity timeline
  • Downtime Timeline — maintenances as planned blocks next to unplanned downtimes
  • Operations Dashboard — upcoming and running maintenances

In Practice

Planned Upgrade Maintenance

  1. Create as draft (title, time window, workspace, optionally affected_hosts)
  2. Publish → maintenance_scheduled
  3. Work within the time window; clearly classify alerts as "during planned maintenance"
  4. End automatically or manually → maintenance_ended

System-wide Provider Maintenance

Provider status feeds (RSS/webhook) can, via AI, create a maintenance with organization=null, a linked provider and affected_pops / hosts / volumes. See DataSources and Incidents.

Post-Mortem

For unexpected problems during the maintenance: note kind=post-mortem and link to the maintenance or to downtimes — see Notes.

API

  • GET/POST /api/v1/maintenances/
  • PATCH /api/v1/maintenances/{id}/
  • POST /api/v1/maintenances/{id}/publish/
  • POST /api/v1/maintenances/{id}/cancel/
  • Writable M2M IDs include affected_host_ids, affected_volume_ids, affected_pop_ids

DRF basename: maintenance.

Related Topics