k4wd

README

K4wd

kubectl port-forward on steroids

Work in Progress! Docs are incomplete and this tool is not properly tested yet

Purpose

K4wd allows to make multiple Resources in a Kubernetes cluster available locally for development and debugging purposes in a pleasant way.

Quickstart / Demo

• Install k4wd, e.g.:

go install github.com/tmsmr/k4wd@latest

• Have some Services deployed, e.g.:

cd docs
kubectl apply -f example.yaml

• Write a Forwardfile, e.g.:

relaxed = true

[forwards.upstream-a]
service = "upstream-a"
namespace = "k4wd"
remote = "http-alt"
local = "8080"

[forwards.upstream-b]
service = "upstream-b"
namespace = "k4wd"
remote = "8080"
local = "0.0.0.0:8081"

[forwards.upstream-c]
service = "upstream-c"
namespace = "k4wd"
remote = "http-alt"

• Start k4wd, e.g.:

$ k4wd
INFO[0000] loaded Forwardfile (relaxed=true) containing 3 entries: (upstream-b, upstream-c, upstream-a) 
INFO[0000] created Kubeclient for https://127.0.0.1:6443 (/home/thomas/.kube/config) 
INFO[0000] initialized Envfile for /tmp/k4wd_env_9c2bed59bac37ab739fca89c25e8cddfc25dd0568537c7c864751d3948962afb 
Forwarding from 127.0.0.1:8080 -> 1234
INFO[0000] upstream-a ready: 127.0.0.1:8080 -> k4wd, upstream-a-5bcdb8b947-m2f9z, 1234 
Forwarding from 0.0.0.0:8081 -> 1234
INFO[0000] upstream-b ready: 0.0.0.0:8081 -> k4wd, upstream-b-577855f5c7-frwjm, 1234 
Forwarding from 127.0.0.1:57079 -> 1234
INFO[0000] upstream-c ready: 127.0.0.1:57079 -> k4wd, upstream-c-6c658678ff-w6cf2, 1234 

Note that for upstream-c a random free port was assigned, since no value is defined in the Forwardfile

• (Optional) Get a new shell in the same context and request the active forwards as env variables, e.g.:

$ k4wd -e
export UPSTREAM_A_ADDR=127.0.0.1:8080
export UPSTREAM_B_ADDR=0.0.0.0:8081
export UPSTREAM_C_ADDR=127.0.0.1:53058

• (Optional) Get the env variables in different formats, e.g.:

$ k4wd -e -o json
[
    {
        "addr": "UPSTREAM_A_ADDR",
        "value": "127.0.0.1:8080"
    },
    {
        "addr": "UPSTREAM_B_ADDR",
        "value": "0.0.0.0:8081"
    },
    {
        "addr": "UPSTREAM_C_ADDR",
        "value": "127.0.0.1:53058"
    }
]

• (Optional) Or write the env variables to a file, e.g.:

$ k4wd -e > .env

• Access the upstream services, e.g.:

$ . .env && curl $UPSTREAM_A_ADDR -I
HTTP/1.0 200 OK
Server: SimpleHTTP/0.6 Python/3.12.1
Date: Sat, 13 Jan 2024 14:55:28 GMT
Content-type: text/html; charset=utf-8
Content-Length: 840

• Stop the k4wd process
• Clean up, e.g.:

kubectl delete -f example.yaml