Notice:
This is the "latest" release of Envoy Gateway, which contains the most recent commits from the main branch.
This release might not be stable.
Please refer to the /docs documentation for the most current information.

ListenerSets

ListenerSet is a Gateway API resource that defines listeners in a separate object and attaches them to a Gateway. Instead of declaring every port, hostname, and TLS certificate on the Gateway itself, teams can manage their own listeners in their own namespaces, while all listeners are served by the same Envoy Proxy fleet.

ListenerSets are useful when:

  • You need more than the 64 listeners allowed on a single Gateway.
  • A platform team owns the Gateway, and application teams need to self-service their own ports, hostnames, and TLS certificates without touching the Gateway.
  • Listeners and their TLS secrets must live in a different namespace than the Gateway.

Envoy Gateway supports attaching HTTPRoute (HTTP/HTTPS), GRPCRoute, TLSRoute, TCPRoute, and UDPRoute to ListenerSet listeners. Envoy Gateway policies, including ClientTrafficPolicy, SecurityPolicy, BackendTrafficPolicy, and EnvoyExtensionPolicy, can target a ListenerSet, or a single listener in it via sectionName.

The ListenerSet CRD ships with the Gateway API CRDs installed by Envoy Gateway. No Envoy Gateway configuration is required: the resource is reconciled whenever the CRD is present in the cluster.

Prerequisites

Follow the steps below to install Envoy Gateway and the example manifest. Before proceeding, you should be able to query the example backend using HTTP.

Expand for instructions
  1. Install the Gateway API CRDs and Envoy Gateway using Helm:

    helm install eg oci://docker.io/envoyproxy/gateway-helm --version v0.0.0-latest -n envoy-gateway-system --create-namespace
    
  2. Install the GatewayClass, Gateway, HTTPRoute and example app:

    kubectl apply -f https://github.com/envoyproxy/gateway/releases/download/latest/quickstart.yaml -n default
    
  3. Verify Connectivity:

    Get the External IP of the Gateway:

    export GATEWAY_HOST=$(kubectl get gateway/eg -o jsonpath='{.status.addresses[0].value}')
       

    Curl the example app through Envoy proxy:

    curl --verbose --header "Host: www.example.com" http://$GATEWAY_HOST/get
       

    The above command should succeed with status code 200.

    Get the name of the Envoy service created the by the example Gateway:

    export ENVOY_SERVICE=$(kubectl get svc -n envoy-gateway-system --selector=gateway.envoyproxy.io/owning-gateway-namespace=default,gateway.envoyproxy.io/owning-gateway-name=eg -o jsonpath='{.items[0].metadata.name}')
       

    Get the deployment of the Envoy service created the by the example Gateway:

    export ENVOY_DEPLOYMENT=$(kubectl get deploy -n envoy-gateway-system --selector=gateway.envoyproxy.io/owning-gateway-namespace=default,gateway.envoyproxy.io/owning-gateway-name=eg -o jsonpath='{.items[0].metadata.name}')
       

    Port forward to the Envoy service:

    kubectl -n envoy-gateway-system port-forward service/${ENVOY_SERVICE} 8888:80 &
       

    Curl the example app through Envoy proxy:

    curl --verbose --header "Host: www.example.com" http://localhost:8888/get
       

    The above command should succeed with status code 200.

Configuration

A Gateway must explicitly opt in to ListenerSet attachment through spec.allowedListeners. By default, no ListenerSets are allowed. Update the Gateway from the Quickstart to accept ListenerSets from the same namespace:

cat <<EOF | kubectl apply -f -
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: eg
spec:
  gatewayClassName: eg
  allowedListeners:
    namespaces:
      from: Same
  listeners:
  - name: http
    port: 80
    protocol: HTTP
EOF

Save and apply the following resource to your cluster:

---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: eg
spec:
  gatewayClassName: eg
  allowedListeners:
    namespaces:
      from: Same
  listeners:
  - name: http
    port: 80
    protocol: HTTP

allowedListeners.namespaces.from also supports All and Selector to accept ListenerSets from any namespace or from namespaces matching a label selector, which is the typical setup when application teams manage ListenerSets in their own namespaces.

Create a ListenerSet that adds an extra HTTP listener on port 8080, and an HTTPRoute that attaches to it by referencing the ListenerSet as its parent:

