# Kuma — Multi-Zone Service Mesh Built on Envoy

> A CNCF service mesh that provides connectivity, observability, and security for containers, Kubernetes, and VMs across multiple zones.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

# Kuma — Multi-Zone Service Mesh Built on Envoy

## Quick Use
```bash
# Install Kuma on Kubernetes
kumactl install control-plane | kubectl apply -f -
# Enable sidecar injection for a namespace
kubectl label namespace default kuma.io/sidecar-injection=enabled
# Apply a traffic permission policy
cat <<EOF | kubectl apply -f -
apiVersion: kuma.io/v1alpha1
kind: MeshTrafficPermission
metadata:
  namespace: kuma-system
  name: allow-all
spec:
  targetRef:
    kind: Mesh
  from:
    - targetRef:
        kind: Mesh
      default:
        action: Allow
EOF
```

## Introduction
Kuma is an open-source service mesh created by Kong and donated to the CNCF. Built on top of the Envoy proxy, it provides service connectivity, traffic management, observability, and security for applications running on Kubernetes, VMs, or hybrid environments. Its multi-zone architecture supports connecting services across multiple clusters and data centers through a single control plane.

## What Kuma Does
- Manages service-to-service communication with automatic mTLS encryption
- Provides traffic control policies: load balancing, circuit breaking, retries, and timeouts
- Offers built-in observability with metrics (Prometheus), tracing (Jaeger/Zipkin), and logging
- Supports multi-zone deployments spanning multiple Kubernetes clusters and VM environments
- Enables zero-trust security with fine-grained traffic permission policies

## Architecture Overview
Kuma consists of a control plane and Envoy-based data plane proxies. In Kubernetes mode, the control plane runs as a deployment and injects Envoy sidecars into application pods via a mutating webhook. In universal mode, data plane proxies run alongside VM workloads. The control plane distributes xDS configuration to all Envoy proxies. In multi-zone setups, a global control plane coordinates with zone control planes, each managing its local proxies, enabling cross-zone service discovery and traffic routing.

## Self-Hosting & Configuration
- Install on Kubernetes with `kumactl install control-plane` or via Helm chart
- For VMs, run the control plane binary and register data plane proxies using tokens
- Policies are applied as Kubernetes CRDs or via the HTTP API in universal mode
- Configure observability backends (Prometheus, Jaeger, Datadog) through mesh-level policies
- Set up multi-zone by deploying a global control plane and zone control planes in each cluster

## Key Features
- Multi-zone mesh: connect services across Kubernetes clusters, VMs, and data centers seamlessly
- Built-in mTLS: automatic certificate provisioning and rotation without external PKI
- Policy-driven configuration: traffic permissions, rate limits, health checks, and fault injection
- Gateway support: Kuma integrates with Kong Gateway for north-south traffic management
- GUI and CLI: web-based dashboard for mesh visualization and kumactl CLI for management

## Comparison with Similar Tools
- **Istio** — feature-rich but complex; Kuma offers simpler setup with built-in multi-zone support
- **Linkerd** — lightweight mesh focused on Kubernetes; Kuma supports both Kubernetes and VM workloads natively
- **Consul Connect** — HashiCorp service mesh with Consul KV; Kuma is a standalone mesh with Envoy
- **Cilium Service Mesh** — eBPF-based mesh; Kuma uses traditional Envoy sidecar proxies with a broader multi-zone architecture

## FAQ
**Q: Does Kuma require Kubernetes?**
A: No. Kuma runs on Kubernetes, VMs, or hybrid environments. Universal mode supports bare-metal and VM workloads without Kubernetes.

**Q: How does multi-zone work?**
A: A global control plane manages zone control planes in each cluster or region. Services in one zone can discover and communicate with services in other zones through the mesh.

**Q: What is the relationship between Kuma and Kong?**
A: Kuma was created by Kong Inc. and donated to the CNCF. It integrates with Kong Gateway for ingress but is a standalone project with its own governance.

**Q: Can I migrate from Istio to Kuma?**
A: Kuma uses Envoy proxies like Istio, but the control plane APIs differ. Migration requires converting Istio resources to Kuma policies. The simpler policy model may reduce operational complexity.

## Sources
- https://github.com/kumahq/kuma
- https://kuma.io/docs

---
Source: https://tokrepo.com/en/workflows/kuma-multi-zone-service-mesh-built-envoy-cfa3f60a
Author: AI Open Source