From a2394c9307b3c8054225246564b685837e2469ff Mon Sep 17 00:00:00 2001 From: slonka Date: Tue, 19 May 2026 12:03:07 +0200 Subject: [PATCH 1/4] docs(mesh): same-namespace consumer precedence Document that a consumer default in the same namespace can override a producer policy for a specific service. Signed-off-by: slonka --- app/mesh/policies-introduction.md | 78 ++++++++++++++++++++++++++++++- 1 file changed, 77 insertions(+), 1 deletion(-) diff --git a/app/mesh/policies-introduction.md b/app/mesh/policies-introduction.md index b67ccb400f..cb2381344a 100644 --- a/app/mesh/policies-introduction.md +++ b/app/mesh/policies-introduction.md @@ -99,7 +99,7 @@ rows: Producer policies allow service owners to define recommended client-side behavior for calls to their service by creating the policy in their service's own namespace. {{ site.mesh_product_name }} then applies it automatically to the outbounds of client workloads. This lets backend owners publish sensible defaults (timeouts, retries, limits) for consumers, -while individual clients can still refine those settings with their own [consumer](#consumer-policies) policies. +while individual clients can still refine those settings with their own [consumer](#consumer-policies) policies.note The following policy tells {{ site.mesh_product_name }} to apply 3 retries with a backoff from `15s` to `1m` on 5xx errors to any client calling `backend`: @@ -311,6 +311,82 @@ For `to` policies, the concatenated arrays are sorted again based on the `spec.t 4. `MeshService` 5. `Mesh` (lowest priority) +### Same-namespace exception + +On Kubernetes, a consumer default in the same namespace can still override a producer policy for a specific service. +This happens because policy role is evaluated before `spec.to[].targetRef` specificity. + +{% navtabs %} +{% navtab "Producer" %} + +```yaml +apiVersion: kuma.io/v1alpha1 +kind: MeshTimeout +metadata: + name: producer-policy + namespace: kuma-demo +spec: + targetRef: + kind: Mesh + to: + - targetRef: + kind: MeshService + name: redis + namespace: kuma-demo + default: + connectionTimeout: 10s +``` + +{% endnavtab %} +{% navtab "Consumer default" %} + +```yaml +apiVersion: kuma.io/v1alpha1 +kind: MeshTimeout +metadata: + name: consumer-default + namespace: kuma-demo +spec: + targetRef: + kind: Mesh + to: + - targetRef: + kind: MeshService + default: + connectionTimeout: 5s +``` + +{% endnavtab %} +{% navtab "Updated consumer policy" %} + +```yaml +apiVersion: kuma.io/v1alpha1 +kind: MeshTimeout +metadata: + name: consumer-specific + namespace: kuma-demo +spec: + targetRef: + kind: Mesh + to: + - targetRef: + kind: MeshService + name: checkout + default: + connectionTimeout: 5s + - targetRef: + kind: MeshService + name: payments + default: + connectionTimeout: 5s +``` + +{% endnavtab %} +{% endnavtabs %} + +In this case, `consumer-default` overrides `producer-policy`. +To keep `producer-policy` effective, replace the mesh-wide consumer default with service-specific entries like `consumer-specific`, or split them into separate consumer policies and leave `redis` out. + Configuration is then built by merging each level using [JSON Merge Patch](https://www.rfc-editor.org/rfc/rfc7386). For example, a producer `MeshTimeout` in `backend-ns` sets broad timeout defaults for all callers: From 685d199770ef9f63b7cfe4ce29b6bb6d5c18c3c3 Mon Sep 17 00:00:00 2001 From: slonka Date: Tue, 19 May 2026 13:07:38 +0200 Subject: [PATCH 2/4] fix(mesh): add tab_group to navtabs The navtabs block requires a tab_group argument. Signed-off-by: slonka --- app/mesh/policies-introduction.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/mesh/policies-introduction.md b/app/mesh/policies-introduction.md index cb2381344a..a37b21893a 100644 --- a/app/mesh/policies-introduction.md +++ b/app/mesh/policies-introduction.md @@ -316,7 +316,7 @@ For `to` policies, the concatenated arrays are sorted again based on the `spec.t On Kubernetes, a consumer default in the same namespace can still override a producer policy for a specific service. This happens because policy role is evaluated before `spec.to[].targetRef` specificity. -{% navtabs %} +{% navtabs "same-namespace-exception" %} {% navtab "Producer" %} ```yaml From c9a261759c61790b27e4297eda80c1e48be91e92 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Krzysztof=20S=C5=82onka?= Date: Tue, 19 May 2026 14:47:07 +0200 Subject: [PATCH 3/4] fix wrong target ref Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- app/mesh/policies-introduction.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/mesh/policies-introduction.md b/app/mesh/policies-introduction.md index a37b21893a..820be1d585 100644 --- a/app/mesh/policies-introduction.md +++ b/app/mesh/policies-introduction.md @@ -351,7 +351,7 @@ spec: kind: Mesh to: - targetRef: - kind: MeshService + kind: Mesh default: connectionTimeout: 5s ``` From 883b073d2e9b64eb76e798394681ed01c02e9f22 Mon Sep 17 00:00:00 2001 From: Lucie Milan Date: Thu, 21 May 2026 10:33:36 +0200 Subject: [PATCH 4/4] review --- app/mesh/policies-introduction.md | 133 +++++++++++++++--------------- 1 file changed, 68 insertions(+), 65 deletions(-) diff --git a/app/mesh/policies-introduction.md b/app/mesh/policies-introduction.md index 820be1d585..72bd9aad0f 100644 --- a/app/mesh/policies-introduction.md +++ b/app/mesh/policies-introduction.md @@ -99,7 +99,10 @@ rows: Producer policies allow service owners to define recommended client-side behavior for calls to their service by creating the policy in their service's own namespace. {{ site.mesh_product_name }} then applies it automatically to the outbounds of client workloads. This lets backend owners publish sensible defaults (timeouts, retries, limits) for consumers, -while individual clients can still refine those settings with their own [consumer](#consumer-policies) policies.note +while individual clients can still refine those settings with their own [consumer](#consumer-policies) policies. + +{:.warning} +> A default consumer policy can override a service-specific producer policy if they are in the same namespace. For more information, see [Same-namespace exception](#same-namespace-exception). The following policy tells {{ site.mesh_product_name }} to apply 3 retries with a backoff from `15s` to `1m` on 5xx errors to any client calling `backend`: @@ -311,59 +314,81 @@ For `to` policies, the concatenated arrays are sorted again based on the `spec.t 4. `MeshService` 5. `Mesh` (lowest priority) -### Same-namespace exception - -On Kubernetes, a consumer default in the same namespace can still override a producer policy for a specific service. -This happens because policy role is evaluated before `spec.to[].targetRef` specificity. +Configuration is then built by merging each level using [JSON Merge Patch](https://www.rfc-editor.org/rfc/rfc7386). -{% navtabs "same-namespace-exception" %} -{% navtab "Producer" %} +For example, a producer `MeshTimeout` in `backend-ns` sets broad timeout defaults for all callers: ```yaml +# Producer policy (lower priority) apiVersion: kuma.io/v1alpha1 kind: MeshTimeout metadata: - name: producer-policy - namespace: kuma-demo + name: backend-producer-timeouts + namespace: backend-ns spec: targetRef: kind: Mesh to: - targetRef: kind: MeshService - name: redis - namespace: kuma-demo + name: backend + namespace: backend-ns default: connectionTimeout: 10s + idleTimeout: 2m + http: + requestTimeout: 30s + streamIdleTimeout: 5m ``` -{% endnavtab %} -{% navtab "Consumer default" %} +The `frontend` team creates a consumer policy to shorten the request timeout for their own calls and cap stream duration: ```yaml +# Consumer policy (higher priority) apiVersion: kuma.io/v1alpha1 kind: MeshTimeout metadata: - name: consumer-default - namespace: kuma-demo + name: frontend-consumer-timeouts + namespace: frontend-ns spec: targetRef: kind: Mesh to: - targetRef: - kind: Mesh + kind: MeshService + name: backend + namespace: backend-ns default: - connectionTimeout: 5s + http: + requestTimeout: 5s + maxStreamDuration: 1m ``` -{% endnavtab %} -{% navtab "Updated consumer policy" %} +The merged configuration applied to `frontend`'s outbound toward `backend` is: + +```yaml +default: + connectionTimeout: 10s # kept from producer: consumer didn't set it + idleTimeout: 2m # kept from producer: consumer didn't set it + http: + requestTimeout: 5s # overridden by consumer + streamIdleTimeout: 5m # kept from producer: consumer didn't set it + maxStreamDuration: 1m # added by consumer +``` + +### Same-namespace exception + +On Kubernetes, a consumer default in the same namespace can still override a producer policy for a specific service. +This happens because the policy role is evaluated before `spec.to[].targetRef`. + +{% navtabs "same-namespace-exception" %} +{% navtab "Producer" %} ```yaml apiVersion: kuma.io/v1alpha1 kind: MeshTimeout metadata: - name: consumer-specific + name: producer-policy namespace: kuma-demo spec: targetRef: @@ -371,83 +396,61 @@ spec: to: - targetRef: kind: MeshService - name: checkout - default: - connectionTimeout: 5s - - targetRef: - kind: MeshService - name: payments + name: redis + namespace: kuma-demo default: - connectionTimeout: 5s + connectionTimeout: 10s ``` {% endnavtab %} -{% endnavtabs %} - -In this case, `consumer-default` overrides `producer-policy`. -To keep `producer-policy` effective, replace the mesh-wide consumer default with service-specific entries like `consumer-specific`, or split them into separate consumer policies and leave `redis` out. - -Configuration is then built by merging each level using [JSON Merge Patch](https://www.rfc-editor.org/rfc/rfc7386). - -For example, a producer `MeshTimeout` in `backend-ns` sets broad timeout defaults for all callers: +{% navtab "Consumer default" %} ```yaml -# Producer policy (lower priority) apiVersion: kuma.io/v1alpha1 kind: MeshTimeout metadata: - name: backend-producer-timeouts - namespace: backend-ns + name: consumer-default + namespace: kuma-demo spec: targetRef: kind: Mesh to: - targetRef: - kind: MeshService - name: backend - namespace: backend-ns + kind: Mesh default: - connectionTimeout: 10s - idleTimeout: 2m - http: - requestTimeout: 30s - streamIdleTimeout: 5m + connectionTimeout: 5s ``` -The `frontend` team creates a consumer policy to shorten the request timeout for their own calls and cap stream duration: +{% endnavtab %} +{% navtab "Updated consumer policy" %} ```yaml -# Consumer policy (higher priority) apiVersion: kuma.io/v1alpha1 kind: MeshTimeout metadata: - name: frontend-consumer-timeouts - namespace: frontend-ns + name: consumer-specific + namespace: kuma-demo spec: targetRef: kind: Mesh to: - targetRef: kind: MeshService - name: backend - namespace: backend-ns + name: checkout default: - http: - requestTimeout: 5s - maxStreamDuration: 1m + connectionTimeout: 5s + - targetRef: + kind: MeshService + name: payments + default: + connectionTimeout: 5s ``` -The merged configuration applied to `frontend`'s outbound toward `backend` is: +{% endnavtab %} +{% endnavtabs %} -```yaml -default: - connectionTimeout: 10s # kept from producer: consumer didn't set it - idleTimeout: 2m # kept from producer: consumer didn't set it - http: - requestTimeout: 5s # overridden by consumer - streamIdleTimeout: 5m # kept from producer: consumer didn't set it - maxStreamDuration: 1m # added by consumer -``` +In this example, `consumer-default` overrides `producer-policy`. +To keep `producer-policy` effective, replace the mesh-wide consumer default with service-specific entries like `consumer-specific`, or split them into separate consumer policies and leave `redis` out. ## Metadata