kpf 0.1.9

A terminal utility to run kubectl port-forward and automatically restart it when endpoint changes are detected

kpf - A better way to port-forward with kubectl

This is a Python utility that (attempts) to dramatically improve the experience of port-forwarding with kubectl.

Primary features: Interactive service selection with colored tables and support for multiple Kubernetes resource types. Automatically restarts port-forwards when endpoint changes are detected. Normally (without this tool), this is a terrible experience with the port-forward cli only updating after you switch to a browser and attempt to connect.

Features

• 🔄 Automatic Restart: Monitors endpoint changes and restarts port-forward automatically
• 🎯 Interactive Selection: Choose services with a colorful, intuitive interface
• 🌈 Color-coded Status: Green for services with endpoints, red for those without
• 🔍 Multi-resource Support: Services, pods, deployments, and more
• 📊 Rich Tables: Beautiful formatted output with port information
• 🏷️ Namespace Aware: Work with specific namespaces or across all namespaces

Installation

Note: oh-my-zsh kubectl plugin will conflict with this kpf command. If you prefer this tool, you can alias at the bottom of your ~/.zshrc file or use a different alias.

If you have uv installed, you can "install" kpf with:

alias kpf="uvx kpf"

Install uv with pipx:

pipx install uv

Usage

Interactive Mode (Recommended)

Warm Tip: You can use the interactive mode to find the service you want, and the command to connect to that service directly next time is output just before the connection is established.

Select services interactively with a colored table:

# Interactive selection in current namespace
kpf --prompt

# or just:
kpf -p

# Interactive selection in specific namespace
kpf --prompt -n production

# or just:
kpf -p -n production

# Show all services across all namespaces
kpf --all

# Include pods and deployments with ports defined
kpf --all-ports

Check Mode

Add endpoint status checking to service selection (slower but shows endpoint health):

# Interactive selection with endpoint status
kpf --prompt --check

# Show all services with endpoint status
kpf --all --check

# Include pods and deployments with status
kpf --all-ports --check

Legacy Mode

Direct port-forward (backward compatible):

# Traditional kubectl port-forward syntax
kpf svc/frontend 8080:8080 -n production
kpf pod/my-pod 3000:3000

Command Options

There is no default command. You must specify one of the arguments below.
You could alias kpf to -p to use interactive mode by default if you prefer.

Example of this in your ~/.zshrc:

alias kpf='uvx kpf -p'

Example usage:
  kpf svc/frontend 8080:8080 -n production      # Direct port-forward (backwards compatible with kpf alias)
  kpf --prompt (or -p)                          # Interactive service selection
  kpf --prompt -n production                    # Interactive selection in specific namespace
  kpf --all (or -A)                             # Show all services across all namespaces
  kpf --all-ports (or -l)                       # Show all services with their ports
  kpf --prompt --check -n production            # Interactive selection with endpoint status

Examples

Interactive Service Selection

Fast mode (without endpoint checking):

$ kpf --prompt -n kube-system

Services in namespace: kube-system

#    Type     Name                    Ports
1    SERVICE  kube-dns               53, 9153
2    SERVICE  metrics-server         443
3    SERVICE  kubernetes-dashboard   443

Select a service [1]: 1
Local port (press Enter for 53): 5353

With endpoint status checking:

$ kpf --prompt --check -n kube-system

Services in namespace: kube-system

#    Type     Name                    Ports           Status
1    SERVICE  kube-dns               53, 9153         ✓
2    SERVICE  metrics-server         443              ✓
3    SERVICE  kubernetes-dashboard   443              ✗

✓ = Has endpoints  ✗ = No endpoints

Select a service [1]: 1
Local port (press Enter for 53): 5353

Cross-Namespace Discovery

$ kpf --all

Services across all namespaces

#    Namespace    Type     Name           Ports        Status
1    default      SERVICE  kubernetes     443          ✓
2    kube-system  SERVICE  kube-dns      53, 9153     ✓
3    production   SERVICE  frontend      80, 443      ✓
4    production   SERVICE  backend       8080         ✗

How It Works

1. Port-Forward Thread: Runs kubectl port-forward in a separate thread
2. Endpoint Watcher: Monitors endpoint changes using kubectl get ep -w
3. Automatic Restart: When endpoints change, gracefully restarts the port-forward
4. Service Discovery: Uses kubectl to discover services and their endpoint status

Requirements

• Python 3.8+
• kubectl configured with cluster access
• Rich library for colored output

Development

Setup Development Environment

# Clone the repository
git clone https://github.com/jessegoodier/kpf.git
cd kpf

# Install with development dependencies
uv venv
uv pip install -e ".[dev]"
source .venv/bin/activate

Code Quality Tools

# Format and lint code
uvx ruff check . --fix
uvx ruff format .

# Sort imports
uvx isort .

# Run tests
uv run pytest

# Bump version
uvx bump-my-version bump patch --allow-dirty --no-commit  --no-tag

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linting
5. Submit a pull request

License

MIT License - see LICENSE file for details.