Skip to content
tonisivesPublic

About

Kubernetes Port Forwarding app

Resources

Stars

11 stars

Watchers

0 watching

Forks

Repository files navigation

Easy KPF - Kubernetes Port Forward Manager

A tool for managing Kubernetes port forwarding. Available as both a GUI desktop app and a TUI terminal app with feature parity.

GUI (Desktop) TUI (Terminal)
EasyKpf desktop app TUI Demo

Features

  • Visual port forwarding management
  • Support for multiple Kubernetes contexts
  • Real-time status monitoring
  • Persistent configuration storage
  • Context grouping with collapsible sections
  • Persistent group collapse state and drag reordering
  • Connection health verification and one-click reconnect
  • SSH port forwarding support
  • Local interface selection: 127.0.0.{x}
  • Auto-suggest names based on service/context
  • Search and filter configs
  • Shared configuration between GUI and TUI
GUI TUI
GUI Main View TUI Main View
GUI Configuration TUI Add Config
GUI Port Forwards TUI Visual Select

Requirements

  • kubectl installed and configured
  • At least one Kubernetes context configured

Installation

Built with Tauri (Rust + React). Cross-platform support for macOS, Windows, and Linux.

GUI App - macOS (Homebrew)

brew install --cask tonisives/tap/easy-kpf

CLI/TUI - macOS/Linux (Homebrew)

brew install tonisives/tap/easykpf

Manual Download

Download the latest build from Releases, or build yourself!

Development

pnpm install
make dev

Build

pnpm tauri build

Release

Create the next patch release and start the GitHub Actions release workflow:

make release

To choose an explicit version instead:

make release VERSION=0.4.0

Releases must be started from a clean main branch that matches origin/main.

Configuration

Port forward configurations are stored in YAML files in the system config directory:

  • macOS: ~/Library/Application Support/EasyKpf/
  • Linux: ~/.config/EasyKpf/
  • Windows: %APPDATA%/EasyKpf/

Configuration Files

  • port-forwards.yaml - Port forward definitions
  • app-config.yaml - Application settings (kubectl path, kubeconfig path)

Port Forward Configuration Structure

configs:
  - name: "My Service"
    context: "minikube"
    namespace: "default"
    service: "my-service"
    ports: ["8080:80", "9090:9090"]

Configuration files are automatically created with defaults on first run.

Automatic reconnect and lifecycle hooks

EasyKpf automatically replaces a failed forward with exponential backoff. A forward is considered recovered after the replacement process remains alive for the configured stability period. Explicitly stopping a forward cancels pending reconnect attempts.

Recovery can be shared by Kubernetes context or SSH host, then overridden for an individual forward. The lookup order is:

  1. The forward's own recovery
  2. Its entry under recovery.kubernetes_contexts or recovery.ssh_hosts
  3. Built-in reconnect defaults

For example:

recovery:
  kubernetes_contexts:
    tgs:
      reconnect:
        enabled: true
        initial_delay_ms: 1000
        max_delay_ms: 30000
        stable_after_seconds: 30
        max_attempts: 0
      hooks:
        before_reconnect:
          - type: command
            command: /bin/launchctl
            args:
              - kickstart
              - -k
              - gui/501/com.example.kubernetes-tunnel
            timeout_seconds: 15
            cooldown_seconds: 30

  ssh_hosts:
    job-host:
      reconnect:
        enabled: true
      hooks:
        before_reconnect:
          - type: ssh
            ssh_host: bastion
            command: sudo systemctl restart job-tunnel
            args: []

configs:
  - name: db gp
    context: tgs
    namespace: infra
    service: postgres-gp-1-cluster-rw
    ports: ["8101:5432"]

  - name: job service
    context: job-host
    namespace: default
    service: job-host
    ports: ["8102:8080"]
    forward_type: Ssh

  - name: special job
    context: job-host
    namespace: default
    service: job-host
    ports: ["8103:8080"]
    forward_type: Ssh
    recovery:
      reconnect:
        enabled: true
      hooks:
        before_reconnect:
          - type: ssh
            ssh_host: bastion
            command: sudo systemctl restart special-job-tunnel
            args: []

The built-in defaults retry indefinitely (max_attempts: 0), starting after one second and backing off to 30 seconds. Local hooks are executed directly as a command and argument list; EasyKpf does not evaluate them through a shell. SSH hooks run the configured command on their forward's ssh_host in batch mode. Cooldowns deduplicate identical hooks, which prevents several forwards that share one upstream tunnel from restarting it repeatedly.

Local hook processes receive these environment variables:

  • EASY_KPF_EVENT: failure, before_reconnect, or recovered
  • EASY_KPF_SERVICE: the configured forward name
  • EASY_KPF_ERROR: the error that initiated or most recently blocked recovery
  • EASY_KPF_ATTEMPT: the current reconnect attempt number

on_failure runs once when a managed forward fails. before_reconnect runs before each reconnect attempt. on_recovered runs after the replacement survives stable_after_seconds.

Each Kubernetes context and SSH host group has a Recovery action for its shared policy. Each forward's Settings dialog has another Recovery action for an exception. Additional lifecycle hooks can be added directly to YAML and are preserved when the UI saves a forward or shared policy.

A macOS recovery script for a launch agent can be as small as:

#!/bin/sh
exec /bin/launchctl kickstart -k "gui/$(id -u)/com.example.kubernetes-tunnel"

Technology

  • Frontend: React + TypeScript + Vite
  • Backend: Rust + Tauri
  • Kubernetes integration via kubectl

About

Kubernetes Port Forwarding app

Resources

Stars

11 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages