feat: enhance debug session management with resource and network policy options

.gitignore

@@ -2,6 +2,7 @@
 .DS_Store
 .vscode
 .idea
+CLAUDE.md
 
 # App artifacts
 .kubebin

Pipfile

@@ -16,4 +16,4 @@ kubectl-application-shell = {file = ".", editable = true}
 python_version = "3.9"
 
 [scripts]
-kubeas = {call = "kubectl_application_shell.cli:app()"}
+kubeas = {call = "kubectl_application_shell:run_cli()"}

README.md

@@ -1,26 +1,317 @@
 # kubectl-application-shell
 
-### Description
+A kubectl plugin that creates safe debug pods from existing Kubernetes deployments.
 
-This kubectl plugin allows you to solve this issue:
+## Description
 
-> You may want to run a one off sql query wrapped up in a script just to glean some information from the database. The traditional way to do this is by using `kubectl exec` into an existing pod running as part of your deployment. However, this may cause issues if your one-off command ends up killing the pod, which may impact production (dropping connections etc). It's much safer just to spin up a pod to do the one off task.
+This kubectl plugin solves a common problem in Kubernetes debugging:
 
-This command essentially wraps around `kubectl run`. It will allow you to specify a deployment name and the deployment namespace, and it will automatically grab the currently running image, resource limits/requests, config and secret mappings so that you have the required environment variables to complete your one-off task without impacting the existing deployment.
+> When you need to run one-off tasks (SQL queries, file inspections, environment debugging), the traditional approach is `kubectl exec` into a running pod. However, this can cause issues if your command crashes the pod, potentially impacting production traffic.
 
-### Pre-requisites
+**kubectl-application-shell** provides a safer alternative by creating isolated debug pods that inherit the configuration from your existing deployment (image, environment variables, volumes, resource limits) without affecting running services.
 
-- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/)
-- [jq](https://github.com/stedolan/jq/wiki/Installation)
+## Features
 
-### Installation
+- 🚀 **Safe Debugging**: Creates isolated pods that don't impact production
+- 🔄 **Auto-Configuration**: Inherits image, env vars, volumes, and resources from target deployment
+- 🔗 **Session Management**: Resume disconnected sessions, list active sessions, manage multiple debugging sessions
+- 🛡️ **Security Options**: Service accounts, user contexts, privileged mode, network policies
+- 💾 **Storage Access**: Mount PVCs for persistent data debugging
+- 📝 **Session Logging**: Record debugging sessions for later analysis
+- ⚡ **Resource Control**: Override CPU/memory limits for specific debugging needs
+- 🎯 **Node Targeting**: Schedule on specific nodes for hardware-specific debugging
 
-This uses pipenv in order to manage dependencies. You need Python 3.
+## Prerequisites
 
-### Usage
+- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) (automatically downloaded if needed)
+- Python 3.9+
 
-Run `pipenv install` and `pipenv shell`.
+## Installation
 
-You can then run `kubeas` and it will give you the options.
+### Using pipenv (Development)
+```bash
+pipenv install
+pipenv shell
+```
 
