Kubermatic: a control plane for thousands of Kubernetes clusters

The problem is many clusters, not one

Kubermatic Kubernetes Platform is described as an open source project to centrally manage the global automation of thousands of Kubernetes clusters across multicloud, on-premises and edge, with what the description calls unparalleled density and resilience.

The word centrally is the whole point. A team that runs clusters in AWS, in a bare metal data centre, and at an edge site has three different credential models, three different upgrade procedures, and three different failure modes. The cost is not the clusters, it is the operational surface area of keeping them all in the same mental model. KKP is a control plane that puts one API in front of that spread.

The primary language is Go, the module path is k8c.io/kubermatic/v2, and the code targets Go 1.27.1. The repository is not archived, the last push was on 2026-10-15, and three release branches were published on 2026-10-09 alone, v2.31.2, v2.30.8, and v2.29.13, which is the signature of a project that maintains several supported lines in parallel.

The homepage is kubermatic.com, and the documentation lives at docs.kubermatic.com, with a version selector at the top of the site so that you read the docs matching the version you run.

Two editions, and where the line sits

The edition structure is stated plainly and it is the first thing to check.

Kubermatic Kubernetes Platform Community Edition is available freely under the Apache License, Version 2.0. Kubermatic Kubernetes Platform Enterprise Edition includes premium features that are most useful for organizations with large-scale Kubernetes installations with more than 50 clusters, and to access it and get official support you have to become a subscriber.

That threshold is a useful signal about who the project is for. If you have fewer than fifty clusters, the Community Edition is the intended path, and the premium features are described as the things that only start to matter at that scale. If you are above it, you are in the audience the Enterprise Edition was designed for.

The licence distinction is worth stating carefully, because the repository metadata reports a custom licence that GitHub cannot classify, and the README says to see the LICENSE file for licensing information as it pertains to files in this repository. The Apache 2.0 statement in the editions section describes the Community Edition as a distribution, while the file-level terms in the repository are what govern the code you actually read. There is also a NOTICE file at the top level, which is the conventional companion to an Apache licence.

The build configuration makes the edition concrete in a different way. The Makefile sets KUBERMATIC_EDITION ?= ce, and the image repository name is derived from it, so a community build and an enterprise build produce differently named images in quay.io/kubermatic.

Seed clusters and user clusters, and how the controllers fit

The developer documentation reveals the architecture, and the key distinction is between the seed cluster and the user cluster.

The development section describes three controllers that can be run locally. The user-cluster-controller-manager is instrumented to allow for a local run by adding a worker-name label with your local machine's name as its value, and scaling down the already running deployment:

# Using a kubeconfig, which points to the seed-cluster
export cluster_id="<id-of-your-user-cluster>"
kubectl label cluster ${cluster_id} worker-name=$(uname -n)
kubectl scale deployment -n cluster-${cluster_id} usercluster-controller --replicas=0

After that the local controller manager is started with a script from the hack directory:

# Using a kubeconfig, which points to the seed-cluster
./hack/run-user-cluster-controller-manager.sh

The other two have their own scripts, ./hack/run-seed-controller-manager.sh and ./hack/run-master-controller-manager.sh.

The model is that user clusters are described as resources inside a seed cluster, which is itself a Kubernetes cluster. That gives you a uniform API over infrastructure that is not Kubernetes at all, because a user cluster might be an AWS EKS cluster, a bare metal cluster, or an edge site, and from the control plane's point of view they are all objects named cluster-something in a namespace named cluster-<id>. The namespace pattern in the scale command is the visible trace of that.

The seed controller then reconciles those objects against the real infrastructure, and the user cluster controller runs inside the user cluster to handle node level concerns. The master controller is the one that runs the platform itself, on the seed.

The repository layout and the container image

The repository layout is documented in the README, and it is a good map of the codebase.

├── addons    # Default Kubernetes addons
├── charts    # The Helm charts we use to deploy
├── cmd       # Various Kubermatic binaries for the controller-managers, operator etc.
├── codegen   # Helper programs to generate Go code and Helm charts
├── docs      # Some basic developer-oriented documentation
├── hack      # scripts for development and CI
└── pkg       # most of the actual codebase

The split between cmd/ and pkg/ is the Go convention, with cmd holding the binaries for the controller managers and the operator, and pkg holding the code. The top level also has a sdk/ directory, and the go.mod replaces k8c.io/kubermatic/sdk/v2 with the local ./sdk path, so the SDK is developed in the same tree rather than versioned separately.