cat <<EOF | kubectl apply -f -
apiVersion: gateway.networking.k8s.io/v1
kind: ListenerSet
metadata:
  name: app-team-listeners
spec:
  parentRef:
    name: eg
  listeners:
  - name: http-8080
    port: 8080
    protocol: HTTP
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: backend-on-8080
spec:
  parentRefs:
  - group: gateway.networking.k8s.io
    kind: ListenerSet
    name: app-team-listeners
    sectionName: http-8080
  rules:
  - backendRefs:
    - name: backend
      port: 3000
EOF

Save and apply the following resources to your cluster:

---
apiVersion: gateway.networking.k8s.io/v1
kind: ListenerSet
metadata:
  name: app-team-listeners
spec:
  parentRef:
    name: eg
  listeners:
  - name: http-8080
    port: 8080
    protocol: HTTP
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: backend-on-8080
spec:
  parentRefs:
  - group: gateway.networking.k8s.io
    kind: ListenerSet
    name: app-team-listeners
    sectionName: http-8080
  rules:
  - backendRefs:
    - name: backend
      port: 3000

Verify that the ListenerSet is accepted and programmed:

kubectl get listenersets

The Gateway status reports the number of attached ListenerSets in status.attachedListenerSets.

Test the new listener:

Get the External IP of the Gateway:

export GATEWAY_HOST=$(kubectl get gateway/eg -o jsonpath='{.status.addresses[0].value}')

Curl the example app through the ListenerSet listener:

curl --verbose --header "Host: www.example.com" http://${GATEWAY_HOST}:8080/

Get the name of the Envoy service created by the example Gateway:

export ENVOY_SERVICE=$(kubectl get svc -n envoy-gateway-system --selector=gateway.envoyproxy.io/owning-gateway-namespace=default,gateway.envoyproxy.io/owning-gateway-name=eg -o jsonpath='{.items[0].metadata.name}')

Port forward to the Envoy service on the ListenerSet port:

kubectl -n envoy-gateway-system port-forward service/${ENVOY_SERVICE} 8080:8080 &

Curl the example app through the ListenerSet listener:

curl --verbose --header "Host: www.example.com" http://localhost:8080/

HTTPS listeners work the same way: a ListenerSet listener can terminate TLS with certificateRefs pointing at Secrets in the ListenerSet’s namespace, so application teams manage their own certificates.

Listener conflicts

Listeners across the Gateway and its ListenerSets must not clash on port, protocol, and hostname. When they do, the Gateway’s own listeners take precedence and conflicted listeners are rejected, reporting Conflicted: True in their status. See the upstream listener conflicts guide for the full rules.

Comparison with Merged Gateways

Before ListenerSet existed in the Gateway API, Envoy Gateway offered the custom Merged Gateways deployment mode (mergeGateways in the EnvoyProxy resource), which collapses the listeners of all Gateways under a GatewayClass onto a single Envoy Proxy fleet. Both features let multiple teams share one data plane, but they work differently:

ListenerSetMerged Gateways (mergeGateways)
APIGateway API-native resource, portable across implementationsEnvoy Gateway-specific EnvoyProxy setting
Unit of sharingOne Gateway shares its infrastructure with many ListenerSetsAll Gateways under one GatewayClass share one Envoy fleet
Opt-inPer Gateway, via spec.allowedListenersPer GatewayClass, via mergeGateways: true in EnvoyProxy
Delegation modelGateway owner controls which namespaces may attach listenersAny Gateway under the GatewayClass is merged, no per-Gateway consent
Listener limit64 per resource, scale by adding ListenerSets to one Gateway64 per resource, scale by adding Gateways under the GatewayClass
Status reportingPer-ListenerSet status, plus attachedListenerSets on the GatewayEach Gateway reports status for its own listeners only
Policy attachmentPolicies can target a ListenerSet or its individual listenersPolicies target each Gateway separately

For new deployments, prefer ListenerSet: it is the upstream Gateway API design for this use case, and it gives the Gateway owner explicit control over who may attach listeners. Moving to ListenerSet requires converting Gateways into ListenerSets and rewriting the parentRefs of every route. See issue 1230 for the original motivation behind mergeGateways.


Last modified November 16, 2026: docs: release note for v1.9.4 (#10615) (c64cfe6)