docs(MADR): 094 zone proxies new deployment model #15460

slonka · 2026-01-29T12:06:37Z

Motivation

Zone proxies are becoming mesh-scoped to enable MeshIdentity and policy support. This requires revisiting the deployment model.

Implementation

MADR 094 addresses:

Unified vs separate zone proxy deployments
Standalone deployment vs sidecar to fake container
Universal (VM) deployment model
Helm configuration structure and user flows (Konnect, self-hosted, unfederated)
Default installation behavior

Key decisions: unified zone proxy as Dataplane with kuma.io/zone-proxy-role label, standalone deployment, mesh-scoped resources.

Supporting documentation

docs/madr/decisions/090-zone-egress-identity.md

fix #9030

Signed-off-by: slonka <[email protected]>

github-actions · 2026-01-29T12:12:47Z

Reviewer Checklist

🔍 Each of these sections need to be checked by the reviewer of the PR 🔍:
If something doesn't apply please check the box and add a justification if the reason is non obvious.

Is the PR title satisfactory? Is this part of a larger feature and should be grouped using > Changelog?
PR description is clear and complete. It Links to relevant issue as well as docs and UI issues
This will not break child repos: it doesn't hardcode values (.e.g "kumahq" as an image registry)
IPv6 is taken into account (.e.g: no string concatenation of host port)
Tests (Unit test, E2E tests, manual test on universal and k8s)
- Don't forget ci/ labels to run additional/fewer tests
Does this contain a change that needs to be notified to users? In this case, UPGRADE.md should be updated.
Does it need to be backported according to the backporting policy? (this GH action will add "backport" label based on these file globs, if you want to prevent it from adding the "backport" label use no-backport-autolabel label)

Signed-off-by: slonka <[email protected]>

Copilot

Pull request overview

This PR introduces MADR 094, which defines the deployment model for zone proxies as they transition from global-scoped to mesh-scoped resources. The architectural change addresses fundamental limitations with the current global zone proxy model, particularly around MeshIdentity issuance and policy application.

Changes:

Adds comprehensive architecture decision record for zone proxy deployment model
Proposes unified zone proxy approach where a single Dataplane type uses labels to determine ingress/egress/both capabilities
Defines deployment patterns for Kubernetes, Universal, Helm, Terraform, and Konnect workflows
Establishes defaults for Helm installations and migration paths from global to mesh-scoped zone proxies

docs/madr/decisions/094-zone-proxy-deployment-model.md

Signed-off-by: slonka <[email protected]>

docs/madr/decisions/094-zone-proxy-deployment-model.md

Signed-off-by: Krzysztof Słonka <[email protected]>

slonka · 2026-02-09T10:36:00Z

General Q:

check what resources we need - do we need RBAC?

docs/madr/decisions/094-zone-proxy-deployment-model.md

Signed-off-by: Krzysztof Słonka <[email protected]>

Signed-off-by: slonka <[email protected]>

docs/madr/decisions/094-zone-proxy-deployment-model.md

Signed-off-by: slonka <[email protected]>

lukidzi · 2026-02-09T13:10:27Z

docs/madr/decisions/094-zone-proxy-deployment-model.md

+
+| Tooling Decision | Choice |
+|------------------|--------|
+| Per-mesh Services | **Yes** - each mesh gets its own Service/LoadBalancer for mTLS isolation |


What means Per-mesh Services? What kind of services ?

Kubernetes Services - specifically the LoadBalancer or NodePort Service that exposes the zone proxy to other zones. Today there's one global Service for zone ingress and one for zone egress. With mesh-scoped zone proxies, each mesh gets its own Service (e.g., kuma-payments-mesh-zoneproxy) because each mesh has a different mTLS CA, so they can't share a single LoadBalancer without complex SNI-based cert selection. This is detailed in the "Per-Mesh Services (Not Shared)" section below.

It's just kubernetes specific what about universal not sure if naming Service is here a good option

lukidzi · 2026-02-09T13:11:30Z

docs/madr/decisions/094-zone-proxy-deployment-model.md

+| Tooling Decision | Choice |
+|------------------|--------|
+| Per-mesh Services | **Yes** - each mesh gets its own Service/LoadBalancer for mTLS isolation |
+| Namespace placement | **kuma-system** |


Does it need to be system namespace? In case of mulitple meshes is it possible to change it or we want to stick to the one only?

