KubePi: a multi-cluster Kubernetes panel from the 1Panel team

What KubePi solves, and who ends up using it

kubectl scales badly as a sharing mechanism. The moment two teams need access to the same cluster, someone starts writing kubeconfig files by hand and hoping the RBAC rules match what was agreed. KubePi takes the position that cluster access should be a product feature: an administrator imports clusters once, then assigns permissions over specific clusters and namespaces to named users. Developers get a UI for the applications already running in those namespaces, plus troubleshooting views, instead of a terminal and a context switch. The README frames the split explicitly: administrators import multiple Kubernetes clusters and distribute cluster and namespace permissions; developers manage and troubleshoot running applications. That two-role model is the whole point. If you are a solo operator with one cluster and a working kubeconfig, KubePi is an extra service to run and patch. It earns its place when the number of people who need cluster visibility is larger than the number of people you trust with a kubeconfig.

How KubePi talks to your clusters

The repository layout tells you most of the architecture. There is a Go server under cmd/ and internal/, a web/ directory holding three separate frontends (web/kubepi, web/dashboard, web/terminal), and a thirdparty/gotty directory. The Makefile builds each of those frontends with npm and compiles the server into a single binary named kubepi-server, with gotty built alongside it. That gotty binary is what backs the in-browser terminal; it is a separate Go program rather than a websocket handler inside the main server. Cluster access goes through the official Kubernetes client libraries: go.mod pins k8s.io/client-go v0.36.2, k8s.io/api, k8s.io/apimachinery, k8s.io/kubectl and k8s.io/cli-runtime at the same version, and pulls in helm.sh/helm/v3 v3.21.1 for chart work. Local state lives in Storm (github.com/asdine/storm/v3), a BoltDB-backed store, which is why the container needs a writable volume and why the README's run command passes --privileged. Authentication is not homegrown: the dependency list includes go-oidc/v3, crewjam/saml, go-ldap/v3, xlzd/gotp for TOTP and skip2/go-qrcode, so OIDC, SAML, LDAP and two-factor codes are all first-class. The web layer is Iris (kataras/iris/v12). One consequence worth noting: because the server speaks to clusters through client-go, the Kubernetes version floor is set by those libraries, not by anything KubePi adds.

Installing KubePi and importing your first cluster

The README gives a single docker run command, and it is the fastest path. Note the --privileged flag and the port mapping, both copied verbatim from the README.

docker run --privileged -d --restart=unless-stopped -p 80:80 1panel/kubepi

The README states the default credentials are admin / kubepi. Change them before anything else touches the instance; a panel with cluster credentials behind a default password is the worst version of this tool. If you already run 1Panel, the README points to the 1Panel app store as an alternative deployment route, which avoids managing the container by hand. Building from source is a three-target affair because the frontends are separate npm projects. The Makefile exposes them individually and as a group:

make build_web
make build_gotty
make build_bin

build_web runs npm install and npm run-script build in each of the three web directories; build_gotty compiles thirdparty/gotty; build_bin produces dist/usr/local/bin/kubepi-server. The Dockerfile does the same work in stages and then, in the final alpine image, downloads kubectl v1.36.2 and a kubectl-aliases tarball, which is a hint about how the terminal is expected to be used. The README sends you to the GitHub wiki for actual usage documentation, not to anything in the repository, so plan on reading the wiki before you hand the UI to a team.

The Kubernetes version floor is the sharpest edge

KubePi v2.0.0 is built with Go 1.26 and Kubernetes client-go v0.36, and the README states the minimum supported Kubernetes version is v1.24, with v1.34 to v1.36 recommended. Kubernetes v1.23 and earlier are explicitly out of scope for v2.0.0. That is a real migration constraint, not a footnote: if you are maintaining an older cluster because an in-house controller has not been updated, KubePi v2 is not the dashboard for it. The PodSecurityPolicy note is the more interesting one. PSP was removed in Kubernetes v1.25, and the README says KubePi only shows the related entry when the target cluster still serves the policy/v1beta1 API. That is a sensible conditional, but it also means the UI differs between clusters you have imported, and any internal documentation you write about "where the PSP page is" will be wrong on newer clusters. Version drift across a fleet is the normal case, and KubePi surfaces it in the interface rather than hiding it.

Licence terms that affect how you ship it

The repository is under the FIT2CLOUD Open Source License, which the README describes as essentially GPLv3 with additional restrictions. Two restrictions are spelled out: you may not replace or modify KubePi's logo and copyright information, and derivative works must comply with GPLv3's open source obligations. The GitHub licence field reports NOASSERTION, which is what you would expect for a modified GPLv3 rather than an SPDX-listed identifier. For internal use this changes little. For anyone planning to embed KubePi in a product, white-label it, or ship it to customers, the logo clause is the one to read carefully, and the README provides [email protected] for commercial licensing. This is not legal advice; if your distribution plans touch the branding clause, get counsel to read the LICENSE file rather than the README summary.

How KubePi compares to Kuboard and K8m

The obvious alternatives people search alongside KubePi are Kuboard, K8m, Kubewall and Rainbond, and the difference that matters is where the panel sits in your access model. Kuboard is also a Kubernetes management UI with a strong focus on workload visualization and multi-cluster views, but it is a separate product with its own deployment and its own permission model; choosing between them is mostly about which UI your operators already know. K8m, judging by the name and the search pattern, is a lighter-weight console in the same family, and Kubewall is another dashboard option. Rainbond goes further and positions itself as an application platform on top of Kubernetes, so it is not really a peer: it wants to own how applications are defined and released, whereas KubePi deliberately stays a view and control surface over clusters you already run. The distinguishing fact for KubePi is its lineage: it is built by the 1Panel team, and the README lists it alongside 1Panel, JumpServer, MaxKB, DataEase and MeterSphere. If you already run 1Panel, the app store deployment and the shared operational assumptions are the practical reason to pick KubePi over the others.

Maintenance cadence and what upgrading costs

The last push to the default branch was on 2026-08-18, and the most recent release, v2.0.3, is dated the same day. Before that, v2.0.2 landed on 2026-08-10 and v2.0.1 on 2026-08-03, so the v2.0.x line has been moving in weekly steps. The repository is not archived. The upgrade cost is mostly the version floor described above: because the server is compiled against client-go v0.36 and the README ties v2.0.0 to Kubernetes v1.24 and later, raising KubePi's version can raise the minimum cluster version you must support. The Dockerfile also pins kubectl v1.36.2 inside the image, so the terminal's kubectl version is tied to the panel release rather than to whatever is on your workstation. Upgrades are container image swaps in the common case, but the Storm database backing local state lives in the container's writable layer, which is why the README's run command uses --privileged and why you should decide on a persistent volume before you have data worth keeping. The README does not document a rollback procedure, so treat the volume as the thing to back up.

Editorial conclusion

Adopt KubePi if you run several clusters and want a browser UI for application troubleshooting plus per-namespace permission handoff, and if the FIT2CLOUD Open Source License terms (GPLv3 plus logo and copyright restrictions) suit your distribution plans. Do not adopt it if you are still on Kubernetes v1.23 or earlier, since v2.0.0 dropped that range, or if you need a dashboard whose branding you can change. Before rolling it out, verify your target cluster versions against the v1.24 minimum and the v1.34 to v1.36 recommendation, and confirm whether your clusters still expose policy/v1beta1 if you rely on PodSecurityPolicy entries in the UI.

Frequently asked questions

Official sources

1. 1Panel-dev/KubePi on GitHub
2. Issues
3. Project website
4. README
5. Releases