# Kubernetes ⎈

Gonzo can now (as of version 0.3.0) natively stream logs from your Kubernetes clusters (using a `kubeconfig`) — no `kubectl logs`, no stern, no piping required. This guide covers the essential setup, commands, and filters you need to get started.

***

### **Overview**

With Kubernetes mode enabled, Gonzo supports:

* Direct log streaming from pods
* Multiple namespaces at once
* Kubernetes label selectors
* Automatic namespace + pod columns
* Interactive namespace/pod filtering (`Ctrl+k`)
* Real-time updates with reconnection

***

### **Prerequisites**

Before you begin, ensure:

* You have access to a Kubernetes cluster
* Your `kubeconfig` is valid
* Your account has read access to pod logs

#### **Required RBAC**

```yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: gonzo-log-reader
rules:
- apiGroups: [""]
  resources: ["pods", "pods/log"]
  verbs: ["get", "list", "watch"]
- apiGroups: [""]
  resources: ["namespaces"]
  verbs: ["get", "list"]
```

***

### **Quick Start**

#### **Stream logs from all pods**

```bash
gonzo --k8s-enabled=true
```

#### **Start with the last 50 log lines**

```bash
gonzo --k8s-enabled=true --k8s-tail=50
```

#### **Watch a specific namespace**

```bash
gonzo --k8s-enabled=true --k8s-namespace=production
```

#### **Watch multiple namespaces**

```bash
gonzo --k8s-enabled \
  --k8s-namespace=production \
  --k8s-namespace=staging
```

#### **Filter by label selector**

```bash
gonzo --k8s-enabled --k8s-selector="app=myapp"
```

**Set-based selectors**

```bash
gonzo --k8s-enabled --k8s-selector="environment in (prod,staging)"
```

***

### **Common Configuration Options**

| Flag                | Description                    |
| ------------------- | ------------------------------ |
| `--k8s-enabled`     | Enable Kubernetes integration  |
| `--k8s-namespace N` | Set namespace(s) to watch      |
| `--k8s-selector`    | Kubernetes label selector      |
| `--k8s-tail N`      | Number of historic log lines   |
| `--k8s-since N`     | Only logs newer than N seconds |
| `--k8s-context`     | Use a specific kube context    |
| `--k8s-kubeconfig`  | Path to kubeconfig file        |

#### **Example: Namespace + Selector + Tail**

```bash
gonzo --k8s-enabled \
  --k8s-namespace=production \
  --k8s-selector="app=api" \
  --k8s-tail=100
```

***

### **Interactive Filtering (Ctrl+k)**

Inside Gonzo, press **Ctrl+k** to open the Kubernetes filter modal.

You can:

* Select **namespaces**
* Select **pods**
* Apply changes instantly

**Navigation:**\
↑/↓ to move • Space to toggle • Enter to apply • ESC to cancel

<figure><img src="https://3483934249-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SdDsOcMkqsJoxnydVXB%2Fuploads%2FKzz6pO9vNOHuLKv51ABx%2FScreenshot%202025-12-01%20at%2012.31.57%E2%80%AFPM.png?alt=media&#x26;token=3a2842ef-76a6-462a-b0d6-7c46fc351b52" alt=""><figcaption></figcaption></figure>

***

### **Kubernetes Display Mode**

Gonzo automatically switches into K8s column mode when logs contain Kubernetes attributes.

```
Time     Level Namespace        Pod                   Message
15:04:05 INFO  production       api-5c44d7f-xkr2p      Started worker process
```

Press **c** to toggle Kubernetes columns on/off.

<figure><img src="https://3483934249-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SdDsOcMkqsJoxnydVXB%2Fuploads%2FuqsTtItYOyEc9Hprqaty%2FScreenshot%202025-12-01%20at%2012.31.44%E2%80%AFPM.png?alt=media&#x26;token=d22eb4c0-4b54-454a-ba0d-45d9097bdab0" alt=""><figcaption></figcaption></figure>

***

### **Example Workflows**

#### **Troubleshoot a new deployment**

```bash
gonzo --k8s-enabled \
  --k8s-namespace=production \
  --k8s-selector="app=api,version=v2.0.0" \
  --k8s-since=300
```

#### **Monitor both staging + prod backend pods**

```bash
gonzo --k8s-enabled \
  --k8s-namespace=production \
  --k8s-namespace=staging \
  --k8s-selector="tier=backend"
```

***

### **Troubleshooting**

#### **No logs appear**

Verify kubectl access:

```bash
kubectl get pods -A
kubectl logs <pod> -n <namespace>
```

#### **Selector not matching**

```bash
kubectl get pods --selector="app=myapp" -A
```

#### **Wrong context**

```bash
gonzo --k8s-context=my-cluster
```

#### **High log volume**

* Narrow your label selector
* Limit historic logs (`--k8s-tail`)
* Limit time window (`--k8s-since`)

***

### **Best Practices**

* Start with **specific namespaces/selectors**
* Use **Ctrl+k** to refine quickly
* Toggle columns with **c** when needed
* Save common setups in config files
* Use contexts to switch clusters cleanly


---

# 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/gonzo-docs/integration-examples/container-environments/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.