-It will automatically grab the image, resource limits/requests, config and secret mappings from the specified deployment.
+### Using pip (Production)
+```bash
+pip install -e .
+```
+
+## Quick Start
+
+```bash
+# 1. Create a debug session from a deployment
+kubeas production api-server --run
+
+# 2. List active sessions (from another terminal)
+kubeas list-sessions
+
+# 3. Resume the session later
+kubeas resume-session debug-api-server-abc123 -n production --run
+
+# 4. Clean up when done
+kubeas terminate-session debug-api-server-abc123 -n production
+```
+
+## Basic Usage
+
+```bash
+# Create debug pod from deployment
+kubeas <namespace> <deployment>
+
+# Run immediately without showing command
+kubeas <namespace> <deployment> --run
+
+# Use custom shell/command
+kubeas <namespace> <deployment> /bin/zsh
+
+# Pass arguments to the command
+kubeas <namespace> <deployment> python3 script.py --verbose
+```
+
+## Advanced Options
+
+### Authentication & Authorization
+```bash
+# Use specific service account for RBAC debugging
+kubeas <namespace> <deployment> --service-account debug-sa
+
+# Run as specific user ID
+kubeas <namespace> <deployment> --run-as-user 1000
+```
+
+### Environment & Runtime
+```bash
+# Override environment variables
+kubeas <namespace> <deployment> --env DEBUG=true --env LOG_LEVEL=debug
+
+# Set working directory
+kubeas <namespace> <deployment> --workdir /app/scripts
+
+# Custom timeout for pod startup
+kubeas <namespace> <deployment> --timeout 10m
+```
+
+### Resource Management
+```bash
+# Override resource limits
+kubeas <namespace> <deployment> --cpu-limit 2 --memory-limit 4Gi
+
+# Set specific resource requests
+kubeas <namespace> <deployment> --cpu-request 500m --memory-request 1Gi
+```
+
+### Storage & Networking
+```bash
+# Mount persistent volume
+kubeas <namespace> <deployment> --mount-pvc data-pvc
+
+# Use host network for network debugging
+kubeas <namespace> <deployment> --host-network
+
+# Target specific nodes
+kubeas <namespace> <deployment> --node-selector kubernetes.io/arch=amd64
+```
+
+### Security & Debugging
+```bash
+# Run in privileged mode for system debugging
+kubeas <namespace> <deployment> --privileged
+
+# Create network policies for isolation
+kubeas <namespace> <deployment> --network-policy block-all-egress
+
+# Allow specific ports through network policy
+kubeas <namespace> <deployment> --network-policy allow-port --network-port 8080
+```
+
+### Session Management
+```bash
+# Log entire session to file
+kubeas <namespace> <deployment> --session-log debug-session.log
+
+# Non-interactive mode for automation
+kubeas <namespace> <deployment> --no-tty
+
+# List active debug sessions
+kubeas list-sessions
+kubeas list-sessions -n production
+
+# Resume an existing session
+kubeas resume-session debug-api-abc123 -n production
+
+# Terminate a session
+kubeas terminate-session debug-api-abc123 -n production
+```
+
+## Common Use Cases
+
+### Database Debugging
+```bash
+# Debug database connectivity with mounted data
+kubeas production api-server --mount-pvc postgres-data --env DEBUG_DB=true
+```
+
+### Network Troubleshooting
+```bash
+# Debug network issues with host network access
+kubeas production web-app --host-network --privileged
+```
+
+### Performance Analysis
+```bash
+# Run with higher resources for performance testing
+kubeas staging api --cpu-limit 4 --memory-limit 8Gi --session-log perf-test.log
+```
+
+### RBAC Testing
+```bash
+# Test with different service account permissions
+kubeas production worker --service-account restricted-sa --no-tty
+```
+
+### Session Management Workflow
+```bash
+# 1. Start a debug session (persists after disconnection)
+kubeas production api-server
+
+# 2. List active sessions to see what's running
+kubeas list-sessions
+
+# 3. Resume a session from another terminal/machine
+kubeas resume-session debug-api-server-abc123 -n production --run
+
+# 4. Clean up when done
+kubeas terminate-session debug-api-server-abc123 -n production
+```
+
+## How It Works
+
+1. **Deployment Inspection**: Queries the target deployment to extract configuration
+2. **Kubectl Download**: Automatically downloads cluster-compatible kubectl binary
+3. **Pod Generation**: Creates pod spec inheriting deployment configuration with session tracking labels
+4. **Resource Creation**: Applies any network policies or additional resources
+5. **Session Management**: Launches interactive shell with persistent session capability
+6. **Session Tracking**: Uses pod labels with user identifiers for session ownership and management
+7. **Cleanup**: NetworkPolicies auto-cleanup; pods persist for resumption until manually terminated
+
+## Advanced Features
+
+### Network Policies
+When using `--network-policy`, the tool creates Kubernetes NetworkPolicy resources:
+- `block-all-ingress`: Deny incoming traffic
+- `block-all-egress`: Deny outgoing traffic  
+- `block-all`: Deny all traffic
+- `allow-port`: Allow specific port (requires `--network-port`)
+- `allow-port-range`: Allow port range (requires `--network-port-range`)
+
+### Session Management
+- **Persistent Sessions**: Debug pods persist after terminal disconnection for later resumption
+- **User Isolation**: Each user can only manage their own sessions (based on system username)
+- **Cross-Platform**: Session state stored in Kubernetes labels, works from any machine
+- **Session Discovery**: `list-sessions` shows all active debug sessions with metadata
+
+### Automatic Cleanup
+- **NetworkPolicies**: Automatically deleted when sessions end
+- **Debug Pods**: Persist for resumption; use `terminate-session` for manual cleanup
+- **Cleanup Reminders**: Tool shows cleanup commands when not auto-running
+
+## Command Reference
+
+### Main Commands
+```bash
+kubeas <namespace> <deployment> [command] [options]    # Create debug session
+kubeas list-sessions [-n namespace]                     # List active sessions  
+kubeas resume-session <name> -n <namespace> [options]   # Resume existing session
+kubeas terminate-session <name> -n <namespace>          # Terminate session
+```
+
+### Common Options
+```bash
+--run                    # Execute immediately
+--context <name>         # Use specific kubeconfig context
+--service-account <sa>   # Use specific service account
+--env KEY=VALUE          # Set environment variables
+--cpu-limit <limit>      # Override CPU limit
+--memory-limit <limit>   # Override memory limit
+--mount-pvc <pvc>        # Mount persistent volume
+--session-log <file>     # Log session to file
+--privileged             # Run in privileged mode
+--host-network           # Use host network
+--no-tty                 # Non-interactive mode
+```
+
+## Troubleshooting
+
+### Common Issues
+- **Permission Denied**: Use `--service-account` with appropriate RBAC
+- **Image Pull Errors**: Verify the deployment's image is accessible
+- **Network Issues**: Try `--host-network` for network debugging
+- **Resource Constraints**: Use custom `--cpu-limit` and `--memory-limit`
+- **Session Not Found**: Check namespace with `kubeas list-sessions`
+- **Cannot Resume Session**: Verify you own the session (sessions are user-isolated)
+
+### Session Management Issues
+```bash
+# Check if sessions exist
+kubeas list-sessions
+
+# Verify session ownership (only your username sessions are manageable)
+kubeas list-sessions -n <namespace>
+
+# Force cleanup if needed (requires kubectl access)
+kubectl delete pod <session-name> -n <namespace>
+```
+
+### Getting Help
+```bash
+kubeas --help                           # Main command help
+kubeas list-sessions --help             # Session listing help
+kubeas resume-session --help            # Resume command help
+kubeas terminate-session --help         # Terminate command help
+```
+
+## Contributing
+
+### Development Setup
+```bash
+git clone <repository>
+cd kubectl-application-shell
+pipenv install --dev
+pipenv shell
+```
+
+### Testing
+```bash
+# Test against a real cluster
+kubeas test-namespace test-deployment --run
+
+# Test session management
+kubeas list-sessions
+```
+
+### Architecture
+This project uses:
+- **Typer** for CLI interface with multiple commands
+- **Rich** for colored output and tables
+- **Kubernetes Python Client** for API interactions
+- **Pipenv** for dependency management
+- **Pod Labels** for session tracking and user isolation
+
+### Key Files
+- `src/kubectl_application_shell/app.py` - Main debug session creation logic
+- `src/kubectl_application_shell/cli.py` - CLI commands and interface
+- `src/kubectl_application_shell/func.py` - Kubernetes API functions and session management
+- `src/kubectl_application_shell/console.py` - Rich console instance
+
+### Adding Features
+1. Add new CLI options to `app.py` main function
+2. Update pod spec generation logic
+3. Add corresponding functions to `func.py` if needed
+4. Update documentation in README.md and CLAUDE.md
+
+## License
+
+See project license file.

