Usage
Define ListenerSets for HAProxy Unified Gateway
A ListenerSet lets you define listeners separately from a Gateway definition, making it possible to reuse a set of listeners across gateways and delegate ownership of listeners to application teams. The Gateway indicates which ListenerSets can attach to it, and each ListenerSet adds ports, hostnames, and TLS settings, enabling a delegated management model suitable for multi-tenant environments at scale. Instead of cramming up to 64 listeners into one Gateway object, you can deploy more than 64 listeners with ListenerSets.
Prerequisites checklist Jump to heading
Before continuing, ensure that you’ve met these prerequisites:
Allow ListenerSets on a Gateway Jump to heading
-
Set
allowedListenersin the Gateway’s spec. In the following example, only ListenerSets in namespaces labeledbelongs-to: app-team-1may attach:gateway.yamlyamlapiVersion: gateway.networking.k8s.io/v1kind: Gatewaymetadata:name: example-haproxy-gatewaynamespace: defaultspec:gatewayClassName: haproxyallowedListeners:namespaces:from: Selectorselector:matchLabels:belongs-to: app-team-1listeners:- name: http-listenerprotocol: HTTPport: 31080allowedRoutes:kinds:- group: gateway.networking.k8s.iokind: HTTPRoutenamespaces:from: Samegateway.yamlyamlapiVersion: gateway.networking.k8s.io/v1kind: Gatewaymetadata:name: example-haproxy-gatewaynamespace: defaultspec:gatewayClassName: haproxyallowedListeners:namespaces:from: Selectorselector:matchLabels:belongs-to: app-team-1listeners:- name: http-listenerprotocol: HTTPport: 31080allowedRoutes:kinds:- group: gateway.networking.k8s.iokind: HTTPRoutenamespaces:from: SameThe
allowedListeners.namespaces.fromfield accepts these values:Field Description NoneThe default. No ListenerSets may attach; only the Gateway’s own listeners are used. SameOnly ListenerSets in the Gateway’s own namespace may attach. AllListenerSets in any namespace may attach, as long as their parentRefnames this Gateway.SelectorOnly ListenerSets in namespaces matching selector.matchLabelsmay attach. Requires theselectorfield. -
Apply the change with
kubectl:nixkubectl apply -f gateway.yamlnixkubectl apply -f gateway.yamloutputtextgateway.gateway.networking.k8s.io/example-haproxy-gateway configuredoutputtextgateway.gateway.networking.k8s.io/example-haproxy-gateway configured -
Label the namespace where the application team will declare its ListenerSet, so that the selector admits it:
nixkubectl label namespace team-1-namespace belongs-to=app-team-1nixkubectl label namespace team-1-namespace belongs-to=app-team-1outputtextnamespace/team-1-namespace labeledoutputtextnamespace/team-1-namespace labeled -
Create the ListenerSet in the application team’s namespace. It names the parent Gateway in
parentRefand declares the listeners the team needs:listenerset.yamlyamlapiVersion: gateway.networking.k8s.io/v1kind: ListenerSetmetadata:name: team-1-listenersnamespace: team-1-namespacespec:parentRef:group: gateway.networking.k8s.iokind: Gatewaynamespace: defaultname: example-haproxy-gatewaylisteners:- name: https-listenerhostname: app.team-1.example.comprotocol: HTTPSport: 443tls:mode: TerminatecertificateRefs:- kind: Secretgroup: ""name: app-team-1-certallowedRoutes:kinds:- group: gateway.networking.k8s.iokind: HTTPRoutenamespaces:from: Samelistenerset.yamlyamlapiVersion: gateway.networking.k8s.io/v1kind: ListenerSetmetadata:name: team-1-listenersnamespace: team-1-namespacespec:parentRef:group: gateway.networking.k8s.iokind: Gatewaynamespace: defaultname: example-haproxy-gatewaylisteners:- name: https-listenerhostname: app.team-1.example.comprotocol: HTTPSport: 443tls:mode: TerminatecertificateRefs:- kind: Secretgroup: ""name: app-team-1-certallowedRoutes:kinds:- group: gateway.networking.k8s.iokind: HTTPRoutenamespaces:from: SameLet’s briefly consider these fields:
Field Description parentRefThe Gateway this ListenerSet contributes to. namespaceis required when the Gateway is in another namespacep; in this example,default. This is allowed because it’s matching on a label assigned to theteam-1-namespacenamespace because oflisteners.allowedRoutes.namespaces.from: Same.listenersThe same listener syntax the Gateway uses. For examples, see Add listeners. allowedRoutesRestricts which Routes can attach to the contributed listener. It’s enforced per listener, not for the ListenerSet as a whole. -
Apply the changes using
kubectl:nixkubectl apply -f listenerset.yamlnixkubectl apply -f listenerset.yamloutputtextlistenerset.gateway.networking.k8s.io/team-1-listeners createdoutputtextlistenerset.gateway.networking.k8s.io/team-1-listeners created -
Confirm that the Gateway admitted it. The Gateway reports how many ListenerSets it has attached, and the ListenerSet reports its own
AcceptedandProgrammedconditions:nixkubectl get gateway example-haproxy-gateway -n default \-o jsonpath='{.status.attachedListenerSets}'nixkubectl get gateway example-haproxy-gateway -n default \-o jsonpath='{.status.attachedListenerSets}'outputtext1outputtext1nixkubectl get listenerset team-1-listeners -n team-1-namespace \-o jsonpath='{range .status.conditions[*]}{.type}={.status} {.reason}{"\n"}{end}'nixkubectl get listenerset team-1-listeners -n team-1-namespace \-o jsonpath='{range .status.conditions[*]}{.type}={.status} {.reason}{"\n"}{end}'outputtextAccepted=True AcceptedProgrammed=True ProgrammedoutputtextAccepted=True AcceptedProgrammed=True Programmed
A ListenerSet’s conditions are summaries of its listeners: Accepted is true when at least one contributed listener is accepted, and Programmed comes from the resource that declared the listener. Each listener also gets its own status entry, exactly as a Gateway’s listeners do.
Attach routes to a ListenerSet Jump to heading
Routes attach to a ListenerSet the same way they attach to a Gateway, through parentRefs. In the following example, the HTTPRoute targets the listener names https-listener in the ListenerSet:
httproute.yamlyamlapiVersion: gateway.networking.k8s.io/v1kind: HTTPRoutemetadata:name: app-routenamespace: team-1-namespacespec:parentRefs:- group: gateway.networking.k8s.iokind: ListenerSetname: team-1-listenerssectionName: https-listenerrules:- backendRefs:- name: app-servicenamespace: team-1-namespaceport: 8080
httproute.yamlyamlapiVersion: gateway.networking.k8s.io/v1kind: HTTPRoutemetadata:name: app-routenamespace: team-1-namespacespec:parentRefs:- group: gateway.networking.k8s.iokind: ListenerSetname: team-1-listenerssectionName: https-listenerrules:- backendRefs:- name: app-servicenamespace: team-1-namespaceport: 8080
Omit sectionName and the Route attaches to every listener in the ListenerSet. The listeners’ own allowedRoutes still apply, so a listener that admits only HTTPRoute resources in its own namespace refuses a Route from anywhere else, and a Route having a refused parent ListenerSet is refused with it.
If a Route must attach to a listener on the ListenerSet and to a listener on the Gateway itself, list both in parentRefs — the ListenerSet first, then the Gateway, each with its own sectionName.
See also Jump to heading
- To add a Gateway and define its own listeners, see Gateways.
- To define the Routes that attach to listeners, see Routes.
- For the resource definition, see the K8s Gateway API ListenerSet reference.
- See the K8s Gateway API Listener Conflicts reference for how the controller prioritizes conflict resolution.