Krayt - Distrobox for Kubernetes

A Kubernetes volume inspector and development environment creator that provides distrobox-like functionality for containerized workloads.

Vision

Krayt enables developers to easily create, enter, and manage development environments that clone the storage and device configuration of any running pod in Kubernetes - similar to how distrobox works for Linux containers, but for Kubernetes pods.

Core Philosophy

• Simple to Start: krayt create my-pod - clone any pod into an inspectable environment
• Rich Development Environment: Comes with extensive development tools pre-installed
• Persistent by Default: Environments persist until you explicitly clean them up
• Multi-Image Support: Alpine (default) and Arch Linux base images
• Configurable: User customization via ~/.config/krayt/
• Reusable: Core functionality available as a Python module for other projects

User Experience

Basic Workflow

# List available pods to clone
krayt list-pods

# Create a development environment (prints YAML for inspection)
krayt create my-app-pod

# Minimal standalone (6 packages, fast startup)
krayt create --standalone --apply my-pod

# Full standalone (33+ packages, comprehensive tools)
krayt create --standalone --full-tools --apply my-pod

# Custom tools with minimal system packages
krayt create --standalone --with-tools "k9s,uv,node@20" --apply my-pod

# Inspect, save to file, or pipe to kubectl
krayt create my-app-pod > inspector.yaml
krayt create my-app-pod | kubectl apply -f -
krayt create --apply my-app-pod  # Direct apply

# Enter to environment (creates if not exists)
krayt enter my-app-pod

# List your active environments
krayt list

# Clean up specific environment
krayt delete my-app-pod-krayt-1703025600

# Clean up all environments
krayt clean

Advanced Usage

# Use Arch Linux instead of default Alpine
krayt create --base-image archlinux my-app-pod

# Create with custom tools
krayt create --with-tools git,nodejs,python,go my-app-pod

# Create with minimal system tools (default behavior)
krayt create --standalone --apply my-pod

# Create with full system tools suite
krayt create --standalone --full-tools --apply my-pod

# Use custom image with additional packages
krayt create --image custom-dev:latest my-app-pod

# Create environment from pod in specific namespace
krayt create --namespace staging my-app-pod

# Export environment configuration
krayt export my-app-pod-krayt-1703025600 > my-dev-env.yaml

# Import environment configuration
krayt import my-dev-env.yaml

# Follow logs of environment creation
krayt logs --follow my-app-pod-krayt-1703025600

Recent Improvements

Performance & Size Optimization (v0.5.1+)

Problem: Default installations included 33+ tools (141 packages, 248.7 MiB)

Solution: Intelligent tiered tool installation:

Minimal Setup (Default)

• Size: ~6 packages only
• Tools: curl, wget, git, vim, bash, starship
• User Shell: Automatically detects and installs user's preferred shell (zsh, fish)
• Startup: Fast, lightweight, perfect for quick inspections
• Use Case: krayt create --standalone --apply my-pod

Full Setup (Optional)

• Size: 33+ packages with all extended tools
• Tools: All minimal + monitoring + networking + database tools
• Startup: Comprehensive but larger footprint
• Use Case: krayt create --standalone --full-tools --apply my-pod

Smart Shell Integration

• Detection: Automatically detects user's shell from $SHELL
• Installation: Includes user's preferred shell in minimal setups
• Fallback: Smart detection in enter command with multiple fallback options
• Consistency: Starship prompt always included for uniform experience

Benefits

1. 🚀 Fast Startup: 6 vs 141 packages for minimal setups
2. 💡 User-Centric: Your preferred shell automatically available
3. 🔧 Flexible: Choose minimal vs full based on needs
4. ⚡ Resource Efficient: Smaller container images, faster deployment
5. 🔄 Backward Compatible: Existing functionality preserved

Architecture

Core Components

1. CLI Interface (krayt/cli.py)

   • Command-line interface using Typer
   • User interaction and orchestration
   • Configuration management
   • Smart shell detection and fallback logic

2. Core Engine (krayt/core.py)

   • Kubernetes API interactions
   • Pod inspection and cloning logic
   • Job/pod lifecycle management
   • Tiered tool installation (minimal vs full)

3. Template System (krayt/templates.py)

   • Simple Jinja2-based templates for pod specs
   • Tool installation scripts
   • Environment setup

4. Package Manager (krayt/packages.py)

   • Development tool definitions
   • Base image package management
   • Multi-package-manager support (apk, pacman, apt, etc.)

5. Configuration (krayt/config.py)

   • User configuration loading
   • Template and customization support
   • Environment variable management

File Structure

krayt/
├── krayt/
│   ├── __init__.py          # Package initialization
│   ├── __about__.py          # Version information
│   ├── cli.py               # Main CLI interface
│   ├── core.py              # Core Kubernetes operations
│   ├── templates.py         # Template management
│   ├── packages.py          # Package definitions
│   ├── config.py            # Configuration system
│   └── utils.py             # Utility functions
├── krayt/
│   └── templates/           # Built-in templates
│       ├── alpine.sh        # Alpine setup script
│       ├── arch.sh          # Arch setup script
│       └── common.sh        # Common setup
├── pyproject.toml           # Package configuration
├── justfile                 # Development tasks
├── krayt1.py               # Reference implementation
└── README.md               # This file

Configuration System

Users can customize Krayt via ~/.config/krayt/:

