# Kuma: a multi-zone service mesh for Kubernetes and VMs, built on Envoy

> Kuma is a CNCF Sandbox service mesh that runs one control plane across Kubernetes and virtual machines, with Envoy as the data plane. It is a good fit when you have both worlds; it is heavier than you need if you only run one cluster.

**kumahq/kuma** — 🐻 The multi-zone service mesh for containers, Kubernetes and VMs. Built with Envoy. CNCF Sandbox Project.

- Repository: https://github.com/kumahq/kuma
- Website: https://kuma.io/install
- Stars: 4,012 · Forks: 371
- Language: Go
- License: Apache-2.0
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/kumahq-kuma

## The problem Kuma solves: one mesh across Kubernetes and VMs

Most service meshes assume every workload lives in Kubernetes. Kuma does not. The README describes it as a service mesh that can run "on every cloud, in a single or multi-zone capacity, across both Kubernetes and VMs", with native support for Envoy as the data plane proxy technology but, in its words, "with no Envoy expertise required".

That last clause is the actual product claim. Envoy is a capable L4/L7 proxy and a painful thing to configure by hand. Kuma takes the position that you should describe intent in mesh policies and let the control plane translate that into Envoy configuration, bootstrap the proxies, and rotate their certificates. The target user is a platform team that already has a mixed estate: some services on Kubernetes, some on VMs or bare metal, and no appetite for running two separate connectivity stacks.

The README also states that Kuma is a CNCF Sandbox project, originally created and donated by Kong. That matters for procurement more than for engineering: the governance sits with the foundation, while the commercial support path runs through Kong's enterprise offerings, which the README links to. Those are two different things and it is worth being clear about which one you are relying on.

## How Kuma works: control plane, Envoy data plane, and zones

The architecture has two halves. The control plane is a distributed component that can run on Kubernetes or on a VM, and it holds the mesh configuration. The data plane is Envoy, injected automatically as a sidecar on Kubernetes, with the README describing "Easy YAML specification for VM and Bare Metal deployments" for workloads outside the cluster. Policies are authored once and the control plane propagates them.

The multi-zone model is where the design gets interesting. A deployment has a global control plane and remote control planes. The README says the multi-zone and multi-cluster support comes with "automatic policy synchronization and connectivity", so a policy written at the global level reaches the zones without per-zone duplication. The repository layout reflects this split: there are api/, app/ and pkg/ directories at the top level, with deployments/ holding the packaging, and the Go module path is github.com/kumahq/kuma/v3.

The second axis is multi-mesh. Kuma can run several isolated meshes on one control plane, which the README frames as lowering operations cost. That is a real distinction from a one-mesh-per-cluster model: tenancy is a mesh boundary rather than a cluster boundary, so you can separate teams without standing up new infrastructure for each. The cost is that mesh boundaries become something you have to reason about when debugging connectivity, because a service in mesh A does not simply see a service in mesh B.

On the security side, the README lists automatic mTLS issuing and identity with optional third-party CA support, automatic certificate rotation for all data planes with configurable settings, and MeshTrafficPermission for firewalling traffic between services. Traffic control is expressed through MeshHTTPRoute and MeshTCPRoute for blue/green, canary, versioning and rollback deployments, and MeshFaultInjection for testing how services behave when a dependency misbehaves.

## Installing Kuma and running a first mesh

The README does not carry install commands inline. It points to two places: the installation page at kuma.io/install, and a Kubernetes quickstart at kuma.io/docs/latest/quickstart/kubernetes-demo/. It also lists a Helm chart and Docker images under the kumahq organisation on Docker Hub, and packages on Artifact Hub and Cloudsmith. So the honest answer to "how do I install it" is: follow the quickstart, not this article.

What the repository does tell you is how the project is built and tested. The Makefile includes mk/kind.mk and mk/k3d.mk, so local development environments are spun up with kind and k3d, and mk/helm.mk covers chart work. If you are evaluating Kuma, the quickstart is the faster path; if you are contributing, the Makefile targets are the entry point.

Once a control plane is running, the unit of configuration is a mesh policy. The README names MeshTrafficPermission, MeshHTTPRoute, MeshTCPRoute and MeshFaultInjection as the built-in policy types. A minimal first step after install is to confirm the control plane is reachable and then apply a traffic permission, because until you do, the zero-trust model means traffic between services is not implicitly allowed. The README describes MeshTrafficPermission as the mechanism "to firewall traffic between services with zero-trust security", which is a deliberate default: you opt services in rather than out.

For a VM workload, the README says the data plane is specified in YAML rather than injected. That is the practical difference between the two paths. On Kubernetes you add a label and the sidecar appears; on a VM you write and distribute a data plane definition, which means your configuration management has to own that file.

## Where Kuma is the wrong tool

The clearest limitation is scope. If every workload you run is in a single Kubernetes cluster, the multi-zone and VM support that Kuma is built around is unused weight. You are still running a control plane and a sidecar per pod, and you have taken on the operational surface of a mesh for connectivity you could get from a simpler in-cluster option.

