From 53d3007528cbc1b2972d952d62944f0d7c55bd9a Mon Sep 17 00:00:00 2001 From: Sahil Patil Date: Tue, 8 Sep 2026 09:05:11 +0000 Subject: [PATCH 1/5] docs(installation): rename K8s Agent to Cluster Collector MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit "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 Claude-Session: https://claude.ai/code/session_01GXgnUKdn8vXQn4oiXSMrDG --- .../docs/installation/agent/_category_.json | 2 +- .../agent/connect/_category_.json | 2 +- .../agent/connect/alertmanager.md | 30 ++++---- .../installation/agent/connect/grafana.md | 2 +- .../installation/agent/connect/logging/elk.md | 32 ++++----- .../agent/connect/logging/index.md | 2 +- .../agent/connect/logging/last9.md | 2 +- .../agent/connect/logging/logz.io.md | 4 +- .../agent/connect/logging/loki.md | 8 +-- .../agent/connect/logging/signoz.md | 22 +++--- .../installation/agent/connect/metrics.md | 2 +- .../agent/connect/multi_tenant_metrics.md | 14 ++-- .../connect/prometheus-troubleshooting.md | 28 ++++---- .../connect/tracing/clickhouse-tracing.md | 2 +- .../agent/connect/tracing/gcp-tracing.md | 16 ++--- .../agent/connect/tracing/index.md | 2 +- doc-server/docs/installation/agent/index.md | 49 ++++++++----- .../installation/agent/installation/index.md | 68 +++++++++---------- .../agent/installation/k8s-provider/gke.md | 4 +- .../agent/installation/upgrade.md | 4 +- .../docs/installation/agent/local-setup.md | 4 +- .../docs/installation/agent/onprem-setup.md | 6 +- .../agent/operate/_category_.json | 2 +- .../agent/operate/agent-health.md | 24 ++++--- .../installation/agent/operate/helm_values.md | 24 +++---- .../agent/operate/module-configuration.md | 8 +-- .../agent/operate/node-agent-configs.md | 4 +- .../agent/operate/storage-and-pvcs.md | 6 +- .../troubleshoot-agent-connectivity.md | 68 +++++++++---------- doc-server/docs/installation/index.md | 10 +-- .../docs/installation/proxy-agent/index.md | 8 +-- .../docs/installation/server/helm_values.md | 6 +- doc-server/docs/installation/server/index.md | 28 ++++---- .../docs/installation/server/upgrade.md | 6 +- 34 files changed, 259 insertions(+), 240 deletions(-) diff --git a/doc-server/docs/installation/agent/_category_.json b/doc-server/docs/installation/agent/_category_.json index 900c8159..1762d76d 100644 --- a/doc-server/docs/installation/agent/_category_.json +++ b/doc-server/docs/installation/agent/_category_.json @@ -1 +1 @@ -{"label": "K8s Agent", "position": 2} +{"label": "Cluster Collector", "position": 2} diff --git a/doc-server/docs/installation/agent/connect/_category_.json b/doc-server/docs/installation/agent/connect/_category_.json index 6d19f593..d833b92c 100644 --- a/doc-server/docs/installation/agent/connect/_category_.json +++ b/doc-server/docs/installation/agent/connect/_category_.json @@ -3,6 +3,6 @@ "position": 2, "link": { "type": "generated-index", - "description": "Point the agent at the metrics, logs, traces, and alerts you already collect." + "description": "Point the Cluster Collector at the metrics, logs, traces, and alerts you already collect." } } diff --git a/doc-server/docs/installation/agent/connect/alertmanager.md b/doc-server/docs/installation/agent/connect/alertmanager.md index fe65b5c0..61f067b5 100644 --- a/doc-server/docs/installation/agent/connect/alertmanager.md +++ b/doc-server/docs/installation/agent/connect/alertmanager.md @@ -5,17 +5,17 @@ sidebar_position: 1 # Alert Forwarding (Alertmanager) -NudgeBee investigates the alerts you already have. To get them, your Alertmanager has to POST them to the agent. The agent Helm chart cannot set this up, because the configuration lives in your Alertmanager. +NudgeBee investigates the alerts you already have. To get them, your Alertmanager has to POST them to the collector. The collector Helm chart cannot set this up, because the configuration lives in your Alertmanager. -If you skip it, nothing breaks visibly. Metrics are pulled, so a bad Prometheus URL shows up right away. Alerts are pushed, so when no receiver targets the agent, all the pods stay healthy, no error is logged, and NudgeBee just never raises an alert-driven event. If your cluster shows metrics and workloads but no alerts, start here. +If you skip it, nothing breaks visibly. Metrics are pulled, so a bad Prometheus URL shows up right away. Alerts are pushed, so when no receiver targets the collector, all the pods stay healthy, no error is logged, and NudgeBee just never raises an alert-driven event. If your cluster shows metrics and workloads but no alerts, start here. There are three independent checks: | Check | What it proves | Where to diagnose | |---|---|---| -| **Alertmanager Connected** in Agent Health | The runner can reach the configured Alertmanager `/-/healthy` endpoint. | Agent configuration, service discovery, authentication, and NetworkPolicy. | +| **Alertmanager Connected** in Agent Health | The runner can reach the configured Alertmanager `/-/healthy` endpoint. | Collector configuration, service discovery, authentication, and NetworkPolicy. | | NudgeBee receiver appears in the loaded Alertmanager route tree | Alertmanager accepted the routing configuration. | The generated Alertmanager config and route ordering. | -| A firing alert appears in NudgeBee | Alertmanager matched the route and delivered the webhook to the correct agent/account. | Alertmanager delivery logs, receiver URL, network path, and agent logs. | +| A firing alert appears in NudgeBee | Alertmanager matched the route and delivered the webhook to the correct collector/account. | Alertmanager delivery logs, receiver URL, network path, and collector logs. | A green Agent Health status proves only the first check. It does not prove that Alertmanager is configured to send alerts to NudgeBee. @@ -97,7 +97,7 @@ helm upgrade --install nudgebee-prometheus prometheus-community/kube-prometheus- -f https://raw.githubusercontent.com/nudgebee/k8s-agent/main/kube-prometheus-stack-values.yaml ``` -One catch: a values file cannot template, so the URL in it is hardcoded to `nudgebee-agent-runner.nudgebee-agent.svc`. It resolves only if your agent release is named `nudgebee-agent` in a namespace of the same name. With any other name, download the file, replace that URL with the one `helm install` printed, and install from your copy. When the URL does not resolve, Alertmanager logs the failed sends and fires `AlertmanagerFailedToSendAlerts`, but NudgeBee has no way to tell you it is missing alerts. +One catch: a values file cannot template, so the URL in it is hardcoded to `nudgebee-agent-runner.nudgebee-agent.svc`. It resolves only if your collector release is named `nudgebee-agent` in a namespace of the same name. With any other name, download the file, replace that URL with the one `helm install` printed, and install from your copy. When the URL does not resolve, Alertmanager logs the failed sends and fires `AlertmanagerFailedToSendAlerts`, but NudgeBee has no way to tell you it is missing alerts. If you already run kube-prometheus-stack and did not install it from that file, add the route and receiver under `alertmanager.config` in your own values: @@ -198,7 +198,7 @@ kubectl create secret generic metrics-datasource-secret \ -n nudgebee-agent ``` -If your backend uses basic auth or OAuth2 instead, VMAlert takes `datasource.basicAuth` or `datasource.oauth2` in place of the bearer token below. None of this involves the NudgeBee agent, which only receives what VMAlertmanager forwards. +If your backend uses basic auth or OAuth2 instead, VMAlert takes `datasource.basicAuth` or `datasource.oauth2` in place of the bearer token below. None of this involves the NudgeBee Cluster Collector, which only receives what VMAlertmanager forwards. ### 2. Install @@ -210,7 +210,7 @@ helm upgrade --install vma vm/victoria-metrics-k8s-stack --version 0.57.0 -f vm- ### 3. `vm-operator.yaml` -Point `datasource.url` at the query endpoint the agent already uses (`globalConfig.prometheus_url`). Everything else the VictoriaMetrics stack can install is turned off here, so this release only evaluates rules and routes alerts. +Point `datasource.url` at the query endpoint the collector already uses (`globalConfig.prometheus_url`). Everything else the VictoriaMetrics stack can install is turned off here, so this release only evaluates rules and routes alerts. ```yaml victoria-metrics-operator: @@ -359,17 +359,17 @@ To keep the token out of the URL, send it as a header instead. Both work: credentials: '' ``` -**If one Alertmanager serves several clusters**, split the traffic rather than sending everything to one destination. Add a route per cluster matching on the external label your Prometheus or Ruler sets (`cluster`, `prometheus`, or whatever you configured), and give each route its own receiver — either the in-cluster agent for that cluster, or the same public webhook with a different `&cluster=` query label so NudgeBee can tell the events apart. +**If one Alertmanager serves several clusters**, split the traffic rather than sending everything to one destination. Add a route per cluster matching on the external label your Prometheus or Ruler sets (`cluster`, `prometheus`, or whatever you configured), and give each route its own receiver — either the in-cluster collector for that cluster, or the same public webhook with a different `&cluster=` query label so NudgeBee can tell the events apart. -This matters most when the receiver is an in-cluster agent: the agent stamps every alert it accepts with its own cluster name, so alerts from cluster B arriving at cluster A's agent are attributed to cluster A and name resources that do not exist there. +This matters most when the receiver is an in-cluster collector: the collector stamps every alert it accepts with its own cluster name, so alerts from cluster B arriving at cluster A's collector are attributed to cluster A and name resources that do not exist there. --- ## Using an AlertmanagerConfig CR -If your platform manages Alertmanager entirely through CRs, you can route to NudgeBee that way — but not by simply creating an `AlertmanagerConfig` in the agent's namespace. That is the one arrangement that quietly does the wrong thing. +If your platform manages Alertmanager entirely through CRs, you can route to NudgeBee that way — but not by simply creating an `AlertmanagerConfig` in the collector's namespace. That is the one arrangement that quietly does the wrong thing. -The operator injects a `namespace=` matcher into every route it generates from an `AlertmanagerConfig`. A CR in the agent's namespace therefore forwards only alerts that originated in that namespace. NudgeBee receives a trickle, which reads as "mostly working" rather than as a broken config. +The operator injects a `namespace=` matcher into every route it generates from an `AlertmanagerConfig`. A CR in the collector's namespace therefore forwards only alerts that originated in that namespace. NudgeBee receives a trickle, which reads as "mostly working" rather than as a broken config. What controls this is `spec.alertmanagerConfigMatcherStrategy.type` on the `Alertmanager` resource: @@ -431,7 +431,7 @@ Do not reach for `None` to fix this. It drops the namespace restriction for ever ## Troubleshooting: Why is NudgeBee Not Receiving Alerts? {#verify} -If your cluster shows healthy metrics and active workloads in the Console but NudgeBee never generates alert-driven events or incident investigations, Alertmanager webhooks are not reaching the agent. +If your cluster shows healthy metrics and active workloads in the Console but NudgeBee never generates alert-driven events or incident investigations, Alertmanager webhooks are not reaching the collector. Follow this systematic diagnostic checklist to locate and fix the blockage. @@ -546,13 +546,13 @@ Look for errors like: #### Correcting the Webhook URL -The receiver URL must match your agent release name and namespace: +The receiver URL must match your collector release name and namespace: ``` http://-runner..svc.cluster.local/api/alerts ``` -- If Alertmanager runs in a different namespace (e.g. `monitoring`) than the agent (`nudgebee-agent`), always supply the full `.svc.cluster.local` domain. +- If Alertmanager runs in a different namespace (e.g. `monitoring`) than the collector (`nudgebee-agent`), always supply the full `.svc.cluster.local` domain. - The runner Service listens on port **80** and routes to container port 5000. Do not append `:5000` to the Service URL. --- @@ -599,7 +599,7 @@ spec: ### Step 6: Test Runner Webhook Intake Directly -You can test the agent runner's `/api/alerts` endpoint independently of Alertmanager to confirm it processes payloads and generates findings: +You can test the collector runner's `/api/alerts` endpoint independently of Alertmanager to confirm it processes payloads and generates findings: 1. Port-forward the runner Service: ```bash diff --git a/doc-server/docs/installation/agent/connect/grafana.md b/doc-server/docs/installation/agent/connect/grafana.md index 78a18ba1..0935b07e 100644 --- a/doc-server/docs/installation/agent/connect/grafana.md +++ b/doc-server/docs/installation/agent/connect/grafana.md @@ -29,7 +29,7 @@ NudgeBee can integrate with Grafana to surface dashboards directly in the NudgeB Setting `url` is what enables the integration; there is no `enabled` flag. -3. **Apply configuration and upgrade the agent** +3. **Apply configuration and upgrade the collector** - **Using shell script**: ```bash sh installation.sh -a -f values.yaml diff --git a/doc-server/docs/installation/agent/connect/logging/elk.md b/doc-server/docs/installation/agent/connect/logging/elk.md index 18767f0f..126687a8 100644 --- a/doc-server/docs/installation/agent/connect/logging/elk.md +++ b/doc-server/docs/installation/agent/connect/logging/elk.md @@ -4,15 +4,15 @@ sidebar_position: 2 # Elasticsearch & OpenSearch (ELK) -Integrate your existing Elasticsearch or OpenSearch cluster with the NudgeBee Kubernetes Agent for centralized log querying and automated incident analysis. +Integrate your existing Elasticsearch or OpenSearch cluster with the NudgeBee Cluster Collector for centralized log querying and automated incident analysis. -The agent supports: +The collector supports: - **Elasticsearch**: Elasticsearch 7.x, 8.x, and Elastic Cloud. - **OpenSearch**: Amazon OpenSearch Service, self-hosted OpenSearch, and Logz.io (via OpenSearch PPL or standard Elasticsearch Query DSL). --- -## 1. NudgeBee Agent Configuration +## 1. NudgeBee Cluster Collector Configuration Elasticsearch is **opt-in**. You must set `runner.es.enabled: true` **and** supply `runner.es.url`. Setting only the URL leaves Elasticsearch disabled so that accidental configuration does not override other providers. @@ -21,7 +21,7 @@ runner: es: # Explicit opt-in required (defaults to false) enabled: true - # Cluster endpoint reachable from the agent runner pod + # Cluster endpoint reachable from the collector runner pod url: "https://elasticsearch-es-internal-http.monitoring.svc:9200" # Auth Option A: API Key (takes precedence over username/password) @@ -47,16 +47,16 @@ runner: | :--- | :--- | :--- | :--- | | `runner.es.enabled` | boolean | `false` | Enables Elasticsearch integration. Must be explicitly set to `true`. | | `runner.es.url` | string | `""` | Base URL for Elasticsearch or OpenSearch (e.g., `http://elasticsearch:9200` or `https://...`). | -| `runner.es.apiKey` | string | `""` | Elasticsearch API key. When present, the agent adds `Authorization: ApiKey `. | +| `runner.es.apiKey` | string | `""` | Elasticsearch API key. When present, the collector adds `Authorization: ApiKey `. | | `runner.es.username` | string | `""` | Basic auth username. Used only if `apiKey` is empty. | | `runner.es.password` | string | `""` | Basic auth password. | | `runner.es.headers` | string | `""` | Semicolon-separated extra headers (`Key: Value; Key2: Value2`) passed on every request. | | `runner.es.sslVerify` | boolean | `false` | When connecting via HTTPS, whether to enforce TLS certificate verification. Defaults to `false`. | :::tip Provider Precedence -When multiple logging integrations are defined, the agent applies strict priority ordering: +When multiple logging integrations are defined, the collector applies strict priority ordering: **Pinot → Elasticsearch → SigNoz → Loki**. -If `runner.es.enabled: true` is set alongside `runner.loki.url`, the agent queries **Elasticsearch**. See the [Logging Overview](./index.md#provider-precedence) for details. +If `runner.es.enabled: true` is set alongside `runner.loki.url`, the collector queries **Elasticsearch**. See the [Logging Overview](./index.md#provider-precedence) for details. ::: --- @@ -139,15 +139,15 @@ runner: ## 3. OpenSearch & PPL Support -The NudgeBee Agent natively supports OpenSearch clusters: +The NudgeBee Cluster Collector natively supports OpenSearch clusters: - **Elasticsearch Query DSL**: Standard `POST /{index}/_search` queries work across both Elasticsearch and OpenSearch. -- **Piped Processing Language (PPL)**: The agent transparently invokes `POST /_plugins/_ppl` when queries utilize OpenSearch PPL expressions. +- **Piped Processing Language (PPL)**: The collector transparently invokes `POST /_plugins/_ppl` when queries utilize OpenSearch PPL expressions. --- ## 4. Health Probing & Diagnostics -The Kubernetes Agent periodically validates connection health by probing: +The Cluster Collector periodically validates connection health by probing: ```http GET /_cluster/health ``` @@ -175,7 +175,7 @@ A healthy response returns JSON with `"status": "green"` or `"status": "yellow"` ## 5. Troubleshooting Common Issues {#troubleshooting} -### Scenario 1: `HTTP 401 Unauthorized` in Health Check or Agent Logs +### Scenario 1: `HTTP 401 Unauthorized` in Health Check or Collector Logs * **Symptom**: Agent Health badge shows `Logs: Disconnected` with error `HTTP 401: Unauthorized`. * **Root Cause**: Invalid API key or username/password credentials. @@ -196,14 +196,14 @@ A healthy response returns JSON with `"status": "green"` or `"status": "yellow"` ### Scenario 3: `x509: certificate signed by unknown authority` * **Symptom**: Health check or query fails during TLS handshake with an internal self-signed certificate. -* **Root Cause**: The agent pod does not trust the cluster's internal Certificate Authority. +* **Root Cause**: The collector pod does not trust the cluster's internal Certificate Authority. * **Resolution**: - **Quick Fix**: Set `runner.es.sslVerify: false` in your Helm values to disable strict TLS verification. - **Production Fix**: Mount your internal CA certificate into the runner deployment or add it to the cluster's trusted CA bundle. ### Scenario 4: Empty Log Query Results (`index_not_found_exception`) -* **Symptom**: Queries succeed but return 0 hits, or agent logs report `index_not_found_exception [no such index]`. +* **Symptom**: Queries succeed but return 0 hits, or collector logs report `index_not_found_exception [no such index]`. * **Root Cause**: The queried index pattern does not match the actual index names or data streams in Elasticsearch. * **Resolution**: 1. List existing indices from the cluster: @@ -212,7 +212,7 @@ A healthy response returns JSON with `"status": "green"` or `"status": "yellow"` curl -k -fsS -u "elastic:" \ 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: ```bash kubectl run es-data-streams --rm -i --restart=Never --image=curlimages/curl -- \ curl -k -fsS -u "elastic:" \ @@ -220,9 +220,9 @@ A healthy response returns JSON with `"status": "green"` or `"status": "yellow"` ``` 3. If your logs reside in non-standard index names (e.g., `app-logs-*`), configure the index pattern appropriately or set `ELASTICSEARCH_LOG_INDEX` in runner environment variables. -### Scenario 5: Elasticsearch Configured but Agent Shows Loki / SigNoz +### Scenario 5: Elasticsearch Configured but Collector Shows Loki / SigNoz -* **Symptom**: You added `runner.es.url`, but the agent still reports logs via Loki or SigNoz. +* **Symptom**: You added `runner.es.url`, but the collector still reports logs via Loki or SigNoz. * **Root Cause**: `runner.es.enabled` was not set to `true`. Unlike Loki or SigNoz (which turn on whenever their URL is non-empty), Elasticsearch is an explicit opt-in. * **Resolution**: Ensure both `runner.es.enabled: true` and `runner.es.url` are set: diff --git a/doc-server/docs/installation/agent/connect/logging/index.md b/doc-server/docs/installation/agent/connect/logging/index.md index d33a35b4..449e7974 100644 --- a/doc-server/docs/installation/agent/connect/logging/index.md +++ b/doc-server/docs/installation/agent/connect/logging/index.md @@ -3,7 +3,7 @@ sidebar_position: 1 --- # Logging -NudgeBee integrates with your existing logging backends to provide instant log context during automated root cause analysis (RCA) and incident triage. Instead of streaming raw log streams out of your cluster to a third-party service, the NudgeBee Agent runner acts as an authenticated in-cluster query proxy, fetching only the targeted log slices needed to investigate specific alert windows. +NudgeBee integrates with your existing logging backends to provide instant log context during automated root cause analysis (RCA) and incident triage. Instead of streaming raw log streams out of your cluster to a third-party service, the NudgeBee Cluster Collector runner acts as an authenticated in-cluster query proxy, fetching only the targeted log slices needed to investigate specific alert windows. ## Supported Logging Providers diff --git a/doc-server/docs/installation/agent/connect/logging/last9.md b/doc-server/docs/installation/agent/connect/logging/last9.md index 74b21718..93f54cdf 100644 --- a/doc-server/docs/installation/agent/connect/logging/last9.md +++ b/doc-server/docs/installation/agent/connect/logging/last9.md @@ -6,7 +6,7 @@ sidebar_position: 4 Last9 exposes Loki apis and can be configured using Loki integrations. -## NudgeBee Agent Configuration +## NudgeBee Cluster Collector Configuration ```yaml runner: diff --git a/doc-server/docs/installation/agent/connect/logging/logz.io.md b/doc-server/docs/installation/agent/connect/logging/logz.io.md index be04f754..1d776532 100644 --- a/doc-server/docs/installation/agent/connect/logging/logz.io.md +++ b/doc-server/docs/installation/agent/connect/logging/logz.io.md @@ -18,6 +18,6 @@ Both `enabled: true` and `url` are required — a URL on its own leaves Elastics Get the token from Logz.io under **Settings → Manage tokens → API tokens**. Use the region-specific host if your account is not in the default region (for example `https://api-eu.logz.io`). -:::note Requires agent chart 0.1.22 or newer -`runner.es.headers` was added in chart 0.1.22. On older agents the value is ignored and queries to Logz.io fail authentication. +:::note Requires collector chart 0.1.22 or newer +`runner.es.headers` was added in chart 0.1.22. On older collectors the value is ignored and queries to Logz.io fail authentication. ::: diff --git a/doc-server/docs/installation/agent/connect/logging/loki.md b/doc-server/docs/installation/agent/connect/logging/loki.md index 6e203ba8..a6b175d3 100644 --- a/doc-server/docs/installation/agent/connect/logging/loki.md +++ b/doc-server/docs/installation/agent/connect/logging/loki.md @@ -4,17 +4,17 @@ sidebar_position: 1 # Grafana Loki -Grafana Loki is a horizontally scalable, multi-tenant log aggregation system. The NudgeBee Agent runner connects to Loki over its HTTP API to execute LogQL range queries, stream label discovery, and fetch targeted logs during root cause analysis (RCA). +Grafana Loki is a horizontally scalable, multi-tenant log aggregation system. The NudgeBee Cluster Collector runner connects to Loki over its HTTP API to execute LogQL range queries, stream label discovery, and fetch targeted logs during root cause analysis (RCA). ## Deployment Architectures Loki can be deployed in two primary topologies: -* **[Monolithic Loki](https://grafana.com/docs/loki/latest/setup/install/helm/install-monolithic)**: Runs all Loki components (distributor, ingester, querier, query-frontend) inside a single pod or binary. The agent connects directly to the service port (usually `http://loki:3100`). -* **[Scalable / Microservices Loki](https://grafana.com/docs/loki/latest/setup/install/helm/install-scalable/)**: Deploys separate read, write, and backend stateful sets fronted by an NGINX gateway (`loki-gateway`). The agent connects to the gateway service (usually port `80` or `3100`). +* **[Monolithic Loki](https://grafana.com/docs/loki/latest/setup/install/helm/install-monolithic)**: Runs all Loki components (distributor, ingester, querier, query-frontend) inside a single pod or binary. The collector connects directly to the service port (usually `http://loki:3100`). +* **[Scalable / Microservices Loki](https://grafana.com/docs/loki/latest/setup/install/helm/install-scalable/)**: Deploys separate read, write, and backend stateful sets fronted by an NGINX gateway (`loki-gateway`). The collector connects to the gateway service (usually port `80` or `3100`). --- -## NudgeBee Agent Configuration +## NudgeBee Cluster Collector Configuration ### Auto-Discovery vs. Explicit Configuration diff --git a/doc-server/docs/installation/agent/connect/logging/signoz.md b/doc-server/docs/installation/agent/connect/logging/signoz.md index 19ec5a01..061898f1 100644 --- a/doc-server/docs/installation/agent/connect/logging/signoz.md +++ b/doc-server/docs/installation/agent/connect/logging/signoz.md @@ -3,15 +3,15 @@ sidebar_position: 3 --- # SigNoz -Integrate [SigNoz](https://signoz.io/) with the NudgeBee Kubernetes Agent for unified log analysis, trace correlation, and automated incident triage. +Integrate [SigNoz](https://signoz.io/) with the NudgeBee Cluster Collector for unified log analysis, trace correlation, and automated incident triage. -The agent queries SigNoz through its v3 query APIs: +The collector queries SigNoz through its v3 query APIs: - **Log Queries**: `POST /api/v3/query_range` - **Attribute Autocomplete**: `GET /api/v3/autocomplete/attribute_keys` and `GET /api/v3/autocomplete/attribute_values` --- -## 1. NudgeBee Agent Configuration +## 1. NudgeBee Cluster Collector Configuration To enable SigNoz, specify the `runner.signoz.url` in your Helm values. Setting a non-empty `url` automatically activates the integration (no separate `enabled` toggle is required). @@ -39,7 +39,7 @@ runner: | `runner.signoz.password` | string | `""` | SigNoz user password. Used in conjunction with `runner.signoz.user`. | :::tip Provider Precedence -The agent checks logging providers in the following order: +The collector checks logging providers in the following order: **Pinot → Elasticsearch → SigNoz → Loki**. SigNoz takes precedence over Loki. However, if Elasticsearch is explicitly enabled (`runner.es.enabled: true`), Elasticsearch takes precedence over SigNoz. See [Logging Overview](./index.md#provider-precedence). ::: @@ -50,7 +50,7 @@ SigNoz takes precedence over Loki. However, if Elasticsearch is explicitly enabl ### Option A: SigNoz API Key (Recommended) -When `apiKey` is provided, the agent attaches the `SIGNOZ-API-KEY` HTTP header to all outbound queries. +When `apiKey` is provided, the collector attaches the `SIGNOZ-API-KEY` HTTP header to all outbound queries. 1. Navigate to **Settings → API Keys** in your SigNoz console. 2. Create a new API key with query permissions. @@ -60,7 +60,7 @@ When `apiKey` is provided, the agent attaches the `SIGNOZ-API-KEY` HTTP header t If using basic user credentials instead of an API key: 1. Provide `runner.signoz.user` (email) and `runner.signoz.password`. -2. The agent automatically calls `POST /api/v1/login` against the SigNoz endpoint to obtain an access JWT. +2. The collector automatically calls `POST /api/v1/login` against the SigNoz endpoint to obtain an access JWT. 3. The JWT token is securely cached in memory and refreshed automatically when it approaches expiration. Outbound queries carry `Authorization: Bearer `. *(Note: If both `apiKey` and `user`/`password` are configured, `apiKey` takes precedence.)* @@ -69,12 +69,12 @@ If using basic user credentials instead of an API key: ## 3. Health Probing & Version Detection -The Kubernetes Agent automatically monitors SigNoz connectivity by probing: +The Cluster Collector automatically monitors SigNoz connectivity by probing: ```http GET /api/v1/health ``` -In addition, the agent queries: +In addition, the collector queries: ```http GET /api/v1/version ``` @@ -107,7 +107,7 @@ A healthy `/api/v1/health` endpoint returns HTTP 200 with an empty body or JSON ### Scenario 1: `HTTP 401 Unauthorized` / Login Failures -* **Symptom**: Agent logs show `signoz login: HTTP 401` or queries return `HTTP 401 Unauthorized`. +* **Symptom**: Collector logs show `signoz login: HTTP 401` or queries return `HTTP 401 Unauthorized`. * **Root Cause**: Invalid API key or expired credentials. * **Resolution**: 1. If using `apiKey`, verify that the key is active in the SigNoz UI under **Settings → API Keys**. @@ -138,12 +138,12 @@ A healthy `/api/v1/health` endpoint returns HTTP 200 with an empty body or JSON * **Symptom**: Log autocompletion fails with `invalid operator:`. * **Root Cause**: Self-hosted SigNoz versions ≤ v0.51 reject attribute queries when `aggregateOperator` is omitted. -* **Resolution**: The NudgeBee Agent automatically injects `aggregateOperator=noop` and `dataSource=logs` on autocomplete requests. If you are using custom external scripts or proxies, ensure these query parameters are passed. +* **Resolution**: The NudgeBee Cluster Collector automatically injects `aggregateOperator=noop` and `dataSource=logs` on autocomplete requests. If you are using custom external scripts or proxies, ensure these query parameters are passed. ### Scenario 4: Connection Refused or Timeout Behind Ingress * **Symptom**: Agent Health reports `Logs: Disconnected` with `dial tcp: i/o timeout` or `connection refused`. -* **Root Cause**: The agent cannot route to the configured SigNoz URL. +* **Root Cause**: The collector cannot route to the configured SigNoz URL. * **Resolution**: 1. Check whether SigNoz is deployed in the same cluster or external. 2. For in-cluster deployments, target the internal Kubernetes Service (e.g. `http://signoz-query-service.platform.svc.cluster.local:8080` or port `3301` depending on your Helm chart values) rather than an external load balancer. diff --git a/doc-server/docs/installation/agent/connect/metrics.md b/doc-server/docs/installation/agent/connect/metrics.md index 46b4c2d8..8358dbc9 100644 --- a/doc-server/docs/installation/agent/connect/metrics.md +++ b/doc-server/docs/installation/agent/connect/metrics.md @@ -65,7 +65,7 @@ A static header does not work for backends that sign each request. For Amazon Ma ## 🚨 Need Alerting? -Alerts only reach NudgeBee if your Alertmanager is configured to forward them to the agent — see [Alert Forwarding](./alertmanager.md). That page covers kube-prometheus-stack, operator-managed Alertmanager (including Thanos-based stacks), plain Alertmanager, and external/central Alertmanagers. +Alerts only reach NudgeBee if your Alertmanager is configured to forward them to the collector — see [Alert Forwarding](./alertmanager.md). That page covers kube-prometheus-stack, operator-managed Alertmanager (including Thanos-based stacks), plain Alertmanager, and external/central Alertmanagers. If your setup has no Alertmanager at all — common with managed metrics backends like Chronosphere — the same page's [VMAlert + VMAlertmanager](./alertmanager.md#vmalert--vmalertmanager) section covers a lightweight alternative. diff --git a/doc-server/docs/installation/agent/connect/multi_tenant_metrics.md b/doc-server/docs/installation/agent/connect/multi_tenant_metrics.md index 3c58bf5e..d099b541 100644 --- a/doc-server/docs/installation/agent/connect/multi_tenant_metrics.md +++ b/doc-server/docs/installation/agent/connect/multi_tenant_metrics.md @@ -4,14 +4,14 @@ sidebar_position: 6 # Multi-cluster Prometheus Setup -When several clusters share one Prometheus-compatible backend, every stored series must carry a stable cluster label. Each NudgeBee agent must also identify the label value for its own cluster, otherwise queries can combine identically named workloads from different clusters. +When several clusters share one Prometheus-compatible backend, every stored series must carry a stable cluster label. Each NudgeBee Cluster Collector must also identify the label value for its own cluster, otherwise queries can combine identically named workloads from different clusters. ## Choose the isolation model | Requirement | Configuration | |---|---| -| Add the cluster selector to NudgeBee-generated PromQL | Set `globalConfig.prometheus_additional_labels` for each agent release. | -| Enforce tenant isolation even if a query omits the selector | Put a label-enforcing proxy in front of the shared backend and give each agent its own proxy endpoint. | +| Add the cluster selector to NudgeBee-generated PromQL | Set `globalConfig.prometheus_additional_labels` for each collector release. | +| Enforce tenant isolation even if a query omits the selector | Put a label-enforcing proxy in front of the shared backend and give each collector its own proxy endpoint. | The chart-level label is query scoping, not a security boundary. The relay substitutes it into NudgeBee's cluster-aware query templates, but the shared Prometheus endpoint remains capable of answering unscoped queries. Use the proxy model when one cluster or tenant must never query another tenant's data. @@ -26,9 +26,9 @@ globalConfig: cluster: prod-us-east-1 ``` -Use a different value in every cluster's agent release. After upgrading, open **Agent Health** and confirm that **Additional Labels** shows the expected map. +Use a different value in every cluster's collector release. After upgrading, open **Agent Health** and confirm that **Additional Labels** shows the expected map. -Before blaming the agent for empty results, verify the label exists upstream: +Before blaming the collector for empty results, verify the label exists upstream: ```promql count by (cluster) (up) @@ -79,7 +79,7 @@ globalConfig: prometheus_url: "http://label-proxy.prometheus.svc:8080" ``` -Every PromQL query the agent runs now goes through the proxy and comes back scoped to the one label value. You can also set `prometheus_additional_labels` to the same label and value so Agent Health records the cluster scope explicitly; the proxy remains the enforcement layer. +Every PromQL query the collector runs now goes through the proxy and comes back scoped to the one label value. You can also set `prometheus_additional_labels` to the same label and value so Agent Health records the cluster scope explicitly; the proxy remains the enforcement layer. ## One proxy per tenant @@ -99,7 +99,7 @@ helm upgrade --install label-proxy-test prometheus-community/prom-label-proxy \ --set config.extraArgs[0]=--label-value=test ``` -Then give each cluster's agent the matching `prometheus_url`: `http://label-proxy-dev.prometheus.svc:8080` for the dev cluster, `http://label-proxy-test.prometheus.svc:8080` for test. +Then give each cluster's collector the matching `prometheus_url`: `http://label-proxy-dev.prometheus.svc:8080` for the dev cluster, `http://label-proxy-test.prometheus.svc:8080` for test. ## If metrics come back empty diff --git a/doc-server/docs/installation/agent/connect/prometheus-troubleshooting.md b/doc-server/docs/installation/agent/connect/prometheus-troubleshooting.md index ec4a9ada..36d8dab6 100644 --- a/doc-server/docs/installation/agent/connect/prometheus-troubleshooting.md +++ b/doc-server/docs/installation/agent/connect/prometheus-troubleshooting.md @@ -16,7 +16,7 @@ This guide provides a systematic **10-step decision tree** to identify and resol --- -## 1. How the Agent Tests Prometheus Connectivity +## 1. How the Collector Tests Prometheus Connectivity During each telemetry cycle, the runner executes this PromQL instant query through the same authenticated client used for metrics operations: @@ -64,17 +64,17 @@ flowchart TD ## 3. Step-by-Step Diagnostic Procedures -### Step 1: Is the Main Kubernetes Agent Connected? -If the primary agent itself is disconnected, all subsystem badges will show disconnected. +### Step 1: Is the Main Cluster Collector Connected? +If the primary collector itself is disconnected, all subsystem badges will show disconnected. ```bash kubectl get pods -n nudgebee-agent -l app.kubernetes.io/name=nudgebee-agent ``` -*If pod is crashlooping or not running, resolve [Agent Connectivity](../operate/troubleshoot-agent-connectivity.md) first.* +*If pod is crashlooping or not running, resolve [Collector Connectivity](../operate/troubleshoot-agent-connectivity.md) first.* --- ### Step 2: Is the Prometheus URL Configured in Helm Values? -Verify what URL the agent was configured with: +Verify what URL the collector was configured with: ```bash helm get values nudgebee-agent -n nudgebee-agent -o json | jq '.globalConfig.prometheus_url' ``` @@ -82,8 +82,8 @@ helm get values nudgebee-agent -n nudgebee-agent -o json | jq '.globalConfig.pro --- -### Step 3: Can the Agent Pod Resolve and Reach the Endpoint? -Exec into the agent runner container and test direct reachability: +### Step 3: Can the Collector Pod Resolve and Reach the Endpoint? +Exec into the collector runner container and test direct reachability: ```bash kubectl run -n nudgebee-agent nudgebee-connectivity-check --rm -i --restart=Never \ --image=curlimages/curl -- -fsS --max-time 5 \ @@ -96,7 +96,7 @@ kubectl run -n nudgebee-agent nudgebee-connectivity-check --rm -i --restart=Neve --- ### Step 4: Is the URL Format Correct? -The agent automatically appends `/api/v1/query` to the configured base URL. +The collector automatically appends `/api/v1/query` to the configured base URL. - ✅ **Correct**: `http://prometheus-operated.monitoring.svc.cluster.local:9090` - ❌ **Incorrect**: `http://prometheus-operated.monitoring.svc.cluster.local:9090/api/v1/query` (will result in double path `/api/v1/query/api/v1/query`). @@ -122,7 +122,7 @@ globalConfig: --- ### Step 6: Is the Endpoint Prometheus-Compatible? -Use the same simple query as the agent to confirm that the endpoint serves the Prometheus query API: +Use the same simple query as the collector to confirm that the endpoint serves the Prometheus query API: ```bash kubectl run -n nudgebee-agent nudgebee-connectivity-check --rm -i --restart=Never \ --image=curlimages/curl -- -fsS \ @@ -154,9 +154,9 @@ kubectl run -n nudgebee-agent nudgebee-connectivity-check --rm -i --restart=Neve ``` *If `result` array is empty, your Prometheus is running but node exporters or kube-state-metrics scrape targets are down.* -### Prometheus is connected, but agent targets or default rules are missing +### Prometheus is connected, but collector targets or default rules are missing -The health badge checks only that the Prometheus query API responds to `vector(1)`. It does not prove that Prometheus has selected or scraped the monitoring objects created by the agent chart. +The health badge checks only that the Prometheus query API responds to `vector(1)`. It does not prove that Prometheus has selected or scraped the monitoring objects created by the collector chart. | Object | Purpose | Chart control | |---|---|---| @@ -185,7 +185,7 @@ In standard `kube-prometheus-stack` installations: #### How to Enable PodMonitors in Default Prometheus Settings -You have two options to ensure Prometheus discovers the agent's monitoring resources: +You have two options to ensure Prometheus discovers the collector's monitoring resources: **Option 1: Configure Prometheus Operator to discover cluster-wide monitors (Recommended for Platform Teams)** @@ -207,7 +207,7 @@ prometheus: **Option 2: Label NudgeBee resources to match Prometheus selectors** -If you cannot modify the Prometheus CR, supply the selector labels expected by Prometheus in the NudgeBee agent's `values.yaml`: +If you cannot modify the Prometheus CR, supply the selector labels expected by Prometheus in the NudgeBee Cluster Collector's `values.yaml`: ```yaml prometheusStack: @@ -215,7 +215,7 @@ prometheusStack: release: kube-prometheus-stack # Replace with your Prometheus release name ``` -This injects the label into the agent's `PodMonitor`, `ServiceMonitor`, and default `PrometheusRule`. +This injects the label into the collector's `PodMonitor`, `ServiceMonitor`, and default `PrometheusRule`. --- diff --git a/doc-server/docs/installation/agent/connect/tracing/clickhouse-tracing.md b/doc-server/docs/installation/agent/connect/tracing/clickhouse-tracing.md index c3fa2c3b..9605fce0 100644 --- a/doc-server/docs/installation/agent/connect/tracing/clickhouse-tracing.md +++ b/doc-server/docs/installation/agent/connect/tracing/clickhouse-tracing.md @@ -10,7 +10,7 @@ The NudgeBee Node Agent is a component designed to collect tracing data from HTT ## Architecture Diagram -![Agent Architecture](/img/nb_agent_architecture.png) +![Collector Architecture](/img/nb_agent_architecture.png) ## Components diff --git a/doc-server/docs/installation/agent/connect/tracing/gcp-tracing.md b/doc-server/docs/installation/agent/connect/tracing/gcp-tracing.md index 41f33782..c4a9a4c0 100644 --- a/doc-server/docs/installation/agent/connect/tracing/gcp-tracing.md +++ b/doc-server/docs/installation/agent/connect/tracing/gcp-tracing.md @@ -4,11 +4,11 @@ sidebar_position: 3 # Google Cloud Trace -Use this when your traces already live in Google Cloud Trace and you do not want a second copy in the agent's bundled ClickHouse. +Use this when your traces already live in Google Cloud Trace and you do not want a second copy in the collector's bundled ClickHouse. ## How it fits together -Cloud Trace has no query API the agent can use for this, so traces are exported from Cloud Trace to BigQuery, and the agent queries BigQuery: +Cloud Trace has no query API the collector can use for this, so traces are exported from Cloud Trace to BigQuery, and the collector queries BigQuery: ```mermaid flowchart LR @@ -17,15 +17,15 @@ flowchart LR NB[NudgeBee agent] -- SQL --> BQ ``` -Two pieces to set up: getting spans into Cloud Trace and on to BigQuery, and giving the agent read access to that dataset. +Two pieces to set up: getting spans into Cloud Trace and on to BigQuery, and giving the collector read access to that dataset. ## 1. Export traces to BigQuery -Point the OpenTelemetry collector at Google Cloud with the [`googlecloud` exporter](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/exporter/googlecloudexporter/README.md), then set up a Cloud Trace [export sink to BigQuery](https://cloud.google.com/trace/docs/trace-export-bigquery). Note the dataset — the agent queries it by project. +Point the OpenTelemetry collector at Google Cloud with the [`googlecloud` exporter](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/exporter/googlecloudexporter/README.md), then set up a Cloud Trace [export sink to BigQuery](https://cloud.google.com/trace/docs/trace-export-bigquery). Note the dataset — the collector queries it by project. -## 2. Give the agent access to BigQuery +## 2. Give the collector access to BigQuery -The agent authenticates with Application Default Credentials, so on GKE it picks up Workload Identity with no credentials in your values file. +The collector authenticates with Application Default Credentials, so on GKE it picks up Workload Identity with no credentials in your values file. ### Using Workload Identity (recommended) @@ -58,7 +58,7 @@ gcloud projects add-iam-policy-binding [PROJECT_ID] \ --role="roles/bigquery.jobUser" ``` -Bind it to the **agent's own** service account. Do not create a new one — the chart already has `-runner-service-account`, and that is the identity the runner uses: +Bind it to the **collector's own** service account. Do not create a new one — the chart already has `-runner-service-account`, and that is the identity the runner uses: ```bash gcloud iam service-accounts add-iam-policy-binding \ @@ -126,7 +126,7 @@ gcloud projects add-iam-policy-binding [PROJECT_ID] \ --role="roles/bigquery.jobUser" # nodes also need the cloud-platform scope; scopes cannot be changed on an -# existing pool, so create one and move the agent to it if they are missing +# existing pool, so create one and move the collector to it if they are missing gcloud container node-pools describe [NODE_POOL_NAME] \ --cluster=[CLUSTER_NAME] --zone=[ZONE] \ --format="value(config.oauthScopes)" diff --git a/doc-server/docs/installation/agent/connect/tracing/index.md b/doc-server/docs/installation/agent/connect/tracing/index.md index d59d2369..ebb8a48b 100644 --- a/doc-server/docs/installation/agent/connect/tracing/index.md +++ b/doc-server/docs/installation/agent/connect/tracing/index.md @@ -10,7 +10,7 @@ NudgeBee reads distributed traces to correlate latency and error spikes with the | Backend | How it connects | |---------|-----------------| -| OpenTelemetry (Otel) | Spans are stored in ClickHouse — see [OTel ClickHouse](./clickhouse-tracing.md). The **Otel** entry under **Admin** > **Integrations** > **Observability** is created and managed by the agent as part of that setup; there is no form to fill in. | +| OpenTelemetry (Otel) | Spans are stored in ClickHouse — see [OTel ClickHouse](./clickhouse-tracing.md). The **Otel** entry under **Admin** > **Integrations** > **Observability** is created and managed by the collector as part of that setup; there is no form to fill in. | | ClickHouse (OTel schema) | [OTel ClickHouse setup](./clickhouse-tracing.md) | | Google Cloud Trace | [Google Cloud Trace setup](./gcp-tracing.md) | | Jaeger | [Jaeger integration](../../../../integrations/Observability/jaeger.md) | diff --git a/doc-server/docs/installation/agent/index.md b/doc-server/docs/installation/agent/index.md index 13b61702..5d09e3d8 100644 --- a/doc-server/docs/installation/agent/index.md +++ b/doc-server/docs/installation/agent/index.md @@ -1,43 +1,58 @@ --- sidebar_position: 1 -sidebar_label: K8s Agent +sidebar_label: Cluster Collector --- -# K8s Agent +# Cluster Collector -The NudgeBee Agent is a lightweight software component that runs inside your Kubernetes cluster. It collects data about workloads, performance, cost, and security, and sends it to the NudgeBee server — feeding the [Semantic Knowledge Graph](../../features/knowledge-graph.md) that powers NudgeBee's Cloud-Ops Intelligence. You need to install an agent in every cluster that you want NudgeBee to monitor. The agent supports AWS, Azure, GCP, and on-premises Kubernetes environments. +The NudgeBee Cluster Collector is a lightweight software component that runs inside your Kubernetes cluster. It collects data about workloads, performance, cost, and security, and sends it to the NudgeBee server — feeding the [Semantic Knowledge Graph](../../features/knowledge-graph.md) that powers NudgeBee's Cloud-Ops Intelligence. You need to install a collector in every cluster that you want NudgeBee to monitor. The collector supports AWS, Azure, GCP, and on-premises Kubernetes environments. :::info -**Both Cloud SaaS and self-hosted users** need to install the agent. This is how NudgeBee gets visibility into your Kubernetes clusters, regardless of your deployment model. +**Both Cloud SaaS and self-hosted users** need to install the collector. This is how NudgeBee gets visibility into your Kubernetes clusters, regardless of your deployment model. ::: :::tip -If you connected a cloud account (AWS, Azure, or GCP), NudgeBee can auto-discover your Kubernetes clusters. You may still need to install the agent for deep monitoring, but cluster discovery happens automatically. +If you connected a cloud account (AWS, Azure, or GCP), NudgeBee can auto-discover your Kubernetes clusters. You may still need to install the collector for deep monitoring, but cluster discovery happens automatically. +::: + +:::note[Previously called the "NudgeBee Agent"] +The Cluster Collector is the component this documentation used to call the **NudgeBee Agent** or +**K8s Agent**. Only the name changed — it is passive data collection, not an autonomous AI agent +(that is [NuBi](../../features/ai/index.md)). + +Nothing you type changes. The Helm repo, chart, release, and namespace are still `nudgebee-agent`, +the pods are still `nudgebee-agent-runner` and `nudgebee-agent-node-agent`, and the console still +labels the status card **Agent Health**. + +Two other components keep the word "agent" and are *not* the Cluster Collector: the +**[Node Agent](https://github.com/nudgebee/node-agent)**, the eBPF DaemonSet that ships inside the +collector, and the **[Proxy Agent](../proxy-agent/)**, a separate binary for datasources outside +Kubernetes. ::: ### What You Will Find in This Section -**Install** — getting the agent running, 5–10 minutes per cluster. +**Install** — getting the collector running, 5–10 minutes per cluster. -- **[Install the agent](./installation/)** — prerequisites, Helm install, and how to verify it connected. +- **[Install the collector](./installation/)** — prerequisites, Helm install, and how to verify it connected. - **[Kubernetes providers](./installation/k8s-provider/)** — extra steps for GKE and AKS. -- **[Upgrade](./installation/upgrade.md)** — moving an existing agent to a newer version. +- **[Upgrade](./installation/upgrade.md)** — moving an existing collector to a newer version. -**Connect data sources** — what the agent reads once it is running. +**Connect data sources** — what the collector reads once it is running. -- **[Alert forwarding](./connect/alertmanager.md)** — point your Alertmanager at the agent. Without this NudgeBee never sees an alert. +- **[Alert forwarding](./connect/alertmanager.md)** — point your Alertmanager at the collector. Without this NudgeBee never sees an alert. - **[Metrics](./connect/metrics.md)** — Prometheus, Thanos, VictoriaMetrics, Chronosphere, and other backends. - **[Why is Prometheus Disconnected?](./connect/prometheus-troubleshooting.md)** — 10-step decision tree for debugging metrics connectivity and authentication. - **[Logs](./connect/logging/)** — Loki, Elasticsearch, SigNoz, Last9. - **[Traces](./connect/tracing/)** — the bundled OTel collector and ClickHouse, or Google Cloud Trace. - **[Grafana](./connect/grafana.md)** and **[multi-tenant Prometheus](./connect/multi_tenant_metrics.md)**. -**Operate & Troubleshoot** — tuning, health monitoring, and diagnostics for a running agent. +**Operate & Troubleshoot** — tuning, health monitoring, and diagnostics for a running collector. -- **[Troubleshoot Agent Connectivity](./operate/troubleshoot-agent-connectivity.md)** — diagnose disconnected agents, periodic heartbeat staleness, flapping, and safe log bundles. +- **[Troubleshoot Collector Connectivity](./operate/troubleshoot-agent-connectivity.md)** — diagnose disconnected collectors, periodic heartbeat staleness, flapping, and safe log bundles. - **[Agent Health & Subsystem Probes](./operate/agent-health.md)** — field-by-field reference for Relay, Prometheus, Logs, Traces, and Node Agent probes. -- **[Enable or Disable Agent Modules](./operate/module-configuration.md)** — module switches, feature impact, and verification steps. -- **[Agent Storage and PVCs](./operate/storage-and-pvcs.md)** — default and custom StorageClasses, pending claims, expansion, and disabling bundled trace storage. +- **[Enable or Disable Collector Modules](./operate/module-configuration.md)** — module switches, feature impact, and verification steps. +- **[Collector Storage and PVCs](./operate/storage-and-pvcs.md)** — default and custom StorageClasses, pending claims, expansion, and disabling bundled trace storage. - **[Helm values](./operate/helm_values.md)** — every value you are likely to set, including access modes and sizing. - **[Node agent configuration](./operate/node-agent-configs.md)** — eBPF collector tuning. - **[Cluster autoscaler](./operate/cluster-autoscaler/)** — Karpenter support. @@ -50,7 +65,7 @@ If you connected a cloud account (AWS, Azure, or GCP), NudgeBee can auto-discove ## Architecture -The NudgeBee Agent runs within your Kubernetes cluster. The main component is the Runner, which acts as a central controller — it coordinates data collection from cluster components and maintains a secure, outbound-only WebSocket connection to the NudgeBee Server. +The NudgeBee Cluster Collector runs within your Kubernetes cluster. The main component is the Runner, which acts as a central controller — it coordinates data collection from cluster components and maintains a secure, outbound-only WebSocket connection to the NudgeBee Server. ```mermaid flowchart TB @@ -132,11 +147,11 @@ Use this table before changing several components at once: | Symptom | Most likely boundary | What can still work | |---|---|---| -| Entire agent is disconnected | Runner-to-collector authentication or network path | In-cluster node-agent and forwarder pods may still be running. | +| Entire collector is disconnected | Runner-to-collector authentication or network path | In-cluster node-agent and forwarder pods may still be running. | | Live queries fail but telemetry heartbeat is current | Relay connection, request signing, or datasource configuration | Periodic inventory and health telemetry can continue. | | Workloads appear but no alert-driven events arrive | Alertmanager route and webhook delivery to `/api/alerts` | Prometheus queries and Kubernetes discovery continue. | | Prometheus is connected but node-agent count is zero | PodMonitor/scrape selection or node-agent target health | Other Prometheus queries can succeed. | | Kubernetes resource changes stop appearing | Forwarder configuration, RBAC, or runner event intake | Prometheus, logs, and traces queries can continue. | | Traces disappear | Node-agent trace export, OTel collector, ClickHouse, or external trace provider | Metrics, inventory, alerts, and logs continue. | -See [Agent Health](./operate/agent-health.md) for the reported fields and [Troubleshoot Agent Connectivity](./operate/troubleshoot-agent-connectivity.md) for the runner-to-server path. +See [Agent Health](./operate/agent-health.md) for the reported fields and [Troubleshoot Collector Connectivity](./operate/troubleshoot-agent-connectivity.md) for the runner-to-server path. diff --git a/doc-server/docs/installation/agent/installation/index.md b/doc-server/docs/installation/agent/installation/index.md index b497abe8..9e7ca3b7 100644 --- a/doc-server/docs/installation/agent/installation/index.md +++ b/doc-server/docs/installation/agent/installation/index.md @@ -5,14 +5,14 @@ sidebar_position: 1 import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -# Agent Installation +# Cluster Collector Installation -Install the NudgeBee Agent on each Kubernetes cluster you want to monitor. The agent runs as a lightweight collector DaemonSet and controller within your cluster. It gathers live workload telemetry, resource utilization, events, logs, and distributed traces, streaming them to the NudgeBee Server to build the **Semantic Knowledge Graph** for real-time AI troubleshooting and cost optimizations. +Install the NudgeBee Cluster Collector on each Kubernetes cluster you want to monitor. It runs as a lightweight DaemonSet and controller within your cluster. It gathers live workload telemetry, resource utilization, events, logs, and distributed traces, streaming them to the NudgeBee Server to build the **Semantic Knowledge Graph** for real-time AI troubleshooting and cost optimizations. -:::note[Do I need the Agent?] +:::note[Do I need the Collector?] - **Connecting a Cloud Account** (AWS/Azure/GCP) provides high-level cloud inventory and cluster auto-discovery without installing software upfront. -- **Installing the Agent** inside the cluster is **required for deep in-cluster telemetry**, live pod logs, kernel-level eBPF network metrics, and automated AI incident RCA. -- Both **Cloud SaaS** and **Self-Hosted** deployments install the exact same agent into monitored clusters. +- **Installing the Collector** inside the cluster is **required for deep in-cluster telemetry**, live pod logs, kernel-level eBPF network metrics, and automated AI incident RCA. +- Both **Cloud SaaS** and **Self-Hosted** deployments install the exact same collector into monitored clusters. ::: :::tip @@ -20,7 +20,7 @@ Install the NudgeBee Agent on each Kubernetes cluster you want to monitor. The a ::: :::info -**Cloud SaaS users**: You only need to install the agent — the server is managed for you. Generate your agent auth key at [app.nudgebee.com](https://app.nudgebee.com) and skip straight to [Install the Agent](#2-install-the-agent). +**Cloud SaaS users**: You only need to install the collector — the server is managed for you. Generate your collector auth key at [app.nudgebee.com](https://app.nudgebee.com) and skip straight to [Install the Collector](#2-install-the-agent). **Self-hosted users**: Make sure the [NudgeBee Server is installed](../../server/) first. You will need the Relay Server URL and Collector Server URL from your server setup — see [Self-Hosted Configuration](#4-for-self-hosted-nudgebee). ::: @@ -50,21 +50,21 @@ Install the NudgeBee Agent on each Kubernetes cluster you want to monitor. The a | **Helm** | v3.x installed and configured | [Install Helm](https://helm.sh/) if you don't have it | | **Linux Kernel** | v4.2 or newer on all nodes | Required for eBPF-based network metrics collection | | **NudgeBee Auth Key** | Generated from the NudgeBee UI | **Admin → Integrations → Kubernetes Clusters → Add K8s Account** | -| **Registry access** | Outbound access to `nudgebee.github.io` (Helm repo) and `ghcr.io/nudgebee` (agent images) | Air-gapped clusters can mirror images internally | +| **Registry access** | Outbound access to `nudgebee.github.io` (Helm repo) and `ghcr.io/nudgebee` (collector images) | Air-gapped clusters can mirror images internally | | **Prometheus** | A running Prometheus instance in the cluster | If omitted, the installer can deploy a bundled instance | ### Resource Footprint -The agent components are designed to be low overhead: +The collector components are designed to be low overhead: | Component | Sizing Breakdown | Notes | |---|---|---| -| **Agent Core (without Prometheus)** | **~2 GB RAM, 1-2 CPU cores** | Includes Runner, Node Agent DaemonSet (eBPF), Event Watcher | -| **Agent with Bundled Observability** | **~5 GB RAM, 2-3 CPU cores** | Includes Prometheus, Alertmanager, and Kube-State-Metrics | +| **Collector Core (without Prometheus)** | **~2 GB RAM, 1-2 CPU cores** | Includes Runner, Node Agent DaemonSet (eBPF), Event Watcher | +| **Collector with Bundled Observability** | **~5 GB RAM, 2-3 CPU cores** | Includes Prometheus, Alertmanager, and Kube-State-Metrics | --- -## 2. Install the Agent +## 2. Install the Collector {#2-install-the-agent} ### Step 1: Generate Your Auth Key @@ -74,7 +74,7 @@ The agent components are designed to be low overhead: 4. The **Finish Setup** step gives you the install command with your **Auth Key** (``) in it. Copy the key. :::caution Blast Radius of Auth Key -Your Auth Key authorizes your agent to send data to your NudgeBee control plane. Store it securely in a secret manager or Kubernetes Secret — never commit it in cleartext. +Your Auth Key authorizes your collector to send data to your NudgeBee control plane. Store it securely in a secret manager or Kubernetes Secret — never commit it in cleartext. ::: ### Step 2: Deploy via Helm @@ -97,7 +97,7 @@ helm upgrade --install nudgebee-prometheus prometheus-community/kube-prometheus- --set kubeStateMetrics.enabled=true \ -f https://raw.githubusercontent.com/nudgebee/k8s-agent/main/kube-prometheus-stack-values.yaml -# 3. Deploy NudgeBee Agent +# 3. Deploy NudgeBee Cluster Collector helm upgrade --install nudgebee-agent nudgebee-agent/nudgebee-agent \ --namespace nudgebee-agent --create-namespace \ --set runner.nudgebee.auth_secret_key="" \ @@ -120,7 +120,7 @@ helm upgrade --install nudgebee-prometheus prometheus-community/kube-prometheus- --set kubeStateMetrics.enabled=true \ -f https://raw.githubusercontent.com/nudgebee/k8s-agent/main/kube-prometheus-stack-values.yaml -# 3. Deploy NudgeBee Agent +# 3. Deploy NudgeBee Cluster Collector helm upgrade --install nudgebee-agent nudgebee-agent/nudgebee-agent \ --namespace nudgebee-agent --create-namespace \ --set runner.nudgebee.auth_secret_key="" \ @@ -135,7 +135,7 @@ helm upgrade --install nudgebee-agent nudgebee-agent/nudgebee-agent \ helm repo add nudgebee-agent https://nudgebee.github.io/k8s-agent/ helm repo update -# 2. Deploy NudgeBee Agent (Azure Monitor integration enabled) +# 2. Deploy NudgeBee Cluster Collector (Azure Monitor integration enabled) helm upgrade --install nudgebee-agent nudgebee-agent/nudgebee-agent \ --namespace nudgebee-agent --create-namespace \ --set runner.nudgebee.auth_secret_key="" \ @@ -152,7 +152,7 @@ helm upgrade --install nudgebee-agent nudgebee-agent/nudgebee-agent \ helm repo add nudgebee-agent https://nudgebee.github.io/k8s-agent/ helm repo update -# 2. Deploy NudgeBee Agent with minimal local footprint +# 2. Deploy NudgeBee Cluster Collector with minimal local footprint helm upgrade --install nudgebee-agent nudgebee-agent/nudgebee-agent \ --namespace nudgebee-agent --create-namespace \ --set runner.nudgebee.auth_secret_key="" \ @@ -163,12 +163,12 @@ helm upgrade --install nudgebee-agent nudgebee-agent/nudgebee-agent \ -### Step 3: Send Your Alerts to the Agent +### Step 3: Send Your Alerts to the Collector -NudgeBee raises alert-driven events only if your Alertmanager posts alerts to the agent. If you installed Prometheus using the values file in Step 2, that receiver is already configured. +NudgeBee raises alert-driven events only if your Alertmanager posts alerts to the collector. If you installed Prometheus using the values file in Step 2, that receiver is already configured. :::caution[Already running Prometheus? Configure Alertmanager to push alerts] -Skipping the Prometheus install is fine—the agent **queries** metrics, so it only needs a reachable URL. +Skipping the Prometheus install is fine—the collector **queries** metrics, so it only needs a reachable URL. Alerts are different: they are **pushed**, and the values file in Step 2 is what configures Alertmanager to send them. If you skip Step 2 without wiring Alertmanager, NudgeBee gets metrics and traces but never an alert, with nothing reporting an error. @@ -203,7 +203,7 @@ For complete configuration instructions across kube-prometheus-stack, VictoriaMe ## 3. Verify the Installation (Checklist) {#3-verify-the-installation} -After running the install command, verify that the agent is communicating with the server: +After running the install command, verify that the collector is communicating with the server: ### 1. Verify Pod Readiness ```bash @@ -214,7 +214,7 @@ kubectl get pods -n nudgebee-agent - `nudgebee-agent-node-agent-*` (DaemonSet): `1/1 Running` on every worker node - `nudgebee-agent-forwarder-*` (event watcher): `1/1 Running` -### 2. Inspect Agent Connection Logs +### 2. Inspect Collector Connection Logs ```bash kubectl logs -n nudgebee-agent -l app=nudgebee-agent-runner --tail=50 ``` @@ -237,13 +237,13 @@ Look for log confirmation: `Connected to NudgeBee Relay successfully` and `Regis Which workloads in this cluster have restarted, entered CrashLoopBackOff, or experienced OOMKills in the last 24 hours? ``` **Expected Result**: On a healthy cluster, NuBi confirms no active restart anomalies are detected. On clusters with issues, it provides affected workloads with exit codes and recommended remediation steps. -4. **Success Verification**: When you receive responses grounded in your cluster's live workloads and node statuses, your agent telemetry pipeline is verified and fully operational. +4. **Success Verification**: When you receive responses grounded in your cluster's live workloads and node statuses, your collector telemetry pipeline is verified and fully operational. --- -## 4. Troubleshooting Agent Installation Errors +## 4. Troubleshooting Collector Installation Errors -Use this diagnostic reference to resolve common agent deployment and communication issues. +Use this diagnostic reference to resolve common collector deployment and communication issues. --- @@ -253,7 +253,7 @@ Use this diagnostic reference to resolve common agent deployment and communicati |---|---|---| | **`401 Unauthorized / Invalid API Key`** | Incorrect or revoked Auth Key | Verify the key under **Admin → Integrations → Kubernetes Clusters** and re-run `helm upgrade` with `--set runner.nudgebee.auth_secret_key=""`. | | **`node-agent CrashLoopBackOff` (eBPF load failure)** | Kernel < 4.2 or non-standard distro (Bottlerocket, Talos, GKE COS) | Check kernel with `uname -r` and ensure `/sys/kernel/debug` is accessible. As a last resort, drop the DaemonSet with `--set nodeAgent.enabled=false` (loses eBPF network metrics and profiling). | -| **No alerts in NudgeBee, everything else working** | No Alertmanager receiver points at the agent | Add the receiver. See [Alert Forwarding](../connect/alertmanager.md). Nothing reports this on its own. | +| **No alerts in NudgeBee, everything else working** | No Alertmanager receiver points at the collector | Add the receiver. See [Alert Forwarding](../connect/alertmanager.md). Nothing reports this on its own. | | **`WebSocket Dial Timeout / EOF`** | Outbound firewall or NetworkPolicy blocking TCP 443 | Verify egress to `wss://relay.nudgebee.com` (SaaS) or your relay Ingress. Ensure port 443 is open. | | **`Prometheus connection refused / empty metrics`** | Wrong Prometheus service URL or missing KSM | Point `globalConfig.prometheus_url` to valid service DNS (e.g. `http://..svc:9090`). | | **`CRD / Webhook timeout error`** | Prometheus operator CRDs not yet established | Wait 30 seconds and re-run the `helm upgrade` command. | @@ -273,7 +273,7 @@ kubectl logs daemonset/nudgebee-agent-node-agent -n nudgebee-agent **Resolution:** - Verify that your Kubernetes node kernel is version **4.2 or higher** (`uname -r`). - For container-optimized operating systems (e.g. AWS Bottlerocket or GKE COS), ensure debugfs and bpf filesystems are mounted. -- If running on microVMs or kernels with restricted eBPF, disable the node agent entirely. The rest of the agent (inventory, events, metrics, alerts) keeps working; you lose eBPF network metrics and profiling: +- If running on microVMs or kernels with restricted eBPF, disable the node agent entirely. The rest of the collector (inventory, events, metrics, alerts) keeps working; you lose eBPF network metrics and profiling: ```shell helm upgrade nudgebee-agent nudgebee-agent/nudgebee-agent \ --namespace nudgebee-agent \ @@ -286,7 +286,7 @@ If the cluster connects in the UI but workload CPU and memory graphs remain empt **Diagnose:** ```shell -# Test Prometheus DNS resolution from inside the agent runner pod +# Test Prometheus DNS resolution from inside the collector runner pod kubectl exec -it deployment/nudgebee-agent-runner -n nudgebee-agent -- wget -qO- http://nudgebee-prometheus-kube-prometheus-prometheus.nudgebee-agent.svc:9090/api/v1/query?query=up ``` @@ -326,7 +326,7 @@ spec: ## 4. For Self-Hosted NudgeBee -If you are running a self-hosted NudgeBee instance, the agent needs to know where your server is. Instead of the `--set` flags in the SaaS installation, create a `values.yaml` file that points to your server's Relay and Collector URLs. +If you are running a self-hosted NudgeBee instance, the collector needs to know where your server is. Instead of the `--set` flags in the SaaS installation, create a `values.yaml` file that points to your server's Relay and Collector URLs. :::info **Where do I find these URLs?** You configured them during [Server Installation](/docs/installation/server/). @@ -380,7 +380,7 @@ helm upgrade nudgebee-agent nudgebee-agent/nudgebee-agent \ --set runner.enableWritePermissions=true ``` -To go the other way and leave the agent with `get`, `list`, `watch` and nothing else: +To go the other way and leave the collector with `get`, `list`, `watch` and nothing else: ```bash helm upgrade nudgebee-agent nudgebee-agent/nudgebee-agent \ @@ -392,19 +392,19 @@ Setting both fails the install. [Permissions and access mode](../operate/helm_va ### Additional Configuration References -- **[Alert Forwarding](../connect/alertmanager.md)** — Point your Alertmanager at the agent. Without it NudgeBee gets no alerts. -- **[Helm Values Reference](../operate/helm_values.md)** — Complete list of all configurable values for the agent Helm chart. +- **[Alert Forwarding](../connect/alertmanager.md)** — Point your Alertmanager at the collector. Without it NudgeBee gets no alerts. +- **[Helm Values Reference](../operate/helm_values.md)** — Complete list of all configurable values for the collector Helm chart. - **[Node Agent Configuration](../operate/node-agent-configs.md)** — Fine-tune the eBPF-based node agent. - **[Kubernetes Provider Setup](./k8s-provider/)** — Provider-specific instructions for GKE, AKS, and other managed Kubernetes services. -- **[Logging Integration](../connect/logging/)** — Connect log sources (ELK, Loki, etc.) to the agent. +- **[Logging Integration](../connect/logging/)** — Connect log sources (ELK, Loki, etc.) to the collector. - **[Tracing Integration](../connect/tracing/)** — Connect tracing backends for distributed tracing. -- **[Upgrade Guide](./upgrade.md)** — How to upgrade an existing agent to a newer version. +- **[Upgrade Guide](./upgrade.md)** — How to upgrade an existing collector to a newer version. --- ## What's Next? -Your agent is installed and sending data to NudgeBee. Here is what to do next: +Your collector is installed and sending data to NudgeBee. Here is what to do next: 1. **[Connect an observability source](/docs/integrations/Observability/)** — Connect Prometheus, Datadog, New Relic, or other monitoring tools for metrics, logs, and traces. 2. **[Set up notifications](/docs/integrations/Notifications/)** — Connect Slack, Teams, or Google Chat to receive alerts. diff --git a/doc-server/docs/installation/agent/installation/k8s-provider/gke.md b/doc-server/docs/installation/agent/installation/k8s-provider/gke.md index e7be7c71..05e3705d 100644 --- a/doc-server/docs/installation/agent/installation/k8s-provider/gke.md +++ b/doc-server/docs/installation/agent/installation/k8s-provider/gke.md @@ -3,8 +3,8 @@ sidebar_position: 2 --- # Google Kubernetes Engine -GKE needs no special agent values. Install the agent the same way as anywhere else: [Agent Installation](../index.md). +GKE needs no special collector values. Install the collector the same way as anywhere else: [Collector Installation](../index.md). ## Cost and pricing data -Pricing comes from the NudgeBee server, not from the agent, so there is nothing to configure in the cluster. Connect the GCP project once and every GKE cluster in it gets cost data: [GCP Account Integration](../../../../features/Cloud/GCP.md). +Pricing comes from the NudgeBee server, not from the collector, so there is nothing to configure in the cluster. Connect the GCP project once and every GKE cluster in it gets cost data: [GCP Account Integration](../../../../features/Cloud/GCP.md). diff --git a/doc-server/docs/installation/agent/installation/upgrade.md b/doc-server/docs/installation/agent/installation/upgrade.md index 2d930563..d323231c 100644 --- a/doc-server/docs/installation/agent/installation/upgrade.md +++ b/doc-server/docs/installation/agent/installation/upgrade.md @@ -4,7 +4,7 @@ sidebar_position: 3 # Upgrade -The Helm chart version and the agent application version are separate. Check both before changing a production cluster: +The Helm chart version and the collector application version are separate. Check both before changing a production cluster: ```bash helm list -n nudgebee-agent @@ -17,7 +17,7 @@ Pin the chart version in production so the same command is repeatable across clu ### Prerequisites -Before upgrading your NudgeBee Agent, ensure the following: +Before upgrading your NudgeBee Cluster Collector, ensure the following: #### Software - **Helm** installed and configured. diff --git a/doc-server/docs/installation/agent/local-setup.md b/doc-server/docs/installation/agent/local-setup.md index bdc513bd..2a27da13 100644 --- a/doc-server/docs/installation/agent/local-setup.md +++ b/doc-server/docs/installation/agent/local-setup.md @@ -4,7 +4,7 @@ sidebar_position: 3 # Try Locally -Run the agent against a throwaway [KinD](https://kind.sigs.k8s.io/) cluster to see what NudgeBee looks like with real data, without touching a real cluster. +Run the collector against a throwaway [KinD](https://kind.sigs.k8s.io/) cluster to see what NudgeBee looks like with real data, without touching a real cluster. ## What you get, and what you don't @@ -38,7 +38,7 @@ kubectl get nodes In [app.nudgebee.com](https://app.nudgebee.com), go to **Admin → Integrations**, open the **Kubernetes Clusters** card, and click **Add K8s Account**. Name it something you will recognise as disposable, mark it **Non-production**, and finish the wizard. Copy the auth key it gives you. -## 3. Install the agent +## 3. Install the collector ```bash wget https://raw.githubusercontent.com/nudgebee/k8s-agent/main/installation.sh diff --git a/doc-server/docs/installation/agent/onprem-setup.md b/doc-server/docs/installation/agent/onprem-setup.md index aaf2cccb..45e41261 100644 --- a/doc-server/docs/installation/agent/onprem-setup.md +++ b/doc-server/docs/installation/agent/onprem-setup.md @@ -6,12 +6,12 @@ sidebar_position: 4 ## Introduction -Example configuration for pointing the agent at a self-hosted NudgeBee server. +Example configuration for pointing the collector at a self-hosted NudgeBee server. ## Prerequisites - Onprem Collector-Server Url - Onprem Relay-Server Url -- Agent Keys +- Cluster Collector Keys - Review [Metrics Provider](./connect/metrics.md) - Review [Logging Providers](./connect/logging/index.md) @@ -47,4 +47,4 @@ opentelemetry-collector: ### Alerts -The values above do not wire up alerts. Add a receiver in your Alertmanager that posts to the agent, otherwise this cluster reports metrics and events but never an alert: [Alert Forwarding](./connect/alertmanager.md). \ No newline at end of file +The values above do not wire up alerts. Add a receiver in your Alertmanager that posts to the collector, otherwise this cluster reports metrics and events but never an alert: [Alert Forwarding](./connect/alertmanager.md). \ No newline at end of file diff --git a/doc-server/docs/installation/agent/operate/_category_.json b/doc-server/docs/installation/agent/operate/_category_.json index 0ce35fc8..9a11f942 100644 --- a/doc-server/docs/installation/agent/operate/_category_.json +++ b/doc-server/docs/installation/agent/operate/_category_.json @@ -3,6 +3,6 @@ "position": 3, "link": { "type": "generated-index", - "description": "Configuration reference and tuning for a running agent." + "description": "Configuration reference and tuning for a running Cluster Collector." } } diff --git a/doc-server/docs/installation/agent/operate/agent-health.md b/doc-server/docs/installation/agent/operate/agent-health.md index 88edf776..e022d2c7 100644 --- a/doc-server/docs/installation/agent/operate/agent-health.md +++ b/doc-server/docs/installation/agent/operate/agent-health.md @@ -3,20 +3,24 @@ id: k8s-agent-health title: Kubernetes Agent Health & Subsystem Status sidebar_label: Kubernetes Agent Health sidebar_position: 3 -keywords: [agent health, k8s agent, relay connection, node agent, logs provider, traces, jaeger, clickhouse] +keywords: [agent health, k8s collector, relay connection, node agent, logs provider, traces, jaeger, clickhouse] intent: inspect provider: kubernetes --- # Kubernetes Agent Health & Subsystem Status -The **Agent Health** view in the NudgeBee Console provides real-time visibility into the internal status of the NudgeBee Kubernetes Agent and all connected cluster datasources. +The **Agent Health** view in the NudgeBee Console provides real-time visibility into the internal status of the NudgeBee Cluster Collector and all connected cluster datasources. + +:::note +The console still labels this view **Agent Health** and its fields **Agent URL** and **Agent Version**. Those are the on-screen labels for the component this documentation now calls the [Cluster Collector](../index.md). +::: --- ## 1. Agent Health Dashboard Overview -On each periodic telemetry tick, the agent runner executes local lightweight probes against all configured datasources and reports their state to the NudgeBee backend. +On each periodic telemetry tick, the collector runner executes local lightweight probes against all configured datasources and reports their state to the NudgeBee backend. ```mermaid graph LR @@ -45,12 +49,12 @@ graph LR Below is the complete reference of every field displayed on the Agent Health card, how it is probed, and what each status means: ### 1. Relay Connection -* **Purpose**: Maintains a bidirectional WebSocket/gRPC reverse proxy tunnel between the in-cluster agent and NudgeBee Server. Allows NuBi and operators to execute live diagnostic queries, fetch pod logs, or run interactive terminal sessions without opening inbound firewall ports into the cluster. +* **Purpose**: Maintains a bidirectional WebSocket/gRPC reverse proxy tunnel between the in-cluster collector and NudgeBee Server. Allows NuBi and operators to execute live diagnostic queries, fetch pod logs, or run interactive terminal sessions without opening inbound firewall ports into the cluster. * **Healthy State**: `Connected` (Green). * **Probe Mechanism**: Continuous WebSocket keepalive ping. * **Failure Causes**: * Outbound firewall blocks TCP port `443` to the Relay server. - * `RELAY_SERVER_SECRET_KEY` mismatch between agent and server. + * `RELAY_SERVER_SECRET_KEY` mismatch between collector and server. * Intermediate reverse proxy drops long-lived WebSocket connections (missing `Upgrade: websocket` headers). --- @@ -68,7 +72,7 @@ Below is the complete reference of every field displayed on the Agent Health car ### 3. Prometheus * **Purpose**: Primary metrics engine for cluster CPU, memory, disk, network usage, and Kubernetes object metrics. * **Healthy State**: `Connected` (Green), with retention duration displayed (e.g. `15d`). -* **Probe Mechanism**: The agent runs the PromQL instant query `vector(1)` through its configured authenticated Prometheus client. A valid Prometheus response with `status: success` marks it Connected. +* **Probe Mechanism**: The collector runs the PromQL instant query `vector(1)` through its configured authenticated Prometheus client. A valid Prometheus response with `status: success` marks it Connected. * **Failure Causes**: Incorrect service URL, DNS or network failure, invalid static or managed-provider credentials, a timeout, or a response that is not a successful Prometheus API payload. * **Troubleshooting Guide**: See [Why is Prometheus Disconnected?](../connect/prometheus-troubleshooting.md). @@ -77,7 +81,7 @@ Below is the complete reference of every field displayed on the Agent Health car ### 4. Alertmanager * **Purpose**: Forwards alert definitions, active firing alerts, and alert silencing rules to NudgeBee's event triage engine. * **Healthy State**: `Connected` (Green). -* **Probe Mechanism**: The agent sends `GET /-/healthy` to the configured Alertmanager URL on each telemetry cycle (60 seconds by default). +* **Probe Mechanism**: The collector sends `GET /-/healthy` to the configured Alertmanager URL on each telemetry cycle (60 seconds by default). * **Failure Causes**: * Alertmanager service not reachable at configured URL. * In-cluster Alertmanager webhook receiver not configured to forward alerts to NudgeBee. @@ -112,7 +116,7 @@ Below is the complete reference of every field displayed on the Agent Health car * **Purpose**: Collects real-time container, pod, and node cost allocations and idle waste metrics. * **Healthy State**: `Connected` (Green). * **Probe Mechanism**: Probes the OpenCost `/healthz` endpoint. -* **Failure Causes**: OpenCost pod not running, or agent lacks RBAC to query OpenCost service. +* **Failure Causes**: OpenCost pod not running, or collector lacks RBAC to query OpenCost service. --- @@ -138,7 +142,7 @@ Below is the complete reference of every field displayed on the Agent Health car --- ### 10. Agent Version & Latest Version -* **Purpose**: Displays the currently running agent container image tag compared against the latest stable release published by NudgeBee. +* **Purpose**: Displays the currently running Cluster Collector container image tag compared against the latest stable release published by NudgeBee. * **Upgrade Recommended**: The Console asks you to update whenever the running version differs from the latest version returned by the server. --- @@ -160,5 +164,5 @@ Below is the complete reference of every field displayed on the Agent Health car ## 4. NuBi Documentation Search Ask NuBi in chat for guided subsystem setup and troubleshooting: -- *"How does the Kubernetes agent probe Prometheus and Loki health?"* +- *"How does the cluster collector probe Prometheus and Loki health?"* - *"What does it mean when Node Agent count shows 0 in Agent Health?"* diff --git a/doc-server/docs/installation/agent/operate/helm_values.md b/doc-server/docs/installation/agent/operate/helm_values.md index 2591fb0d..7c83098c 100644 --- a/doc-server/docs/installation/agent/operate/helm_values.md +++ b/doc-server/docs/installation/agent/operate/helm_values.md @@ -15,7 +15,7 @@ The chart is open source at [`nudgebee/k8s-agent`](https://github.com/nudgebee/k | https://charts.bitnami.com/bitnami | clickhouse | 3.1.* | `opentelemetry-collector.enabled` | | https://open-telemetry.github.io/opentelemetry-helm-charts | opentelemetry-collector | 0.165.0 | `opentelemetry-collector.enabled` | -For task-oriented guidance, see [Enable or Disable Agent Modules](./module-configuration.md) and [Agent Storage and PVCs](./storage-and-pvcs.md). +For task-oriented guidance, see [Enable or Disable Collector Modules](./module-configuration.md) and [Collector Storage and PVCs](./storage-and-pvcs.md). --- @@ -23,14 +23,14 @@ For task-oriented guidance, see [Enable or Disable Agent Modules](./module-confi | Key | Type | Default | Description | |---|---|---|---| -| `runner.nudgebee.auth_secret_key` | string | `""` | Agent auth key from **Admin → Integrations → Kubernetes Clusters**. The backend derives the account and cluster from this key. | +| `runner.nudgebee.auth_secret_key` | string | `""` | Collector auth key from **Admin → Integrations → Kubernetes Clusters**. The backend derives the account and cluster from this key. | | `runner.nudgebee.endpoint` | string | `https://collector.nudgebee.com` | Collector URL. Self-hosted: `https://collector.yourcompany.com`. | | `runner.relay_address` | string | `wss://relay.nudgebee.com/register` | Relay WebSocket URL. Self-hosted: `wss://relay.yourcompany.com/register`. | | `globalConfig.prometheus_url` | string | `""` | Prometheus/Thanos/VictoriaMetrics query URL. Empty = auto-discover in-cluster. | ### Auth key from an existing Secret -If something else creates the credential — External Secrets, a parent chart, your own pipeline — point the agent at that Secret instead of putting the key in your values. Setting this and `auth_secret_key` together fails the install rather than silently picking one. +If something else creates the credential — External Secrets, a parent chart, your own pipeline — point the collector at that Secret instead of putting the key in your values. Setting this and `auth_secret_key` together fails the install rather than silently picking one. ```yaml runner: @@ -49,12 +49,12 @@ A default install can already act on workloads: delete and evict pods, exec into | Key | Type | Default | Description | |---|---|---|---| | `runner.enableWritePermissions` | bool | `false` | Adds the cluster-shape permissions the default install leaves out: node delete, Service/Endpoint/ServiceAccount management, Secret update and delete, namespace create and delete, ResourceQuota and LimitRange writes, `statefulsets/scale`, workload creation, Ingress and NetworkPolicy writes, rollout lifecycle. | -| `runner.readOnly` | bool | `false` | Cuts the ClusterRole down to `get`, `list`, `watch`. No Secrets access at all, no `pods/exec`, no eviction, no node patch. The few writes the agent needs to run come from a Role scoped to the release namespace. | -| `runner.mutateEnabled` | bool | `true` | Turns the runner's mutating actions on or off inside the agent itself (`delete_pod`, `cordon`, `rollout_restart`, PrometheusRule CRUD, Alertmanager silences, Loki rules). With `false` they are never registered at startup, whatever RBAC allows. | +| `runner.readOnly` | bool | `false` | Cuts the ClusterRole down to `get`, `list`, `watch`. No Secrets access at all, no `pods/exec`, no eviction, no node patch. The few writes the collector needs to run come from a Role scoped to the release namespace. | +| `runner.mutateEnabled` | bool | `true` | Turns the runner's mutating actions on or off inside the collector itself (`delete_pod`, `cordon`, `rollout_restart`, PrometheusRule CRUD, Alertmanager silences, Loki rules). With `false` they are never registered at startup, whatever RBAC allows. | | `runner.scannerAutoCopyPullSecrets` | bool | `false` | Lets an image scan copy the scanned pod's `imagePullSecrets` into the scanner namespace so private images can be pulled. Also grants secret update, patch, and delete in the release namespace to clean the copies up afterwards. | | `runner.customClusterRoleRules` | list | `[]` | Extra rules appended to the runner ClusterRole. | | `runnerServiceAccount.imagePullSecrets` | list | `[]` | Pull secrets attached to the runner ServiceAccount. | -| `automountServiceAccountToken` | bool | `true` | Mount the ServiceAccount token in agent pods. | +| `automountServiceAccountToken` | bool | `true` | Mount the ServiceAccount token in collector pods. | | Capability | Default | `enableWritePermissions` | `readOnly` | |---|---|---|---| @@ -82,7 +82,7 @@ helm upgrade nudgebee-agent nudgebee-agent/nudgebee-agent \ Under `readOnly` the rightsizing recommendations still compute; you just cannot apply them from the UI. If your security review needs to see the exact permissions first, the whole read-only ClusterRole is in one file: [`runner-service-account-readonly.yaml`](https://github.com/nudgebee/k8s-agent/blob/main/charts/nudgebee-agent/templates/runner-service-account-readonly.yaml). -If what you want is for the agent not to act, rather than for its ServiceAccount to lose the permission, `mutateEnabled: false` is the smaller change. The actions are never registered and the RBAC stays as it is. +If what you want is for the collector not to act, rather than for its ServiceAccount to lose the permission, `mutateEnabled: false` is the smaller change. The actions are never registered and the RBAC stays as it is. ### Actions triggered from the UI @@ -92,7 +92,7 @@ runner: relay_signing_public_key: "" ``` -This is the relay's Ed25519 public key. The agent uses it to check that a request really came from the relay before running a workload mutation. Leave it empty and those requests are rejected with `401` no matter what RBAC allows. The install command generated by the UI fills it in for you; you only set it by hand when writing your own values file for a self-hosted server. +This is the relay's Ed25519 public key. The collector uses it to check that a request really came from the relay before running a workload mutation. Leave it empty and those requests are rejected with `401` no matter what RBAC allows. The install command generated by the UI fills it in for you; you only set it by hand when writing your own values file for a self-hosted server. --- @@ -113,7 +113,7 @@ In-cluster Prometheus needs none of the `auth` values. Use them for managed back ## Alerts -These values only control the alert rules the chart ships. Getting alerts to the agent is a separate job that happens in your Alertmanager: see [Alert Forwarding](../connect/alertmanager.md). +These values only control the alert rules the chart ships. Getting alerts to the collector is a separate job that happens in your Alertmanager: see [Alert Forwarding](../connect/alertmanager.md). | Key | Type | Default | Description | |---|---|---|---| @@ -156,7 +156,7 @@ See [Logging Integration](../connect/logging/index.md). | `runner.chronosphere.tracesEnabled` | bool | `true` | Report Chronosphere as the traces provider when `url` is set. | | `runner.chronosphere.tracesUrl` | string | `""` | Explicit traces URL; empty falls back to `prometheus_url` when it points at chronosphere.io. | | `runner.pinot.url` / `authToken` / `username` / `password` | string | `""` | Apache Pinot broker. | -| `runner.grafana.url` / `username` / `password` / `extra_headers` | string | `""` | Grafana endpoint the agent proxies UI requests to. `extra_headers` is semicolon-separated. | +| `runner.grafana.url` / `username` / `password` / `extra_headers` | string | `""` | Grafana endpoint the collector proxies UI requests to. `extra_headers` is semicolon-separated. | See [Tracing Integration](../connect/tracing/index.md). @@ -240,9 +240,9 @@ Without the prometheus-operator there is no PodMonitor to create. Scrape the nod | `openshift.createPrivilegedScc` | bool | `false` | Privileged SCC (node agent eBPF). | | `openshift.sccName` / `privilegedSccName` / `sccPriority` / `privilegedSccPriority` | | `null` | Overrides. | | `enablePrometheusStack` | bool | `true` | Asserts that the prometheus-operator CRDs (`ServiceMonitor`, `PodMonitor`, `PrometheusRule`) are registered, so those manifests still render during offline templating (Argo CD, Flux). Set `false` on a cluster with no operator. | -| `enableServiceMonitors` | bool | `true` | Render ServiceMonitors for agent components. | +| `enableServiceMonitors` | bool | `true` | Render ServiceMonitors for collector components. | | `nameOverride` / `fullnameOverride` | string | `""` | Resource naming. | -| `globalConfig.custom_annotations` | object | `{}` | Annotations added to all agent pods. | +| `globalConfig.custom_annotations` | object | `{}` | Annotations added to all collector pods. | ### Installing where there is no Prometheus operator diff --git a/doc-server/docs/installation/agent/operate/module-configuration.md b/doc-server/docs/installation/agent/operate/module-configuration.md index ee434acb..9d5c59d3 100644 --- a/doc-server/docs/installation/agent/operate/module-configuration.md +++ b/doc-server/docs/installation/agent/operate/module-configuration.md @@ -1,11 +1,11 @@ --- sidebar_position: 2 -title: Enable or Disable Agent Modules +title: Enable or Disable Collector Modules --- -# Enable or Disable Agent Modules +# Enable or Disable Collector Modules -Start with the smallest agent installation that supports the workflows you use. Change modules in a values file and run `helm upgrade`; avoid relying on a long sequence of `--set` arguments that is difficult to review later. +Start with the smallest collector installation that supports the workflows you use. Change modules in a values file and run `helm upgrade`; avoid relying on a long sequence of `--set` arguments that is difficult to review later. ## Module controls and impact @@ -123,4 +123,4 @@ The values file is the source of truth for the full resource map. Disabling a wa 4. Upgrade the release and inspect **Agent Health**. 5. Keep the saved values for rollback. -See [Helm Chart Values](./helm_values.md) for the complete operator-facing value reference and [Agent Storage and PVCs](./storage-and-pvcs.md) before disabling a stateful component. +See [Helm Chart Values](./helm_values.md) for the complete operator-facing value reference and [Collector Storage and PVCs](./storage-and-pvcs.md) before disabling a stateful component. diff --git a/doc-server/docs/installation/agent/operate/node-agent-configs.md b/doc-server/docs/installation/agent/operate/node-agent-configs.md index 76ff5ae9..3d109f0e 100644 --- a/doc-server/docs/installation/agent/operate/node-agent-configs.md +++ b/doc-server/docs/installation/agent/operate/node-agent-configs.md @@ -14,7 +14,7 @@ Some of these have a dedicated chart value and are easier to set that way: `node | 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` | | `CGROUPFS_ROOT` | Path to cgroup filesystem mount | `/sys/fs/cgroup` | | `EPHEMERAL_PORT_RANGE` | Skip tracking these TCP port ranges | `32768-60999` | | `TRACK_PUBLIC_NETWORK` | Whitelisted public IP networks to track | `0.0.0.0/0` | @@ -222,7 +222,7 @@ Run this query directly in the Prometheus configured at `globalConfig.prometheus | **Series exist with `job="kubernetes-pods"` or `job="coroot-node-agent"`** | The pod is scraped under an alternate job name. See [Fixing Scrape Job Names](../connect/prometheus-troubleshooting.md#scenario-1-node-agent-is-scraped-under-a-different-job-name). | | **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`. | #### Matching Prometheus Operator Selectors diff --git a/doc-server/docs/installation/agent/operate/storage-and-pvcs.md b/doc-server/docs/installation/agent/operate/storage-and-pvcs.md index 7cad9c59..ea22fc2f 100644 --- a/doc-server/docs/installation/agent/operate/storage-and-pvcs.md +++ b/doc-server/docs/installation/agent/operate/storage-and-pvcs.md @@ -1,11 +1,11 @@ --- sidebar_position: 3 -title: Agent Storage, ClickHouse & OpenTelemetry Collector +title: Collector Storage, ClickHouse & OpenTelemetry Collector --- -# Agent Storage, ClickHouse & OpenTelemetry Collector +# Collector Storage, ClickHouse & OpenTelemetry Collector -The agent runner, event watcher, and node-agent DaemonSet do not require persistent volumes. A default chart installation creates persistent storage for bundled **ClickHouse**, which stores trace and telemetry data received by the bundled **OpenTelemetry Collector**. +The collector runner, event watcher, and node-agent DaemonSet do not require persistent volumes. A default chart installation creates persistent storage for bundled **ClickHouse**, which stores trace and telemetry data received by the bundled **OpenTelemetry Collector**. When ClickHouse or the OpenTelemetry Collector crashloop, restart, or fail to start, follow this guide to identify the root cause and remediate it. diff --git a/doc-server/docs/installation/agent/operate/troubleshoot-agent-connectivity.md b/doc-server/docs/installation/agent/operate/troubleshoot-agent-connectivity.md index e5a02cd6..6be78f95 100644 --- a/doc-server/docs/installation/agent/operate/troubleshoot-agent-connectivity.md +++ b/doc-server/docs/installation/agent/operate/troubleshoot-agent-connectivity.md @@ -1,22 +1,22 @@ --- id: agent-connectivity -title: Troubleshoot NudgeBee Agent Connectivity -sidebar_label: Agent Connectivity & Heartbeat +title: Troubleshoot NudgeBee Cluster Collector Connectivity +sidebar_label: Collector Connectivity & Heartbeat sidebar_position: 2 -keywords: [agent disconnected, agent heartbeat, agent flapping, last connected, proxy agent, agent health, agent status] +keywords: [collector disconnected, collector heartbeat, collector flapping, last connected, proxy agent, agent health, collector status] intent: diagnose provider: all --- -# Troubleshoot NudgeBee Agent Connectivity +# Troubleshoot NudgeBee Cluster Collector Connectivity -This guide helps you diagnose and resolve connectivity issues between your infrastructure agents (Kubernetes Agent, Proxy Agent, or Cloud Integrations) and the NudgeBee backend platform. +This guide helps you diagnose and resolve connectivity issues between NudgeBee's data-collection components (Cluster Collector, Proxy Agent, or Cloud Integrations) and the NudgeBee backend platform. --- -## 1. What Agent Connectivity Status Means +## 1. What Collector Connectivity Status Means -NudgeBee monitors the health of all registered agents using an active telemetry heartbeat loop: +NudgeBee monitors the health of all registered collectors using an active telemetry heartbeat loop: ```mermaid sequenceDiagram @@ -40,40 +40,40 @@ sequenceDiagram | Status | Badge | Meaning | | :--- | :--- | :--- | -| **Connected** | 🟢 Green | The agent is actively reporting telemetry and sending periodic heartbeats. | -| **Not Connected** | 🔴 Red | No telemetry heartbeat has been received within the connection threshold, or the agent process is stopped. | -| **Degraded / Warning** | 🟡 Yellow | The core agent is connected, but one or more critical subsystems (e.g., Prometheus, Logs, Traces) failed their local health probe. | -| **Pending / Initializing** | ⚪ Gray | The agent registration has been created, but the initial heartbeat has not yet been received. | +| **Connected** | 🟢 Green | The collector is actively reporting telemetry and sending periodic heartbeats. | +| **Not Connected** | 🔴 Red | No telemetry heartbeat has been received within the connection threshold, or the collector process is stopped. | +| **Degraded / Warning** | 🟡 Yellow | The core collector is connected, but one or more critical subsystems (e.g., Prometheus, Logs, Traces) failed their local health probe. | +| **Pending / Initializing** | ⚪ Gray | The collector registration has been created, but the initial heartbeat has not yet been received. | --- ## 2. Key Connectivity Concepts ### What Does "Last Connected" Mean? -`Last Connected` represents the exact UTC timestamp when the NudgeBee backend last received and validated a telemetry payload or heartbeat ping from the agent (`last_connected_at`). +`Last Connected` represents the exact UTC timestamp when the NudgeBee backend last received and validated a telemetry payload or heartbeat ping from the collector (`last_connected_at`). ### Heartbeat Staleness & Recovery -- **Heartbeat Interval**: The Kubernetes agent periodically posts telemetry snapshots to the backend. -- **Automatic Recovery**: As soon as the agent recovers and delivers a successful heartbeat tick, the backend automatically transitions the status back to `Connected` without requiring manual intervention or cluster restarts. +- **Heartbeat Interval**: The cluster collector periodically posts telemetry snapshots to the backend. +- **Automatic Recovery**: As soon as the collector recovers and delivers a successful heartbeat tick, the backend automatically transitions the status back to `Connected` without requiring manual intervention or cluster restarts. -### Why Does an Agent Alternate (Flap) Between Connected and Not Connected? +### Why Does a Collector Alternate (Flap) Between Connected and Not Connected? Frequent status toggling usually indicates one of three root causes: -1. **Pod OOMKills / Restarts**: The agent pod is repeatedly crashing and restarting due to memory pressure during large cluster discovery sweeps. -2. **Network Jitter / Proxy Timeouts**: Intermediate firewalls, HTTP proxies, or cloud NAT gateways are dropping idle connections before the agent's keepalive ping. +1. **Pod OOMKills / Restarts**: The collector pod is repeatedly crashing and restarting due to memory pressure during large cluster discovery sweeps. +2. **Network Jitter / Proxy Timeouts**: Intermediate firewalls, HTTP proxies, or cloud NAT gateways are dropping idle connections before the collector's keepalive ping. 3. **Telemetry Probes Timeout**: A local datasource probe (such as a slow Prometheus query) exceeds the internal probe budget, delaying the heartbeat post. -### Agent vs. Proxy Agent -- **Direct Kubernetes Agent**: Runs inside your target Kubernetes cluster. It directly scrapes local endpoints (`http://prometheus-server...`) and opens an outbound connection to NudgeBee. -- **Proxy Agent**: Runs in a bastion or jump-host environment. It is designed to bridge private, air-gapped VPCs/clusters or private databases where direct outbound agent installation is restricted. See [Proxy Agent Troubleshooting](../../proxy-agent/troubleshooting.md). +### Collector vs. Proxy Agent +- **Direct Cluster Collector**: Runs inside your target Kubernetes cluster. It directly scrapes local endpoints (`http://prometheus-server...`) and opens an outbound connection to NudgeBee. +- **Proxy Agent**: Runs in a bastion or jump-host environment. It is designed to bridge private, air-gapped VPCs/clusters or private databases where direct outbound collector installation is restricted. See [Proxy Agent Troubleshooting](../../proxy-agent/troubleshooting.md). -### Agent Version Compatibility -NudgeBee agents maintain broad backward compatibility with NudgeBee server releases. However, older agent versions may lack probe definitions for newer features or custom trace providers, leading to unpopulated health fields in the UI. Upgrading your agent alongside server updates is recommended. +### Collector Version Compatibility +NudgeBee Cluster Collectors maintain broad backward compatibility with NudgeBee server releases. However, older collector versions may lack probe definitions for newer features or custom trace providers, leading to unpopulated health fields in the UI. Upgrading your collector alongside server updates is recommended. --- ## 3. Diagnostic Decision Tree -Use this decision tree to pinpoint why your agent is disconnected: +Use this decision tree to pinpoint why your collector is disconnected: ```mermaid graph TD @@ -92,17 +92,17 @@ graph TD ## 4. Provider-Specific Verification Steps -### A. Kubernetes Agent -Run the following commands to check agent pod health and logs: +### A. Cluster Collector +Run the following commands to check collector pod health and logs: ```bash # 1. Check pod status in the release namespace kubectl get pods -n nudgebee-agent -o wide -# 2. Inspect recent agent pod events +# 2. Inspect recent collector pod events kubectl describe deployment nudgebee-agent-runner -n nudgebee-agent -# 3. Stream live logs from the agent runner +# 3. Stream live logs from the collector runner kubectl logs -n nudgebee-agent deploy/nudgebee-agent-runner -c runner --tail=100 -f ``` @@ -115,7 +115,7 @@ kubectl logs -n nudgebee-agent deploy/nudgebee-agent-runner -c runner --tail=100 --- ### B. AWS Cloud Account Synchronization -For AWS agent connections: +For AWS collector connections: 1. Verify that the **CloudFormation Stack** deployed in the target account is in `CREATE_COMPLETE` or `UPDATE_COMPLETE` state. 2. Confirm the cross-account IAM Role trust policy allows NudgeBee's backend IAM role (`sts:AssumeRole`). 3. Check if AWS API rate limiting is occurring (`RequestLimitExceeded`). @@ -140,7 +140,7 @@ For GCP connections: ### Failure 1: Invalid Backend Authentication Secret - **Symptom**: Pod logs output `telemetry post failed: HTTP 401 Unauthorized` or `auth secret mismatch`. -- **Cause**: The `authSecretKey` in the agent's Helm release does not match the secret key configured on the NudgeBee server. +- **Cause**: The `authSecretKey` in the collector's Helm release does not match the secret key configured on the NudgeBee server. - **Remediation**: ```bash helm upgrade --install nudgebee-agent nudgebee-agent/nudgebee-agent \ @@ -155,7 +155,7 @@ For GCP connections: - **Cause**: Kubernetes cluster egress policies or perimeter firewalls block outbound HTTPS traffic on port `443` to the NudgeBee backend or relay endpoint. - **Remediation**: - Whitelist the NudgeBee backend domain and relay domain on port `443` (TCP). - - If using an outbound corporate HTTP proxy, configure `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` in the agent's `values.yaml`: + - If using an outbound corporate HTTP proxy, configure `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` in the collector's `values.yaml`: ```yaml runner: additional_env_vars: @@ -175,7 +175,7 @@ For GCP connections: ``` ### Failure 3: Memory Exhaustion (OOMKilled) on Large Clusters -- **Symptom**: Agent pod restarts frequently with `OOMKilled (Exit Code 137)`. +- **Symptom**: Collector pod restarts frequently with `OOMKilled (Exit Code 137)`. - **Cause**: The runner's informer cache and discovery snapshot exceed its configured memory limit. Object count matters more than request traffic. - **Remediation**: Increase resource limits in `values.yaml`: @@ -194,7 +194,7 @@ For GCP connections: ## 6. Support Escalation & Diagnostic Bundle -Collect the affected account, UTC time range, pod status, recent Kubernetes events, and relevant agent logs. Confirm your namespace and pod/container names before running the commands. +Collect the affected account, UTC time range, pod status, recent Kubernetes events, and relevant collector logs. Confirm your namespace and pod/container names before running the commands. The example below requires Bash, Python 3, and kubectl. It stores diagnostics with owner-only permissions and redacts common credential formats. Redaction is best-effort: review the complete file locally before sharing it, including URLs, event messages, customer identifiers, and application-specific secrets. @@ -233,5 +233,5 @@ If collection fails, inspect the partial output locally and correct the namespac ## 7. NuBi Documentation Search Ask NuBi in chat for guided connectivity troubleshooting: -- *"How do I troubleshoot a disconnected Kubernetes agent in NudgeBee?"* -- *"How do I generate a sanitized agent diagnostic bundle for support?"* +- *"How do I troubleshoot a disconnected cluster collector in NudgeBee?"* +- *"How do I generate a sanitized collector diagnostic bundle for support?"* diff --git a/doc-server/docs/installation/index.md b/doc-server/docs/installation/index.md index 0fd4acc3..9d281bad 100644 --- a/doc-server/docs/installation/index.md +++ b/doc-server/docs/installation/index.md @@ -7,8 +7,8 @@ sidebar_label: Installation Overview Before you install, select the deployment model that matches your organization's requirements: -- **Cloud SaaS** — NudgeBee hosts and manages the server control plane for you. You only install the **NudgeBee Agent** on each Kubernetes cluster you want monitored (or connect a cloud account for instant discovery). Generate your auth key in the UI and go straight to [Agent Installation](./agent/installation/index.md). -- **Self-Hosted** — You run the **NudgeBee Server** inside your own Kubernetes cluster, giving you full data ownership and air-gapped support. Deploy the [Server](./server/index.md) first, then install the [Agent](./agent/installation/index.md) on each monitored cluster. +- **Cloud SaaS** — NudgeBee hosts and manages the server control plane for you. You only install the **NudgeBee Cluster Collector** on each Kubernetes cluster you want monitored (or connect a cloud account for instant discovery). Generate your auth key in the UI and go straight to [Cluster Collector Installation](./agent/installation/index.md). +- **Self-Hosted** — You run the **NudgeBee Server** inside your own Kubernetes cluster, giving you full data ownership and air-gapped support. Deploy the [Server](./server/index.md) first, then install the [Cluster Collector](./agent/installation/index.md) on each monitored cluster. :::info Scope & Infrastructure Prerequisites **Kubernetes-Specialized**: NudgeBee monitors Kubernetes workloads. @@ -24,8 +24,8 @@ Use the table below to determine the exact path for your setup: | Your Situation | Recommended Model | Where to Go | |---|---|---| -| **Want fastest start & zero infra management** | **Cloud SaaS** | [Agent Installation](./agent/installation/index.md) (or [Cloud Account Discovery](../features/Cloud/index.md)) | -| **Strict data residency / air-gapped environment** | **Self-Hosted** | [Server Installation](./server/index.md) → then [Agent Installation](./agent/installation/index.md) | +| **Want fastest start & zero infra management** | **Cloud SaaS** | [Cluster Collector Installation](./agent/installation/index.md) (or [Cloud Account Discovery](../features/Cloud/index.md)) | +| **Strict data residency / air-gapped environment** | **Self-Hosted** | [Server Installation](./server/index.md) → then [Cluster Collector Installation](./agent/installation/index.md) | | **Evaluating free open-source edition** | **Self-Hosted (Community)** | [Server Installation](./server/index.md) (select Community edition) | | **No Kubernetes clusters yet** | **Cloud SaaS** | Sign up at [app.nudgebee.com](https://app.nudgebee.com) — add clusters when ready | @@ -34,6 +34,6 @@ Use the table below to determine the exact path for your setup: ## Installation Components * **[Server Installation](./server/index.md)** — *(Self-hosted only)* Deploy the central control plane, Semantic Knowledge Graph, and workflow engine to your Kubernetes cluster. -* **[K8s Agent Installation](./agent/installation/index.md)** — *(Everyone)* Install the lightweight collector DaemonSet and runner into each Kubernetes cluster you want to monitor. +* **[Cluster Collector Installation](./agent/installation/index.md)** — *(Everyone)* Install the lightweight collector DaemonSet and runner into each Kubernetes cluster you want to monitor. (Formerly called the K8s Agent; the Helm chart and namespace are still `nudgebee-agent`.) * **[Proxy Agent](./proxy-agent/index.md)** — *(Optional)* Deploy secure proxy connectivity to private datasources, isolated databases, or internal endpoints. diff --git a/doc-server/docs/installation/proxy-agent/index.md b/doc-server/docs/installation/proxy-agent/index.md index b090ff4e..84141795 100644 --- a/doc-server/docs/installation/proxy-agent/index.md +++ b/doc-server/docs/installation/proxy-agent/index.md @@ -6,15 +6,15 @@ sidebar_position: 1 ## When to Use -Use the Proxy Agent when you need NudgeBee to query databases, run SSH commands on servers, or access services that are **not running inside Kubernetes**, or when your infrastructure is in a private network that the NudgeBee K8s agent cannot reach. +Use the Proxy Agent when you need NudgeBee to query databases, run SSH commands on servers, or access services that are **not running inside Kubernetes**, or when your infrastructure is in a private network that the NudgeBee Cluster Collector cannot reach. | Scenario | Use | |----------|-----| | Database on a VM, bare metal, or managed service (RDS, Cloud SQL, etc.) | **Proxy Agent** | | Run commands on Linux/Windows servers via SSH | **Proxy Agent** | -| Database running inside your Kubernetes cluster | K8s Agent (default) | +| Database running inside your Kubernetes cluster | Cluster Collector (default) | | Database or server in a private VPC with no K8s access | **Proxy Agent** | -| You already have a K8s agent but want to add non-K8s resources | **Proxy Agent** (alongside your K8s agent) | +| You already have a Cluster Collector but want to add non-K8s resources | **Proxy Agent** (alongside your Cluster Collector) | ## How It Works @@ -100,7 +100,7 @@ Best for: Self-hosted deployments, GitOps workflows, infrastructure-as-code setu ### Proxy-only versus dual-mode -Most types above are **dual-mode**: NudgeBee can reach them either through the in-cluster agent or through Forager, and you choose per integration with the connection mode. `postgresql`, `mysql`, `mssql`, `clickhouse`, `oracle`, `redis`, `ssh`, `mcp` and `rabbitmq` all work either way. +Most types above are **dual-mode**: NudgeBee can reach them either through the Cluster Collector or through Forager, and you choose per integration with the connection mode. `postgresql`, `mysql`, `mssql`, `clickhouse`, `oracle`, `redis`, `ssh`, `mcp` and `rabbitmq` all work either way. `mongodb_proxy`, `kafka_proxy` and `http_proxy` are **proxy-only** — they have no in-cluster equivalent, so Forager is the only way to reach them. diff --git a/doc-server/docs/installation/server/helm_values.md b/doc-server/docs/installation/server/helm_values.md index c3fb372d..198fe5e0 100644 --- a/doc-server/docs/installation/server/helm_values.md +++ b/doc-server/docs/installation/server/helm_values.md @@ -21,10 +21,10 @@ side-by-side examples. | Key | Type | Default | Description | |-----|------|---------|-------------| -| agent.accessKey | string | `""` | Agent credential. Set explicitly for offline/GitOps renders (Argo CD, Flux) — the chart cannot read an existing credential back and refuses to re-issue it on upgrade. | +| agent.accessKey | string | `""` | Cluster Collector credential. Set explicitly for offline/GitOps renders (Argo CD, Flux) — the chart cannot read an existing credential back and refuses to re-issue it on upgrade. | | agent.accessSecret | string | `""` | See `agent.accessKey`. | -| agent.clusterName | string | `"nb-control-plane-k8s"` | Name the bundled agent registers its cluster under. | -| agent.enabled | bool | `true` | Installs the NudgeBee agent alongside the server and connects the hosting cluster. The agent shares this Helm release, so `helm uninstall` removes it too. | +| agent.clusterName | string | `"nb-control-plane-k8s"` | Name the bundled Cluster Collector registers its cluster under. | +| agent.enabled | bool | `true` | Installs the NudgeBee Cluster Collector alongside the server and connects the hosting cluster. It shares this Helm release, so `helm uninstall` removes it too. | | app.fullnameOverride | string | `"app"` | | | app.image.repository | string | `"nudgebee-app"` | | | app.image.tag | string | `""` | | diff --git a/doc-server/docs/installation/server/index.md b/doc-server/docs/installation/server/index.md index 172cb685..904f5de2 100644 --- a/doc-server/docs/installation/server/index.md +++ b/doc-server/docs/installation/server/index.md @@ -8,10 +8,10 @@ import TabItem from '@theme/TabItem'; # Server Installation -The NudgeBee Server is the central control plane of the NudgeBee platform. It hosts the web UI, Semantic Knowledge Graph, AI agent orchestrator, and workflow execution engine. It receives data from NudgeBee Agents across your clusters and integrates with identity providers and observability tools. +The NudgeBee Server is the central control plane of the NudgeBee platform. It hosts the web UI, Semantic Knowledge Graph, AI agent orchestrator, and workflow execution engine. It receives data from NudgeBee Cluster Collectors across your clusters and integrates with identity providers and observability tools. :::note[Self-Hosted Only] -**Cloud SaaS users**: You do not need to install the server. It is fully managed for you at [app.nudgebee.com](https://app.nudgebee.com). Skip directly to [Agent Installation](../agent/installation/index.md). +**Cloud SaaS users**: You do not need to install the server. It is fully managed for you at [app.nudgebee.com](https://app.nudgebee.com). Skip directly to [Cluster Collector Installation](../agent/installation/index.md). **Infrastructure Scope**: The self-hosted NudgeBee Server requires its own Kubernetes cluster (or dedicated namespace) on Kubernetes v1.27+. If you do not operate Kubernetes infrastructure, use Cloud SaaS. ::: @@ -19,7 +19,7 @@ The NudgeBee Server is the central control plane of the NudgeBee platform. It ho :::tip[Choosing an edition] The self-hosted server comes in two editions (see [Editions & Capabilities](../../editions.md) for the full comparison): -- **Community** — free, source-available self-hosted edition. The Server is licensed under **BSL 1.1** (converting to Apache 2.0 on its stated change date); Agents are **Apache 2.0**. Images are pulled from the public `ghcr.io/nudgebee` registry. **No license key required.** OAuth SSO (Google, Okta, OneLogin, Azure AD / B2C, Auth0), magic-link email, and credentials login are all included. +- **Community** — free, source-available self-hosted edition. The Server is licensed under **BSL 1.1** (converting to Apache 2.0 on its stated change date); Cluster Collectors are **Apache 2.0**. Images are pulled from the public `ghcr.io/nudgebee` registry. **No license key required.** OAuth SSO (Google, Okta, OneLogin, Azure AD / B2C, Auth0), magic-link email, and credentials login are all included. - **Enterprise** — adds **SAML 2.0** SSO, NudgeBee's managed models (`nb-llm`, `nb-slm`), and commercial SLA support. Images are pulled from `registry.nudgebee.com` and require a license key. The installation steps below use tabs — pick your edition in each step. @@ -160,7 +160,7 @@ Your cluster needs the following network access. Understanding why each rule exi - **Outbound to Container Registry** (`ghcr.io/nudgebee` or `registry.nudgebee.com` on port 443): **Required during install/upgrade** to pull container images. *What breaks if blocked:* Pods get stuck in `ImagePullBackOff`. - **Internal Cluster DNS Resolution**: **Required for internal service communication**. The server pods must be able to resolve `BASE_URL` and internal service endpoints. *What breaks if blocked:* Auth callback loops and service-to-service communication failures. - **Outbound to Integrations** (Slack, Jira, Teams, GitHub, OpenAI / Cloud APIs on port 443): **Required only for enabled integrations**. *What breaks if blocked:* Alert notifications, auto-PRs, or AI analysis queries will fail to dispatch. -- **Inbound Access** (Port 80/443 via Ingress or port-forward): **Required for user web UI access, webhook triggers, and agent telemetry reception**. +- **Inbound Access** (Port 80/443 via Ingress or port-forward): **Required for user web UI access, webhook triggers, and collector telemetry reception**. :::tip Start Simple with Port-Forwarding **Why skip Ingress initially?** For local evaluation, testing, or sandboxes, you can run NudgeBee entirely with `kubectl port-forward` without provisioning DNS records, public IPs, or SSL certificates. Add Ingress when transitioning to team use. @@ -175,7 +175,7 @@ The installation follows three steps: select your edition, configure `values.yam ### Step 1: Select Your Edition & Registry Login :::caution[Protecting Your License & Auth Credentials] -**Keep your license / auth key secret.** This key authenticates your cluster to the NudgeBee registry and allows agents to report into your control plane. Treat it like a root password: +**Keep your license / auth key secret.** This key authenticates your cluster to the NudgeBee registry and allows collectors to report into your control plane. Treat it like a root password: - Store it in a secret manager (AWS Secrets Manager, Vault) or a Kubernetes Secret. - Never commit it to version control or paste it in shared channels. - Avoid passing it as an inline CLI flag to prevent it from saving in your shell history (e.g. use `read -s NUDGEBEE_LICENSE_KEY` or environment files). @@ -319,8 +319,8 @@ kubectl get pods -n nudgebee | Pod Name Pattern | Ready State | Status | Role | |---|---|---|---| | `nudgebee-app-*` | `1/1` | `Running` | Main UI and GraphQL/REST API | -| `nudgebee-k8s-collector-*` | `1/1` | `Running` | Telemetry receiver for agents | -| `nudgebee-relay-server-*` | `1/1` | `Running` | WebSocket agent relay server | +| `nudgebee-k8s-collector-*` | `1/1` | `Running` | Telemetry receiver for Cluster Collectors | +| `nudgebee-relay-server-*` | `1/1` | `Running` | WebSocket Cluster Collector relay server | | `nudgebee-postgresql-0` | `1/1` | `Running` | Core database (if bundled) | | `nudgebee-rabbitmq-0` | `1/1` | `Running` | Event message bus (if bundled) | | `nudgebee-schema-migration-*` | `0/1` | `Completed` | Post-install database migration job | @@ -387,9 +387,9 @@ Once logged into the dashboard, complete your initial control plane verification 1. **Verify UI & Dashboard Navigation**: Navigate through **Kubernetes**, **Troubleshoot**, and **Optimizations** to confirm all views load without errors. 2. **Connect an LLM Provider (BYOM)**: Navigate to **Settings → AI / LLM** and configure your API key ([OpenAI, AWS Bedrock, or Ollama](../../integrations/LLM/)) to enable NuBi AI investigations and automated RCA. -3. **Next Step: Install the K8s Agent**: The NudgeBee Server is the control plane. To begin ingesting real-time pod telemetry, logs, and metrics from your target clusters, proceed to: +3. **Next Step: Install the Cluster Collector**: The NudgeBee Server is the control plane. To begin ingesting real-time pod telemetry, logs, and metrics from your target clusters, proceed to: -👉 **[Install the NudgeBee Agent on Your Cluster](../agent/installation/index.md)** +👉 **[Install the NudgeBee Cluster Collector on Your Cluster](../agent/installation/index.md)** --- @@ -409,11 +409,11 @@ NudgeBee exposes three services that each need their own Ingress entry: | Service | Purpose | Example domain | |---|---|---| | **App** | The web UI and API | `nudgebee.yourcompany.com` | -| **Collector** | Receives data from agents running in your monitored clusters | `collector.yourcompany.com` | -| **Relay** | WebSocket connection for real-time agent communication | `relay.yourcompany.com` | +| **Collector Server** | Receives data from Cluster Collectors running in your monitored clusters | `collector.yourcompany.com` | +| **Relay** | WebSocket connection for real-time Cluster Collector communication | `relay.yourcompany.com` | :::info -**Relay and Collector URLs for Agent Installation**: When you install agents with Ingress enabled, use: +**Relay and Collector URLs for Cluster Collector Installation**: When you install collectors with Ingress enabled, use: - **Relay Server URL**: `wss://relay.yourcompany.com` - **Collector Server URL**: `https://collector.yourcompany.com` ::: @@ -618,7 +618,7 @@ kubectl logs deployment/nudgebee-services-server -n nudgebee | grep -i rabbit Verify that `RABBIT_MQ_HOST` matches your service name (default `rabbitmq` or `nudgebee-rabbitmq`) and that the `RABBIT_MQ_PASSWORD` matches the secret generated during install. #### 4. Ingress 502 Bad Gateway / WebSocket EOF -If the NudgeBee web UI loads but live events, agent connections, or NuBi AI chat stream disconnect unexpectedly: +If the NudgeBee web UI loads but live events, Cluster Collector connections, or NuBi AI chat stream disconnect unexpectedly: **Resolution:** Ensure your Ingress controller is configured for long-lived WebSocket connections. For NGINX Ingress, apply these annotations: @@ -671,6 +671,6 @@ This removes all NudgeBee components and data. Make sure to back up any data you Your NudgeBee server is running. Here is what to do next: -1. **[Install the NudgeBee Agent](../agent/installation/index.md)** on each Kubernetes cluster you want to monitor — this is how NudgeBee gets visibility into your workloads. +1. **[Install the NudgeBee Cluster Collector](../agent/installation/index.md)** on each Kubernetes cluster you want to monitor — this is how NudgeBee gets visibility into your workloads. 2. **[Configure Integrations](../../integrations/index.md)** — connect your observability tools, notification channels, and LLM provider to unlock the full platform. 3. **[Explore the Getting Started Guide](../../features/index.md)** — see the recommended setup order and what to do after your first login. diff --git a/doc-server/docs/installation/server/upgrade.md b/doc-server/docs/installation/server/upgrade.md index fd310c4b..011902c5 100644 --- a/doc-server/docs/installation/server/upgrade.md +++ b/doc-server/docs/installation/server/upgrade.md @@ -7,7 +7,7 @@ import TabItem from '@theme/TabItem'; # Upgrade NudgeBee Server -Upgrading your NudgeBee Server control plane ensures you benefit from the latest features, security patches, database optimizations, and agent compatibility updates. +Upgrading your NudgeBee Server control plane ensures you benefit from the latest features, security patches, database optimizations, and Cluster Collector compatibility updates. This guide provides code-grounded operational procedures for upgrading NudgeBee Server via Helm, inspecting manifest diffs, troubleshooting database migration hooks, diagnosing StatefulSet/PVC storage issues, and executing rollback runbooks. @@ -24,7 +24,7 @@ The chart location and image registry differ by edition (see [Editions & Capabil ### Version Pinning Invariant In production environments, **always pin explicit chart versions** using `--version `. Never run unbounded upgrades against `latest`, which can pull unverified dependencies or major database schema changes without preparation. -Review the [Server Release Notes](../../releases/server/index.md) before upgrading to check for breaking schema migrations, minimum agent version requirements, or deprecated Helm values. +Review the [Server Release Notes](../../releases/server/index.md) before upgrading to check for breaking schema migrations, minimum Cluster Collector version requirements, or deprecated Helm values. ### Export Active Configuration & Stored Values Helm merges your supplied `-f values.yaml` with values stored in the Helm release secret from the previous deployment. Stored values can carry obsolete parameters across major chart revisions. @@ -525,7 +525,7 @@ kubectl get pods --namespace nudgebee --field-selector=status.phase!=Running kubectl run curl-test --rm -it --image=curlimages/curl --restart=Never -- \ -sS http://nudgebee-services-server.nudgebee.svc.cluster.local:8080/healthz -# 4. Verify connected agents can reach relay-server +# 4. Verify connected Cluster Collectors can reach relay-server kubectl logs --namespace nudgebee -l app.kubernetes.io/name=relay-server --tail=50 | grep -i "handshake" ``` From 5f305925384b7ca40ee4d0fb946ad0e23928dbd3 Mon Sep 17 00:00:00 2001 From: Sahil Patil Date: Tue, 8 Sep 2026 09:38:27 +0000 Subject: [PATCH 2/5] docs(installation): replace collector architecture diagram MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Claude-Session: https://claude.ai/code/session_01GXgnUKdn8vXQn4oiXSMrDG --- doc-server/docs/installation/agent/index.md | 55 ++++---------- .../architecture/cluster-collector-dark.svg | 74 +++++++++++++++++++ .../architecture/cluster-collector-light.svg | 74 +++++++++++++++++++ 3 files changed, 163 insertions(+), 40 deletions(-) create mode 100644 doc-server/static/img/architecture/cluster-collector-dark.svg create mode 100644 doc-server/static/img/architecture/cluster-collector-light.svg diff --git a/doc-server/docs/installation/agent/index.md b/doc-server/docs/installation/agent/index.md index 5d09e3d8..6b2ce845 100644 --- a/doc-server/docs/installation/agent/index.md +++ b/doc-server/docs/installation/agent/index.md @@ -3,6 +3,9 @@ sidebar_position: 1 sidebar_label: Cluster Collector --- +import ThemedImage from '@theme/ThemedImage'; +import useBaseUrl from '@docusaurus/useBaseUrl'; + # Cluster Collector The NudgeBee Cluster Collector is a lightweight software component that runs inside your Kubernetes cluster. It collects data about workloads, performance, cost, and security, and sends it to the NudgeBee server — feeding the [Semantic Knowledge Graph](../../features/knowledge-graph.md) that powers NudgeBee's Cloud-Ops Intelligence. You need to install a collector in every cluster that you want NudgeBee to monitor. The collector supports AWS, Azure, GCP, and on-premises Kubernetes environments. @@ -67,46 +70,18 @@ Kubernetes. The NudgeBee Cluster Collector runs within your Kubernetes cluster. The main component is the Runner, which acts as a central controller — it coordinates data collection from cluster components and maintains a secure, outbound-only WebSocket connection to the NudgeBee Server. -```mermaid -flowchart TB - classDef runner fill:#eff6ff,stroke:#3b82f6,stroke-width:2px,color:#1e40af,rx:6,ry:6; - classDef collector fill:#f0fdf4,stroke:#22c55e,stroke-width:2px,color:#14532d,rx:6,ry:6; - classDef k8s fill:#fffbeb,stroke:#f59e0b,stroke-width:2px,color:#92400e,rx:6,ry:6; - classDef server fill:#f5f3ff,stroke:#8b5cf6,stroke-width:2px,color:#5b21b6,rx:6,ry:6; - - subgraph MONITORED["Monitored Kubernetes Cluster"] - API_SERVER["Kubernetes API Server
Cluster state, Pods, Deployments"]:::k8s - - subgraph AGENT["NudgeBee Agent Namespace (nudgebee-agent)"] - RUNNER["NudgeBee Runner (Deployment)
• Aggregates telemetry signals
• Executes in-cluster diagnostic & remediation tasks
• Outbound WSS tunnel"]:::runner - KUBEWATCH["Event Watcher (Kubewatch)
Streams resource changes & pod events"]:::collector - NODE_AGENT["Node Agent (DaemonSet)
eBPF network metrics, latency & packet telemetry"]:::collector - OTEL["OTel Collector + ClickHouse
Installed by the chart, stores eBPF spans"]:::collector - end - - PROM["Prometheus / VictoriaMetrics
Yours, not installed by the agent"]:::k8s - AM["Alertmanager
Yours — needs a receiver pointing at the agent"]:::k8s - LOGS["Log store
Loki • Elasticsearch • SigNoz"]:::k8s - end - - subgraph BACKEND["NudgeBee Server Control Plane"] - RELAY["Relay Server (:8080)
wss://relay.nudgebee.com/register"]:::server - COLLECTOR["Collector Server
https://collector.nudgebee.com"]:::server - end - - API_SERVER -->|Watch Events| KUBEWATCH - KUBEWATCH -->|Forward Events| RUNNER - NODE_AGENT -->|Scraped by| PROM - NODE_AGENT -->|OTLP Spans| OTEL - AM -->|"POST /api/alerts"| RUNNER - - RUNNER -->|Query Metrics| PROM - RUNNER -->|Query Logs| LOGS - RUNNER -->|Query Traces| OTEL - - RUNNER -->|"Outbound WSS :443"| RELAY - RUNNER -->|"HTTPS Telemetry :443"| COLLECTOR -``` +
+ +
+ The Runner is the only component that talks to NudgeBee, and it only ever dials out. +
+
## Components diff --git a/doc-server/static/img/architecture/cluster-collector-dark.svg b/doc-server/static/img/architecture/cluster-collector-dark.svg new file mode 100644 index 00000000..cb4cb8d7 --- /dev/null +++ b/doc-server/static/img/architecture/cluster-collector-dark.svg @@ -0,0 +1,74 @@ + + + + + + + + + +MONITORED KUBERNETES CLUSTER +ALREADY RUNNING IN YOUR CLUSTER + +NUDGEBEE CLUSTER COLLECTOR +namespace: nudgebee-agent + +NUDGEBEE CONTROL PLANE + +watch events + +events + +POST /api/alerts + +query logs + +PromQL + +query traces + +OTLP spans + +scraped for eBPF network metrics + + + +Kubernetes API Server +Cluster state, pods, events + +Alertmanager +Yours — needs a receiver + +Log store +Loki · Elasticsearch · SigNoz + +Prometheus +VictoriaMetrics · Thanos · Mimir + +Event Watcher +Kubewatch + +Runner +Deployment · the only component that talks to NudgeBee +Aggregates telemetry · runs in-cluster diagnostics +Holds the one outbound tunnel + +Node Agent +DaemonSet · eBPF + +OTel Collector ++ ClickHouse (bundled) + +Relay Server +wss://relay… · 443 + +Collector Server +https://collector… · 443 +How data moves + +pushed into the collector + +collector queries in place — no second copy + +outbound only · no inbound port opened + \ No newline at end of file diff --git a/doc-server/static/img/architecture/cluster-collector-light.svg b/doc-server/static/img/architecture/cluster-collector-light.svg new file mode 100644 index 00000000..2587f379 --- /dev/null +++ b/doc-server/static/img/architecture/cluster-collector-light.svg @@ -0,0 +1,74 @@ + + + + + + + + + +MONITORED KUBERNETES CLUSTER +ALREADY RUNNING IN YOUR CLUSTER + +NUDGEBEE CLUSTER COLLECTOR +namespace: nudgebee-agent + +NUDGEBEE CONTROL PLANE + +watch events + +events + +POST /api/alerts + +query logs + +PromQL + +query traces + +OTLP spans + +scraped for eBPF network metrics + + + +Kubernetes API Server +Cluster state, pods, events + +Alertmanager +Yours — needs a receiver + +Log store +Loki · Elasticsearch · SigNoz + +Prometheus +VictoriaMetrics · Thanos · Mimir + +Event Watcher +Kubewatch + +Runner +Deployment · the only component that talks to NudgeBee +Aggregates telemetry · runs in-cluster diagnostics +Holds the one outbound tunnel + +Node Agent +DaemonSet · eBPF + +OTel Collector ++ ClickHouse (bundled) + +Relay Server +wss://relay… · 443 + +Collector Server +https://collector… · 443 +How data moves + +pushed into the collector + +collector queries in place — no second copy + +outbound only · no inbound port opened + \ No newline at end of file From da272c82fdce82d094d3282372a21a5a7f36b0a4 Mon Sep 17 00:00:00 2001 From: Sahil Patil Date: Tue, 8 Sep 2026 10:17:30 +0000 Subject: [PATCH 3/5] docs(installation): add missing components to architecture diagram MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Claude-Session: https://claude.ai/code/session_01GXgnUKdn8vXQn4oiXSMrDG --- doc-server/docs/installation/agent/index.md | 7 + .../architecture/cluster-collector-dark.svg | 157 ++++++++++-------- .../architecture/cluster-collector-light.svg | 157 ++++++++++-------- 3 files changed, 189 insertions(+), 132 deletions(-) diff --git a/doc-server/docs/installation/agent/index.md b/doc-server/docs/installation/agent/index.md index 6b2ce845..f9da80cf 100644 --- a/doc-server/docs/installation/agent/index.md +++ b/doc-server/docs/installation/agent/index.md @@ -70,6 +70,8 @@ Kubernetes. The NudgeBee Cluster Collector runs within your Kubernetes cluster. The main component is the Runner, which acts as a central controller — it coordinates data collection from cluster components and maintains a secure, outbound-only WebSocket connection to the NudgeBee Server. +Telemetry reaches the Runner two ways: events, alerts and eBPF spans are **pushed** to it, while metrics, logs, traces and cost data are **queried in place**, so no second copy of your telemetry is shipped anywhere. The Runner also **acts** on the cluster — restarting, scaling, cordoning, exec-ing into pods and silencing alerts. That path is gated by RBAC and by [`runner.mutateEnabled`](./operate/helm_values.md#permissions-and-access-mode), and every mutation request is signature-checked against the relay's public key before it runs. +
+ + - - + + MONITORED KUBERNETES CLUSTER -ALREADY RUNNING IN YOUR CLUSTER - -NUDGEBEE CLUSTER COLLECTOR -namespace: nudgebee-agent - -NUDGEBEE CONTROL PLANE - -watch events - -events - -POST /api/alerts - -query logs - -PromQL - -query traces - -OTLP spans - -scraped for eBPF network metrics - - - -Kubernetes API Server -Cluster state, pods, events - -Alertmanager -Yours — needs a receiver - -Log store -Loki · Elasticsearch · SigNoz - -Prometheus -VictoriaMetrics · Thanos · Mimir - -Event Watcher -Kubewatch - -Runner -Deployment · the only component that talks to NudgeBee -Aggregates telemetry · runs in-cluster diagnostics -Holds the one outbound tunnel - -Node Agent -DaemonSet · eBPF - -OTel Collector -+ ClickHouse (bundled) - -Relay Server -wss://relay… · 443 - -Collector Server -https://collector… · 443 -How data moves - -pushed into the collector - -collector queries in place — no second copy - -outbound only · no inbound port opened + +NUDGEBEE CLUSTER COLLECTOR +namespace: nudgebee-agent + +NUDGEBEE CONTROL PLANE + +watch events + +discover workloads + +remediate · exec + +events + +POST /api/alerts + +probe · silences + +query logs + +PromQL + +query traces + +cost probe + +OTLP spans + +launches Jobs + +scraped for eBPF metrics + + + +Kubernetes API Server +Cluster state · pods · workloads · events + +Alertmanager +Yours — needs a receiver + +Log store +Loki · Elasticsearch · SigNoz + +Prometheus +VictoriaMetrics · Thanos · Mimir + +Event Watcher +Kubewatch + +Runner +Deployment · the only component that talks to NudgeBee +Aggregates telemetry · runs in-cluster diagnostics · applies remediation +Holds the one outbound tunnel + +Node Agent +DaemonSet · eBPF + +OTel + ClickHouse +bundled trace store + +Diagnostic Jobs +Trivy · KRR · Popeye + +OpenCost +optional · off by default + +Relay Server +wss://relay… · 443 + +Collector Server +https://collector… · 443 +How data moves + +pushed into the collector + +queried in place + +acts on your cluster (RBAC-gated) + +outbound only · no inbound port +Components + +already running in your cluster + +installed by the Helm chart + +optional module, off by default \ No newline at end of file diff --git a/doc-server/static/img/architecture/cluster-collector-light.svg b/doc-server/static/img/architecture/cluster-collector-light.svg index 2587f379..93e8d17a 100644 --- a/doc-server/static/img/architecture/cluster-collector-light.svg +++ b/doc-server/static/img/architecture/cluster-collector-light.svg @@ -1,74 +1,99 @@ - + + - - + + MONITORED KUBERNETES CLUSTER -ALREADY RUNNING IN YOUR CLUSTER - -NUDGEBEE CLUSTER COLLECTOR -namespace: nudgebee-agent - -NUDGEBEE CONTROL PLANE - -watch events - -events - -POST /api/alerts - -query logs - -PromQL - -query traces - -OTLP spans - -scraped for eBPF network metrics - - - -Kubernetes API Server -Cluster state, pods, events - -Alertmanager -Yours — needs a receiver - -Log store -Loki · Elasticsearch · SigNoz - -Prometheus -VictoriaMetrics · Thanos · Mimir - -Event Watcher -Kubewatch - -Runner -Deployment · the only component that talks to NudgeBee -Aggregates telemetry · runs in-cluster diagnostics -Holds the one outbound tunnel - -Node Agent -DaemonSet · eBPF - -OTel Collector -+ ClickHouse (bundled) - -Relay Server -wss://relay… · 443 - -Collector Server -https://collector… · 443 -How data moves - -pushed into the collector - -collector queries in place — no second copy - -outbound only · no inbound port opened + +NUDGEBEE CLUSTER COLLECTOR +namespace: nudgebee-agent + +NUDGEBEE CONTROL PLANE + +watch events + +discover workloads + +remediate · exec + +events + +POST /api/alerts + +probe · silences + +query logs + +PromQL + +query traces + +cost probe + +OTLP spans + +launches Jobs + +scraped for eBPF metrics + + + +Kubernetes API Server +Cluster state · pods · workloads · events + +Alertmanager +Yours — needs a receiver + +Log store +Loki · Elasticsearch · SigNoz + +Prometheus +VictoriaMetrics · Thanos · Mimir + +Event Watcher +Kubewatch + +Runner +Deployment · the only component that talks to NudgeBee +Aggregates telemetry · runs in-cluster diagnostics · applies remediation +Holds the one outbound tunnel + +Node Agent +DaemonSet · eBPF + +OTel + ClickHouse +bundled trace store + +Diagnostic Jobs +Trivy · KRR · Popeye + +OpenCost +optional · off by default + +Relay Server +wss://relay… · 443 + +Collector Server +https://collector… · 443 +How data moves + +pushed into the collector + +queried in place + +acts on your cluster (RBAC-gated) + +outbound only · no inbound port +Components + +already running in your cluster + +installed by the Helm chart + +optional module, off by default \ No newline at end of file From 5c5370f22be6e3cab5fc810dd0abe02b5fadf204 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 8 Sep 2026 10:26:48 +0000 Subject: [PATCH 4/5] Revert "docs(installation): add missing components to architecture diagram" This reverts commit da272c82fdce82d094d3282372a21a5a7f36b0a4. --- doc-server/docs/installation/agent/index.md | 7 - .../architecture/cluster-collector-dark.svg | 157 ++++++++---------- .../architecture/cluster-collector-light.svg | 157 ++++++++---------- 3 files changed, 132 insertions(+), 189 deletions(-) diff --git a/doc-server/docs/installation/agent/index.md b/doc-server/docs/installation/agent/index.md index f9da80cf..6b2ce845 100644 --- a/doc-server/docs/installation/agent/index.md +++ b/doc-server/docs/installation/agent/index.md @@ -70,8 +70,6 @@ Kubernetes. The NudgeBee Cluster Collector runs within your Kubernetes cluster. The main component is the Runner, which acts as a central controller — it coordinates data collection from cluster components and maintains a secure, outbound-only WebSocket connection to the NudgeBee Server. -Telemetry reaches the Runner two ways: events, alerts and eBPF spans are **pushed** to it, while metrics, logs, traces and cost data are **queried in place**, so no second copy of your telemetry is shipped anywhere. The Runner also **acts** on the cluster — restarting, scaling, cordoning, exec-ing into pods and silencing alerts. That path is gated by RBAC and by [`runner.mutateEnabled`](./operate/helm_values.md#permissions-and-access-mode), and every mutation request is signature-checked against the relay's public key before it runs. -
+ - - - + + MONITORED KUBERNETES CLUSTER - -NUDGEBEE CLUSTER COLLECTOR -namespace: nudgebee-agent - -NUDGEBEE CONTROL PLANE - -watch events - -discover workloads - -remediate · exec - -events - -POST /api/alerts - -probe · silences - -query logs - -PromQL - -query traces - -cost probe - -OTLP spans - -launches Jobs - -scraped for eBPF metrics - - - -Kubernetes API Server -Cluster state · pods · workloads · events - -Alertmanager -Yours — needs a receiver - -Log store -Loki · Elasticsearch · SigNoz - -Prometheus -VictoriaMetrics · Thanos · Mimir - -Event Watcher -Kubewatch - -Runner -Deployment · the only component that talks to NudgeBee -Aggregates telemetry · runs in-cluster diagnostics · applies remediation -Holds the one outbound tunnel - -Node Agent -DaemonSet · eBPF - -OTel + ClickHouse -bundled trace store - -Diagnostic Jobs -Trivy · KRR · Popeye - -OpenCost -optional · off by default - -Relay Server -wss://relay… · 443 - -Collector Server -https://collector… · 443 -How data moves - -pushed into the collector - -queried in place - -acts on your cluster (RBAC-gated) - -outbound only · no inbound port -Components - -already running in your cluster - -installed by the Helm chart - -optional module, off by default +ALREADY RUNNING IN YOUR CLUSTER + +NUDGEBEE CLUSTER COLLECTOR +namespace: nudgebee-agent + +NUDGEBEE CONTROL PLANE + +watch events + +events + +POST /api/alerts + +query logs + +PromQL + +query traces + +OTLP spans + +scraped for eBPF network metrics + + + +Kubernetes API Server +Cluster state, pods, events + +Alertmanager +Yours — needs a receiver + +Log store +Loki · Elasticsearch · SigNoz + +Prometheus +VictoriaMetrics · Thanos · Mimir + +Event Watcher +Kubewatch + +Runner +Deployment · the only component that talks to NudgeBee +Aggregates telemetry · runs in-cluster diagnostics +Holds the one outbound tunnel + +Node Agent +DaemonSet · eBPF + +OTel Collector ++ ClickHouse (bundled) + +Relay Server +wss://relay… · 443 + +Collector Server +https://collector… · 443 +How data moves + +pushed into the collector + +collector queries in place — no second copy + +outbound only · no inbound port opened \ No newline at end of file diff --git a/doc-server/static/img/architecture/cluster-collector-light.svg b/doc-server/static/img/architecture/cluster-collector-light.svg index 93e8d17a..2587f379 100644 --- a/doc-server/static/img/architecture/cluster-collector-light.svg +++ b/doc-server/static/img/architecture/cluster-collector-light.svg @@ -1,99 +1,74 @@ - + - - - + + MONITORED KUBERNETES CLUSTER - -NUDGEBEE CLUSTER COLLECTOR -namespace: nudgebee-agent - -NUDGEBEE CONTROL PLANE - -watch events - -discover workloads - -remediate · exec - -events - -POST /api/alerts - -probe · silences - -query logs - -PromQL - -query traces - -cost probe - -OTLP spans - -launches Jobs - -scraped for eBPF metrics - - - -Kubernetes API Server -Cluster state · pods · workloads · events - -Alertmanager -Yours — needs a receiver - -Log store -Loki · Elasticsearch · SigNoz - -Prometheus -VictoriaMetrics · Thanos · Mimir - -Event Watcher -Kubewatch - -Runner -Deployment · the only component that talks to NudgeBee -Aggregates telemetry · runs in-cluster diagnostics · applies remediation -Holds the one outbound tunnel - -Node Agent -DaemonSet · eBPF - -OTel + ClickHouse -bundled trace store - -Diagnostic Jobs -Trivy · KRR · Popeye - -OpenCost -optional · off by default - -Relay Server -wss://relay… · 443 - -Collector Server -https://collector… · 443 -How data moves - -pushed into the collector - -queried in place - -acts on your cluster (RBAC-gated) - -outbound only · no inbound port -Components - -already running in your cluster - -installed by the Helm chart - -optional module, off by default +ALREADY RUNNING IN YOUR CLUSTER + +NUDGEBEE CLUSTER COLLECTOR +namespace: nudgebee-agent + +NUDGEBEE CONTROL PLANE + +watch events + +events + +POST /api/alerts + +query logs + +PromQL + +query traces + +OTLP spans + +scraped for eBPF network metrics + + + +Kubernetes API Server +Cluster state, pods, events + +Alertmanager +Yours — needs a receiver + +Log store +Loki · Elasticsearch · SigNoz + +Prometheus +VictoriaMetrics · Thanos · Mimir + +Event Watcher +Kubewatch + +Runner +Deployment · the only component that talks to NudgeBee +Aggregates telemetry · runs in-cluster diagnostics +Holds the one outbound tunnel + +Node Agent +DaemonSet · eBPF + +OTel Collector ++ ClickHouse (bundled) + +Relay Server +wss://relay… · 443 + +Collector Server +https://collector… · 443 +How data moves + +pushed into the collector + +collector queries in place — no second copy + +outbound only · no inbound port opened \ No newline at end of file From f4744a6ff03be80477e7ad16aa3b368a069d58e2 Mon Sep 17 00:00:00 2001 From: Sahil Patil Date: Tue, 8 Sep 2026 10:37:14 +0000 Subject: [PATCH 5/5] docs(installation): show the full relay and collector URLs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Claude-Session: https://claude.ai/code/session_01GXgnUKdn8vXQn4oiXSMrDG --- .../architecture/cluster-collector-dark.svg | 22 +++++++++---------- .../architecture/cluster-collector-light.svg | 22 +++++++++---------- 2 files changed, 22 insertions(+), 22 deletions(-) diff --git a/doc-server/static/img/architecture/cluster-collector-dark.svg b/doc-server/static/img/architecture/cluster-collector-dark.svg index cb4cb8d7..3e46c74b 100644 --- a/doc-server/static/img/architecture/cluster-collector-dark.svg +++ b/doc-server/static/img/architecture/cluster-collector-dark.svg @@ -1,19 +1,19 @@ - + - + MONITORED KUBERNETES CLUSTER ALREADY RUNNING IN YOUR CLUSTER NUDGEBEE CLUSTER COLLECTOR namespace: nudgebee-agent - -NUDGEBEE CONTROL PLANE + +NUDGEBEE CONTROL PLANE watch events @@ -58,17 +58,17 @@ OTel Collector + ClickHouse (bundled) - -Relay Server -wss://relay… · 443 - -Collector Server -https://collector… · 443 + +Relay Server +wss://relay.nudgebee.com/register + +Collector Server +https://collector.nudgebee.com How data moves pushed into the collector collector queries in place — no second copy -outbound only · no inbound port opened +outbound only on 443 · no inbound port opened \ No newline at end of file diff --git a/doc-server/static/img/architecture/cluster-collector-light.svg b/doc-server/static/img/architecture/cluster-collector-light.svg index 2587f379..252de92a 100644 --- a/doc-server/static/img/architecture/cluster-collector-light.svg +++ b/doc-server/static/img/architecture/cluster-collector-light.svg @@ -1,19 +1,19 @@ - + - + MONITORED KUBERNETES CLUSTER ALREADY RUNNING IN YOUR CLUSTER NUDGEBEE CLUSTER COLLECTOR namespace: nudgebee-agent - -NUDGEBEE CONTROL PLANE + +NUDGEBEE CONTROL PLANE watch events @@ -58,17 +58,17 @@ OTel Collector + ClickHouse (bundled) - -Relay Server -wss://relay… · 443 - -Collector Server -https://collector… · 443 + +Relay Server +wss://relay.nudgebee.com/register + +Collector Server +https://collector.nudgebee.com How data moves pushed into the collector collector queries in place — no second copy -outbound only · no inbound port opened +outbound only on 443 · no inbound port opened \ No newline at end of file