docs(MADR): mesh-scoped zone proxies representation and address syncing #15566

lobkovilya · 2026-02-09T13:56:54Z

Motivation

We want to replace global-scoped ZoneIngress/ZoneEgress with mesh-scoped Dataplane (with new fields for zone proxy specific info).

Supporting documentation

Fix https://github.com/Kong/kong-mesh/issues/9028

Signed-off-by: Ilya Lobkov <[email protected]>

docs/madr/decisions/095-mesh-scoped-zone-ingress-egress.md

github-actions · 2026-02-09T14:23:22Z

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: Ilya Lobkov <[email protected]>

Copilot

Pull request overview

Adds a new MADR documenting the proposed representation of Zone Ingress/Zone Egress as mesh-scoped Dataplane resources and how their advertised addresses should be shared across zones.

Changes:

Introduces MADR 095 describing a mesh-scoped schema for zone proxies using Dataplane extensions.
Documents policy targeting considerations for zone proxy dataplanes (including targetRef.sectionName usage).
Proposes address/port syncing via MeshService.spec (zone ingress) and MeshExternalService.status (zone egress).

docs/madr/decisions/095-mesh-scoped-zone-ingress-egress.md

Co-authored-by: Copilot <[email protected]> Signed-off-by: Ilya Lobkov <[email protected]>

lahabana

There are really at least 3 MADRs here. We should consider splitting things.

I'm fine with using DP but we need to think a bit more about what it means to have multiple Ingress or Egress deployments.

I'm still not convinced at all with having egress and ingress addresses in MES/MS it just feels like "we didn't know what to do with this info so we put it there..." I'm sure we can do better!

lahabana · 2026-02-11T08:55:57Z

docs/madr/decisions/095-mesh-scoped-zone-ingress-egress.md

+
+##### Open Questions
+
+1. Should `networking.zoneIngress` and `networking.zoneEgress` be an array?


We discussed this offline yesterday. It should never be an array. I missed that this question was still in the doc.

lahabana · 2026-02-11T08:59:44Z

docs/madr/decisions/095-mesh-scoped-zone-ingress-egress.md

