NudgeBee Kubernetes Agent

Helm chart for the NudgeBee Kubernetes agent. The agent runs in your cluster, collects Kubernetes state, events, metrics, logs, and traces, and forwards them to the NudgeBee backend for observability, cost visibility, and incident automation.

What it deploys

Component	Purpose
runner	Connects to the NudgeBee backend over WebSocket; executes diagnostic and remediation actions in-cluster (source: runner/)
kubewatch (forwarder)	Streams Kubernetes resource changes and events to the runner
node-agent (DaemonSet)	Per-node logs, profiles, and traces collector (eBPF-based)
opencost (subchart)	Kubernetes cost allocation metrics
opentelemetry-collector (subchart)	Receives OTLP signals from node-agent and exports to ClickHouse
clickhouse (subchart)	Local store for traces / logs / metrics (7-day TTL by default)
Prometheus rules / ServiceMonitors	Default alerting + scrape config for kube-prometheus-stack users

The runner connects out to wss://relay.nudgebee.com/register and https://collector.nudgebee.com. No inbound connectivity is required.

Prerequisites

• Kubernetes 1.24+
• Helm 3.12+
• (Optional but recommended) kube-prometheus-stack — the chart ships ServiceMonitor and PrometheusRule resources by default
• A StorageClass for the ClickHouse volume — the cluster default is used unless you set one explicitly (see Storage)
• A NudgeBee account and auth key — sign up at https://nudgebee.com

Install

helm repo add nudgebee-agent https://nudgebee.github.io/k8s-agent/
helm repo update

helm upgrade --install nudgebee-agent nudgebee-agent/nudgebee-agent \
  --namespace nudgebee-agent --create-namespace \
  --set runner.nudgebee.auth_secret_key="<your-auth-key>"

Or use the opinionated installer (auto-installs kube-prometheus-stack and wires up Prometheus discovery):

curl -sSL https://raw.githubusercontent.com/nudgebee/k8s-agent/main/installation.sh \
  | bash -s -- -a "<your-auth-key>"

The script refuses to run on a cluster with no default StorageClass — pass -C <storage-class> instead, and the name is applied to every PVC it creates: ClickHouse, and the Prometheus (50Gi) and Loki (10Gi) volumes when it installs those stacks:

curl -sSL https://raw.githubusercontent.com/nudgebee/k8s-agent/main/installation.sh \
  | bash -s -- -a "<your-auth-key>" -C gp3

Verifying chart signatures

Chart packages are signed with cosign keyless signing. Each GitHub release attaches a <chart>.tgz.sigstore.json Sigstore bundle (signature + certificate + transparency-log entry) alongside the chart tarball. To verify a downloaded package (requires cosign v3+):

VERSION=0.1.1
BASE="https://github.com/nudgebee/k8s-agent/releases/download/nudgebee-agent-${VERSION}"
curl -sSLO "${BASE}/nudgebee-agent-${VERSION}.tgz"
curl -sSLO "${BASE}/nudgebee-agent-${VERSION}.tgz.sigstore.json"

cosign verify-blob \
  --bundle "nudgebee-agent-${VERSION}.tgz.sigstore.json" \
  --certificate-identity-regexp "^https://github\.com/nudgebee/k8s-agent/\.github/workflows/release(-rc)?\.yml@.*" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
  "nudgebee-agent-${VERSION}.tgz"

Configuration

All configurable values live in charts/nudgebee-agent/values.yaml. Common overrides:

runner:
  # Required
  nudgebee:
    auth_secret_key: "<your-auth-key>"

  # Optional integrations — set the URL to enable
  loki:
    url: ""
  es:
    url: ""
    apiKey: ""
  signoz:
    url: ""
    apiKey: ""
  grafana:
    url: ""
    username: ""
    password: ""

  # Grant write permissions (drain nodes, scale workloads, manage services etc.)
  # Off by default — only enable if you want NudgeBee to perform remediations.
  enableWritePermissions: false

# StorageClass for the PVCs the chart creates (see Storage below)
global:
  storageClass: ""

