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

  1. Set allowedListeners in the Gateway’s spec. In the following example, only ListenerSets in namespaces labeled belongs-to: app-team-1 may attach:

    gateway.yaml
    yaml
    apiVersion: gateway.networking.k8s.io/v1
    kind: Gateway
    metadata:
    name: example-haproxy-gateway
    namespace: default
    spec:
    gatewayClassName: haproxy
    allowedListeners:
    namespaces:
    from: Selector
    selector:
    matchLabels:
    belongs-to: app-team-1
    listeners:
    - name: http-listener
    protocol: HTTP
    port: 31080
    allowedRoutes:
    kinds:
    - group: gateway.networking.k8s.io
    kind: HTTPRoute
    namespaces:
    from: Same
    gateway.yaml
    yaml
    apiVersion: gateway.networking.k8s.io/v1
    kind: Gateway
    metadata:
    name: example-haproxy-gateway
    namespace: default
    spec:
    gatewayClassName: haproxy
    allowedListeners:
    namespaces:
    from: Selector
    selector:
    matchLabels:
    belongs-to: app-team-1
    listeners:
    - name: http-listener
    protocol: HTTP
    port: 31080
    allowedRoutes:
    kinds:
    - group: gateway.networking.k8s.io
    kind: HTTPRoute
    namespaces:
    from: Same

    The allowedListeners.namespaces.from field accepts these values:

    Field Description
    None The default. No ListenerSets may attach; only the Gateway’s own listeners are used.
    Same Only ListenerSets in the Gateway’s own namespace may attach.
    All ListenerSets in any namespace may attach, as long as their parentRef names this Gateway.
    Selector Only ListenerSets in namespaces matching selector.matchLabels may attach. Requires the selector field.
  2. Apply the change with kubectl:

    nix
    kubectl apply -f gateway.yaml
    nix
    kubectl apply -f gateway.yaml
    output
    text
    gateway.gateway.networking.k8s.io/example-haproxy-gateway configured
    output
    text
    gateway.gateway.networking.k8s.io/example-haproxy-gateway configured
  3. Label the namespace where the application team will declare its ListenerSet, so that the selector admits it:

    nix
    kubectl label namespace team-1-namespace belongs-to=app-team-1
    nix
    kubectl label namespace team-1-namespace belongs-to=app-team-1
    output
    text
    namespace/team-1-namespace labeled
    output
    text
    namespace/team-1-namespace labeled
  4. Create the ListenerSet in the application team’s namespace. It names the parent Gateway in parentRef and declares the listeners the team needs:

    listenerset.yaml
    yaml
    apiVersion: gateway.networking.k8s.io/v1
    kind: ListenerSet
    metadata:
    name: team-1-listeners
    namespace: team-1-namespace
    spec:
    parentRef:
    group: gateway.networking.k8s.io
    kind: Gateway
    namespace: default
    name: example-haproxy-gateway
    listeners:
    - name: https-listener
    hostname: app.team-1.example.com
    protocol: HTTPS
    port: 443
    tls:
    mode: Terminate
    certificateRefs:
    - kind: Secret
    group: ""
    name: app-team-1-cert
    allowedRoutes:
    kinds:
    - group: gateway.networking.k8s.io
    kind: HTTPRoute
    namespaces:
    from: Same
    listenerset.yaml
    yaml
    apiVersion: gateway.networking.k8s.io/v1
    kind: ListenerSet
    metadata:
    name: team-1-listeners
    namespace: team-1-namespace
    spec:
    parentRef:
    group: gateway.networking.k8s.io
    kind: Gateway
    namespace: default
    name: example-haproxy-gateway
    listeners:
    - name: https-listener
    hostname: app.team-1.example.com
    protocol: HTTPS
    port: 443
    tls:
    mode: Terminate
    certificateRefs:
    - kind: Secret
    group: ""
    name: app-team-1-cert
    allowedRoutes:
    kinds:
    - group: gateway.networking.k8s.io
    kind: HTTPRoute
    namespaces:
    from: Same

    Let’s briefly consider these fields:

    Field Description
    parentRef The Gateway this ListenerSet contributes to. namespace is required when the Gateway is in another namespacep; in this example, default. This is allowed because it’s matching on a label assigned to the team-1-namespace namespace because of listeners.allowedRoutes.namespaces.from: Same.
    listeners The same listener syntax the Gateway uses. For examples, see Add listeners.
    allowedRoutes Restricts which Routes can attach to the contributed listener. It’s enforced per listener, not for the ListenerSet as a whole.
  5. Apply the changes using kubectl:

    nix
    kubectl apply -f listenerset.yaml
    nix
    kubectl apply -f listenerset.yaml
    output
    text
    listenerset.gateway.networking.k8s.io/team-1-listeners created
    output
    text
    listenerset.gateway.networking.k8s.io/team-1-listeners created
  6. Confirm that the Gateway admitted it. The Gateway reports how many ListenerSets it has attached, and the ListenerSet reports its own Accepted and Programmed conditions:

    nix
    kubectl get gateway example-haproxy-gateway -n default \
    -o jsonpath='{.status.attachedListenerSets}'
    nix
    kubectl get gateway example-haproxy-gateway -n default \
    -o jsonpath='{.status.attachedListenerSets}'
    output
    text
    1
    output
    text
    1
    nix
    kubectl get listenerset team-1-listeners -n team-1-namespace \
    -o jsonpath='{range .status.conditions[*]}{.type}={.status} {.reason}{"\n"}{end}'
    nix
    kubectl get listenerset team-1-listeners -n team-1-namespace \
    -o jsonpath='{range .status.conditions[*]}{.type}={.status} {.reason}{"\n"}{end}'
    output
    text
    Accepted=True Accepted
    Programmed=True Programmed
    output
    text
    Accepted=True Accepted
    Programmed=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.yaml
yaml
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: app-route
namespace: team-1-namespace
spec:
parentRefs:
- group: gateway.networking.k8s.io
kind: ListenerSet
name: team-1-listeners
sectionName: https-listener
rules:
- backendRefs:
- name: app-service
namespace: team-1-namespace
port: 8080
httproute.yaml
yaml
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: app-route
namespace: team-1-namespace
spec:
parentRefs:
- group: gateway.networking.k8s.io
kind: ListenerSet
name: team-1-listeners
sectionName: https-listener
rules:
- backendRefs:
- name: app-service
namespace: team-1-namespace
port: 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

Do you have any suggestions on how we can improve the content of this page? Please leave feedback!