Metadata-Version: 2.4
Name: kubeloom
Version: 0.0.2
Summary: Service mesh policy discovery and management for Kubernetes
Project-URL: Homepage, https://github.com/adhityaravi/kubeloom
Project-URL: Repository, https://github.com/adhityaravi/kubeloom
Project-URL: Issues, https://github.com/adhityaravi/kubeloom/issues
Author: kubeloom contributors
License: GPL-3.0-only
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Networking
Classifier: Topic :: System :: Systems Administration
Requires-Python: <3.14,>=3.10
Requires-Dist: click>=8.1.7
Requires-Dist: httpx>=0.25.2
Requires-Dist: kubernetes>=28.1.0
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: rich>=13.7.0
Requires-Dist: textual>=0.47.0
Provides-Extra: dev
Requires-Dist: pre-commit>=3.6.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.1; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=7.4.3; extra == 'dev'
Requires-Dist: ruff>=0.1.9; extra == 'dev'
Requires-Dist: tox-uv>=1.0; extra == 'dev'
Requires-Dist: tox>=4.0; extra == 'dev'
Requires-Dist: ty; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5.3; extra == 'docs'
Requires-Dist: mkdocs>=1.5.3; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.24.0; extra == 'docs'
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.21.1; extra == 'test'
Requires-Dist: pytest-cov>=4.1.0; extra == 'test'
Requires-Dist: pytest-mock>=3.12.0; extra == 'test'
Requires-Dist: pytest>=7.4.3; extra == 'test'
Description-Content-Type: text/markdown

<h1 align="center">kubeloom</h1>

<p align="center">A service mesh debugging TUI built with Python and <a href="https://textual.textualize.io/">Textual</a></p>

## Installation

### From PyPI

```bash
pip install kubeloom
```

### Run without installing

```bash
uvx kubeloom tui
```

### Run from source

```bash
uvx --from git+https://github.com/adhityaravi/kubeloom kubeloom tui
```

> **Note:** Requires Python >=3.10, <3.14. Python 3.14 has stricter SSL certificate validation that may cause issues with some Kubernetes clusters.

## Why

Debugging service mesh issues with `kubectl logs` means grepping through thousands of log lines across multiple pods (ztunnel, waypoint, istiod), mentally correlating timestamps, and figuring out which denial came from where. kubeloom aggregates all of this into a single pane.

Instead of:
```bash
kubectl logs -n istio-system -l app=ztunnel --tail=1000 | grep -i denied
kubectl logs -n istio-system -l app=waypoint --tail=1000 | grep -i RBAC
# repeat for every namespace, every component, correlate manually...
```

You get a single TUI that tails everything, categorizes errors, and shows you exactly what's wrong.

## Mesh support

Currently supports **Istio ambient** mode only. Designed to be mesh agnostic with other mesh backends planned.

