☸️Kubernetes

Kube ahoy!

Collect container logs and cluster events from Kubernetes clusters via an in-cluster agent.

How it works

The ControlTheory agent runs inside your cluster and forwards data to Dstl8. It has two components:

• DaemonSet — runs on every node to collect pod and container logs. Optionally exposes OTLP ports (1757, 1758) on each node so applications co-located with the agent can push their own telemetry to it.

• Cluster component — runs once per cluster to collect cluster-wide events, metadata, and topology snapshots (how your workloads, pods, services, and nodes connect).

You can install both (recommended, default), or either one independently.

Add a Kubernetes source

1. Create the source in Dstl8

From Sources, click Add Source and select Kubernetes. Configure the source and complete setup — Dstl8 will provide:

• Organization ID

• DaemonSet and cluster admission tokens

• Config and data endpoints

• A ready-to-run install command

2. Install the agent

With kubectl configured against the target cluster, run the install script (the UI provides this command with your values prefilled):

./install.sh \
  -i <org-id> \
  --ds-token <ds-token> \
  --cluster-token <cluster-token> \
  --config-endpoint <config-url> \
  --data-endpoint <host:port> \
  --cluster-name <name> \
  -e <env>

The agent installs via Helm into the controltheory namespace by default.

3. Verify

Check the rollout:

./install.sh -o status

In the Dstl8 UI, the source transitions from Pending to Healthy as the agent connects and begins forwarding. Streams appear as pods emit logs — typical stream types include Deployments, DaemonSets, StatefulSets, and Jobs.

Install options

Flag	Description
-i, --org-id	Organization identifier (required)
--config-endpoint	Config endpoint URL (required)
--data-endpoint	Data endpoint host:port (required)
--cluster-name	Name to identify this cluster (required)
-e, --env	Deployment environment, e.g. prod, staging (required)
--ds-token	DaemonSet admission token (required for ds / both)
--cluster-token	Cluster admission token (required for cluster / both)
-t, --type	Install ds, cluster, or both (default: both)
-n, --namespace	Kubernetes namespace (default: controltheory)
--no-host-port	Don't expose OTLP ports (1757 / 1758) on nodes
--kubeconfig	Path to kubeconfig (default: ~/.kube/config)
--helm-version	Pin a specific Helm chart version (default: latest stable)

Other operations

./install.sh -o preflight     # check node capacity, taints, and schedulability before install
./install.sh -o status        # report on current agent state
./install.sh -o uninstall     # remove the agent

Run preflight on large or constrained clusters to surface scheduling issues — node capacity, taints, and overprovisioned pods — before committing to install.

Updating the agent

The agent ships as two Helm charts — aigent-ds (DaemonSet) and aigent-cluster (cluster component) — published to the ControlTheory chart repository at https://control-theory.github.io/helm-charts. The two charts are versioned in lockstep; always upgrade both together.

Check what you're running and what's available:

helm list -n controltheory            # installed releases and chart versions
helm repo update ct-helm
helm search repo ct-helm              # latest published versions

(./install.sh -o status also reports the installed release versions.)

Option 1: Re-run the install script (recommended)

install.sh uses helm upgrade --install and refreshes the chart repository on every run, so re-running your original install command upgrades the agent in place — same flags, same tokens, latest chart:

./install.sh \
  -i <org-id> \
  --ds-token <ds-token> \
  --cluster-token <cluster-token> \
  --config-endpoint <config-url> \
  --data-endpoint <host:port> \
  --cluster-name <name> \
  -e <env>

Don't have the command handy? Open Sources in the Dstl8 UI, open the Kubernetes source's actions menu, and select Install Script — it returns the same command with your values prefilled. To upgrade to a specific chart version instead of the latest, add --helm-version <version>.

Option 2: Upgrade with Helm directly

If you manage the releases with Helm yourself (or in CI), upgrade both charts in the install namespace:

helm repo add ct-helm https://control-theory.github.io/helm-charts
helm repo update ct-helm

helm upgrade aigent-ds ct-helm/aigent-ds -n controltheory --reuse-values
helm upgrade aigent-cluster ct-helm/aigent-cluster -n controltheory --reuse-values

--reuse-values carries forward the values the install script originally set (admission tokens, endpoints, cluster name), so you don't need to re-supply them. Pin a version with --version <version> on each command. If you installed into a different namespace, adjust -n accordingly.

--reuse-values keeps your previous values but does not pick up new chart defaults introduced by a release. If release notes mention new configuration options, prefer re-running the install script (Option 1), which re-applies every value explicitly on top of fresh chart defaults.

Verify and roll back

After upgrading, confirm the pods are healthy and the source stays Healthy in the Dstl8 UI:

kubectl get pods -n controltheory
./install.sh -o status

If something goes wrong, Helm keeps the previous release revision — roll back either chart:

helm rollback aigent-ds -n controltheory
helm rollback aigent-cluster -n controltheory

Tips

• Install a separate Kubernetes source per cluster rather than sharing tokens across clusters.

• If OTLP ports 1757 / 1758 conflict with existing workloads on your nodes, pass --no-host-port.

• Assign the resulting streams to workspaces as described in Sources → Assigning streams to workspaces.