# 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 and metadata.

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.

### 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: 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:

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

The question should be specific, self-contained, and written in natural language.
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.