Skip to main content

CodeXray Cluster Agent

The CodeXray Cluster Agent is the Kubernetes-aware companion to the Node Agent. Where the Node Agent sits on every node and captures per-host telemetry via eBPF, the Cluster Agent runs once per cluster and captures signals that only make sense at the cluster level: the state of every workload, control-plane health, pod events, and cluster-wide profiles.

Node Agent vs Cluster Agent

They're designed to work together, not replace each other. The Node Agent tells you what's happening on each node. The Cluster Agent tells you what's happening across the cluster. Most Kubernetes deployments run both.

What It Collects​

CapabilityWhat you get
Kubernetes stateLive inventory of every Deployment, StatefulSet, DaemonSet, Pod, Service, Endpoint, Namespace, ConfigMap, and Secret — plus their relationships and current status.
Pod eventsContainer lifecycle events (creation, OOM, crash-loop, eviction, image pull failures) with the pod, namespace, and reason attached.
Resource metricsNode and pod resource usage from the Kubernetes Metrics API.
Cluster profilesContinuous profiles from workloads exposing a pprof endpoint — aggregated across the cluster.
Kubernetes events (optional)Native kubectl get events stream ingested and correlated with the workloads they affect.

This cluster-level context is what makes the Applications view group pods correctly, the Topology view show actual workload relationships, and incidents link back to the right deployment.

Requirements​

Kubernetes cluster​

  • Any Kubernetes 1.24+ cluster is supported.
  • A working metrics server is recommended (enables the resource-metrics collection path).

Permissions​

The agent ships with a ClusterRole that requests read-only access to:

  • Core: pods, nodes, services, endpoints, namespaces, configmaps, secrets
  • Apps: deployments, replicasets, statefulsets, daemonsets
  • Metrics: nodes, pods under metrics.k8s.io
  • Subresources: nodes/proxy, nodes/stats, nodes/metrics

All access is get, list, watch — nothing is ever modified in the cluster.

Network​

  • Outbound connectivity to the CodeXray collector endpoint.
  • No inbound traffic is required — the agent only pushes data.

Credentials​

  • A project API key from the CodeXray UI (Project Settings → API Keys).

Installation​

Pick the path that fits your workflow — Helm for a value-driven install you can keep in Git, or a single manifest for a quick kubectl apply.

Kubernetes — Helm chart (recommended)​

The chart is published as an OCI artifact on GHCR and rolls out the namespace, ServiceAccount, ClusterRole/Binding, and Deployment in one command.

Step 1 — Authenticate to GHCR​

The chart packages are private, so Helm needs a GitHub token with read:packages scope before it can pull the chart.

echo "$GHCR_TOKEN" | helm registry login ghcr.io \
  -u <github-username> --password-stdin

You only need to do this once per machine (or once per CI runner).

Step 2 — Install the chart​

helm upgrade --install cluster-agent oci://ghcr.io/codifinary/helm/cluster-agent \
  --version 0.1.0 \
  -n codexray --create-namespace \
  --set-string clusterAgent.codexray_url='https://your-codexray.example.com' \
  --set-string clusterAgent.apiKey='your-project-api-key'

The two values you almost always set:

Helm valueDescription
clusterAgent.codexray_urlBase URL of your CodeXray collector
clusterAgent.apiKeyProject API key from the CodeXray UI

Common overrides:

Helm valueDefaultWhen to change
clusterAgent.image.tagv1.1.2Pin a specific agent version
clusterAgent.resourcessensible defaultsRight-size for your cluster footprint
clusterAgent.nodeSelector / tolerationsnoneRestrict which nodes the Deployment runs on
serviceAccount.imagePullSecretsghcr-secretSwap if you mirror the image to a private registry

Full values reference: see the chart README on GitHub.

Installing Node + Cluster Agents together (umbrella chart)​

When you want both agents on the same cluster — the typical pattern — use the umbrella chart instead of installing each one separately. One release, one set of overrides, one place to upgrade.

helm upgrade --install codexray-agents oci://ghcr.io/codifinary/helm/codexray-agents \
  --version 0.1.1 \
  -n codexray --create-namespace \
  --set nodeagent.enabled=true \
  --set clusteragent.enabled=true \
  --set-string nodeagent.nodeAgent.collector_endpoint='https://your-codexray.example.com' \
  --set-string clusteragent.clusterAgent.codexray_url='https://your-codexray.example.com' \
  --set-string nodeagent.nodeAgent.apiKey='your-project-api-key' \
  --set-string clusteragent.clusterAgent.apiKey='your-project-api-key'