# Subcharts can be disabled if not needed
opencost:
  enabled: true
opentelemetry-collector:
  enabled: true
clickhouse:
  enabled: true

Full configuration reference: installation guide.

Storage

ClickHouse is the only component of this chart that claims persistent storage — one PVC per replica, 50Gi by default. Left unset, the PVC is provisioned from the cluster's default StorageClass; on clusters that have none, the PVC stays Pending and the ClickHouse pod never starts. Set the class explicitly:

global:
  # Applies to the ClickHouse PVC, the only one this chart creates by default.
  storageClass: "gp3"

clickhouse:
  persistence:
    size: 50Gi
    # Per-component alternative — only consulted when global.storageClass is empty.
    storageClass: ""

Or on the command line:

helm upgrade --install nudgebee-agent nudgebee-agent/nudgebee-agent \
  --namespace nudgebee-agent --create-namespace \
  --set runner.nudgebee.auth_secret_key="<your-auth-key>" \
  --set global.storageClass="gp3" \
  --set clickhouse.persistence.size="100Gi"

Value	Effect
"" (default)	storageClassName is omitted — the cluster's default StorageClass provisions the volume
"<name>"	PVCs request that StorageClass (e.g. gp3, managed-csi, standard-rwo)
"-"	storageClassName: "" — dynamic provisioning is disabled, so the PVC binds a pre-created PV

The "-" form is a chart-value convention and works only for the values above, not for the installer's -C flag (see below).

global.storageClass takes precedence over clickhouse.persistence.storageClass when both are set. The StorageClass of an existing PVC is immutable, so changing it on an already-installed release only affects PVCs created afterwards — delete the old PVC (losing the local traces/logs, which have a 7-day TTL) to move ClickHouse to a different class.

global.storageClass is a Helm convention, not a guarantee: it reaches a subchart's PVCs only if that subchart reads it. The Bitnami ClickHouse subchart does. The OpenCost subchart does not — it writes storageClassName unconditionally, so leaving its class unset means storageClassName: "", which disables dynamic provisioning rather than falling back to the cluster default. Its PVC is off by default; if you turn it on, set opencost.opencost.exporter.persistence.storageClass explicitly.

The stacks installation.sh installs alongside the agent claim volumes of their own, and -C sets the class on those too:

PVC	Size	Value the installer sets
ClickHouse (this chart)	50Gi	global.storageClass
Prometheus (kube-prometheus-stack, via kube-prometheus-stack-values.yaml)	50Gi	prometheus.prometheusSpec.storageSpec.volumeClaimTemplate.spec.storageClassName
Loki (loki-stack)	10Gi	loki.persistence.storageClassName

Grafana and Alertmanager are left on their chart defaults (no PVC), so nothing is set for them. Installing the chart directly with helm only creates the ClickHouse PVC — the other two come from stacks the script installs for you.

Before installing anything, the script checks the StorageClass it is about to use: an unknown -C name, or no -C on a cluster with no default class, is an error that lists the classes that do exist. A PVC bound to a missing class only sits Pending, so failing up front is the difference between a one-line message and a silent stall.

-C takes a StorageClass name only — not the "-" form above, which the Prometheus and Loki charts do not implement. To bind pre-created PVs, install the chart directly with --set global.storageClass=- and install those stacks yourself.

Uninstall

helm uninstall nudgebee-agent --namespace nudgebee-agent
kubectl delete namespace nudgebee-agent

Note: ClickHouse PVCs are not deleted automatically — remove them manually if you no longer need the data.

Data sent to NudgeBee

By default, the agent forwards:

• Kubernetes object state (deployments, pods, services, etc.) and events
• Cluster and node metrics (via Prometheus scrape)
• OpenCost allocation data
• Logs, traces, and profiles from node-agent (configurable; sensitive HTTP headers are redacted via the SENSITIVE_HEADERS env var)

Secrets are explicitly not watched by the kubewatch forwarder (kubewatch.config.resource.secret: false).

Contributing

See CONTRIBUTING.md. For security issues, see SECURITY.md.

License

Apache License 2.0.