Home / Kong Mesh
Edit
Report

Progressively roll out unified resource naming

Uses: Kong Mesh
Incompatible with
konnect
Related Documentation
Mesh Documentation
Tags
#observability
Minimum Version
Kong Mesh - 2.12
TL;DR

Apply a ContainerPatch to one workload, verify stats, then roll out cluster-wide with a default patch list or global feature flag.

Prerequisites

Helm

You will need Helm, a package manager for Kubernetes.

A running Kubernetes cluster

This guide requires a running Kubernetes cluster. If you already have a Kubernetes cluster running, you can skip this step. It can be a cluster running locally, like Docker, or in a public cloud like AWS EKS, GCP GKE, etc.

For example, if you are using minikube:

minikube start -p mesh-zone

Install Kong Mesh with demo configuration

  1. Install Kong Mesh:

    helm repo add kong-mesh https://kong.github.io/kong-mesh-charts
helm repo update
helm upgrade \
  --install \
  --create-namespace \
  --namespace kong-mesh-system \
  kong-mesh kong-mesh/kong-mesh
kubectl wait -n kong-mesh-system --for=condition=ready pod --selector=app=kong-mesh-control-plane --timeout=90s

  2. Apply the demo configuration:

    echo "
apiVersion: v1
kind: Namespace
metadata:
  labels:
    kuma.io/sidecar-injection: enabled
  name: kong-mesh-demo
---
apiVersion: v1
kind: Service
metadata:
  name: demo-app
  namespace: kong-mesh-demo
spec:
  ports:
  - appProtocol: http
    port: 5050
    protocol: TCP
    targetPort: 5050
  selector:
    app: demo-app
---
apiVersion: v1
kind: Service
metadata:
  name: demo-app-v1
  namespace: kong-mesh-demo
spec:
  ports:
  - appProtocol: http
    port: 5050
    protocol: TCP
    targetPort: 5050
  selector:
    app: demo-app
    version: v1
---
apiVersion: v1
kind: Service
metadata:
  name: demo-app-v2
  namespace: kong-mesh-demo
spec:
  ports:
  - appProtocol: http
    port: 5050
    protocol: TCP
    targetPort: 5050
  selector:
    app: demo-app
    version: v2
---
apiVersion: v1
kind: Service
metadata:
  name: kv
  namespace: kong-mesh-demo
spec:
  ports:
  - appProtocol: http
    port: 5050
    protocol: TCP
    targetPort: 5050
  selector:
    app: kv
---
apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app: demo-app
    version: v1
  name: demo-app
  namespace: kong-mesh-demo
spec:
  replicas: 1
  selector:
    matchLabels:
      app: demo-app
      version: v1
  template:
    metadata:
      labels:
        app: demo-app
        version: v1
    spec:
      containers:
      - env:
        - name: OTEL_SERVICE_NAME
          value: demo-app
        - name: OTEL_EXPORTER_OTLP_ENDPOINT
          value: http://opentelemetry-collector.mesh-observability:4317
        - name: KV_URL
          value: http://kv.kong-mesh-demo.svc.cluster.local:5050
        - name: APP_VERSION
          valueFrom:
            fieldRef:
              fieldPath: metadata.labels['version']
        image: ghcr.io/kumahq/kuma-counter-demo:latest@sha256:daf8f5cffa10b576ff845be84e4e3bd5a8a6470c7e66293c5e03a148f08ac148
        name: app
        ports:
        - containerPort: 5050
          name: http
---
apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app: demo-app
    version: v2
  name: demo-app-v2
  namespace: kong-mesh-demo
spec:
  replicas: 0
  selector:
    matchLabels:
      app: demo-app
      version: v2
  template:
    metadata:
      labels:
        app: demo-app
        version: v2
    spec:
      containers:
      - env:
        - name: OTEL_SERVICE_NAME
          value: demo-app
        - name: OTEL_EXPORTER_OTLP_ENDPOINT
          value: http://opentelemetry-collector.mesh-observability:4317
        - name: KV_URL
          value: http://kv.kong-mesh-demo.svc.cluster.local:5050
        - name: APP_VERSION
          valueFrom:
            fieldRef:
              fieldPath: metadata.labels['version']
        image: ghcr.io/kumahq/kuma-counter-demo:latest@sha256:daf8f5cffa10b576ff845be84e4e3bd5a8a6470c7e66293c5e03a148f08ac148
        name: demo-app
        ports:
        - containerPort: 5050
          name: http
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: kv
  namespace: kong-mesh-demo
spec:
  replicas: 1
  selector:
    matchLabels:
      app: kv
  template:
    metadata:
      labels:
        app: kv
    spec:
      containers:
      - env:
        - name: OTEL_SERVICE_NAME
          value: kv
        - name: OTEL_EXPORTER_OTLP_ENDPOINT
          value: http://opentelemetry-collector.mesh-observability:4317
        - name: APP_VERSION
          valueFrom:
            fieldRef:
              fieldPath: metadata.labels['version']
        image: ghcr.io/kumahq/kuma-counter-demo:latest@sha256:daf8f5cffa10b576ff845be84e4e3bd5a8a6470c7e66293c5e03a148f08ac148
        name: app
        ports:
        - containerPort: 5050
          name: http
---
apiVersion: kuma.io/v1alpha1
kind: Mesh
metadata:
  name: default
