From 90555eb86ae2ab2a947a0ffcd8a6cf6c700a70ad Mon Sep 17 00:00:00 2001 From: Simo Kinnunen Date: Wed, 30 Sep 2026 02:26:22 +0900 Subject: [PATCH 1/2] docs: document maintenance window timezone and pause/silence scope [RED-1015] Document `timezone`, `pauseAllChecks`, `silenceAlertsTags` and `silenceAllAlerts` on the MaintenanceWindow construct page, and the matching Terraform attributes. Also correct the `repeatUnit` values in the construct's configuration table. Co-Authored-By: Claude Opus 5.5 --- constructs/maintenance-window.mdx | 86 ++++++++++++++++++- .../iac/terraform/maintenance-windows.mdx | 22 +++++ 2 files changed, 104 insertions(+), 4 deletions(-) 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..0d2b4900 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`. +- Removing an attribute resets it: `timezone` to UTC, the others to off. 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). From c8f3abd6e8d7ee48a69141a1f0556b81b5c2e38d Mon Sep 17 00:00:00 2001 From: Simo Kinnunen Date: Wed, 30 Sep 2026 03:27:13 +0900 Subject: [PATCH 2/2] docs: say the Terraform resource manages the whole maintenance window [RED-1015] Co-Authored-By: Claude Opus 5.5 --- integrations/iac/terraform/maintenance-windows.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/integrations/iac/terraform/maintenance-windows.mdx b/integrations/iac/terraform/maintenance-windows.mdx index 0d2b4900..c026cd70 100644 --- a/integrations/iac/terraform/maintenance-windows.mdx +++ b/integrations/iac/terraform/maintenance-windows.mdx @@ -38,7 +38,7 @@ resource "checkly_maintenance_windows" "maintenance-nightly" { - 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`. -- Removing an attribute resets it: `timezone` to UTC, the others to off. Settings made in the Checkly UI on a Terraform-managed window show up as changes in your next plan. +- 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).