The Dockerfile is worth reading for one specific reason. It ships multiple kubectl binaries, version 1.37, 1.36, 1.35, and 1.34, and the comment explains why: to support a wider range of Kubernetes userclusters, and the version is deduced from the version skew policy. In other words, one control plane binary talks to user clusters running several different Kubernetes versions, and it picks the right client for each. The image is built on alpine:3.24, installs Helm 3.19.0, and adds ca-certificates so the KKP API can verify the certificates of the OIDC server, usually Dex.

The Makefile shows the build conventions: CGO_ENABLED is 0 by default, GOFLAGS are -mod=readonly -trimpath, the build output goes to _build, and the ldflags stamp the git version, the container tag, and the UI container tag into the binary.

Working on the code: lint, test, and the code generation problem

The contributor workflow is three commands, and each one has a wrinkle worth knowing.

Before every push, you run the linter:

make lint

And the tests:

make test

The third is the interesting one. The Kubernetes code-generator tool does not work outside of GOPATH, with the upstream issue linked, so the script below automatically runs the code generation in a Docker container:

hack/update-codegen.sh

That is a workaround for a real upstream limitation, and it explains the codegen/ directory in the layout, which holds the helper programs that generate Go code and Helm charts. Running the generator inside a container means you do not need the Kubernetes toolchain installed locally, at the cost of a Docker daemon in your development loop.

The setup itself starts with a clone:

git clone [email protected]:kubermatic/kubermatic.git
cd kubermatic

Two things about the contribution rules are specific. CONTRIBUTING.md carries the instructions on the developer certificate of origin that the project requires, and there is a DCO file at the top level, so contributions are sign-off commits rather than a CLA. The repository also has an OWNERS file and an OWNERS_ALIASES file, which is the mechanism that assigns reviewers by team rather than by person.

The dependency list in go.mod is a useful map of what the platform talks to. There are Azure SDK packages for armcompute, armcontainerservice, armnetwork, and others, the AWS SDK v2, the Alibaba Cloud SDK, and a replace directive pinning the Nutanix prism-go-client to v0.4.0 because there is no way to test v0.5.1 without a working Nutanix environment. That comment is a small window into how many infrastructures one control plane has to speak to.

Against a managed cloud control plane, and against plain Terraform

The alternative for a multi-cluster operator is a managed service from a cloud provider, where EKS, GKE, or AKS gives you a hosted control plane and you manage node pools.

The difference in approach is the scope. A managed service is tied to one cloud, and its API is that cloud's API. KKP is infrastructure-neutral, and the point of the seed and user cluster model is that the same objects describe a cluster regardless of where it runs, including on-premises and at the edge, which is a segment managed services generally do not serve at all. For an organisation with a hybrid footprint, that neutrality is the reason to use it.

The other difference is where the control plane itself runs. A managed service runs in the provider's region and you pay for it per cluster. KKP runs in your own seed cluster, which is a Kubernetes cluster you already run, and the cost of the platform is the cost of that cluster. That is a real saving at scale, and it is a real operational responsibility too, since the control plane becomes something you have to keep upgraded and available.

The second alternative is to skip the platform and use infrastructure as code directly. Terraform or OpenTofu would create the clusters, and a configuration management tool would handle the add-ons. The difference is that IaC describes a cluster as a resource you create and then forget, while KKP keeps a running model of it that reconciles, upgrades, and reports on. If your clusters are static and created rarely, IaC is simpler and there is no reason to add a control plane. If you have hundreds of clusters that need upgrades and different versions of add-ons, the continuous model earns its cost.

The one warning the README gives applies to the other two as well. The code and sample YAML files in the main branch are under active development and are not guaranteed to be stable, and the project strongly recommends using an official release instead, with the installation instructions in the documentation.

Editorial conclusion

Adopt Kubermatic if you operate more than a handful of Kubernetes clusters across more than one infrastructure and need one control plane with a consistent API for all of them. Do not adopt it for a single cluster or a single cloud, since a managed offering will be simpler. Verify first which edition contains the features you need, because the Enterprise Edition is the one described as useful above fifty clusters and it is a paid subscription.

Frequently asked questions

Official sources

1. Issues
2. kubermatic/kubermatic on GitHub
3. Project website
4. README
5. Releases