> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kodostatus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Scheduled Maintenance

> Plan and communicate maintenance windows to your users

Scheduled maintenance lets you proactively communicate planned downtime to your users. Unlike incidents (which are unexpected), maintenance is planned and communicated in advance.

## Why Schedule Maintenance?

* **Set expectations**: Users know downtime is planned, not a surprise outage
* **Reduce support tickets**: Proactive communication prevents confusion
* **Build trust**: Transparency about maintenance shows reliability
* **Automatic status updates**: Status page automatically reflects maintenance state

## Maintenance States

| State         | Description                           | Status Page Display               |
| ------------- | ------------------------------------- | --------------------------------- |
| `scheduled`   | Maintenance is planned for the future | Shows upcoming maintenance banner |
| `in_progress` | Maintenance has started               | Services show "Under Maintenance" |
| `completed`   | Maintenance finished successfully     | Normal status restored            |
| `cancelled`   | Maintenance was cancelled             | Removed from schedule             |

## Creating Maintenance Windows

<Tabs>
  <Tab title="Dashboard">
    1. Go to **Dashboard → Maintenance → Schedule Maintenance**
    2. Fill in the details:
       * **Title**: "Database Migration" or "Infrastructure Upgrade"
       * **Description**: What you're doing and expected impact
       * **Start Time**: When maintenance begins
       * **End Time**: Expected completion time
       * **Affected Services**: Which services will be impacted
    3. Choose notification settings:
       * Notify subscribers when scheduled
       * Notify when maintenance starts
       * Notify when maintenance completes
    4. Click **Schedule Maintenance**
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    # Schedule maintenance
    kodo maintenance create \
      --title "Database Migration" \
      --description "Migrating to new database cluster. Expect 30 minutes of read-only access." \
      --start "2024-02-01T02:00:00Z" \
      --end "2024-02-01T04:00:00Z" \
      --services api,database \
      --notify-subscribers
    ```
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    curl -X POST "https://kodostatus.com/api/v1/maintenance" \
      -H "X-API-Key: your_api_key" \
      -H "Content-Type: application/json" \
      -d '{
        "title": "Database Migration",
        "description": "Migrating to new database cluster. Expect 30 minutes of read-only access.",
        "scheduled_start": "2024-02-01T02:00:00Z",
        "scheduled_end": "2024-02-01T04:00:00Z",
        "service_ids": ["svc_api", "svc_database"],
        "notify_subscribers": true
      }'
    ```
  </Tab>
</Tabs>

## Managing Maintenance

### Starting Maintenance Early

If you're ready to begin before the scheduled time:

```bash theme={null}
kodo maintenance start maint_abc123
```

### Extending Maintenance

If maintenance is taking longer than expected:

```bash theme={null}
kodo maintenance update maint_abc123 --end "2024-02-01T05:00:00Z"
```

This notifies subscribers of the updated timeline.

### Completing Maintenance

When maintenance is finished:

```bash theme={null}
kodo maintenance complete maint_abc123 --message "Migration completed successfully"
```

### Cancelling Maintenance

If plans change:

```bash theme={null}
kodo maintenance cancel maint_abc123 --reason "Rescheduling due to critical bug fix needed"
```

Subscribers are notified of the cancellation.

## Subscriber Notifications

Kodo sends notifications at key points:

1. **When scheduled**: "Scheduled maintenance: Database Migration on Feb 1, 2:00 AM UTC"
2. **Reminder** (optional): "Reminder: Maintenance begins in 1 hour"
3. **When started**: "Maintenance in progress: Database Migration"
4. **When completed**: "Maintenance completed: Database Migration"
5. **If cancelled**: "Maintenance cancelled: Database Migration"

## Best Practices

<AccordionGroup>
  <Accordion title="Schedule during low-traffic periods">
    Use your analytics to identify the lowest-traffic window for your users' timezones.
  </Accordion>

  <Accordion title="Provide specific time estimates">
    "2-4 hours" is better than "several hours". Be realistic—it's better to finish early than extend.
  </Accordion>

  <Accordion title="Explain the impact">
    Tell users exactly what they can and cannot do during maintenance: "API read operations will work, writes will return 503."
  </Accordion>

  <Accordion title="Communicate completion">
    Always mark maintenance as complete—don't leave users wondering if it's still ongoing.
  </Accordion>

  <Accordion title="Post updates during long maintenance">
    For maintenance over 1 hour, post periodic updates: "50% complete, on track to finish by 4 AM."
  </Accordion>
</AccordionGroup>

## Recurring Maintenance

For regular maintenance windows (weekly backups, monthly updates):

```bash theme={null}
# Create recurring maintenance template
kodo maintenance create \
  --title "Weekly Database Backup" \
  --recurrence "weekly" \
  --day "sunday" \
  --start-time "03:00" \
  --duration "1h" \
  --services database
```

## Integration with Monitors

During scheduled maintenance:

* Uptime monitors are automatically **paused** for affected services
* This prevents false alerts during planned downtime
* Monitors automatically resume when maintenance completes

You can disable this behavior per-maintenance if needed:

```bash theme={null}
kodo maintenance create ... --keep-monitors-active
```