Toggle nodeagent.enabled / clusteragent.enabled to install just one side later without changing release name. Per-agent values are namespaced under nodeagent.* and clusteragent.* — see the umbrella chart README for the full mapping.

The umbrella supports three install shapes — both agents (above), node-only, and cluster-only:

Node-agent only via umbrella:

helm upgrade --install codexray-agents oci://ghcr.io/codifinary/helm/codexray-agents \
  --version 0.1.1 \
  -n codexray --create-namespace \
  --set nodeagent.enabled=true \
  --set clusteragent.enabled=false \
  --set-string nodeagent.nodeAgent.collector_endpoint='https://your-codexray.example.com' \
  --set-string nodeagent.nodeAgent.apiKey='your-project-api-key'

Cluster-agent only via umbrella:

helm upgrade --install codexray-agents oci://ghcr.io/codifinary/helm/codexray-agents \
  --version 0.1.1 \
  -n codexray --create-namespace \
  --set nodeagent.enabled=false \
  --set clusteragent.enabled=true \
  --set-string clusteragent.clusterAgent.codexray_url='https://your-codexray.example.com' \
  --set-string clusteragent.clusterAgent.apiKey='your-project-api-key'

Using the umbrella with one side disabled — instead of installing the standalone chart directly — keeps a consistent release name and a single upgrade path if you decide to enable the other agent later.

Kubernetes — Manifest​

If you'd rather skip Helm, the same components ship as a single Kubernetes manifest.

kubectl apply -f https://raw.githubusercontent.com/codifinary/codexray-cluster-agent/main/manifests/codexray-cluster-agent.yaml

Before applying, edit the manifest to set:

VariableDescription
CODEXRAY_URLBase URL of your CodeXray collector (required)
API_KEYProject API key from the CodeXray UI (required)

Verify the install:

kubectl -n codexray-agents get deploy codexray-cluster-agent
kubectl -n codexray-agents logs -l app=codexray-cluster-agent

You should see workloads appearing in the Applications view within a couple of minutes, and Kubernetes events showing up in the Incidents stream shortly after.

One per cluster — not per namespace

The Cluster Agent is designed to run as a single Deployment per cluster (not a DaemonSet, not per-namespace). It watches the entire cluster via the Kubernetes API. Running multiple copies is unnecessary and just duplicates data.

Configuration​

All configuration is via environment variables (or CLI flags).

Core settings​

VariableRequiredDescription
CODEXRAY_URL✓Base URL of your CodeXray collector.
API_KEY✓Project API key.
INSECURE_SKIP_VERIFY—Set to true to skip TLS certificate verification (dev/internal CA only).

Tuning intervals​

Defaults work for most clusters. Tune these only if you have specific needs:

VariableDefaultDescription
METRICS_SCRAPE_INTERVALserver-controlledHow often cluster metrics are collected.
METRICS_SCRAPE_TIMEOUT10sTimeout for a single metrics scrape.
PROFILES_SCRAPE_INTERVAL60sHow often profiles are collected.
PROFILES_SCRAPE_TIMEOUT10sTimeout for a single profile scrape.
CONFIG_UPDATE_INTERVAL60sHow often the agent refreshes its config from the backend.
COLLECT_KUBERNETES_EVENTStrueSet to false to disable Kubernetes event collection.

Verifying It's Working​

  1. Pod health: kubectl -n codexray-agents get pods — the Cluster Agent should be Running with zero restarts.
  2. Logs: kubectl -n codexray-agents logs -l app=codexray-cluster-agent — you should see periodic "watching pods", "watching deployments" messages and a successful connection to the backend.
  3. UI check: the Applications view lists your workloads grouped by Deployment/StatefulSet/DaemonSet. The Topology view draws service relationships.
Troubleshooting "workloads missing"

If some workloads don't appear in the UI, the most common causes are: (a) RBAC — check the agent isn't getting 403 Forbidden in its logs; (b) the namespace is filtered server-side — check Project Settings for namespace inclusions/exclusions; or (c) the workload genuinely has no running pods.

Next Steps​