> For the complete documentation index, see [llms.txt](https://docs.controltheory.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.controltheory.com/controltheory-documentation/dstl8-docs/sources/kubernetes.md).

# Kubernetes

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](/controltheory-documentation/dstl8-docs/topology.md) (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):

```bash
./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:

```bash
./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

```bash
./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:

```bash
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:

```bash
./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:

```bash
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.

{% hint style="warning" %}
`--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.
{% endhint %}

#### Verify and roll back

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

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

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

```bash
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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.controltheory.com/controltheory-documentation/dstl8-docs/sources/kubernetes.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.