Kuma Service Mesh Documentation

Kuma provides a comprehensive set of service mesh capabilities including:

• Connectivity & Discovery: Automatic discovery, ingress, and connectivity across single and multi-zones. Supports internal and external services.
• Security: Automatic mTLS with identity and encryption, TLS rotation, and MeshTrafficPermission for zero-trust firewalling.
• Traffic Control: Dynamic load-balancing for blue/green, canary, and rollback deployments using MeshHTTPRoute and MeshTCPRoute. Includes MeshRetry for reliability.
• Observability: Native Prometheus/Grafana support via MeshMetric, full traffic tracing via MeshTrace, and activity logging via MeshAccessLog.
• Resilience: System hardening via MeshFaultInjection.
• Deployment Models: Supports Multi-Mesh (isolated meshes on one control plane), Single/Multi-Zone (cross-cloud/cross-cluster), and Global/Remote Control Planes for scalability.
• Management: Platform-agnostic (K8s, VM, Bare Metal), transparent proxying, and a browser-based GUI for exploration.

Kuma is migrating to a consistent naming convention for non-system Envoy resources and stats. This change affects how resources are identified and how their metrics are reported in observability tools like Prometheus and Grafana.

Applicability

These new naming formats apply only to environments using the new service discovery model. If your environment uses the legacy kuma.io/service tag, these changes do not apply to you. The new formats are used for resources generated from:

• MeshService
• MeshExternalService
• MeshMultiZoneService

Impacted Components

• Observability: Grafana dashboards installed via kumactl install observability are being updated to support both old and new formats.
• Kuma GUI: The Dataplane view (which shows inbound/outbound endpoints) is being updated to handle the transition between legacy and new naming formats during the migration period.

Kuma uses a release pipeline designed to minimize release times by skipping redundant tests on tags. Instead of running the full end-to-end (e2e) and unit test suites when a tag is created, the pipeline relies on the fact that these tests were already passed and the artifacts were already published during the push run on the branch.

Key Pipeline Characteristics:

• Reduced Latency: Cuts release time from ~100–220m down to ~20–30m.
• Verification Strategy: On a tag, the pipeline only verifies the ldflags delta using container-structure tests on the freshly-built image and a binary-version assert.
• Security & Reliability: Security controls (SBOM, provenance, signing, and scanning) remain unchanged in the build_publish step. A "hard green-SHA gate" ensures that a tag can only be released if the specific commit SHA has a successful, published push run.
• No Rehearsal Needed: Every push already builds and publishes a preview via _build_publish.yaml, so the publish/sign path is continuously exercised.

Kuma's policy matching algorithm maps user-provided policies into a structured list of Rules. Each rule consists of a Subset (defining the criteria for matching), a Conf (the configuration applied when the criteria are met), and an Origin.

This structure is utilized by both "from" and "to" policy plugins. Policy plugins iterate over the Rules list to compute the appropriate Conf for a known destination by checking if the destination belongs to the Rules[].Subset.

Rules:
  - Subset:
      - Key: kuma.io/service
        Not: false
        Value: foo
    Conf:
      connectionTimeout: 2s
      http:
        requestTimeout: 15s
      idleTimeout: 20s
    Origin: [ ... ]
  - Subset:
      - Key: kuma.io/service
        Not: false
        Value: bar
    Conf:
      connectionTimeout: 2s
      http:
        requestTimeout: 20s
      idleTimeout: 20s
    Origin: [ ... ]

Kuma uses a targetRef selector to attach policies to specific resources. This allows for a hierarchical and role-oriented approach to policy management (e.g., Mesh operators vs. Service owners).

Supported TargetRef Kinds

• Mesh: Affects all Data Plane Proxies (DPPs) in the mesh.
• MeshSubset: Affects a subset of DPPs in the mesh (selected via tags).
• MeshService: Affects all DPPs of a specific service (selected via name).
• MeshServiceSubset: Affects a subset of a specific service (selected via name and tags).
• MeshGatewayRoute: Affects a specific MeshGatewayRoute (selected via name).
• MeshHTTPRoute: Affects a specific MeshHTTPRoute (selected via name).

TargetRef Structure

Each policy contains a single top-level targetRef that identifies the set of DPPs affected by the policy. Traffic direction is then expressed using to (for outbound) or from (for inbound) arrays.

message TargetRef {
  // Kind of the referenced resource
  // +kubebuilder:validation:Enum=Mesh;MeshSubset;MeshService;MeshServiceSubset;MeshGatewayRoute;MeshHTTPRoute
  string kind = 1;

  // Name of the referenced resource
  string name = 2;

  // Tags are used with MeshSubset and MeshServiceSubset to define a subset of proxies
  map<string, string> tags = 3;
  
  // Mesh is used with MeshService and MeshServiceSubset to identify the service from another mesh.
  string mesh = 4;
}