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

📋 Prerequisites

• kubectl — Kubernetes CLI, configured with cluster access
• fzf — 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

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