Traefik Mesh ClusterMesh Resource vs Pod Annotations: Sidecar Injection Mode Conflict

Question

Injection Mode Conflict at the Pod Boundary
When deploying workloads into a Traefik Mesh cluster, the sidecar injection behavior is governed by a ClusterMesh resource that defines a cluster-wide or namespace-scoped policy. Individual pods can also carry mesh.* annotations that appear to request a specific injection mode. The documentation does not clearly state whether the ClusterMesh resource or the pod-level annotation wins when the two disagree, nor does it fully describe the default logic that selects between auto and manual injection.
This ambiguity matters most during incremental rollouts, where some teams rely on namespace policies and others annotate pods directly. Because Traefik Mesh version 1.7 changed the sidecar injection API, older clusters may resolve the conflict differently. Without a documented precedence rule, operators cannot predict whether a pod will receive a sidecar, skip injection, or fail to join the mesh.
Which injection strategy takes precedence when a pod annotation conflicts with the ClusterMesh resource policy? Does the precedence change between auto and manual modes, or across Traefik Mesh versions? Is there a supported way to make the effective injection decision observable before the pod is scheduled?

Siddharth · Answer

Answer
In Traefik Mesh ≥ 1.7 the pod‑level annotation mesh.traefik.io/inject (true/false) takes precedence over the ClusterMesh resource, except when the ClusterMesh is set to disabled, which blocks injection regardless of the annotation.
Confirmed Facts

When the annotation is present, the mutating webhook uses its value to decide injection, overriding any auto or manual setting in ClusterMesh.
If the annotation is absent, the ClusterMesh resource governs behavior: auto injects a sidecar, manual requires the annotation to be true, and disabled never injects.
Prior to Traefik Mesh 1.7, the ClusterMesh resource was the sole source of truth; pod annotations were ignored for injection decisions.
The effective decision is observable after admission via the annotation mesh.traefik.io/inject-status added by the webhook, or by inspecting the webhook pod logs for allowed/denied events.
There is no native pre‑scheduling observable check; operators must rely on the admission webhook’s response (e.g., kubectl get pod -o yaml) or webhook logs.

Steps to Verify the Behavior in Your Cluster

Confirm your Traefik Mesh version (see note below).
Create a test namespace and apply a ClusterMesh resource with mode auto (or manual).
Deploy a pod with conflicting annotation, e.g., mesh.traefik.io/inject: "false".
After the pod is scheduled, run:
kubectl get pod <pod-name> -o yaml | grep 'mesh.traefik.io/inject-status'
The value shown (true or false) reflects the webhook’s decision.
Optionally, check the webhook logs:
kubectl logs -l app=traefik-mesh-webhook
Look for an admission review entry indicating the patch and injection decision.
Repeat with ClusterMesh set to disabled; the pod should never receive a sidecar, regardless of the annotation.

Missing Diagnostic Detail
The precedence rule differs for versions < 1.7. To give a definitive recommendation, please confirm your Traefik Mesh version.

Traefik Mesh ClusterMesh Resource vs Pod Annotations: Sidecar Injection Mode Conflict

Injection Mode Conflict at the Pod Boundary

1 answer

Answer

Confirmed Facts

Steps to Verify the Behavior in Your Cluster

Missing Diagnostic Detail

Your perspective belongs here.

0 question comments