[ROB-3081] Add GCP alerts webhook documentation #2001
Conversation
Add documentation for setting up a webhook notification channel in GCP Cloud Monitoring to forward alerts to Robusta. This covers creating a managed webhook channel with basic authentication using the Robusta account ID and API key.
Alerts must include a cluster or cluster_name label for Robusta to properly route them. Added instructions for setting this via custom labels in the alerting policy's Documentation section.
|
✅ Docker image ready for
Use this tag to pull the image for testing. 📋 Copy commandsgcloud auth configure-docker us-central1-docker.pkg.dev
docker pull us-central1-docker.pkg.dev/robusta-development/temporary-builds/robusta-runner:c33c59a
docker tag us-central1-docker.pkg.dev/robusta-development/temporary-builds/robusta-runner:c33c59a me-west1-docker.pkg.dev/robusta-development/development/robusta-runner-dev:c33c59a
docker push me-west1-docker.pkg.dev/robusta-development/development/robusta-runner-dev:c33c59aPatch Helm values in one line: helm upgrade --install robusta robusta/robusta \
--reuse-values \
--set runner.image=me-west1-docker.pkg.dev/robusta-development/development/robusta-runner-dev:c33c59a |
WalkthroughAdds documentation for integrating GCP Cloud Monitoring with Robusta via webhook, including prerequisites, account setup, webhook channel creation, configuration steps, and validation procedures. Updates navigation indices to include the new GCP monitoring documentation. Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~5 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@docs/configuration/alertmanager-integration/gcp-monitoring.rst`:
- Around line 45-56: Update "Step 3: Use the Webhook in Alerting Policies" to
instruct users to add the cluster_name as an Alert Policy User Label (structured
key/value) instead of placing it in the policy's Documentation section;
specifically, replace the bullet that tells them to add the label in
Documentation with instructions to add a User Label key: cluster_name and value:
your cluster name (or external), and mention that this label will be delivered
in the webhook JSON under incident.policy_user_labels so Robusta can read it.
🧹 Nitpick comments (1)
docs/index.rst (1)
43-43: Consider alphabetical ordering of entries.The new "GCP Cloud Monitoring" entry is placed after "Google Managed Prometheus" (line 42), but alphabetically "GCP" should come before "Google" (G-C-P vs G-o-o-g-l-e).
📝 Suggested alphabetical ordering
Embedded Prometheus Stack <configuration/alertmanager-integration/embedded-prometheus> - Google Managed Prometheus <configuration/alertmanager-integration/google-managed-prometheus> GCP Cloud Monitoring <configuration/alertmanager-integration/gcp-monitoring> + Google Managed Prometheus <configuration/alertmanager-integration/google-managed-prometheus> Grafana - Self-Hosted <configuration/alertmanager-integration/grafana-self-hosted>
| Step 3: Use the Webhook in Alerting Policies | ||
| -------------------------------------------- | ||
|
|
||
| 1. Navigate to **Monitoring -> Alerting -> Policies**. | ||
| 2. Create a new alerting policy or edit an existing one. | ||
| 3. In the **Notifications** section, select the **RobustaWebhook** notification channel. | ||
| 4. **Add a cluster label** (required): In the policy's **Documentation** section, add a custom label: | ||
|
|
||
| - **Key**: ``cluster_name`` | ||
| - **Value**: Your Robusta cluster name (e.g., ``my-gcp-cluster``) or ``external`` for non-Kubernetes alerts | ||
|
|
||
| 5. Save the alerting policy. |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
GCP Cloud Monitoring alerting policy custom labels webhook payload
💡 Result:
Short answer: policy (custom) labels you add to an alerting policy are included in the webhook JSON under incident.policy_user_labels. Metric / system / user labels appear in the payload under the incident/metadata or incident.metric fields (e.g. metadata.system_labels, metadata.user_labels, incident.metric.labels). Example (1.2 schema):
{
"incident": {
"policy_name": "...",
"summary": "...",
"policy_user_labels": { "my_label": "value" },
"condition_name": "...",
"metric": {
"displayName":"…",
"labels": { "instance_name":"vm-1", "severity":"critical" }
},
"metadata": {
"system_labels": { "state":"ACTIVE" },
"user_labels": { "env":"prod" }
}
},
"version":"1.2"
}
Sources: Google Cloud Monitoring — Annotate incidents with labels; Create/manage notification channels (webhook payload examples). [1][2]
References
[1] https://cloud.google.com/monitoring/alerts/labels
[2] https://cloud.google.com/monitoring/support/notification-options
🏁 Script executed:
find . -type f \( -name "*.rst" -o -name "*.md" -o -name "*.py" \) | head -20 | xargs grep -l "cluster_name" 2>/dev/null | head -10Repository: robusta-dev/robusta
Length of output: 182
🏁 Script executed:
rg -n "cluster_name" --glob "*.rst" -C 3Repository: robusta-dev/robusta
Length of output: 26086
Use GCP Alert Policy User Labels instead of the Documentation section.
Lines 51-54 provide incorrect instructions. According to GCP Cloud Monitoring webhook documentation, policy labels must be added as Alert Policy User Labels (structured key-value pairs), not in the policy's Documentation section. The Documentation text is not passed to webhooks as structured data.
GCP webhook payloads include policy user labels under incident.policy_user_labels, which is how Robusta receives the cluster_name label required by line 8. The current instructions will not satisfy this requirement—users following them won't have cluster_name in the webhook payload.
Correct approach:
- Add the label directly in the GCP alerting policy settings as a User Label (key:
cluster_name, value: your cluster name orexternal) - This label will then appear in the webhook JSON under
incident.policy_user_labelsas required by Robusta
🤖 Prompt for AI Agents
In `@docs/configuration/alertmanager-integration/gcp-monitoring.rst` around lines
45 - 56, Update "Step 3: Use the Webhook in Alerting Policies" to instruct users
to add the cluster_name as an Alert Policy User Label (structured key/value)
instead of placing it in the policy's Documentation section; specifically,
replace the bullet that tells them to add the label in Documentation with
instructions to add a User Label key: cluster_name and value: your cluster name
(or external), and mention that this label will be delivered in the webhook JSON
under incident.policy_user_labels so Robusta can read it.
No description provided.