kdebug 0.4.0__tar.gz → 0.5.0__tar.gz

{kdebug-0.4.0 → kdebug-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kdebug
-Version: 0.4.0
+Version: 0.5.0
 Summary: Universal Kubernetes Debug Container Utility
 Project-URL: Homepage, https://github.com/jessegoodier/kdebug
 Project-URL: Repository, https://github.com/jessegoodier/kdebug
@@ -20,81 +20,51 @@ Description-Content-Type: text/markdown
 
 Simple utility for launching ephemeral debug containers in Kubernetes pods with interactive shell access, backup capabilities, and a colorful TUI for pod selection.
 
-Similar to kpf <https://github.com/jessegoodier/kpf>, this is a python wrapper around `kubectl debug` and `kubectl cp`.
+Similar to [kpf](https://github.com/jessegoodier/kpf), this is a python wrapper around `kubectl debug` and `kubectl cp`.
+
+>Notice: the default debug container image is <https://github.com/jessegoodier/toolbox/tree/main/common> and may not be ideal for all users. This is configurable both with an arg and a global config file
 
 ## Features
 
-- 🐚 **Interactive Shell Access** - Launch bash/zsh sessions in debug containers directly to the directory of your choice
-- 💾 **Backup Capabilities** - Copy files/directories from pods with optional compression
-- 🔍 **Multiple Selection Modes** - Direct pod, controller-based, or interactive tui
+- 🐚 **Interactive Shell Access** - Launch bash/sh sessions in debug containers directly to the directory of your choice
+- 💾 **Backup Capabilities** - Copy files/directories from pods with optional compression and configurable local paths
+- 🔍 **Multiple Selection Modes** - Direct pod, controller-based, or interactive TUI
 - 🎯 **Smart Container Selection** - Auto-select containers or choose specific targets
 - 🔐 **Root Access Support** - Run debug containers as root when needed
 - 📦 **Controller Support** - Works with Deployments, StatefulSets, and DaemonSets
+- ⚙️ **Config File** - Set defaults for debug image, shell command, and backup paths
 
-## Installation
-
-```bash
-brew install jessegoodier/kdebug/kdebug
-```
-
-Or
+<details open>
+<summary>Demo of the debug TUI</summary>
 
-```bash
-# Clone the repository
-git clone https://github.com/jessegoodier/kdebug.git
-cd kdebug
-```
+![debug tui](docs/kdebug-demo_tui.gif)
+</details>
 
-Then make it is executable and add to something in your PATH
-
-```
-chmod +x bin/kdebug
-ln -s $(pwd)/bin/kdebug ~/.local/bin/kdebug
-```
-
-## Shell Completion
+<details open>
+<summary>Demo of backups</summary>
 
-kdebug supports tab completion for bash and zsh with dynamic lookups for namespaces, pods, and controller names.
+![backup demo](docs/kdebug-demo_backups.gif)
+</details>
 
-### Bash
+## Installation
 
 ```bash
-# Add to ~/.bashrc
-source <(kdebug --completions bash)
-
-# Or source the file directly
-source /path/to/kdebug/completions/kdebug.bash
+brew install jessegoodier/kdebug/kdebug
 ```
 
-### Zsh
+## Usage
 
-```bash
-# Option 1: Source directly (add to ~/.zshrc)
-source <(kdebug --completions zsh)
+kdebug uses subcommands for its two modes of operation:
 
-# Option 2: Install to fpath (recommended)
-mkdir -p ~/.zsh/completions
-kdebug --completions zsh > ~/.zsh/completions/_kdebug
-# Add to ~/.zshrc before compinit:
-fpath=(~/.zsh/completions $fpath)
-autoload -Uz compinit && compinit
 ```
-
-### Completion Features
-
-- `kdebug --<TAB>` - Complete all options
-- `kdebug -n <TAB>` - Complete namespace names from cluster
-- `kdebug --pod <TAB>` - Complete pod names (respects -n flag)
-- `kdebug --controller <TAB>` - Complete controller types
-- `kdebug --controller sts --controller-name <TAB>` - Complete controller names
-- `kdebug --context <TAB>` - Complete context names from kubeconfig
-- `kdebug --kubeconfig <TAB>` - Complete file paths
-
-## Usage
+kdebug debug [options]          # Interactive debug session (default)
+kdebug backup [options]         # Backup files from pod
+kdebug [options]                # Same as "kdebug debug" for convenience
+```
 
 ### Global Options
 
-kdebug supports kubectl-compatible `--context` and `--kubeconfig` flags to target different clusters:
+These shared options work with both subcommands:
 
 ```bash
 # Use a specific context
@@ -107,58 +77,54 @@ kdebug --kubeconfig .kubeconfig -n openclaw
 kdebug --kubeconfig /path/to/config --context staging -n myapp --pod api-0
 ```
 
-These options are passed to all kubectl commands, including those used for tab completion.
-
 ### Interactive Mode (TUI)
 
 When no pod or controller is specified, kdebug launches an interactive menu system:
 
-# Interactive mode - select from all resources in current namespace
 ```bash
+# Interactive mode - select from all resources in current namespace
 kdebug
-```
 
 # Interactive mode with specific namespace
-
-```bash
 kdebug -n openclaw
 ```
 
-**TUI Features:**
-- ⬆️⬇️ Use arrow keys to navigate
-- 1️⃣-9️⃣ Press numbers for quick selection
-- ↩️ Press Enter to confirm
-- ❌ Press 'q' to quit
+### Debug Subcommand
 
-The TUI displays all pods in the namespace with:
-- Color-coded status indicators (Green=Running, Yellow=Pending, etc.)
-- Pod names highlighted for easy identification
-- Real-time status information
-
-### Direct Pod Selection
+The `debug` subcommand (or naked `kdebug`) launches an interactive shell session in an ephemeral debug container.
 
 ```bash
-# Interactive session with direct pod
+# Interactive session with direct pod (bare usage = debug)
 kdebug -n kubecost --pod aggregator-0 --container aggregator
 
+# Explicit debug subcommand with custom shell
+kdebug debug -n kubecost --pod aggregator-0 --cmd sh
+
 # Auto-select first container if not specified
-kdebug -n kubecost --pod aggregator-0
+kdebug debug -n kubecost --pod aggregator-0
 
-# Custom shell command
-kdebug -n kubecost --pod aggregator-0 --cmd sh
+# Change to a directory on start
+kdebug debug -n kubecost --pod aggregator-0 --cd-into /var/configs
 ```
 
+**Debug-specific options:**
+
+| Option | Description |
+|---|---|
+| `--cmd CMD` | Command to run in debug container (default: `bash`) |
+| `--cd-into DIR` | Change to directory on start (via `/proc/1/root`) |
+
 ### Controller-Based Selection
 
 ```bash
 # Using StatefulSet (sts)
-kdebug -n kubecost --controller sts --controller-name aggregator --container aggregator
+kdebug --controller sts/aggregator --container aggregator
 
 # Using Deployment
-kdebug -n myapp --controller deployment --controller-name frontend --cmd bash
+kdebug -n myapp --controller deploy/frontend --cmd sh
 
 # Using DaemonSet
-kdebug -n logging --controller ds --controller-name fluentd
+kdebug -n logging --controller ds/fluentd
 ```
 
 **Supported Controller Types:**
@@ -166,41 +132,155 @@ kdebug -n logging --controller ds --controller-name fluentd
 - `statefulset` or `sts` - StatefulSets
 - `daemonset` or `ds` - DaemonSets
 
-### Advanced Features
+### Backup Subcommand
 
-#### Change Directory on Start
+The `backup` subcommand copies files or directories from a pod to your local machine.
 
 ```bash
-# Start shell in specific directory
-kdebug -n kubecost --pod aggregator-0 --cd-into /var/configs
+# Backup a directory (uncompressed)
+kdebug backup -n kubecost --pod aggregator-0 --container-path /var/configs
+
+# Backup with compression
+kdebug backup -n kubecost --pod aggregator-0 --container-path /var/configs --compress
+
+# Backup with a custom local path using template variables
+kdebug backup --pod web-0 --container-path /var/data \
+  --local-path ./my-backups/{namespace}/{pod}
+
+# Backup using controller selection
+kdebug backup --controller deploy/kubecost-local-store \
+  --container-path /var/configs/localBucket_v002
 ```
 
-#### Backup Mode
+**Backup-specific options:**
 
-```bash
-# Backup directory (uncompressed)
-kdebug -n kubecost --pod aggregator-0 --backup /var/configs
+| Option | Description |
+|---|---|
+| `--container-path PATH` | **(required)** Path inside the container to back up |
+| `--local-path TEMPLATE` | Local destination (default: `./backups/{namespace}/{date}_{pod}`) |
+| `--compress` | Compress backup as tar.gz |
+| `--tar-exclude PATH` | Exclude a path or pattern from the archive (repeatable) |
 
-# Backup with compression
-kdebug -n kubecost --pod aggregator-0 --backup /var/configs --compress
+**Using `--tar-exclude`:**
+
+Excludes are matched against paths inside the archive and can be repeated. Provide a name or relative pattern — **do not include the full container path prefix**:
+
+```bash
+# Exclude a single subdirectory by name
+kdebug backup -n kubecost --pod aggregator-0 --container-path /var/configs \
+  --compress --tar-exclude waterfowl
 
-# Backups are saved to: ./backups/<namespace>/<timestamp>_<pod-name>
+# Exclude multiple paths
+kdebug backup -n kubecost --pod aggregator-0 --container-path /var/configs \
+  --compress --tar-exclude waterfowl --tar-exclude tmp --tar-exclude '*.log'
 ```
 
-#### Run as Root
+**Template variables for `--local-path`:**
+
+| Variable | Value |
+|---|---|
+| `{namespace}` | Kubernetes namespace |
+| `{pod}` | Pod name |
+| `{date}` | Timestamp (`YYYY-MM-DD_HH-MM-SS`) |
+| `{container}` | Target container name |
+
+### Run as Root
 
 ```bash
 # Launch debug container as root user
 kdebug -n myapp --pod frontend-abc123 --as-root
 ```
 
-#### Debug Mode
+### Verbose Mode
 
 ```bash
 # Show all kubectl commands being executed
-kdebug -n myapp --pod frontend-abc123 --debug
+kdebug -n myapp --pod frontend-abc123 --verbose
+```
+
+## Config File
+
+kdebug supports a JSON config file at `~/.config/kdebug/kdebug.json` (respects `XDG_CONFIG_HOME`). CLI flags always take priority over config values.
+
+```json
+{
+  "debugImage": "busybox:latest",
+  "cmd": "sh",
+  "cdInto": "/app",
+  "backupContainerPath": "/var/data",
+  "backupLocalPath": "./backups/{namespace}/{date}_{pod}"
+}
+```
+
+| Key | Description | Default |
+|---|---|---|
+| `debugImage` | Debug container image | `ghcr.io/jessegoodier/toolbox-common:latest` |
+| `cmd` | Shell command for debug sessions | `bash` |
+| `cdInto` | Directory to cd into on start | *(none)* |
+| `backupContainerPath` | Default container path for backups | *(none)* |
+| `backupLocalPath` | Default local path template for backups | `./backups/{namespace}/{date}_{pod}` |
+
+String values support `${ENV_VAR}` expansion:
+
+```json
+{
+  "debugImage": "${MY_DEBUG_IMAGE}",
+  "backupLocalPath": "${HOME}/kdebug-backups/{namespace}/{date}_{pod}"
+}
+```
+
+### Example: Using busybox as debug image
+
+If you don't need the full toolbox image, busybox is a lightweight alternative:
+
+```json
+{
+  "debugImage": "busybox:latest",
+  "cmd": "sh"
+}
+```
+
+Since busybox doesn't include bash, set `cmd` to `sh`. With this config, simply run `kdebug --pod my-pod` and it will use busybox with sh automatically.
+
+## Shell Completion
+
+kdebug supports tab completion for bash and zsh with dynamic lookups for namespaces, pods, controller names, and subcommands.
+
+### Bash
+
+```bash
+# Add to ~/.bashrc
+source <(kdebug --completions bash)
+
+# Or source the file directly
+source /path/to/kdebug/completions/kdebug.bash
 ```
 
+### Zsh
+
+```bash
+# Option 1: Source directly (add to ~/.zshrc)
+source <(kdebug --completions zsh)
+
+# Option 2: Install to fpath (recommended)
+mkdir -p ~/.zsh/completions
+kdebug --completions zsh > ~/.zsh/completions/_kdebug
+# Add to ~/.zshrc before compinit:
+fpath=(~/.zsh/completions $fpath)
+autoload -Uz compinit && compinit
+```
+
+### Completion Features
+
+- `kdebug <TAB>` - Complete subcommands (`debug`, `backup`)
+- `kdebug --<TAB>` - Complete shared options
+- `kdebug debug --<TAB>` - Complete debug-specific options
+- `kdebug backup --<TAB>` - Complete backup-specific options
+- `kdebug -n <TAB>` - Complete namespace names from cluster
+- `kdebug --pod <TAB>` - Complete pod names (respects -n flag)
+- `kdebug --controller <TAB>` - Complete controller types and names
+- `kdebug --context <TAB>` - Complete context names from kubeconfig
+
 ## Examples
 
 ### Example 1: Interactive Pod Selection
@@ -229,7 +309,7 @@ Use ↑/↓ arrows or numbers to select, Enter to confirm, q to quit
 
 ```bash
 # Launch debug container and get bash shell
-kdebug -n kubecost --controller sts --controller-name aggregator --container aggregator
+kdebug -n kubecost --controller sts/aggregator --container aggregator
 
 # Output:
 # ══════════════════════════════════════════════════════════════════════
@@ -239,21 +319,25 @@ kdebug -n kubecost --controller sts --controller-name aggregator --container agg
 # ══════════════════════════════════════════════════════════════════════
 ```
 
-### Example 3: Backup Configuration Files
+### Example 3: Backup with Custom Local Path
 
 ```bash
-# Backup with compression
-kdebug -n production --pod api-server-0 --backup /etc/app/config --compress
+# Backup with compression to a custom path
+kdebug backup -n production --pod api-server-0 \
+  --container-path /etc/app/config \
+  --local-path ./config-backups/{namespace}/{date}_{pod} \
+  --compress
 
 # Output:
 # ══════════════════════════════════════════════════════════════════════
 # Creating backup from pod api-server-0
-# Path: /etc/app/config
+# Container path: /etc/app/config
+# Local path: ./config-backups/production/2024-02-04_10-30-45_api-server-0.tar.gz
 # Mode: Compressed (tar.gz)
 # ══════════════════════════════════════════════════════════════════════
 # ✓ Path exists: /etc/app/config
 # ✓ Backup archive created
-# ✓ Backup saved to: ./backups/production/2024-02-04_10-30-45_api-server-0.tar.gz
+# ✓ Backup saved to: ./config-backups/production/2024-02-04_10-30-45_api-server-0.tar.gz
 ```
 
 ## Color Scheme
@@ -270,7 +354,7 @@ kdebug uses a kubecolor-inspired color scheme:
 
 ## Requirements
 
-- Python 3.6+
+- Python 3.9+
 - kubectl configured with cluster access
 - Kubernetes cluster with ephemeral containers support (v1.23+)
 
@@ -304,7 +388,7 @@ Check:
 - Debug image is accessible from cluster
 - Pod has sufficient resources
 - Network policies allow image pull
-- Use `--debug` flag to see kubectl commands
+- Use `--verbose` flag to see kubectl commands
 
 ## License
 
@@ -316,4 +400,4 @@ Contributions welcome! Please open issues or pull requests.
 
 ---
 
-Made with ❤️ and Bob
+Made with ❤️ and Bob