Overview
TheNotificationEngine is triggered whenever:
NotificationPolicy CRD
TheNotificationPolicy defines which events trigger notifications, to which channels, and with which throttling rules.
Spec Fields
NotificationRule
Each rule defines a match + channels pair. Multiple rules can be defined in the same policy.NotificationMatch
All fields are optional. If omitted, it acts as a wildcard (match all). When multiple fields are defined, the logic is AND between fields and OR within each field.ThrottleConfig
Controls the frequency and deduplication of notifications to prevent alert fatigue.Notification Channels
1. Slack
Sends notifications via Slack Incoming Webhooks using Block Kit for rich formatting.Full Slack configuration
Full Slack configuration
Block Kit colors by severity:
Block Kit payload sent:
2. PagerDuty
Integrates with PagerDuty via Events API v2 for on-call incident management.Full PagerDuty configuration
Full PagerDuty configuration
Default severity mapping:
Deduplication:The
dedup_key ensures that updates to the same incident do not create duplicate alerts in PagerDuty. The default uses the Issue name, but it can be customized:Resolved, the NotificationEngine sends event_action: resolve with the same dedup_key, automatically closing the incident in PagerDuty.3. OpsGenie
Integrates with OpsGenie for alerts and on-call management with P1-P4 priorities.Full OpsGenie configuration
Full OpsGenie configuration
Default priority mapping:
Responder types:
4. Email
Sends notifications via SMTP with STARTTLS support and HTML templates.Full Email configuration
Full Email configuration
Variables available in templates:
Example with STARTTLS:
5. Webhook
Sends notifications to arbitrary HTTP endpoints with HMAC-SHA256 signing.Full Webhook configuration
Full Webhook configuration
HMAC-SHA256 signing:When
secret is defined, every request includes the X-ChatCLI-Signature header with the HMAC-SHA256 signature of the body:6. Microsoft Teams
Sends notifications to Microsoft Teams channels via Adaptive Cards and Incoming Webhooks.Full Microsoft Teams configuration
Full Microsoft Teams configuration
Generated Adaptive Card:The NotificationEngine builds an Adaptive Card with sections for:
- Header with colored severity
- Resource details (namespace, kind, name)
- AI analysis (if available)
- Suggested actions
- Link to the Grafana dashboard
EscalationPolicy CRD
TheEscalationPolicy defines the automatic escalation chain when an alert is not acknowledged within the defined timeout.
Spec Fields
EscalationLevel
EscalationTarget
How Escalation Works
Tracking via annotations: TheEscalationPolicy reconciler tracks escalation state using annotations on the Issue CR:
Acknowledgement:
To stop the escalation chain, the on-call must acknowledge the alert:
Complete Examples
Notification Policy: Slack + PagerDuty
Escalation Policy L1 -> L2 -> L3
Email for SLA Breaches
Troubleshooting
Notifications are not being sent
Notifications are not being sent
Diagnostic checklist:
- Verify that the
NotificationPolicyexists in the correct namespace:
- Check the operator logs for dispatch errors:
- Confirm that the matching is correct:
- Verify that throttling is not suppressing notifications:
Slack returns 404 or invalid_payload error
Slack returns 404 or invalid_payload error
- Confirm that the
webhook_urlis correct and the Slack app is installed in the workspace - Verify that the channel exists and the bot has permission to post
- Test the webhook manually:
PagerDuty does not create incidents
PagerDuty does not create incidents
- Confirm that the
routing_keyis an Integration Key (not an API Key) - Verify that the service in PagerDuty is active
- Validate the payload in the PagerDuty Event Debugger
- Confirm that the event is not being deduplicated by the
dedup_key
Emails are not arriving
Emails are not arriving
- Verify SMTP connectivity:
- Confirm credentials in the Secret referenced by
password_secret - Verify that
tls_skip_verify: falseand the server certificate is valid - Check the recipients’ spam folder
Escalation does not advance to the next level
Escalation does not advance to the next level
- Check Issue annotations:
- Confirm that
escalation-acknowledgedis not set totrue - Check the EscalationPolicy reconciler logs
- Confirm that the level
timeoutis not greater than the time since creation
Webhook returns signature error
Webhook returns signature error
- Confirm that the
secretin the policy is the same used by the receiver for verification - Verify that the receiver is reading the raw body before parsing JSON
- Use
hmac.compare_digest(or equivalent) to avoid timing attacks
Prometheus Metrics
The notification system exposes metrics for full observability:
Recommended Prometheus alerts:
Next Steps
SLOs and SLAs
Service Level Objectives management with burn rate alerting
Approval Workflow
Change control with approval policies and blast radius
AIOps Platform
Deep-dive into the AIOps architecture
K8s Operator
Operator configuration and CRDs