Image description

https://github.com/sanspareilsmyn/kforward

Hello community! 👋

If you're developing applications that interact with services running inside a Kubernetes cluster, you've probably felt the pain. Managing countless kubectl port-forward sessions in separate terminals? Trying to remember which local port maps to which service? Hardcoding localhost:PORT in your configs, only to change it back for deployment? It's a frustrating, error-prone dance.

That's why I built kforward!

kforward is a lightweight, single-binary Go CLI tool designed to streamline your local development workflow against Kubernetes. It acts as a local HTTP proxy that automatically manages kubectl port-forward processes for you.

🤔 The Pain Points kforward Solves

  • Tedious Port-Forwarding: Opening a new terminal for every single service you need access to? It's messy, easy to forget one, and doesn't scale as your app grows.
  • Configuration Chaos: Littering your local development config files with localhost:3001, localhost:9200, localhost:5433 makes them differ significantly from how your app actually runs in the cluster, leading to potential "works on my machine" issues.
  • Complexity Overkill: Tools offering deep integration (like network interception or file mirroring) are awesome but can be complex to set up or might be more than you need if you just want to talk to your backend API or database service.

✨ Enter kforward: Simplicity First

kforward takes a simpler approach.

  • 🚀 Simple & Reliable: It provides a standard HTTP/HTTPS proxy on your local machine. Under the hood, it intelligently uses the battle-tested kubectl port-forward for the actual tunneling.
  • 🤖 kubectl Automation: Point kforward at a specific service (namespace/service-name) or an entire namespace, and it automatically finds ready pods and starts/manages the required kubectl port-forward processes in the background. No more manual juggling!
  • 📦 Single Go Binary: Easy to install and run. Just make sure you have kubectl installed and in your PATH (kforward uses it!).
  • 🌐 Use Native Service Names: This is the magic! Configure your local app (or just your terminal session) to use the kforward proxy. Now you can use standard Kubernetes service DNS names like http://my-api.my-namespace.svc.cluster.local:8080 directly in your code or tools like curl, just like you would inside the cluster.

🏗️ How Does It Work? (The Gist)

kforward runs as a local process that you start from your terminal.

  1. It reads your kubeconfig (or uses the context you specify) to talk to your K8s cluster using client-go.
  2. Based on the services or namespace you target, it figures out which ports need forwarding.
  3. It launches kubectl port-forward commands in the background for each required target, mapping them to available local ports (like localhost:10001, localhost:10002, etc.). It keeps track of this mapping.
  4. It starts a local HTTP/HTTPS proxy (defaulting to localhost:1080).
  5. You configure your local application or terminal environment to use this proxy (e.g., export http_proxy=http://localhost:1080).
  6. When your app makes a request to http://my-service.default.svc.cluster.local, the request hits the kforward proxy.
  7. The proxy identifies the target (my-service.default) and looks up the corresponding local port (e.g., 10001) managed by a background kubectl process.
  8. The proxy forwards the request to localhost:10001, which the kubectl process tunnels securely to the actual pod in your cluster.

Here's a simplified view:

Image description

🙌 Get Involved!

kforward is open source and built to solve a common developer pain point. Give it a try and see if it simplifies your Kubernetes development workflow!

  • Check out the code, detailed architecture, and contribute on GitHub: [Link to your GitHub Repo]
  • Found it useful? Star the repo! ⭐
  • Feedback & Ideas: Open an issue or join the discussion!

Let me know what you think in the comments! How do you currently handle local development against Kubernetes services?