pyproject.toml

@@ -16,7 +16,7 @@ dependencies = [
 ]
 
 [project.scripts]
-kubeas = "kubectl_application_shell.cli:app"
+kubeas = "kubectl_application_shell:run_cli"
 
 [build-system]
 requires = ["hatchling"]

src/kubectl_application_shell/__init__.py

@@ -0,0 +1,20 @@
+"""kubectl-application-shell package"""
+
+import sys
+from typing import List
+
+
+def run_cli():
+    """Entry point that handles default command behavior"""
+    from .cli import app
+
+    # If we have arguments and the first one is not a known command
+    known_commands = ["main", "list-sessions", "resume-session", "terminate-session", "--help", "-h"]
+
+    if len(sys.argv) > 1 and sys.argv[1] not in known_commands:
+        # Check if the first argument starts with -- (it's an option)
+        if not sys.argv[1].startswith("-"):
+            # Insert "main" as the command
+            sys.argv.insert(1, "main")
+
+    app(prog_name="kubeas")

src/kubectl_application_shell/__main__.py

@@ -1,5 +1,5 @@
 """Helper module to run the CLI application."""
 
 if __name__ == "__main__":
-    from kubectl_application_shell.cli import app
-    app(prog_name="kubeas")
+    from kubectl_application_shell import run_cli
+    run_cli()