Kuberr: Your Kubernetes Debugging Assistant

Kuberr is a smart command-line utility that transforms messy Kubernetes log and event data from your clipboard into clean, readable, and actionable markdown.

It's designed to slash your debugging time and help you create perfect, context-rich prompts for collaboration with colleagues or AI assistants.

---

Before Kuberr

A wall of text from kubectl describe:

...
  Warning  Failed     15s (x4 over 30s)    kubelet            Error: container has runAsNonRoot and image has non-numeric user (node), cannot verify user is non-root (pod: "example-instance-55c5b4bb97-dfwhc_org-252-no(744958df-536d-4f05-ab35-e686832e04ca)", container: status-frontend)
  Warning  BackOff    10s (x2 over 25s)    kubelet            Back-off restarting failed container status-backend in pod example-instance-55c5b4bb97-dfwhc_org-252-no(744958df-536d-4f05-ab35-e686832e04ca)
...

After Kuberr (kuberr)

A clean, structured summary ready to be shared:

## Kubernetes Resource Summary

### Key Information
- **Pod Name:** `example-instance-55c5b4bb97-dfwhc`
- **Namespace:** `org-252-no`
- **Containers:** `status-frontend, status-backend`

### Problem Summary
- Warning  Failed     15s (x4 over 30s)    kubelet            Error: container has runAsNonRoot and image has non-numeric user (node), cannot verify user is non-root (pod: "example-instance-55c5b4bb97-dfwhc_org-252-no(744958df-536d-4f05-ab35-e686832e04ca)", container: status-frontend)
- Warning  BackOff    10s (x2 over 25s)    kubelet            Back-off restarting failed container status-backend in pod example-instance-55c5b4bb97-dfwhc_org-252-no(744958df-536d-4f05-ab35-e686832e04ca)

### Key Commands

- **Describe pod:** `kubectl describe pod example-instance-55c5b4bb97-dfwhc -n org-252-no`
- **Get logs:** `kubectl logs example-instance-55c5b4bb97-dfwhc -n org-252-no --all-containers`
- **Get events:** `kubectl get events -n org-252-no --field-selector involvedObject.name=example-instance-55c5b4bb97-dfwhc`

---

Key Features

• Clipboard-Powered: Instantly processes error logs from your clipboard. No need to pipe or save to a file.
• Intelligent Parsing: Understands output from both kubectl describe and k9s logs.
• Structured Log Support: Automatically detects and pretty-prints JSON-formatted logs, perfect for operators.
• Key Info Extraction: Reliably identifies pod names, namespaces, containers, and images.
• Problem-Focused Summary: Filters and highlights critical Warning, Failed, Error, and BackOff events.
• Actionable Commands: Provides ready-to-use kubectl commands for deeper investigation.
• Live Data Enrichment: Use the --fetch flag to enrich the report with live event data from your cluster.

Installation

Install kuberr directly from the repository:

cargo install --git https://code.252.no/pub/kuberr

How to Use

Your workflow is simple: Copy, Run, Paste.

1. Copy: In k9s or your terminal, copy the output from a failing pod (using d for describe in k9s, or kubectl describe pod ...).
2. Run: Open a new terminal and simply run kuberr.

   kuberr
   

3. Paste: The formatted markdown is now in your clipboard, ready to be pasted into a document, a Slack message, a GitHub issue, or as context for a large language model.

Example with Operator (JSON) Logs

Kuberr can even untangle structured JSON logs from operators.

1. Copy this k9s operator log to your clipboard:

2025-06-30T16:21:34Z    INFO    Updating existing Deployment    {"controller": "statusdispatcher", "controllerGroup": "status.252.no", "controllerKind": "StatusDispatcher", "StatusDispatcher": {"name":"252-no-dispatcher","namespace":"org-252-no"}, "namespace": "org-252-no", "name": "252-no-dispatcher", "reconcileID": "8f2a69ef-14b8-426a-aba3-5a2b8dca9848", "Deployment.Namespace": "org-252-no", "Deployment.Name": "252-no-dispatcher"}

2. Run kuberr:

3. Get beautifully formatted output:

# K9s Log Report

**Source:** `monitoring-privileged/status-operator-5897985fd8-sn5xd:status-operator`
**K9s Version:** `v0.50.5`
...

## Logs

2025-06-30T16:21:34Z    INFO    Updating existing Deployment

```json
{
  "Deployment.Name": "252-no-dispatcher",
  "Deployment.Namespace": "org-252-no",
  "StatusDispatcher": {
    "name": "252-no-dispatcher",
    "namespace": "org-252-no"
  },
  "controller": "statusdispatcher",
  "controllerGroup": "status.252.no",
  "controllerKind": "StatusDispatcher",
  "name": "252-no-dispatcher",
  "namespace": "org-252-no",
  "reconcileID": "8f2a69ef-14b8-426a-aba3-5a2b8dca9848"
}

Advanced Usage

Fetching Live Data

If kuberr finds a pod name and namespace, you can use the --fetch flag to enrich its report with live event data directly from your cluster.

kuberr --fetch

The --fetch command uses kubectl and respects your KUBECONFIG environment variable.

---

Library Usage

You can also use kuberr as a library in your own Rust projects to parse Kubernetes-related text.

Add this to your Cargo.toml:

[dependencies]
kuberr = "0.1.0" # Replace with the desired version from crates.io

And use it in your code:

let k8s_output = r#"
  Warning  BackOff    4s (x2 over 5s)    kubelet            Back-off restarting failed container status-backend in pod example-instance-55c5b4bb97-dfwhc_org-252-no(744958df-536d-4f05-ab35-e686832e04ca)
"#;

let k8s_info = kuberr::format_k8s_output(k8s_output);
println!("{}", k8s_info.summary);

Contributing

Contributions are welcome! Whether it's improving the parsing logic, adding features, or fixing bugs, please feel free to open an issue or submit a pull request.

License

This project is licensed under the AGPL3 License.