docs(agent): say that skipping the Prometheus step drops alert delivery - #828
Merged
Conversation
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the NudgeBee agent installation documentation, changing the referenced Prometheus values file and adding a detailed caution block for users with an existing Prometheus setup to ensure Alertmanager is correctly configured to push alerts. The review feedback suggests using the bracketed syntax for the Docusaurus admonition title, clarifying how to merge the Alertmanager YAML configuration, and correcting the reference to the Helm installation output.
"Install Prometheus (skip if already running in cluster)" is true for metrics
and quietly wrong for alerts. Metrics are queried, so an existing Prometheus
genuinely only needs its URL. Alerts are pushed, and the values file in that
step is the only thing configuring Alertmanager to send them -- so anyone with
an existing Prometheus follows this page correctly and ends up with an agent
that receives metrics and traces but never an alert, with nothing reporting an
error anywhere. That is the normal state of an established cluster adopting
NudgeBee, not an edge case.
Adds the receiver to paste into an existing Alertmanager, and three things that
are not obvious:
- use the URL helm install prints, not the one in the values file, which
resolves only for a release named `nudgebee-agent` in a namespace of the
same name;
- continue: true, or the first matching route wins and existing receivers
stop seeing alerts;
- not an AlertmanagerConfig CR -- prometheus-operator scopes those to their
own namespace by default, so it forwards only that namespace's alerts.
Plus the out-of-cluster case, where the in-cluster URL cannot work at all, and
how to confirm delivery via the Watchdog alert.
Also updates the values file URL, renamed upstream from extra-scrape-config.yaml
to kube-prometheus-stack-values.yaml because the old name described a fraction
of its contents and encouraged exactly the skip above.
blue4209211
force-pushed
the
docs/agent-install-alert-wiring
branch
from
September 5, 2026 08:45
53be1c7 to
fc27dea
Compare
…d adjust helm output reference
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Companion to k8s-agent#590.
The problem
True for metrics, quietly wrong for alerts.
Metrics are queried — an existing Prometheus genuinely only needs its URL. Alerts are pushed, and the values file in that step is the only thing that configures Alertmanager to send them.
So someone with an existing Prometheus follows this page correctly and ends up with an agent that receives metrics and traces but never an alert, with nothing reporting an error. That is the normal state of any established cluster adopting NudgeBee, not an edge case — and it is how this was found.
What's added
A caution block after the install tabs with the receiver to paste into an existing Alertmanager, plus three things that are not obvious:
helm installprints, not the one in the values file — that resolves only for a release namednudgebee-agentin a namespace of the same namecontinue: true, or the first matching route wins and existing receivers stop seeing alertsAlertmanagerConfigCR — prometheus-operator scopes those to their own namespace by default, so it forwards only that namespace's alerts (tried here before, does not work)Plus the out-of-cluster case (Grafana Cloud, Chronosphere), where the in-cluster URL cannot work at all, and how to confirm delivery via the
Watchdogalert.Also
Updates the values file URL — renamed upstream to
kube-prometheus-stack-values.yaml, becauseextra-scrape-config.yamldescribed a fraction of its contents and actively encouraged the skip above.This page will 404 on the old URL once #590 merges, so these two should land together.
Verified:
:::fences and<Tabs>balanced, and the/docs/integrations/Webhooks/link target exists.