kdebug 0.3.4__tar.gz → 0.4.1__tar.gz

{kdebug-0.3.4 → kdebug-0.4.1}/.gitignore

@@ -1,3 +1,7 @@
+backups/
+temp/
+.vscode/
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[codz]

{kdebug-0.3.4 → kdebug-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kdebug
-Version: 0.3.4
+Version: 0.4.1
 Summary: Universal Kubernetes Debug Container Utility
 Project-URL: Homepage, https://github.com/jessegoodier/kdebug
 Project-URL: Repository, https://github.com/jessegoodier/kdebug
@@ -20,7 +20,7 @@ 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`.
 
 ## Features
 
@@ -31,6 +31,18 @@ Similar to kpf <https://github.com/jessegoodier/kpf>, this is a python wrapper a
 - 🔐 **Root Access Support** - Run debug containers as root when needed
 - 📦 **Controller Support** - Works with Deployments, StatefulSets, and DaemonSets
 
+<details open>
+<summary>Demo of the debug TUI</summary>
+
+![debug tui](docs/kdebug-demo_tui.gif)
+</details>
+
+<details open>
+<summary>Demo of backups</summary>
+
+![backup demo](docs/kdebug-demo_backups.gif)
+</details>
+
 ## Installation
 
 ```bash
@@ -45,7 +57,7 @@ git clone https://github.com/jessegoodier/kdebug.git
 cd kdebug
 ```
 
-Then make it is executable and add to something in your PATH
+Then make it executable and add to something in your PATH
 
 ```
 chmod +x bin/kdebug
@@ -113,14 +125,11 @@ These options are passed to all kubectl commands, including those used for tab c
 
 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
 ```
 
@@ -270,7 +279,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+)
 

{kdebug-0.3.4 → kdebug-0.4.1}/README.md

@@ -2,7 +2,7 @@
 
 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`.
 
 ## Features
 
@@ -13,6 +13,18 @@ Similar to kpf <https://github.com/jessegoodier/kpf>, this is a python wrapper a
 - 🔐 **Root Access Support** - Run debug containers as root when needed
 - 📦 **Controller Support** - Works with Deployments, StatefulSets, and DaemonSets
 
+<details open>
+<summary>Demo of the debug TUI</summary>
+
+![debug tui](docs/kdebug-demo_tui.gif)
+</details>
+
+<details open>
+<summary>Demo of backups</summary>
+
+![backup demo](docs/kdebug-demo_backups.gif)
+</details>
+
 ## Installation
 
 ```bash
@@ -27,7 +39,7 @@ git clone https://github.com/jessegoodier/kdebug.git
 cd kdebug
 ```
 
-Then make it is executable and add to something in your PATH
+Then make it executable and add to something in your PATH
 
 ```
 chmod +x bin/kdebug
@@ -95,14 +107,11 @@ These options are passed to all kubectl commands, including those used for tab c
 
 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
 ```
 
@@ -252,7 +261,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+)
 

