diff --git a/constructs/maintenance-window.mdx b/constructs/maintenance-window.mdx index d259b717..510cfe60 100644 --- a/constructs/maintenance-window.mdx +++ b/constructs/maintenance-window.mdx @@ -47,10 +47,14 @@ new MaintenanceWindow("weekly-backup", { | `name` | `string` | ✅ | - | Name of the maintenance window | | `startsAt` | `Date` | ✅ | - | Start date and time (ISO 8601 timestamp) | | `endsAt` | `Date` | ✅ | - | End date and time (ISO 8601 timestamp) | -| `tags` | `string[]` | ✅ | - | Tags that filter which checks are affected | +| `tags` | `string[]` | ❌ | `[]` | Tags that filter which checks are paused | | `repeatInterval` | `number` | ❌ | - | Repeat interval from the first occurrence | -| `repeatUnit` | `string` | ❌ | - | Repeat strategy: `'WEEK'` \| `'MONTH'` \| `'YEAR'` | +| `repeatUnit` | `string` | ❌ | - | Repeat strategy: `'DAY'` \| `'WEEK'` \| `'MONTH'` | | `repeatEndsAt` | `Date` | ❌ | - | When to stop repeating (ISO 8601 timestamp) | +| `timezone` | `string` | ❌ | UTC | IANA time zone used to schedule recurring occurrences | +| `pauseAllChecks` | `boolean` | ❌ | `false` | Pause every check in the account, regardless of `tags` | +| `silenceAlertsTags` | `string[]` | ❌ | `[]` | Tags that filter which checks have their alerts silenced | +| `silenceAllAlerts` | `boolean` | ❌ | `false` | Silence alerts for every check in the account | ### `MaintenanceWindow` Options @@ -69,9 +73,9 @@ new MaintenanceWindow("my-maintenance", { **Use cases**: Window identification, dashboard display, maintenance tracking. - + -Tags that filter which checks are affected by this maintenance window. Checks with ANY of these tags will be paused during the maintenance period to avoid unnecessary alerts. +Tags that filter which checks are affected by this maintenance window. Checks with ANY of these tags will be paused during the maintenance period to avoid unnecessary alerts. Not needed when `pauseAllChecks` is `true`. **Usage:** @@ -216,6 +220,80 @@ new MaintenanceWindow("limited-recurring", { **Use cases**: Limited-time maintenance periods, project-based scheduling, planned end dates. + +The named [IANA time zone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) used to schedule recurring occurrences, for example `"America/New_York"`. Occurrences keep the same local time across daylight-saving changes; see [Timezones and daylight saving](/communicate/maintenance-windows/overview#timezones-and-daylight-saving). Editors suggest known zone names as you type. + +`startsAt` and `endsAt` stay absolute instants: the time zone does not reinterpret them, it only decides how later occurrences follow local time. UTC offsets such as `"+05:00"` or `"Etc/GMT+5"` are not accepted. Defaults to UTC. + +**Usage:** + +```ts highlight={4} +new MaintenanceWindow("nightly-maintenance", { + name: "Nightly Maintenance", + tags: ["production"], + timezone: "Europe/Berlin", + startsAt: new Date("2025-02-15T02:00:00.000Z"), // 03:00 in Berlin + endsAt: new Date("2025-02-15T03:00:00.000Z"), + repeatInterval: 1, + repeatUnit: "DAY", +}) +``` + + +The CLI always sends the time zone on deploy. If you remove `timezone` from your code, or a time zone was set for the window in the Checkly UI, the next deploy resets the window to UTC. A time zone can't be changed while a maintenance is active, so a deploy that changes it during an active maintenance fails until the maintenance ends. + + +**Use cases**: Maintenance tied to local business hours, recurring windows that must survive daylight-saving changes. + + + +Pause every check in the account during the maintenance window, regardless of `tags`. + +**Usage:** + +```ts highlight={3} +new MaintenanceWindow("platform-migration", { + name: "Platform Migration", + pauseAllChecks: true, + /* More options... */ +}) +``` + +**Use cases**: Account-wide migrations, full platform downtime. + + + +Tags that filter which checks have their alerts silenced during the maintenance window. Silenced checks keep running and collecting data, but alert channels aren't notified. Ignored when `silenceAllAlerts` is `true`. + +**Usage:** + +```ts highlight={3} +new MaintenanceWindow("degraded-api", { + name: "Expected API Degradation", + silenceAlertsTags: ["api"], + /* More options... */ +}) +``` + +**Use cases**: Keep monitoring during expected degradation without noisy alerts. + + + +Silence alerts for every check in the account during the maintenance window, regardless of `silenceAlertsTags`. Checks keep running. + +**Usage:** + +```ts highlight={3} +new MaintenanceWindow("quiet-period", { + name: "Quiet Period", + silenceAllAlerts: true, + /* More options... */ +}) +``` + +**Use cases**: Account-wide alert silencing while monitoring continues. + + ## Examples diff --git a/integrations/iac/terraform/maintenance-windows.mdx b/integrations/iac/terraform/maintenance-windows.mdx index cc26d437..c026cd70 100644 --- a/integrations/iac/terraform/maintenance-windows.mdx +++ b/integrations/iac/terraform/maintenance-windows.mdx @@ -19,4 +19,26 @@ resource "checkly_maintenance_windows" "maintenance-monthly" { } ``` +Set `timezone` to an [IANA time zone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) to keep recurring windows at the same local time across daylight-saving changes, and use `pause_all_checks`, `silence_alerts_tags` and `silence_all_alerts` to control which checks are paused and which only have their alerts silenced: + +```terraform +resource "checkly_maintenance_windows" "maintenance-nightly" { + name = "Nightly maintenance" + starts_at = "2025-02-15T02:00:00.000Z" // 03:00 in Berlin + ends_at = "2025-02-15T03:00:00.000Z" + repeat_unit = "DAY" + repeat_interval = 1 + timezone = "Europe/Berlin" // Defaults to UTC + tags = ["database"] // Checks with these tags are paused + silence_alerts_tags = ["api"] // Checks with these tags keep running, without alerts +} +``` + +`starts_at` and `ends_at` stay absolute instants; see [Timezones and daylight saving](/communicate/maintenance-windows/overview#timezones-and-daylight-saving) for how later occurrences follow local time. Keep in mind: + +- Use the canonical IANA name, such as `America/New_York` rather than `US/Eastern`. UTC offsets such as `+05:00` aren't accepted. +- `pause_all_checks` and `silence_all_alerts` take precedence over `tags` and `silence_alerts_tags`. +- Terraform manages the whole window, including `description` and the `status_page_visibility` block. Removing an attribute resets it to its default, such as `timezone` to UTC, and settings made in the Checkly UI on a Terraform-managed window show up as changes in your next plan. +- A time zone can't be changed while a maintenance is active. + You can see all the configuration options for maintenance windows, as well as more examples, on the official Terraform registry [documentation page](https://registry.terraform.io/providers/checkly/checkly/latest/docs/resources/maintenance_windows).