Built for debugging [Charmed Istio](https://github.com/canonical/istio-k8s-operator/) but should work with any Istio ambient deployment.

## Walkthrough

You've got a mesh. Something's broken. Let's debug.

### 1. Check your policies

Start in the **Policies** tab. You see all AuthorizationPolicies in your cluster, organized by namespace. The detail pane shows the full policy spec with sources, targets, and allowed routes. ALLOW policies are green, DENY policies are red.

![Policies Tab](assets/policies.png)

### 2. Check affected resources

Switch to **Resources** tab (`2`). These are pods and services that are targeted by your policies. kubeloom pre filters these so you're not staring at every pod in the cluster.

Red highlighting means the pod isn't enrolled in the mesh or a service doesn't have a waypoint proxy configured. These workloads won't be able to communicate properly with mesh enrolled workloads.

![Resources Tab](assets/resources.png)

### 3. Start tailing errors

Switch to **Mispicks** tab (`3`) and press `s` to start tailing logs. kubeloom watches all mesh firewall components (ztunnel, waypoint proxies) across all namespaces, parses their logs in real time, and categorizes errors:

| Error Type | Meaning |
|------------|---------|
| `source_not_on_mesh` | Source pod isn't enrolled so mesh can't identify it |
| `access_denied` | Policy explicitly blocked the request (RBAC denial) |
| `mtls_error` | mTLS handshake failed between workloads |
| `connection_error` | Upstream connection failed (502/503/504) |

The detail pane shows the full context: source workload, target service, port, HTTP method/path if L7, and the raw log line. Press `y` to copy the raw error message to clipboard.

If you're seeing noise from known sources, select the error and press `i` to ignore all errors with the same type and source workload. Press `I` to clear all ignore rules.

You see a `source_not_on_mesh` error. A pod is trying to talk to a mesh service, but the mesh can't identify who's calling because the source pod isn't enrolled.

![Mispicks - Source Not On Mesh](assets/mispicks_source_not_on_mesh.png)

### 4. Enroll the pod

Back to **Resources** tab (`2`). Find the pod that's not enrolled (highlighted red), select it with `j/k`, and press `e` to enroll it into the mesh.

kubeloom adds the appropriate labels/annotations to inject the sidecar or register with ztunnel depending on your mesh mode.

![Enroll Pod](assets/resources_enroll.png)

### 5. New error appears

Check **Mispicks** again (`3`). The `source_not_on_mesh` errors stop. But now you see `access_denied` mixed in with other noise. Press `i` on any `connection_error` you don't care about to hide them. Now you can focus on the `access_denied`. The pod is on the mesh, the mesh knows who it is, but there's no AuthorizationPolicy allowing it to talk to the target service.

![Mispicks - Access Denied](assets/mispicks_access_denied.png)

### 6. Weave a policy

With the `access_denied` error selected, press `w` to weave a policy. kubeloom generates an AuthorizationPolicy based on the error context. It extracts the source workload/namespace, target service/port, and creates an ALLOW policy.

![Weave Policy](assets/mispicks_weave.png)

> **Warning:** Woven policies are best effort. kubeloom extracts what it can from the error logs, but the generated policy might be too permissive, too restrictive, or just wrong. It's meant to unblock you during debugging, not to be your production policy.

### 7. Check the woven policy

Back to **Policies** tab (`1`). The new policy shows up, highlighted in cyan to indicate it's kubeloom managed. The labels tell you it's auto generated:

```yaml
labels:
  kubeloom.io/managed: "true"
  kubeloom.io/policy-type: l4
```

![Kubeloom Policy](assets/policies_kubeloom_policy.png)

Traffic flows. You've identified the issue: this workload needed a policy to talk to that service.

### 8. Clean up

These are temporary debugging aids. To revert everything:

Press `W` (shift+w) in **Mispicks** to unweave all kubeloom created policies. This deletes every policy with the `kubeloom.io/managed: true` label.

![Unweave Policies](assets/mispicks_unweave.png)

Press `u` in **Resources** to unenroll the pod from the mesh.

![Unenroll Pod](assets/resources_unenroll.png)

Now you know what was wrong.

## Warning: Not for production

kubeloom's enroll and weave features are **debugging tools only**.

**Woven policies are best effort.** They're generated from log context which may be incomplete. The policy might allow more than intended or not cover all cases.

**No security review.** Auto generated policies haven't been reviewed by a human. Don't ship them to production.

**Temporary by design.** Use kubeloom to identify what's wrong, then write proper policies with appropriate scoping, review, and testing.

The enroll/unenroll and weave/unweave features exist to quickly unblock debugging, not to manage your production mesh.

## Keybindings

| Key | Action |
|-----|--------|
| `1/2/3` | Switch tabs (Policies / Resources / Mispicks) |
| `j/k` | Navigate up/down |
| `h/l` | Scroll detail pane |
| `n/p` | Next/prev namespace |
| `/` | Filter current list |
| `r` | Refresh data |
| `y` | Copy manifest (Policies) or error message (Mispicks) to clipboard |
| `s` | Start tailing logs |
| `x` | Stop tailing logs |
| `c` | Clear collected errors |
| `i` | Ignore errors matching selected error's type and source |
| `I` | Clear all ignore rules |
| `e` | Enroll pod into mesh |
| `u` | Unenroll pod from mesh |
| `w` | Weave policy from error |
| `W` | Unweave all kubeloom policies |
| `q` | Quit |