+1. Should `networking.zoneIngress` and `networking.zoneEgress` be an array?
+2. There is also `networking.advertisedAddress` field (but no `networking.advertisedPort`). 
+It was a very niche Universal-only field [contributed by community](https://github.com/kumahq/kuma/pull/2116) that I think we should remove in v3. 
+I think `networking.zoneIngress.advertisedAddress` should be `required` so it never falls back to `networking.advertisedAddress`.


Sounds good. So in a more concrete manner we disallow using networking.advertisedAddress always in 2.14? Or do we warn in 2.14 and remove later?

lahabana · 2026-02-11T09:02:10Z

docs/madr/decisions/095-mesh-scoped-zone-ingress-egress.md

+2. There is also `networking.advertisedAddress` field (but no `networking.advertisedPort`). 
+It was a very niche Universal-only field [contributed by community](https://github.com/kumahq/kuma/pull/2116) that I think we should remove in v3. 
+I think `networking.zoneIngress.advertisedAddress` should be `required` so it never falls back to `networking.advertisedAddress`.
+


Can we be at the same time:

ZoneEgress, ZoneIngress, Regular DP?

How do we filter in the API to get just the Ingress? Just the Egress?

Does that mean you can have multiple Egress/Ingress?

lahabana · 2026-02-11T09:08:53Z

docs/madr/decisions/095-mesh-scoped-zone-ingress-egress.md

+However, on Universal we can have both sidecar and zone proxy listeners on the same DPP since transparent proxying is not required.
+But the question is do we want to allow that? It might be confusing for users and doesn't allow us having schema level validation.
+
+### Policy Targeting for Zone Ingress and Zone Egress


This should be its own MADR IMO

There will be a separate MADR for policies. Here, I only want to cover how the top-level targetRef will work with the extended Dataplane resource. Since this MADR focuses on the new Dataplane API, I think this part belongs here.

lahabana · 2026-02-11T09:09:32Z

docs/madr/decisions/095-mesh-scoped-zone-ingress-egress.md

+Dataplanes that represent zone proxies don't need `transparentProxying` even on Kubernetes.
+This means on Kubernetes we can't mix `inbounds` and zone proxy listeners on the same DPP.
+However, on Universal we can have both sidecar and zone proxy listeners on the same DPP since transparent proxying is not required.
+But the question is do we want to allow that? It might be confusing for users and doesn't allow us having schema level validation.


OK let's not allow it but we can at least be both Ingress and Egress.

TODO: think if we can make less exceptions if nothing wrong with inbound and zoneIngress/zoneEgress listeners working together then we probably shouldn't limit it

lahabana · 2026-02-11T09:10:34Z

docs/madr/decisions/095-mesh-scoped-zone-ingress-egress.md

+               value: "spiffe://default/"
+```
+
+Field `targetRef.sectionName` can be used to select only zone egress or zone ingress listener. 


Can you show an actual example here?

lahabana · 2026-02-11T09:12:37Z

docs/madr/decisions/095-mesh-scoped-zone-ingress-egress.md

+New `zoneEgress` and `zoneIngress` sections have `name` field and can be selected with `spec.targetRef.sectionName`.
+There are no reasons to keep `kuma.io/proxy-type` label and it should be removed in v3, see [#15567](https://github.com/kumahq/kuma/issues/15567).
+
+### Syncing Zone Ingress Addresses via MeshService


Same other MADR

Not sure. This MADR explains how we’re going to convert the globally scoped ZoneIngress resource, which is synced everywhere, into a mesh-scoped Dataplane resource that is synced only to Global. IMO answering the syncing question here makes the design more complete. The entire doc is still only about 200 lines.

lahabana · 2026-02-11T09:16:25Z

docs/madr/decisions/095-mesh-scoped-zone-ingress-egress.md

+    port: 16739
+    targetPort: target-port-from-container
+    appProtocol: tcp
+  zoneIngress: # different name? maybe 'multizone'?


We need a better name.

Also I feel like we should keep the same field names and on Ingress (advertised).

todo: single MeshZoneAddress resource per zone?

spec: address: 192.168.0.1 port: 10001 status: origin: # k8s service ???

todo: write why can't we use zone object?

lahabana · 2026-02-11T09:17:04Z

docs/madr/decisions/095-mesh-scoped-zone-ingress-egress.md

+    zoneIngress:
+      address: 10.0.0.1 # required, address listener binds to
+      port: 10001 # required, port listener binds to
+      advertisedAddress: 192.168.1.100  # required, address visible to other zones


There's something wrong about this because advertisedAddress is common to all ZoneIngress...

It’s the same today, right? Multiple ZoneIngress resources in the same zone can have the same advertisedAddress when they're behind the LB

The fact that it is like this today doesn't mean it's right :)

TODO:

There are 2 flows possible:

meshservice_controller.go watches Service which is labels as "ingress" and reconciles MS (or . In that case we don't need the advertisedAddress in DPP

pod_controller.go reconciles

We'd like to get rid of the advertisedAddress in the DPP.

lobkovilya added 2 commits February 9, 2026 14:37

initial draft, missing address sync

630b13a

Signed-off-by: Ilya Lobkov <[email protected]>

update the madr

2df7ef0

Signed-off-by: Ilya Lobkov <[email protected]>

lobkovilya commented Feb 9, 2026

View reviewed changes

docs/madr/decisions/095-mesh-scoped-zone-ingress-egress.md Show resolved Hide resolved

lobkovilya commented Feb 9, 2026

View reviewed changes

docs/madr/decisions/095-mesh-scoped-zone-ingress-egress.md Outdated Show resolved Hide resolved

lobkovilya commented Feb 9, 2026

View reviewed changes

docs/madr/decisions/095-mesh-scoped-zone-ingress-egress.md Show resolved Hide resolved

review

67b2535

Signed-off-by: Ilya Lobkov <[email protected]>

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

lobkovilya added 3 commits February 9, 2026 21:26

mes status section

24dc062

Signed-off-by: Ilya Lobkov <[email protected]>

remove deprecation section

324cba0

Signed-off-by: Ilya Lobkov <[email protected]>

fix style and grammar

3fba522

lobkovilya marked this pull request as ready for review February 10, 2026 09:12

lobkovilya requested a review from a team as a code owner February 10, 2026 09:12

lobkovilya requested review from Copilot, lukidzi and slonka February 10, 2026 09:12

Copilot started reviewing on behalf of lobkovilya February 10, 2026 09:13 View session

Copilot AI reviewed Feb 10, 2026

View reviewed changes

Apply suggestions from code review

df4e45a

Co-authored-by: Copilot <[email protected]> Signed-off-by: Ilya Lobkov <[email protected]>

lahabana reviewed Feb 11, 2026

View reviewed changes


		##### Open Questions

		1. Should `networking.zoneIngress` and `networking.zoneEgress` be an array?

docs(MADR): mesh-scoped zone proxies representation and address syncing #15566

Are you sure you want to change the base?

docs(MADR): mesh-scoped zone proxies representation and address syncing #15566

Uh oh!

Conversation

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

Uh oh!

Motivation

Supporting documentation

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Feb 9, 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!

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!

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!

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!

2 participants

lobkovilya commented Feb 9, 2026 •

edited

Loading