{kdebug-0.3.4 → kdebug-0.4.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "kdebug"
-version = "0.3.4"
+version = "0.4.1"
 description = "Universal Kubernetes Debug Container Utility"
 readme = "README.md"
 license = "MIT"

{kdebug-0.3.4 → kdebug-0.4.1}/src/kdebug/__init__.py

@@ -1,4 +1,4 @@
-from importlib.metadata import version, PackageNotFoundError
+from importlib.metadata import PackageNotFoundError, version
 
 try:
     __version__ = version("kdebug")

{kdebug-0.3.4 → kdebug-0.4.1}/src/kdebug/cli.py

@@ -466,9 +466,7 @@ def select_pod(args) -> Optional[Dict]:
     # Validate cluster connection and namespace before proceeding
     error = validate_cluster_connection(namespace)
     if error:
-        print(
-            f"{colorize('✗ Error:', Colors.RED)} {error}"
-        )
+        print(f"{colorize('✗ Error:', Colors.RED)} {error}")
         return None
 
     # Direct pod selection
@@ -495,12 +493,12 @@ def select_pod(args) -> Optional[Dict]:
         return pods[0]
 
     # Interactive mode - no pod or controller specified
-    print(f"\n{colorize('Starting interactive pod selection...', Colors.BRIGHT_CYAN)}")
+    print(f"\n{colorize('Starting interactive pod selection...', Colors.CYAN)}")
 
     # Direct pod selection via TUI
     pod_name = select_pod_interactive(namespace)
     if not pod_name:
-        print(f"\n{colorize('Selection cancelled', Colors.YELLOW)}")
+        print(f"\n{colorize('Selection cancelled', Colors.CYAN)}")
         return None
 
     return {"name": pod_name, "namespace": namespace}
@@ -703,6 +701,42 @@ def check_pod_security_context(pod_name: str, namespace: str) -> Dict:
         return {"can_run_as_root": True, "reason": "Unable to parse pod spec"}
 
 
+def get_container_run_as_user(
+    pod_name: str, namespace: str, target_container: Optional[str]
+) -> Optional[int]:
+    """Detect the runAsUser UID from the target container or pod security context."""
+    cmd = f"{kubectl_base_cmd()} get pod {pod_name} -n {namespace} -o json"
+    output = run_command(cmd, check=False)
+
+    if not output:
+        return None
+
+    try:
+        pod_data = json.loads(output)
+        spec = pod_data.get("spec", {})
+
+        # Check container-level securityContext first (overrides pod-level)
+        if target_container:
+            for container in spec.get("containers", []):
+                if container.get("name") == target_container:
+                    container_uid = container.get("securityContext", {}).get(
+                        "runAsUser"
+                    )
+                    if container_uid is not None:
+                        return int(container_uid)
+                    break
+
+        # Fall back to pod-level securityContext
+        pod_uid = spec.get("securityContext", {}).get("runAsUser")
+        if pod_uid is not None:
+            return int(pod_uid)
+
+    except (json.JSONDecodeError, ValueError, TypeError):
+        pass
+
+    return None
+
+
 def launch_debug_container(
     pod_name: str,
     namespace: str,
@@ -710,6 +744,7 @@ def launch_debug_container(
     target_container: Optional[str],
     existing_containers: List[str],
     as_root: bool = False,
+    run_as_user: Optional[int] = None,
 ) -> Optional[str]:
     """Launch a debug container attached to the pod and return its name."""
     print(f"Launching debug container for pod {colorize(pod_name, Colors.CYAN)}...")
@@ -727,12 +762,16 @@ def launch_debug_container(
                 file=sys.stderr,
             )
             print(f"{colorize('Tip:', Colors.CYAN)} Try without --as-root flag\n")
-
-    if existing_containers:
+    elif run_as_user is not None:
         print(
-            f"Existing ephemeral containers: {colorize(', '.join(existing_containers), Colors.BRIGHT_BLACK)}"
+            f"Running as UID {colorize(str(run_as_user), Colors.CYAN)} (matching target container)"
         )
 
+    # if existing_containers:
+    #     print(
+    #         f"Existing ephemeral containers: {colorize(', '.join(existing_containers), Colors.BRIGHT_BLACK)}"
+    #     )
+
     # Build kubectl debug command
     cmd_parts = [
         f"nohup {kubectl_base_cmd()} debug -i --tty",
@@ -752,6 +791,10 @@ def launch_debug_container(
 
     if as_root:
         cmd_parts.append('--custom=<(echo \'{"securityContext":{"runAsUser":0}}\')')
+    elif run_as_user is not None:
+        cmd_parts.append(
+            f'--custom=<(echo \'{{"securityContext":{{"runAsUser":{run_as_user}}}}}\')'
+        )
 
     cmd_parts.extend(
         [
@@ -798,13 +841,12 @@ def exec_interactive(
 ) -> int:
     """Execute an interactive command in the debug container."""
     print(f"\n{colorize('=' * 60, Colors.BLUE)}")
-    print(
-        f"{colorize('Starting interactive session', Colors.BOLD)} in pod {colorize(pod_name, Colors.CYAN)}"
-    )
+    print(f"{colorize('Starting interactive session', Colors.BOLD)} in:")
+    print(f"Pod: {colorize(pod_name, Colors.CYAN)}")
     print(f"Container: {colorize(container_name, Colors.CYAN)}")
-    print(f"Command: {colorize(cmd, Colors.YELLOW)}")
+    print(f"Command: {colorize(cmd, Colors.CYAN)}")
     if cd_into:
-        print(f"Directory: {colorize(cd_into, Colors.MAGENTA)}")
+        print(f"Directory: {colorize(cd_into, Colors.CYAN)}")
     print(f"{colorize('=' * 60, Colors.BLUE)}\n")
 
     # If cd_into is specified, wrap command to cd first
@@ -883,7 +925,7 @@ def create_backup(
         f"{kubectl_base_cmd()} exec {pod_name} "
         f"-n {namespace} "
         f"-c {container_name} "
-        f"-- ls -d {backup_path} 2>/dev/null"
+        f"-- ls -d /proc/1/root{backup_path} 2>/dev/null"
     )
 
     result = run_command(verify_cmd, check=False)
@@ -903,7 +945,7 @@ def create_backup(
                 f"{kubectl_base_cmd()} exec {pod_name} "
                 f"-n {namespace} "
                 f"-c {container_name} "
-                f"-- ls -la {parent_dir} 2>/dev/null | head -20"
+                f"-- ls -la /proc/1/root{parent_dir} 2>/dev/null | head -20"
             )
             parent_result = run_command(parent_cmd, check=False)
             if parent_result:
@@ -977,7 +1019,7 @@ def create_backup(
             f"{kubectl_base_cmd()} cp "
             f"-n {namespace} "
             f"-c {container_name} "
-            f"{pod_name}:{backup_path} "
+            f"{pod_name}:/proc/1/root{backup_path} "
             f"{local_filename}"
         )
 
@@ -1043,7 +1085,7 @@ def parse_controller_arg(value: str) -> Tuple[str, str]:
     controller_type, controller_name = value.split("/", 1)
     if not controller_name:
         raise argparse.ArgumentTypeError(
-            f"Missing controller name after '/'. Expected TYPE/NAME (e.g. sts/myapp)."
+            "Missing controller name after '/'. Expected TYPE/NAME (e.g. sts/myapp)."
         )
     if controller_type.lower() not in CONTROLLER_ALIASES:
         valid_types = ", ".join(sorted(CONTROLLER_ALIASES.keys()))
@@ -1200,15 +1242,13 @@ Usage:
         )
 
     print(f"\n{colorize('=' * 60, Colors.BLUE)}")
+    print(f"{colorize('Namespace:', Colors.BOLD)} {colorize(namespace, Colors.CYAN)}")
     print(f"{colorize('Target Pod:', Colors.BOLD)} {colorize(pod_name, Colors.CYAN)}")
-    print(
-        f"{colorize('Namespace:', Colors.BOLD)} {colorize(namespace, Colors.MAGENTA)}"
-    )
     print(
         f"{colorize('Target Container:', Colors.BOLD)} {colorize(target_container, Colors.CYAN)}"
     )
     print(
-        f"{colorize('Debug Image:', Colors.BOLD)} {colorize(args.debug_image, Colors.BRIGHT_BLACK)}"
+        f"{colorize('Debug Image:', Colors.BOLD)} {colorize(args.debug_image, Colors.CYAN)}"
     )
     print(f"{colorize('=' * 60, Colors.BLUE)}\n")
 
@@ -1222,7 +1262,12 @@ Usage:
             f"Found existing ephemeral containers: {colorize(', '.join(existing_containers), Colors.BRIGHT_BLACK)}"
         )
         # For simplicity, we'll create a new one. In production, you might want to reuse.
-        print(f"{colorize('Creating new debug container...', Colors.YELLOW)}")
+        print(f"{colorize('Creating new debug container...', Colors.MAGENTA)}")
+
+    # Detect target container UID for the debug container
+    run_as_user = None
+    if not args.as_root:
+        run_as_user = get_container_run_as_user(pod_name, namespace, target_container)
 
     # Launch debug container
     debug_container = launch_debug_container(
@@ -1232,6 +1277,7 @@ Usage:
         target_container,
         existing_containers,
         args.as_root,
+        run_as_user,
     )
 
     if not debug_container: