docs: rename K8s Agent to Cluster Collector - #848
Conversation
"Agent" is already a customer-facing term for NudgeBee's autonomous AI (NuBi), so calling the passive in-cluster component an "agent" overclaims what it does and confuses scope in sales conversations. The in-cluster component only aggregates metrics, events, logs and traces and relays them out over a WebSocket — no LLM, no decision-making, no autonomy. Renames the narrative across the installation docs so the install flow tells users to install the Cluster Collector rather than the agent: - Sidebar label, page titles, headings and prose under installation/** - Landing page, server docs and the K8s references in the Proxy Agent docs - Adds a terminology note mapping the old name to the new one Deliberately unchanged, so nothing a user types or clicks breaks: - Helm repo/chart/release and the nudgebee-agent namespace - Pod, service account and values key names (nodeAgent.*, agent.accessKey) - URL paths, doc ids and the #2-install-the-agent anchor, now pinned explicitly on the renamed heading - Node Agent (eBPF DaemonSet) and Proxy Agent (Forager), which are separate components that keep their names - Console labels the UI still shows: Agent Health, Agent URL, Agent Version — called out in a note rather than silently renamed Verified with a production Docusaurus build (onBrokenLinks: throw). Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GXgnUKdn8vXQn4oiXSMrDG
There was a problem hiding this comment.
Code Review
This pull request updates the documentation to rename the "NudgeBee Agent" (or "K8s Agent") to "Cluster Collector" across various installation, configuration, and troubleshooting guides. The review feedback correctly identifies a few instances where this renaming was over-applied: specifically, the third-party "Elastic Agent" was incorrectly renamed to "Elastic Collector," and references to the "Node Agent" (which is a distinct sub-component that retains the "agent" name) were mistakenly changed to "collector."
| https://elasticsearch-es-internal-http.monitoring.svc:9200/_cat/indices?v | ||
| ``` | ||
| 2. Check data stream aliases if using modern Elastic Agent or Fleet: | ||
| 2. Check data stream aliases if using modern Elastic Collector or Fleet: |
There was a problem hiding this comment.
Elastic Agent is the official name of the product by Elastic (often used with Fleet). Renaming it to "Elastic Collector" is incorrect and may confuse users. It should remain "Elastic Agent".
| 2. Check data stream aliases if using modern Elastic Collector or Fleet: | |
| 2. Check data stream aliases if using modern Elastic Agent or Fleet: |
References
- When writing documentation, always use the verbatim labels, feature flags, or UI strings as they appear in the product interface, even if they deviate from standard spelling or capitalization rules, to prevent confusing users who are trying to locate those elements.
| | Flag | Description | Default | | ||
| | ---------------------- | --------------------------------------------------- | ---------------- | | ||
| | `LISTEN` | Address the agent listens on (`ip:port` or `:port`) | `0.0.0.0:80` | | ||
| | `LISTEN` | Address the collector listens on (`ip:port` or `:port`) | `0.0.0.0:80` | |
There was a problem hiding this comment.
Since the Node Agent is a separate component that retains the "agent" name (and is not the Cluster Collector), referring to it as "the collector" here can be confusing. It should be referred to as "the node agent".
| | `LISTEN` | Address the collector listens on (`ip:port` or `:port`) | `0.0.0.0:80` | | |
| | `LISTEN` | Address the node agent listens on (`ip:port` or `:port`) | `0.0.0.0:80` | |
| | **Series exist with value `0`** | Prometheus cannot reach the pod IP on port 80. Inspect NetworkPolicies or firewall rules blocking Prometheus scrape egress. | | ||
| | **Fewer series than cluster nodes** | Pods may be missing on tainted nodes (e.g. GPU, Karpenter, or master/control-plane nodes). Add tolerations via `nodeAgent.tolerations`. | | ||
| | **Duplicate series per pod with different labels** | Both a static scrape job and PodMonitor are active, scraping the agent twice with conflicting `instance` labels. Disable `nodeAgent.podmonitor.enabled: false`. | | ||
| | **Duplicate series per pod with different labels** | Both a static scrape job and PodMonitor are active, scraping the collector twice with conflicting `instance` labels. Disable `nodeAgent.podmonitor.enabled: false`. | |
There was a problem hiding this comment.
Since the PodMonitor scrapes the Node Agent pods (which are distinct from the Cluster Collector), referring to it as "the collector" here is confusing. It should be "the node agent".
| | **Duplicate series per pod with different labels** | Both a static scrape job and PodMonitor are active, scraping the collector twice with conflicting `instance` labels. Disable `nodeAgent.podmonitor.enabled: false`. | | |
| | **Duplicate series per pod with different labels** | Both a static scrape job and PodMonitor are active, scraping the node agent twice with conflicting `instance` labels. Disable `nodeAgent.podmonitor.enabled: false`. | |
The Mermaid render was low-contrast and hard to read, and its node labels still said "NudgeBee Agent Namespace" / "pointing at the agent" — the rename pass skipped fenced code blocks, so the picture contradicted the prose around it. Replaces it with a hand-authored SVG served through ThemedImage, so the diagram follows the site's light/dark toggle instead of inheriting Mermaid's washed-out dark palette. The drawing now makes the mechanism explicit rather than just naming the parts. Edges are encoded by how data actually moves, with a legend: - solid — pushed into the collector (K8s events, Alertmanager webhooks, eBPF spans) - dashed — the Runner queries metrics, logs and traces in place, which is why no second copy of your telemetry is shipped anywhere - amber — the single outbound trunk to Relay and Collector Server, carrying the "no inbound port opened" claim Grouping also shows what the Helm chart installs versus what is already yours, a question the old diagram left to small print. Both SVGs are generated from one layout definition so the themes cannot drift; type is sized for the ~0.74x downscale into the docs column. Verified with a production build and by screenshotting the served page in both themes. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GXgnUKdn8vXQn4oiXSMrDG
Review against the chart's own component inventory (helm_values subcharts, module-configuration switches, agent-health probes) found six things the architecture picture never showed. All six were missing from the original Mermaid too, so this is a gap being closed rather than a regression. Added to the diagram: - Runner to Kubernetes API, read: workload and service discovery. The old picture connected the API only to the Event Watcher, which made the Runner look like it learned about the cluster purely through events. - Runner to Kubernetes API, write: restart, scale, cordon, evict, exec and PrometheusRule edits. This is the whole "act" half of the product and the question a security review asks first, so it gets its own edge class rather than being folded into the read path. - Diagnostic Jobs (Trivy, KRR, Popeye) — short-lived Jobs the runner launches, already documented in the Components section below the diagram but absent from it. - OpenCost — optional bundled exporter, off by default, probed by the runner. Drawn with a dashed border so its status is visible. - Alertmanager as a two-way relationship: alerts POST in, while the runner probes /-/healthy and writes silences back. - The push versus pull distinction now extends to cost data. The legend gains an "acts on your cluster (RBAC-gated)" edge class and a component key separating what the chart installs, what is already yours, and what is optional. Prose updated to match: the Architecture section now states the push/pull split and the RBAC-gated remediation path (including relay signature verification), and OpenCost joins the Components list. Not drawn, deliberately: the runner ServiceMonitor. Prometheus scrapes the runner as well as the node agent, but that is an observability detail rather than a data path an operator reasons about at install time. Verified with a production build and by screenshotting the served page. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GXgnUKdn8vXQn4oiXSMrDG
…agram" This reverts commit da272c8.
The endpoint URLs were elided to "wss://relay… " and "https://collector… " to fit the control-plane boxes. Those URLs are the reason the boxes are there — they are what you allowlist for egress — so a half URL is worse than no URL. Widens the control-plane column so both fit whole, matching what the original Mermaid diagram showed. The port moves from the box subtitles to the legend, which now reads "outbound only on 443", so the information is still on the page without truncating anything. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GXgnUKdn8vXQn4oiXSMrDG
"Agent" is already a customer-facing term for NudgeBee's autonomous AI (NuBi), so calling the passive in-cluster component an "agent" overclaims what it does and confuses scope in sales conversations. The in-cluster component only aggregates metrics, events, logs and traces and relays them out over a WebSocket — no LLM, no decision-making, no autonomy.
Renames the narrative across the installation docs so the install flow tells users to install the Cluster Collector rather than the agent:
Deliberately unchanged, so nothing a user types or clicks breaks:
Verified with a production Docusaurus build (onBrokenLinks: throw).
Claude-Session: https://claude.ai/code/session_01GXgnUKdn8vXQn4oiXSMrDG
Summary
Briefly describe what this PR changes and why. Link related issues
(e.g.,
Closes #123).Type of change
Checklist
npm run buildlocally and the site builds without errorsnpm run lintlocally and lint passesgit commit -s)Screenshots (if visual changes)
Additional notes
Anything reviewers should know — tradeoffs, follow-ups, things you
considered and rejected.