Progressively rolling out unified resource naming

By default, Envoy resources and stats in Kuma use mixed, legacy formats. Names often do not line up with the Kuma resources that produced them, which makes dashboards noisy and troubleshooting slower. For example, a query like:

sum:envoy.cluster.upstream_rq.count{service:my-example-service, !envoy_cluster:kuma_*, !envoy_cluster:meshtrace_*, !envoy_cluster:access_log_sink} by {envoy_cluster}.as_count()

is not intuitive and does not point cleanly back to the right Kuma resource. Different resources and their related stats often look unrelated, even when they describe the same traffic path.

Starting with 2.12, you can adopt a unified resource naming scheme that makes names predictable, consistent, and directly tied to Kuma resources. This improves observability, simplifies queries, and makes it much easier to understand what is happening in the mesh.

Prerequisites

You have completed the Kubernetes Quickstart and have the demo environment running. This guide assumes you already have the demo-app service running from the quickstart.

Step 1: Create a ContainerPatch

Apply a ContainerPatch resource that enables unified naming on the sidecar:

echo "apiVersion: kuma.io/v1alpha1
kind: ContainerPatch
metadata:
  name: enable-feature-unified-resource-naming
  namespace: kuma-system
spec:
  sidecarPatch:
  - op: add
    path: /env/-
    value: '{
      \"name\": \"KUMA_DATAPLANE_RUNTIME_UNIFIED_RESOURCE_NAMING_ENABLED\",
      \"value\": \"true\"
    }'" | kubectl apply -f -

This patch configures every sidecar that references it to set an environment variable that turns on the unified naming feature.

Step 2: Enable for a single workload

Apply the patch to a workload by annotating its pods via the Deployment’s pod template (not the Deployment object itself). This lets you enable the feature progressively, service by service.

# add/overwrite the annotation on the Deployment's pod template
kubectl patch -n kuma-demo deployment demo-app -p '{"spec":{"template":{"metadata":{"annotations":{"kuma.io/container-patches":"enable-feature-unified-resource-naming"}}}}}'

To disable later for that workload:

# set to an empty list on the pod template
kubectl patch -n kuma-demo deployment demo-app \
  -p '{"spec":{"template":{"metadata":{"annotations":{"kuma.io/container-patches":""}}}}}'

# or remove the annotation entirely from the pod template
kubectl patch -n kuma-demo deployment demo-app --type=json \
  -p='[{"op":"remove","path":"/spec/template/metadata/annotations/kuma.io~1container-patches"}]'

Step 3: Verify the new naming

Inspect the sidecar stats to confirm that unified naming is applied:

• In one terminal, port-forward to the demo-app pod:

  POD=$(kubectl get pod -n kuma-demo -l app=demo-app -o jsonpath='{.items[0].metadata.name}')
  kubectl port-forward -n kuma-demo pod/$POD 9901:9901
  

• In another terminal, confirm that unified naming is applied by inspecting stats:

  curl -s localhost:9901/stats | grep -i kri
  

You should see entries that map directly to Kuma resources, for example:

cluster.kri_msvc_default_us-east-2_kuma-demo_demo-app_http

These names show the MeshService resource (demo-app) and section (http) clearly, making them much easier to connect back to the original Kuma resource.

You can also look at cluster names for confirmation:

curl -s localhost:9901/clusters | head -n 50

Step 4: Choose cluster-wide enablement mode

Option A: Default ContainerPatch (keeps per-workload control)

Set a default list of patches the injector applies when a workload does not specify its own list. This approach makes the feature opt-out: it will be applied everywhere unless you explicitly disable it.

kumactl install control-plane \
  --set "controlPlane.envVars.KUMA_RUNTIME_KUBERNETES_INJECTOR_CONTAINER_PATCHES=enable-feature-unified-resource-naming" \
  | kubectl apply -f -

# Before installing Kuma with Helm, configure your local Helm repository:
# https://kuma.io/docs/2.12.x/production/cp-deployment/kubernetes/#helm
helm install \
  --create-namespace \
  --namespace kuma-system \
  --set "controlPlane.envVars.KUMA_RUNTIME_KUBERNETES_INJECTOR_CONTAINER_PATCHES=enable-feature-unified-resource-naming" \
  kuma kuma/kuma

Per-workload overrides:

# disable for a workload (set to an empty list on the pod template)
kubectl patch -n kuma-demo deployment demo-app \
  -p '{"spec":{"template":{"metadata":{"annotations":{"kuma.io/container-patches":""}}}}}'

# provide a custom list for a workload (on the pod template)
kubectl patch -n kuma-demo deployment demo-app \
  -p '{"spec":{"template":{"metadata":{"annotations":{"kuma.io/container-patches":"my-custom-patch-1,my-custom-patch-2"}}}}}'

Option B: Global feature flag (no per-workload override)

Enable unified naming for every injected workload. This makes the feature mandatory and removes the ability to disable it on a per-workload basis.

kumactl install control-plane \
  --set "dataPlane.features.unifiedResourceNaming: true" \
  | kubectl apply -f -

# Before installing Kuma with Helm, configure your local Helm repository:
# https://kuma.io/docs/2.12.x/production/cp-deployment/kubernetes/#helm
helm install \
  --create-namespace \
  --namespace kuma-system \
  --set "dataPlane.features.unifiedResourceNaming: true" \
  kuma kuma/kuma

Benefits of unified naming

Unified naming improves traceability and reduces the time required to understand what a stat refers to. With a progressive roll-out, you can safely validate the new scheme in your environment, then move to a cluster-wide roll-out when you are ready.