# 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