Skip to content

docs: rename K8s Agent to Cluster Collector - #848

Open
Sahil52sp wants to merge 5 commits into
mainfrom
claude/docs-collector-terminology-21w0j6
Open

docs: rename K8s Agent to Cluster Collector#848
Sahil52sp wants to merge 5 commits into
mainfrom
claude/docs-collector-terminology-21w0j6

Conversation

@Sahil52sp

Copy link
Copy Markdown
Contributor

"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 chore(deps-dev): bump @tsconfig/docusaurus from 1.0.7 to 2.0.2 in /doc-server #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).

image image

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

  • Typo / minor wording fix
  • New documentation page
  • Update to existing documentation
  • Build, CI, or tooling change
  • Other (please describe)

Checklist

  • I ran npm run build locally and the site builds without errors
  • I ran npm run lint locally and lint passes
  • Internal links work; new external links open the correct page
  • My commits are signed off (DCO — git commit -s)
  • I read CONTRIBUTING.md

Screenshots (if visual changes)

Additional notes

Anything reviewers should know — tradeoffs, follow-ups, things you
considered and rejected.

"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

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

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".

Suggested change
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
  1. 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` |

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

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".

Suggested change
| `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`. |

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

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".

Suggested change
| **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`. |

Sahil Patil and others added 4 commits September 8, 2026 09:38
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
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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants