Skip to content

docs: recommend ListenerSet over mergeGateways #9524

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
zhaohuabing merged 2 commits into from
Jul 21, 2026
+19 −0
Merged

docs: recommend ListenerSet over mergeGateways #9524

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
05ceef7
docs: recommend ListenerSet over mergeGateways
zhaohuabing Jul 19, 2026
4d4e05e
fix docs lint
zhaohuabing Jul 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions site/content/en/latest/tasks/operations/deployment-mode.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,16 @@ Please follow the example [Multi-tenancy](#multi-tenancy).

### Merged Gateways onto a single EnvoyProxy fleet

{{% alert title="Recommendation" color="primary" %}}

The `mergeGateways` feature was introduced before the Gateway API supported [ListenerSet][]. For splitting listeners
across multiple resources, prefer [ListenerSet][]: it is the Gateway API-native mechanism, it removes the
single-Gateway 64-listener limit, and it enables a delegated management model where a platform team owns the Gateway
and application teams define ports, hostnames, and TLS certificates in their own ListenerSets, suitable for
high-scale, multi-tenant environments. See the [ListenerSet user guide][] and [issue 1230][] for details.

{{% /alert %}}

By default, each Gateway has its own dedicated set of Envoy Proxy and its configurations.
However, for some deployments, it may be more convenient to merge listeners across multiple Gateways and deploy a single Envoy Proxy fleet.

Expand Down Expand Up @@ -659,6 +669,12 @@ Handling connection for 8889

### Merged gateways deployment

{{% alert title="Recommendation" color="primary" %}}

For new deployments, consider using [ListenerSet][] instead of `mergeGateways`.

{{% /alert %}}

In this example, we will deploy GatewayClass

```shell
Expand Down Expand Up @@ -1083,3 +1099,6 @@ curl --header "Host: www.merged3.com" http://$GATEWAY_HOST:8082/example3
[Gateway Namespace Mode]: ./gateway-namespace-mode
[issue1231]: https://github.com/envoyproxy/gateway/issues/1231
[issue2629]: https://github.com/envoyproxy/gateway/issues/2629
[issue 1230]: https://github.com/envoyproxy/gateway/issues/1230
[ListenerSet]: https://gateway-api.sigs.k8s.io/reference/api-types/listenerset/
[ListenerSet user guide]: https://gateway-api.sigs.k8s.io/guides/user-guides/listener-set/