~/.config/krayt/
├── config.yaml             # Main configuration
├── templates/              # Custom templates
│   ├── custom.sh           # Custom setup script
│   └── production.sh       # Environment-specific templates
├── packages/               # Custom package definitions
│   ├── dev-tools.yaml      # Custom tool bundles
│   └── company-tools.yaml  # Organization-specific tools
└── init.d/                 # Initialization scripts
    ├── 00-proxy.sh         # Proxy setup
    ├── 10-company-tools.sh # Company tool installation
    └── 99-personal.sh      # Personal customizations

Configuration Example

# ~/.config/krayt/config.yaml
default_base_image: "alpine"  # or "archlinux"

base_images:
  alpine:
    image: "alpine:latest"
    package_manager: "apk"
    init_script: "alpine.sh"
  
  archlinux:
    image: "archlinux:latest"
    package_manager: "pacman"
    init_script: "arch.sh"

tool_bundles:
  web:
    - nodejs
    - npm
    - yarn
  
  python:
    - python3
    - pip
    - uv
    - python-dev
  
  database:
    - postgresql-client
    - mysql-client
    - redis-tools

defaults:
  always_include: ["git", "curl", "vim"]
  shell: "/bin/bash"
  persistence:
    ttl_seconds: 86400  # 24 hours
    cleanup_on_exit: false

Base Images

Alpine Linux (Default)

• Lightweight, secure, fast startup
• APK package manager
• Ideal for minimal environments
• Good for CI/CD and automated tasks

Arch Linux

• Rolling release, always latest packages
• Pacman package manager
• Excellent AUR support
• Great for development with latest tools

Package Management

Krayt supports installing tools via multiple package managers:

# System packages (apk, pacman, apt, dnf, yum)
krayt create --with-packages git,vim,htop my-pod

# Package bundles (predefined groups)
krayt create --with-bundles web,database my-pod

# Language-specific tools
krayt create --with-tools nodejs,python3,go my-pod

# GitHub releases (via jpillora installer or eget)
krayt create --with-github cli/cli my-pod
krayt create --with-github github/copilot-cli my-pod

# Custom installation commands
krayt create --with-install "curl -fsSL https://example.com/install.sh | sh" my-pod

Tool Installation

Krayt provides flexible tool installation options:

Minimal Setup (Default)

Fast, lightweight environments with only essential tools:

# Minimal standalone (6 packages)
krayt create --standalone --apply my-pod

# Includes: curl, wget, git, vim, bash, starship + user's shell

Full Setup (Optional)

Comprehensive development environments with extensive tools:

# Full standalone (33+ packages)  
krayt create --standalone --full-tools --apply my-pod

# Includes: All minimal tools + extended + specialized tools

Custom Tools

Install specific tools via mise:

# Custom mise tools
krayt create --with-tools k9s,uv,node@20 my-pod

Tool Categories

Minimal Essential (default):

• curl, wget, git, vim, bash, starship
• User's preferred shell (zsh, fish) automatically detected and installed

Extended Tools (--full-tools):

• File & Navigation: eza, fd, fzf, ripgrep, bat
• System Monitoring: htop, bottom, dust, ncdu
• Shell Enhancements: zsh, fish, neovim
• Text Processing: jq, yq, file, hexyl

Specialized Tools (--full-tools):

• Network Tools: nmap, mtr, bind-tools, iperf3, netcat
• Database Clients: postgresql-client, mysql-client, sqlite

Smart Features

• Shell Detection: Automatically detects user's shell and installs it
• Smart Enter: Detects available shells and chooses best option
• Consistent Experience: Starship prompt always included
• Backward Compatible: Existing behavior preserved with --full-tools

Reusable Module Design

The core functionality is designed to be reusable in other projects:

from krayt import KraytInspector

# Use as a module
inspector = KraytInspector()

# Clone a pod
job = inspector.create_inspector(
    pod_name="my-app",
    namespace="default",
    base_image="archlinux",
    tools=["git", "python3", "nodejs"]
)

# Apply to cluster
job.apply()

# Connect to inspector
inspector.connect(job.name, job.namespace)

Use cases for the module:

• CI/CD pipelines that need to debug storage issues
• Automated testing environments
• Development tooling that needs pod access
• Monitoring and debugging tools

Development Phases

Phase 1: Core Foundation (MVP)

• Extract and clean up core functionality from krayt1.py
• Implement basic create, enter, list, delete, clean commands
• Add Alpine Linux support with basic tool installation
• Implement configuration system basics
• Add proper packaging and installation

Phase 2: Enhanced Features

• Add Arch Linux support
• Port comprehensive tool installation from test.sh
• Implement package bundles and tool management
• Add export/import functionality
• Enhance configuration system with templates

Phase 3: Advanced Features

• Multi-pod workspace support (if needed)
• Advanced networking features
• Plugin system for custom tools
• Performance optimizations
• Extended documentation and examples
• GitHub releases tool installation (jpillora installer/eget)
• Tool versioning and updates

Testing Strategy

• Unit Tests: Core Kubernetes operations
• Integration Tests: Real cluster testing with kind/minikube
• Manual Testing: User experience validation
• Performance Tests: Large-scale pod inspection

Success Metrics

1. Ease of Use: Users can create and enter environments in <30 seconds
2. Feature Parity: All functionality from krayt1.py preserved
3. Extensibility: Easy to add new base images and tools
4. Reliability: Robust error handling and cleanup
5. Performance: Fast pod creation and connection times

Migration Path

For existing krayt1.py users:

1. Install new krayt alongside krayt1.py
2. Gradually migrate workflows
3. Deprecate krayt1.py after feature parity is achieved
4. Provide migration guide and breaking changes documentation

---

Goal: Create a robust, extensible, and user-friendly tool that makes Kubernetes development environments as easy to use as local development environments.