Introducing Wakuwi

Wakuwi is an open source, lightweight, read-only web interface for exploring Kubernetes clusters. It runs locally, uses the contexts already present in your kubeconfig, and requires no additional configuration. Install it, run it, and point your browser at localhost. It can also be run in your Kubernetes cluster.

The name stands for:

Why Another KUbernetes Web Interface?

Which is a perfectly reasonable question.

It started with port forwarding

Wakuwi did not begin as an attempt to build a general Kubernetes interface.

The original motivation was much narrower: I wanted an easier way to create and manage port forwards.

I use kubectl port-forward regularly, and the command itself is straightforward enough. The awkwardness begins once you have several of them running. You need to remember which terminal owns which forward, which local port maps to which pod, whether the underlying pod still exists, and which process needs to be killed when you are finished.

I wanted a small interface that would let me find a workload, start a port forward, see what was currently running, and stop it again without hunting through terminal windows or process lists.

That was the project.

At first.

Once I could browse the cluster far enough to choose a pod, the obvious next question was why I should stop there. The application already knew about contexts, namespaces, and workloads. It was already talking to the Kubernetes API. Showing more resources was a natural extension.

Then came resource details, manifests, and descriptions. Then logs. Then search. Then links between related resources. Then a view highlighting issues across the cluster.

Somewhere along the way, the port-forwarding tool became a Kubernetes web interface.

Hence the name.

Why another Kubernetes interface?

There are already plenty of ways to interact with Kubernetes.

kubectl is excellent when I know what I am looking for and what I want to do with it. It is less convenient when I am exploring an unfamiliar cluster, moving between namespaces, comparing resources, following links between related objects, or trying to get a general sense of what is happening.

There are also several existing graphical interfaces, including some very capable ones. However, many are desktop applications, services that must be installed into the cluster, or considerably larger platforms than I need for everyday investigation.

Wakuwi grew into something that fitted a particular gap in how I work:

1. Run a command locally.
2. Open a browser.
3. Browse every cluster and namespace in my existing kubeconfig.
4. Create and manage port forwards without juggling terminal processes.
5. Avoid changing anything accidentally.

The port-forwarding problem remains part of its core purpose, but Wakuwi now also provides a convenient way to browse, search, and understand a cluster.

Running Wakuwi inside a cluster

Although Wakuwi was initially designed to run on a developer’s machine, it can also be deployed inside a Kubernetes cluster.

In this mode, Wakuwi automatically uses the pod’s service account rather than looking for a local kubeconfig. The interface skips context selection, and the resources it can display are determined by the Kubernetes permissions granted to that service account.

There is a small irony here: port forwarding, the feature that started the whole project, is disabled when Wakuwi is running inside a cluster. Local process management is disabled too. Both features depend on Wakuwi running on your own machine, so neither makes much sense from inside a pod.

The rest of the interface remains useful, however. An in-cluster deployment provides a lightweight, browser-based way to explore resources, inspect manifests, follow logs, search the cluster, and identify common problems. It can be particularly useful when you want to make Wakuwi available to a team without requiring everyone to install it locally, and, with a suitably secure ingress configuration, they can share URLs to specific resources and views.

The repository includes a deployment manifest containing a Namespace, a ServiceAccount, a read-only ClusterRole, a Deployment, and a ClusterIP Service:

kubectl apply -f deploy/wakuwi.yaml

The safest way to access it is then through kubectl port-forward:

kubectl -n wakuwi port-forward svc/wakuwi 9753:9753

You can then open Wakuwi at http://localhost:9753, just as you would when running the binary locally.

Wakuwi deliberately has no built-in authentication. The supplied manifest therefore exposes it only through a ClusterIP Service, which is not ordinarily accessible from outside the cluster. If you choose to expose Wakuwi through an Ingress, you must put an authentication layer in front of it, or make it reachable only via a VPN. Anyone who can reach the interface can see everything its service account is authorised to read.

Secrets remain hidden by default. Enabling them in an in-cluster deployment requires both the --show-secrets command-line flag and an explicit RBAC rule granting the service account permission to read them. The flag controls whether Wakuwi exposes them through its interface; Kubernetes RBAC remains the actual security boundary.

Running Wakuwi inside a cluster changes its emphasis slightly. Locally, it is partly a tool for managing interactions between your machine and Kubernetes. In-cluster, it becomes a small, read-only window into the cluster itself.

Screenshots

Meh!

No doubt that’s what most of you are thinking, but thanks for reading this far! I built Wakuwi to scratch a particular itch I had, and I’m publishing it in case it helps you with one of yours. Either way, peace, love, and cheesy biscuits.

Yes, it was built by Claude (Fable 5 in particular) as the developer, and me as product manager and code reviewer. No, I don’t apologise for it; this is one of the things it’s good at!

If you feel particularly moved by this project, feel free to raise issues, pull requests, all that good stuff.