For single-mesh (this MADR's scope), kuma-system keeps everything together with the CP. For multi-mesh, standalone kuma-zone-proxy releases can target any namespace — the Helm --namespace flag controls that. We could add a dedicated namespace option per mesh later, but the single-mesh default of kuma-system keeps things simple. I'll clarify this in the namespace section.

We need to ensure there is transparent proxy disabled for a zoneproxy - even if it's enabled on the namespace we should have it disabled on the deployment

This is not good because that assumes kuma-system namespace will be marked as a "meshed" namespace which we don't want right?

Also kuma-system is sort of meant to be admin realm here there's almost a Mesh operator persona comes in no?

docs/madr/decisions/094-zone-proxy-deployment-model.md

lahabana

Is there a PoC for this?

lahabana · 2026-02-11T09:29:33Z

docs/madr/decisions/094-zone-proxy-deployment-model.md

+
+2. **Cannot apply policies on zone proxies**: Kuma policies (MeshTrafficPermission, MeshTimeout, etc.) are mesh-scoped.
+   A global zone proxy cannot be targeted by mesh-specific policies, limiting observability and traffic control for cross-zone communication.
+


Observability story is tricky (how do you share to a mesh a subset of all the observability)

lahabana · 2026-02-11T09:35:00Z

docs/madr/decisions/094-zone-proxy-deployment-model.md

+**Scope of this document**: This MADR focuses on **deployment tooling** — how users deploy zone proxies via Helm, Konnect UI, and Terraform.
+
+**Single-mesh focus**: This document assumes **single-mesh-per-zone as the default** deployment pattern.
+For multi-mesh scenarios, deploy additional zone proxies using separate Helm releases with a dedicated `kuma-zone-proxy` chart. A multi-mesh deployment guide will be provided separately.


No let's not as we're just creating maintainance for a path we don't recommend.

I think for folks that NEED multi-mesh they can:

Just write their own deployment

Push for Mesh to be supported by KO

Our goal for K3 is really to streamline what folks can do. Adding a new helm short is a complete no go.

lahabana · 2026-02-11T09:38:48Z

docs/madr/decisions/094-zone-proxy-deployment-model.md

+| Tooling Decision | Choice |
+|------------------|--------|
+| Per-mesh Services | **Yes** - each mesh gets its own Service/LoadBalancer for mTLS isolation |
+| Namespace placement | **kuma-system** |


This is not good because that assumes kuma-system namespace will be marked as a "meshed" namespace which we don't want right?

lahabana · 2026-02-11T09:39:23Z

docs/madr/decisions/094-zone-proxy-deployment-model.md

+| Tooling Decision | Choice |
+|------------------|--------|
+| Per-mesh Services | **Yes** - each mesh gets its own Service/LoadBalancer for mTLS isolation |
+| Namespace placement | **kuma-system** |


Also kuma-system is sort of meant to be admin realm here there's almost a Mesh operator persona comes in no?

lahabana · 2026-02-11T09:41:57Z

docs/madr/decisions/094-zone-proxy-deployment-model.md

+│ Mesh: [default ▼]                                       │
+│ (if multiple meshes detected there will be info here on │
+│ how to handle that)                                     │
+└─────────────────────────────────────────────────────────┘


What if no mesh?

lahabana · 2026-02-11T09:44:06Z

docs/madr/decisions/094-zone-proxy-deployment-model.md

+    # mesh defaults to "default"
+```
+
+If the user selected a non-default mesh name:


Why not always do it?

slonka added 10 commits January 28, 2026 09:02

docs(MADR): initial commit of zone proxies new deployment model

369db61

Signed-off-by: slonka <[email protected]>

docs(MADR): rework context and problem statement

9874350

Signed-off-by: slonka <[email protected]>

docs(MADR): improve question 1

bbec9c2

Signed-off-by: slonka <[email protected]>

docs(MADR): improve question 2

a701f5a

Signed-off-by: slonka <[email protected]>

docs(MADR): link up issues

007cb1e

Signed-off-by: slonka <[email protected]>

docs(MADR): improve question 3

082d1fd

Signed-off-by: slonka <[email protected]>

docs(MADR): improve question 5

ba37797

Signed-off-by: slonka <[email protected]>

docs(MADR): adjust decisions

bc9da6a

Signed-off-by: slonka <[email protected]>

docs(MADR): fix links

ff7ca10

Signed-off-by: slonka <[email protected]>

docs(MADR): add an angle about ingress egress being just listeners

34a962d

Signed-off-by: slonka <[email protected]>

slonka added the ci/skip-test PR: Don't run unit and e2e tests (maybe this is just a doc change) label Jan 29, 2026

slonka added 4 commits January 29, 2026 13:13

docs(MADR): make each sentence on new line

c259c00

Signed-off-by: slonka <[email protected]>

docs(MADR): remove links to 15429

5a19173

Signed-off-by: slonka <[email protected]>

docs(MADR): added user flows

c9b9134

Signed-off-by: slonka <[email protected]>

docs(MADR): small adjustments

20cae98

Signed-off-by: slonka <[email protected]>

slonka marked this pull request as ready for review January 30, 2026 13:00

slonka requested a review from a team as a code owner January 30, 2026 13:00

slonka requested review from Automaat, Copilot and lukidzi January 30, 2026 13:00

slonka marked this pull request as draft January 30, 2026 13:00

Copilot started reviewing on behalf of slonka January 30, 2026 13:00 View session

Copilot AI reviewed Jan 30, 2026

View reviewed changes

docs/madr/decisions/094-zone-proxy-deployment-model.md Outdated Show resolved Hide resolved

slonka changed the title ~~docs(MADR): initial commit of zone proxies new deployment model~~ docs(MADR): zone proxies new deployment model Feb 2, 2026

lobkovilya reviewed Feb 2, 2026

View reviewed changes

slonka added 4 commits February 3, 2026 09:20

docs(MADR): post review adjustments

321a874

Signed-off-by: slonka <[email protected]>

docs(MADR): make helm create the resources

7b94c26

Signed-off-by: slonka <[email protected]>

docs(MADR): improve current state

e88d320

Signed-off-by: slonka <[email protected]>

docs(MADR): adjust one sentence

eb82c58

Signed-off-by: slonka <[email protected]>

lobkovilya reviewed Feb 9, 2026

View reviewed changes

docs/madr/decisions/094-zone-proxy-deployment-model.md Outdated Show resolved Hide resolved

slonka added 2 commits February 9, 2026 11:32

Update docs/madr/decisions/094-zone-proxy-deployment-model.md

25045b2

Signed-off-by: Krzysztof Słonka <[email protected]>

Update docs/madr/decisions/094-zone-proxy-deployment-model.md

63d1884

Signed-off-by: Krzysztof Słonka <[email protected]>

slonka commented Feb 9, 2026

View reviewed changes

docs/madr/decisions/094-zone-proxy-deployment-model.md Show resolved Hide resolved

slonka commented Feb 9, 2026

View reviewed changes

docs/madr/decisions/094-zone-proxy-deployment-model.md Outdated Show resolved Hide resolved

slonka added 3 commits February 9, 2026 11:44

Apply suggestion from @slonka

c979a1b

Signed-off-by: Krzysztof Słonka <[email protected]>

docs(MADR): service name override and limits

5302938

Signed-off-by: slonka <[email protected]>

docs(MADR): note migration is opt-in on upgrade

53a6171

Signed-off-by: slonka <[email protected]>

Automaat reviewed Feb 9, 2026

View reviewed changes

docs/madr/decisions/094-zone-proxy-deployment-model.md Show resolved Hide resolved

Automaat previously approved these changes Feb 9, 2026

View reviewed changes

bartsmykla previously approved these changes Feb 9, 2026

View reviewed changes

slonka marked this pull request as ready for review February 9, 2026 11:28

lobkovilya reviewed Feb 9, 2026

View reviewed changes

docs/madr/decisions/094-zone-proxy-deployment-model.md Show resolved Hide resolved

docs/madr/decisions/094-zone-proxy-deployment-model.md Outdated Show resolved Hide resolved

docs/madr/decisions/094-zone-proxy-deployment-model.md Outdated Show resolved Hide resolved

docs(MADR): adjust comments

9196180

Signed-off-by: slonka <[email protected]>

slonka dismissed stale reviews from bartsmykla and Automaat via 9196180 February 9, 2026 11:52

bartsmykla previously approved these changes Feb 9, 2026

View reviewed changes

Automaat previously approved these changes Feb 9, 2026

View reviewed changes

docs(MADR): reframe helm structure as subchart, group passthrough values

c2f5f9e

Signed-off-by: slonka <[email protected]>

slonka dismissed stale reviews from Automaat and bartsmykla via c2f5f9e February 9, 2026 12:47

slonka added 2 commits February 9, 2026 13:48

docs(MADR): remove one thing

1bc54df

Signed-off-by: slonka <[email protected]>

docs(MADR): remove best for

692bf18

Signed-off-by: slonka <[email protected]>

lukidzi reviewed Feb 9, 2026

View reviewed changes

slonka requested review from Automaat, bartsmykla, lobkovilya and lukidzi February 10, 2026 12:57

lahabana reviewed Feb 11, 2026

View reviewed changes


		2. Cannot apply policies on zone proxies: Kuma policies (MeshTrafficPermission, MeshTimeout, etc.) are mesh-scoped.
		A global zone proxy cannot be targeted by mesh-specific policies, limiting observability and traffic control for cross-zone communication.

docs(MADR): 094 zone proxies new deployment model #15460

Are you sure you want to change the base?

docs(MADR): 094 zone proxies new deployment model #15460

Uh oh!

Conversation

slonka commented Jan 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation

Implementation

Supporting documentation

Uh oh!

github-actions bot commented Jan 29, 2026

Reviewer Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

slonka commented Feb 9, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

slonka Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lahabana left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

slonka commented Jan 29, 2026 •

edited

Loading

slonka Feb 10, 2026 •

edited

Loading