spec:
  meshServices:
    mode: Exclusive
  mtls:
    backends:
    - name: ca-1
      type: builtin
    enabledBackend: ca-1
---
apiVersion: kuma.io/v1alpha1
kind: MeshTrafficPermission
metadata:
  name: kv
  namespace: kong-mesh-demo
spec:
  from:
  - default:
      action: Allow
    targetRef:
      kind: MeshSubset
      tags:
        app: demo-app
        k8s.kuma.io/namespace: kong-mesh-demo
  targetRef:
    kind: Dataplane
    labels:
      app: kv" | kubectl apply -f -
kubectl wait -n kong-mesh-demo --for=condition=available --timeout=120s deployment --all

By default, Envoy resources and stats in Kong Mesh use mixed, legacy formats. Names often don’t line up with the Kong Mesh resources that produce them, which makes dashboards noisy and troubleshooting slower. For example, the following query isn’t intuitive and doesn’t point cleanly back to the right Kong Mesh resource:

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()

Different resources and their related stats often look unrelated, even when they describe the same traffic path.

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

With a progressive rollout, you can validate the new scheme on a single workload, then move to a cluster-wide rollout when you’re ready.

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: kong-mesh-system
spec:
  sidecarPatch:
  - op: add
    path: /env/-
    value: '{
      \"name\": \"KUMA_DATAPLANE_RUNTIME_UNIFIED_RESOURCE_NAMING_ENABLED\",
      \"value\": \"true\"
    }'" | kubectl apply -f -

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

Enable unified naming for one workload

Apply the patch to a workload by updating the Deployment Pod template annotation. This lets you enable the feature progressively, service by service.

  1. Add the kuma.io/container-patches annotation to the demo-app Deployment:

    kubectl patch -n kong-mesh-demo deployment demo-app -p '{"spec":{"template":{"metadata":{"annotations":{"kuma.io/container-patches":"enable-feature-unified-resource-naming"}}}}}'

    Kubernetes rolls out new Pods that include the patched sidecar configuration.

  2. Wait for the demo-app Deployment rollout to complete before continuing:

    kubectl rollout status deployment/demo-app -n kong-mesh-demo --timeout=90s

Verify unified naming

Inspect sidecar stats to confirm that unified naming is applied.

  1. Port-forward to the demo-app Pod:

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

  2. In a new terminal window, inspect stats:

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

    The command filters for kri entries, which are part of the unified resource naming format. You should see entries that map directly to Kong Mesh resources, for example:

    cluster.kri_msvc_default_default_kong-mesh-demo_demo-app-v1_5050

    In this format, msvc identifies a MeshService, and the remaining segments identify the mesh, zone, namespace, Service name, and section. This example shows the MeshService resource demo-app-v1 and section 5050.

Roll out cluster-wide

After you confirm the feature works on a single workload, set a default list of patches that the injector applies when a workload doesn’t specify its own list. This approach makes the feature opt-out: the injector applies it everywhere unless you explicitly disable it.

Upgrade the Kong Mesh Helm release to set the default patch list on the injector:

helm upgrade \
  --install \
  --create-namespace \
  --namespace kong-mesh-system \
  --set "kuma.controlPlane.envVars.KUMA_RUNTIME_KUBERNETES_INJECTOR_CONTAINER_PATCHES=enable-feature-unified-resource-naming" \
  kong-mesh kong-mesh/kong-mesh

Validate the rollout

Inspect stats and confirm that cluster names include the kri_msvc_ prefix and your mesh resource names:

curl -s localhost:9901/stats | grep -i 'kri_msvc_'

FAQs

How do I disable the feature for a workload?

You have two options:

  • Set the annotation to an empty value to keep the key in place:

    kubectl patch -n kong-mesh-demo deployment demo-app -p '{"spec":{"template":{"metadata":{"annotations":{"kuma.io/container-patches":""}}}}}'

  • Remove the annotation entirely for a clean pod template:

    kubectl patch -n kong-mesh-demo deployment demo-app --type=json \
  -p='[{"op":"remove","path":"/spec/template/metadata/annotations/kuma.io~1container-patches"}]'

How do I enable unified naming for every workload without per-workload opt-out?

Upgrade the Kong Mesh Helm release to turn on the global feature flag. This approach makes the feature mandatory and removes the ability to disable it on a per-workload basis.

helm upgrade \
  --install \
  --create-namespace \
  --namespace kong-mesh-system \
  --set "kuma.dataPlane.features.unifiedResourceNaming=true" \
  kong-mesh kong-mesh/kong-mesh

How do I override the default patch list for a specific workload?

After setting a default patch list cluster-wide, you can override it per workload in two ways.

  • Clear the annotation to disable unified naming for a workload:

    kubectl patch -n kong-mesh-demo deployment demo-app \
  -p '{"spec":{"template":{"metadata":{"annotations":{"kuma.io/container-patches":""}}}}}'

  • Or set the annotation to a different patch list to apply custom patches instead:

    kubectl patch -n kong-mesh-demo deployment demo-app \
  -p '{"spec":{"template":{"metadata":{"annotations":{"kuma.io/container-patches":"my-custom-patch-1,my-custom-patch-2"}}}}}'
Something wrong?
Report an Issue | Edit this Page
View all Kong documentation

Help us make these docs great!

Kong Developer docs are open source. If you find these useful and want to make them better, contribute today!
Contribute

Still need help?

Ask in our Slack Community
Contact Support