kdbg
Interactive CLI to launch privileged debug containers against running
Kubernetes pods. Wraps kubectl debug with fzf-powered selection
and automatic Pod Security Admission management.
flowchart TB
A[kdbg] --> B{Interactive selection}
B --> C[Context]
B --> D[Namespace]
B --> E[Pod]
B --> F[Container]
C & D & E & F --> G[Apply privileged PSA label]
G --> H[kubectl debug -it]
H --> I[Debug session]
I --> J[Cleanup PSA label]
🚀 Features
| Feature | Description |
|---|---|
| 🔍 Interactive selection | fzf-powered picker for context, namespace, pod, and container |
| 🐳 Custom debug image | --image to use any debug image (default: obeoneorg/netshoot) |
| 🔒 PSA management | Auto-applies privileged label, cleans up on exit |
| 👑 Root by default | Forces runAsUser: 0 on the ephemeral container (opt-out: --preserve-user) |
| 🧪 Dry-run mode | --dry-run prints the generated kubectl command |
| 🎨 Colored logging | Adjustable verbosity with --log-level |
| 🐚 Shell completion | Bash, Zsh, and Fish completion scripts |
| ⚙️ Security profiles | --profile or KDBG_PROFILE env var |
📋 Prerequisites
kubectl— Kubernetes CLI, configured with cluster accessfzf— command-line fuzzy finder
📦 Installation
From PyPI (recommended)
uv tool install kdbg
or with pipx:
pipx install kdbg
From GitHub
uv tool install \
'kdbg @ git+https://github.com/obeone/scripts.git#subdirectory=kdbg'
From a local clone
git clone https://github.com/obeone/scripts.git
uv tool install ./scripts/kdbg
Shell completion
Add the appropriate line to your shell configuration file:
Bash (~/.bashrc):
eval "$(kdbg --completion bash)"
Zsh (~/.zshrc):
eval "$(kdbg --completion zsh)"
Fish (~/.config/fish/config.fish):
kdbg --completion fish | source
🛠️ Usage
Quick start
Run without arguments for full interactive mode:
kdbg
Direct targeting
kdbg -C my-cluster -n my-namespace -p my-pod -c app-container
Common options
| Option | Description |
|---|---|
-C, --context |
Kubernetes context |
-n, --namespace |
Target namespace |
-p, --pod |
Target pod |
-c, --container |
Target container |
-i, --image |
Debug image (default: obeoneorg/netshoot) |
--profile |
Security profile (default: sysadmin) |
--preserve-user |
Inherit target's runAsUser/runAsGroup/runAsNonRoot instead of forcing root |
--dry-run |
Print command without executing |
-l, --log-level |
debug, info, warn, error |
Examples
Custom debug image:
kdbg --image busybox:latest
Dry-run to inspect the command:
kdbg -n my-namespace -p my-pod --dry-run
Run a command in the debug container:
kdbg -n my-namespace -p my-pod -- tcpdump -i eth0
Inherit the target's user instead of forcing root:
kdbg -n my-namespace -p my-pod --preserve-user
Verbose output:
kdbg --log-level debug
📄 License
MIT — see LICENSE for details.
Author: obeone
Metadata
Release files for kdbg 0.6.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| kdbg-0.6.0.tar.gz | 17.1 kB | Without provenance | Details for kdbg-0.6.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| kdbg-0.6.0-py3-none-any.whl | Python 3 | none | any | Details for kdbg-0.6.0-py3-none-any.whl |
Total release size: 33.9 kB
Release files / kdbg-0.6.0.tar.gz
| Download URL | kdbg-0.6.0.tar.gz |
|---|---|
| Size | 17.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2775c6ecd2fdcec4205ac671a4b570265e19ce28f3cf7e4c5676ba3d3e6ce0b7
|
|
BLAKE2b-256 checksum How to use checksums |
c6f5fc9eb45287cb2a0395b706dd8d4e6ca5c88f44f4d73ce593302314cf6cf1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.6
|
Release files / kdbg-0.6.0-py3-none-any.whl
| Download URL | kdbg-0.6.0-py3-none-any.whl |
|---|---|
| Size | 16.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
63ee801c25f3bc3bd34b551764093b2c341be4dca0ba78d4ed06b871e7eb1b71
|
|
BLAKE2b-256 checksum How to use checksums |
955f182806fcd3a2f6dc14c1afa16047424df644cfc56b9f85c55c7fd7f4b89f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.6
|
Security for kdbg 0.6.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.