diff --git a/mission-control/docs/guide/notifications/concepts/silence-notification-form.png b/mission-control/docs/guide/notifications/concepts/silence-notification-form.png deleted file mode 100644 index 26d58aba..00000000 Binary files a/mission-control/docs/guide/notifications/concepts/silence-notification-form.png and /dev/null differ diff --git a/mission-control/docs/guide/notifications/concepts/silences.mdx b/mission-control/docs/guide/notifications/concepts/silences.mdx index 17decad5..41b1d655 100644 --- a/mission-control/docs/guide/notifications/concepts/silences.mdx +++ b/mission-control/docs/guide/notifications/concepts/silences.mdx @@ -4,52 +4,75 @@ sidebar_custom_props: icon: mage:notification-bell-muted --- +import Silence from "@site/docs/reference/notifications/_silence.mdx" + A silence is a way to temporarily suppress notifications. Each silence has: -- A set duration - like an expiration timer -- A scope - it can be applied to either: - - Individual resources (a specific catalog, health check, or component) - - Multiple matching resources using filters +- A description - explaining why the silence was created +- A duration - specified by `from` and `until` timestamps in RFC3339 format, datetime or datemath expressions (e.g., `now`, `now+2d`) +- A scope - defined through selectors and filters to target specific resources +- A recursive flag - to apply silence to child resources :::note Notifications that aren't sent due to silence are still visible in the notification history for auditing purposes. ::: + +```yaml title="" file=/modules/mission-control/fixtures/silences/silence-test-env.yaml +``` + ## Use cases -- Planned maintenance or deployments. Eg: You can silence a namespace or a helm release and automatically silence notifications from all their children. -- Non-critical resources: Notifications from resources that routinely trigger alerts but are expected and harmless can be silenced. -- Known issues: If there's a known issue that can't be immediately resolved (e.g., due to dependencies or resource constraints), you might silence related alerts until a fix can be implemented. +- Planned maintenance or deployments - Silence notifications from a namespace or helm release and optionally all their children +- Non-critical resources - Suppress notifications from resources that routinely trigger expected and harmless alerts +- Known issues - Temporarily silence alerts for known issues that can't be immediately resolved due to dependencies or resource constraints + +## Creating Silences + +Silences can be created in multiple ways: +1. Through the notification page UI +2. Using the silence button on Slack notifications (when using default templates) +3. By applying a NotificationSilence custom resource + + -## Add Silence +### Resource Selection -Silences can be added from the notification page. Alternatively, if you're using the default slack notification templates, you get a silence button -on each notification. +Silences can target resources using selectors, filters, or a specific resource. At least one targeting method must be specified. -![Silence Notification form](./silence-notification-form.png) +1. **Selectors**: Direct resource matching using types, names, namespaces, labels, and tags +2. **Filters**: Complex matching using CEL expressions +3. **Specific Resource**: Selecting a specific config, check, canary, or component (via UI) -### Filters +:::info +When both `filter` and `selectors` are specified, the filter is evaluated first. If the filter matches, the silence is applied. Selectors are only evaluated if the filter does not match. +::: + +#### Selectors + +Selectors use [Resource Selectors](/docs/reference/resource-selector) to target specific resources. Multiple selectors can be specified to target different resources. -A silence can optionally contain a filter. A filter is a cel-expression that results in a boolean value. -If a filter return true, the notification is silenced. +#### Filters -#### Examples +A filter is a CEL expression that evaluates to a boolean value. The notification is silenced when the filter returns true. Filters provide powerful, flexible matching capabilities. -| Filter | description | +##### Filter Examples + +| Filter | Description | |--------|-------------| -| `check.type == 'http'` | silences only HTTP check related notifications. | -| `regexp.Match("^check-[0-9]+", check.name)` | matches any check with the prefix `check-` | -| `config.name == "postgresql" && config.type == "Kubernetes::StatefulSet"` | silences notifications from a stateful set named "postgresql" | -| `config.type == "Kubernetes::Pod" && catalog.traverse(config.id, "Kubernetes::Namespace", "incoming").size > 0 && catalog.traverse(config.id, "Kubernetes::Namespace", "incoming")[0].tags.?env.orValue("") == "prod"` | matches kubernetes pod in a prod namespace | +| `check.type == 'http'` | Silences HTTP check notifications | +| `regexp.Match("^check-[0-9]+", check.name)` | Matches checks with prefix `check-` | +| `config.name == "postgresql" && config.type == "Kubernetes::StatefulSet"` | Silences notifications from a specific StatefulSet | +| `config.type == "Kubernetes::Pod" && catalog.traverse(config.id, "Kubernetes::Namespace", "incoming").size > 0 && catalog.traverse(config.id, "Kubernetes::Namespace", "incoming")[0].tags.?env.orValue("") == "prod"` | Matches pods in production namespaces | -#### Template variables +##### Available Template Variables +Filters can reference these variables: - [CheckEvents](/docs/reference/notifications/template_vars/checks) - [ConfigEvents](/docs/reference/notifications/template_vars/config) -### Recursive mode - -When a silence is recursively applied, it applies to its all children. -So silencing a namespace would silence all deployments, statefulsets, pods, etc in that namespace. - +### Recursive Mode +When `recursive: true` is set, the silence applies to all child resources of the matched resources. For example: +- Silencing a namespace affects all deployments, statefulsets, pods, etc. within it +- Silencing a statefulset affects all its pods diff --git a/mission-control/docs/reference/notifications/_env_vars.mdx b/mission-control/docs/reference/notifications/_env_vars.mdx index ec553c07..c9bad802 100644 --- a/mission-control/docs/reference/notifications/_env_vars.mdx +++ b/mission-control/docs/reference/notifications/_env_vars.mdx @@ -19,12 +19,27 @@ export function CheckHealthEnv() { { "field": "permalink", "scheme": "string", - "description": "Link to the Catalog in mission control" + "description": "A link to the resource in Mission Control" + }, + { + "field": "silenceURL", + "scheme": "string", + "description": "A link to silence this notification" }, { "field": "agent", "scheme": "[`Agent`](#agent)", - "description": "Details of the agent that created the config." + "description": "Details of the agent" + }, + { + "field": "channel", + "scheme": "string", + "description": "The notification channel, e.g. `slack`, `email`" + }, + { + "field": "groupedResources", + "scheme": "`[]string`", + "description": "A list of grouped resource names. Only available when notifications are grouped using `waitFor`." } ]} /> @@ -35,23 +50,43 @@ export function ConfigEventsTemplateVars() { rows={[ { "field": "config", - "scheme": "[`Config`](#config)", + "scheme": "[`Config`](#config-item)", "description": "Corresponding config item." }, { "field": "new_state", - "scheme": "`created`, `updated`, `deleted`", - "description": "The db state change that caused this event.\n\n*Only available on state events.*" + "scheme": "`created` | `updated` | `deleted`", + "description": "The state change that triggered this event.\n\n*Only available on config state events (e.g. `config.created`, `config.updated`, `config.deleted`).*" }, { "field": "permalink", "scheme": "string", - "description": "Link to the Catalog in mission control" + "description": "A link to the resource in Mission Control" + }, + { + "field": "silenceURL", + "scheme": "string", + "description": "A link to silence this notification" }, { "field": "agent", "scheme": "[`Agent`](#agent)", - "description": "Details of the agent that created the config." + "description": "Details of the agent" + }, + { + "field": "recent_events", + "scheme": "`[]string`", + "description": "Recent config changes from the last hour" + }, + { + "field": "channel", + "scheme": "string", + "description": "The notification channel, e.g. `slack`, `email`" + }, + { + "field": "groupedResources", + "scheme": "`[]string`", + "description": "A list of grouped resource names. Only available when notifications are grouped using `waitFor`." } ]} /> diff --git a/mission-control/docs/reference/notifications/_silence.mdx b/mission-control/docs/reference/notifications/_silence.mdx new file mode 100644 index 00000000..0dc2c47b --- /dev/null +++ b/mission-control/docs/reference/notifications/_silence.mdx @@ -0,0 +1,40 @@ + + +:::info +At least one of `filter` or `selectors` must be specified to target resources for the silence. When both are specified, `filter` takes precedence. +:::