kpf 0.3.0

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.

It is essentially a wrapper around kubectl port-forward that adds an interactive service selection with automatic reconnect when the pods are restarted or your network connection is interrupted (computer goes to sleep, etc).

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, etc.

Installation

Note: The oh-my-zsh kubectl plugin will conflict with this kpf command. You must unalias kpf before using this tool.

echo "unalias kpf" >> ~/.zshrc

Homebrew (Recommended)

brew tap jessegoodier/kpf
brew install kpf

Or install directly:

brew install jessegoodier/kpf/kpf

Using uv

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

alias kpf="uvx kpf"

Install uv with pipx (brew can be behind):

pipx install uv

Usage

Interactive Mode (Recommended)

Warm Tip: You can use the interactive mode to find the service you want, and it will output the command to connect to that service directly next time.

Note: You might think that "warm tip" is something that AI wrote, but that's not the case. It really is just a little bit cooler than a hot tip.

Select services interactively:

Interactive selection in current namespace:

kpf --prompt

Interactive selection in specific namespace:

kpf --prompt -n production

Show all services across all namespaces:

```bash
kpf --all

Include pods and deployments with ports defined:

kpf --all-ports

Combine a few options (interactive mode, all services, and endpoint status checking, debug mode):

kpf -pAdl

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 (maintain expected behavior):

# 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.

Example usage:
  kpf svc/frontend 8080:8080 -n production      # Direct port-forward (maintain expected behavior)
  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
  kpf --prompt -0                               # Listen on 0.0.0.0 (all interfaces)

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

• kubectl configured with cluster access

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

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.