Upgrades are the second constraint. The repository ships an UPGRADE.md file at the top level, which is a signal that version transitions need reading rather than assuming. The release list shows three maintained lines at once, v2.14.5, v2.13.11 and v2.12.15, all published within days of each other. Running three lines is normal for a project with enterprise consumers, but it means you have to decide deliberately which line you are on and when you move. Nothing in the README documents rollback, so if a policy change breaks connectivity in production, you should not assume an automated undo exists.

The third case is teams without Kubernetes or VM operations capacity. Kuma reduces the amount of connectivity code your services carry, but it does not remove the need to run and monitor infrastructure. A sidecar mesh adds a proxy to every request path, and when something is wrong you are debugging Envoy behaviour through the control plane's abstractions. The README's claim of "no Envoy expertise required" is about configuration, not about troubleshooting.

## Kuma compared with Istio

Istio is the obvious comparison, and the difference is not features so much as the deployment model. Istio is built around Kubernetes as the primary environment, with VM support available but secondary. Kuma treats Kubernetes and VMs as equal citizens on both the control plane and the data plane, per the README. If your estate is genuinely mixed, that is the axis that matters.

The second difference is tenancy. Kuma's multi-mesh support lets several isolated meshes share one control plane, which the README presents as an operations-cost reduction. Istio's isolation model leans on namespaces and revisions rather than a first-class mesh object. Whether that is better depends on whether your organisational boundaries map to meshes or to namespaces.

Both use Envoy, so the data plane performance characteristics are not the differentiator. Governance is: Kuma is a CNCF Sandbox project, which the README states was donated by Kong. Istio is a CNCF project at a more advanced maturity level. If foundation maturity stage is part of your adoption criteria, that is a real difference and the README is explicit about Kuma's stage.

A note on search noise: queries for "Kuma" also return Kaspersky's KUMA platform and Uptime Kuma. Neither is related to this project. If you are reading documentation, check the URL is kuma.io before you follow a command.

## Maintenance, releases and licence

The repository is not archived and the last push was on 2026-09-23, so the codebase is being worked on. Recent releases show v2.14.5 on 2026-09-18, v2.13.11 on 2026-09-11 and v2.12.15 on 2026-09-11. Three parallel lines with backported patches means security and bug fixes reach older lines, but it also means you should check which line receives a given fix before you assume you are covered.

The upgrade path is documented in UPGRADE.md at the repository root rather than in the README, and there is a CHANGELOG.md alongside it. The top-level active-branches.json file is another place to check which branches are currently supported. Budget time for reading those before a version jump; the existence of a dedicated upgrade document is a reasonable indicator that the project expects non-trivial transitions.

Kuma is licensed under Apache-2.0, which permits commercial use, modification and redistribution, and includes an explicit patent grant. It also means there is no copyleft obligation on your own code. This is not legal advice; if you are embedding Kuma in a product you ship, have counsel read the LICENSE and NOTICE files in the repository. Kong's enterprise offerings are a separate commercial arrangement and are not covered by the Apache-2.0 grant.

## Conclusion

Adopt Kuma if you need one mesh spanning Kubernetes clusters and VMs, and you want Envoy without writing Envoy config yourself. Do not adopt it if you only run a single Kubernetes cluster and a lighter sidecar-less option would do, or if you cannot commit to tracking the upgrade notes that ship in UPGRADE.md. Before rollout, verify which of the three release lines you are pinning to, read the upgrade notes for the version you are moving from, and confirm whether you need the enterprise offering for support.

## FAQ

### What is Kuma and who is it for?

Kuma is an Envoy-based service mesh that runs on Kubernetes and VMs in single or multi-zone deployments. It is aimed at organisations that need L4-L7 connectivity, security and observability across a mixed estate without writing Envoy configuration directly.

### How do I install Kuma?

The README points to kuma.io/install for installation and to the Kubernetes quickstart at kuma.io/docs/latest/quickstart/kubernetes-demo/. The README itself does not include install commands.

### Does Kuma require Kubernetes?

No. The README states that Kuma supports both Kubernetes and VMs on the control plane and the data plane. On Kubernetes the sidecar is injected automatically; on VMs and bare metal the data plane is specified in YAML.

### How does Kuma compare with Istio?

Both use Envoy as the data plane. Kuma's README emphasises equal support for Kubernetes and VMs plus multi-mesh support on one control plane, and states that Kuma is a CNCF Sandbox project donated by Kong.

### What licence is Kuma under?

Apache-2.0, per the repository's LICENSE file and the licence badge in the README.

## Sources

- [kumahq/kuma on GitHub](https://github.com/kumahq/kuma)
- [License: Apache-2.0](https://github.com/kumahq/kuma/blob/master/LICENSE)
- [Project website](https://kuma.io/install)
- [README](https://github.com/kumahq/kuma/blob/master/README.md)
- [Releases](https://github.com/kumahq/kuma/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/kumahq-kuma