Tag 7: Mehrmandantenfähigkeit – allowedRoutes, ReferenceGrant, ListenerSet
Ziel: Ein Gateway, mehrere Teams: Jede Rolle darf genau das, was ihr gehört – technisch erzwungen durch RBAC, allowedRoutes, ReferenceGrant und ListenerSet. · Dauer: ca. 75 min · Voraussetzung: Tag 6
Briefing
- Gateway API trennt drei Rollen: Cluster-Operator
(GatewayClass), Plattform-Team (Gateway in
infra), App-Teams (Routes inshop,payments). allowedRoutesam Listener entscheidet, wer sich anhängen darf:Same,AlloderSelectorauf Namespace-Labels, optional eingeschränkt aufkinds.- Namespaceübergreifende Referenzen (Route → Service, Gateway → Secret) brauchen eine ReferenceGrant im Ziel-Namespace. Der Besitzer des Ziels gibt frei, nicht der Anfragende.
- ListenerSet (
v1seit Gateway API v1.5): App-Teams bringen eigene Listener samt Zertifikat mit, ohne das Gateway zu ändern. - Konflikte löst die API deterministisch: älteste Route gewinnt, Status zeigt die Überschneidung.
| Rolle | Gruppe im Lab | Darf | Darf nicht |
|---|---|---|---|
| Cluster-Operator | team-cluster |
GatewayClasses | Gateways, Routes ändern |
| Plattform-Team | team-infra |
Gateways, Certificates in infra |
Routes der Teams |
| App-Team Shop | team-shop |
Routes, ListenerSets in shop |
Gateway, ReferenceGrants |
Drill 1: RBAC pro Rolle
Das komplette Manifest (drei Rollen plus Lese-Recht auf das Gateway)
liegt im Begleitcode unter ~/gw-lab/code/tag07/rbac.yaml.
Der Kern für das App-Team:
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
name: gw-app-dev
namespace: shop
rules:
- apiGroups: ["gateway.networking.k8s.io"]
resources: ["httproutes", "grpcroutes", "listenersets"]
verbs: ["*"]
# dazu: ClusterRole gw-cluster-operator (gatewayclasses, Gruppe team-cluster),
# Role gw-infra (gateways, referencegrants, certificates in infra, team-infra),
# Role gw-viewer (gateways lesen in infra, team-shop)mkdir -p ~/gw-lab/tag07 && cd ~/gw-lab/tag07
export GW_IP=$(gw-ip.sh) CA=~/gw-lab/tag04/lab-ca.crt
kubectl apply -f ~/gw-lab/code/tag07/rbac.yamlJetzt die Probe – --as/--as-group
simulieren die Lab-User:
ci() { printf '%-58s %s\n' "$*" "$(kubectl auth can-i "$@" 2>/dev/null)"; }
ci create gatewayclasses --as=carla --as-group=team-cluster
ci create gateways -n infra --as=carla --as-group=team-cluster
ci patch gateways -n infra --as=ingo --as-group=team-infra
ci create httproutes -n shop --as=ingo --as-group=team-infra
ci create httproutes -n shop --as=sam --as-group=team-shop
ci get gateways -n infra --as=sam --as-group=team-shop
ci patch gateways -n infra --as=sam --as-group=team-shop
ci create httproutes -n payments --as=sam --as-group=team-shop
ci create referencegrants -n shop --as=sam --as-group=team-shop
ci create listenersets -n shop --as=sam --as-group=team-shopErwartet:
create gatewayclasses --as=carla --as-group=team-cluster yes
create gateways -n infra --as=carla --as-group=team-cluster no
patch gateways -n infra --as=ingo --as-group=team-infra yes
create httproutes -n shop --as=ingo --as-group=team-infra no
create httproutes -n shop --as=sam --as-group=team-shop yes
get gateways -n infra --as=sam --as-group=team-shop yes
patch gateways -n infra --as=sam --as-group=team-shop no
create httproutes -n payments --as=sam --as-group=team-shop no
create referencegrants -n shop --as=sam --as-group=team-shop no
create listenersets -n shop --as=sam --as-group=team-shop yes
referencegrants gibt es bewusst nicht für das App-Team:
Wer Zugriff auf seinen Namespace freigibt, entscheidet in diesem Lab der
Plattform-Prozess (Drill 3).
Fortschritt speichern? Kostenlos registrieren
Drill 2: allowedRoutes mit Namespace-Selector
Bisher stand an jedem Listener from: All. Die Namespaces
tragen seit Tag 0 das Label gw-lab/team. Das Plattform-Team
bindet jeden Listener an die Teams, denen er gehört. Das komplette
Manifest mit allen sieben Listenern liegt im Begleitcode unter
~/gw-lab/code/tag07/gateway-mandanten.yaml. Der
entscheidende Ausschnitt:
spec:
allowedListeners: # ListenerSets nur aus App-Team-Namespaces (Drill 5)
namespaces:
from: Selector
selector:
matchLabels:
gw-lab/team: shop
listeners:
- name: http # nur der HTTPS-Redirect aus infra
protocol: HTTP
port: 80
allowedRoutes:
namespaces:
from: Same
- name: https-shop
# ... tls wie an Tag 4 ...
allowedRoutes:
namespaces:
from: Selector
selector:
matchLabels:
gw-lab/team: shop
- name: https-api # geteilt: shop und payments
# ... tls wie an Tag 4 ...
allowedRoutes:
namespaces:
from: Selector
selector:
matchExpressions:
- key: gw-lab/team
operator: In
values: [shop, payments]
kinds:
- kind: HTTPRoute
# tls-secure: shop · https-grpc, tcp, udp: payments (jeweils mit kinds)kubectl apply -f ~/gw-lab/code/tag07/gateway-mandanten.yaml
kubectl -n infra get gateway web -o json \
| jq -r '.status.listeners[] | "\(.name) \(.attachedRoutes)"'Erwartet:
gateway.gateway.networking.k8s.io/web configured
http 1
https-shop 1
https-api 2
tls-secure 1
https-grpc 1
tcp 1
udp 1
Alle bestehenden Routes hängen noch – jede kommt aus dem richtigen
Namespace. Jetzt versucht ein fremdes Team, sich /admin auf
dem Shop-Hostname zu sichern:
kubectl create namespace rogue
cat > rogue.yaml <<'EOF'
# Ein fremdes Team versucht, sich an den Shop-Listener zu hängen
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: kapern
namespace: rogue
spec:
parentRefs:
- name: web
namespace: infra
sectionName: https-shop
hostnames:
- shop.gw.localtest.me
rules:
- matches:
- path: {type: PathPrefix, value: /admin}
backendRefs:
- name: irgendwas
port: 80
EOF
kubectl apply -f rogue.yaml
sleep 3
conds.sh httproute kapern rogueErwartet:
namespace/rogue created
httproute.gateway.networking.k8s.io/kapern created
parent infra/web/https-shop:
Accepted=False (NotAllowedByListeners): No listeners included by this parent ref
allowed this attachment.
ResolvedRefs=False (BackendNotFound): Failed to process route rule 0 backendRef 0:
service rogue/irgendwas not found.
(Meldungen umbrochen.) Ohne Label kein Zugang – und RBAC verhindert,
dass das fremde Team sein Namespace-Label selbst setzt, solange es
namespaces nicht patchen darf.
Sicherheit: Der Selector ist nur so stark wie die Kontrolle über Namespace-Labels. Labels wie
gw-lab/teamper Policy (Kyverno, ValidatingAdmissionPolicy) schützen.
Fortschritt speichern? Kostenlos registrieren
Drill 3: ReferenceGrant für ein Backend in einem anderen Namespace
Der Shop will /checkout an die HTTP-API des
Payments-Teams geben:
kubectl apply -f ~/gw-lab/code/tag07/payments-api.yaml # echo-basic, Port 80
cat > checkout-route.yaml <<'EOF'
# Shop-Route mit Backend im Namespace payments
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: checkout
namespace: shop
spec:
parentRefs:
- name: web
namespace: infra
sectionName: https-shop
rules:
- matches:
- path: {type: PathPrefix, value: /checkout}
backendRefs:
- name: payments-api
namespace: payments
port: 80
EOF
kubectl apply -f checkout-route.yaml
kubectl -n payments rollout status deploy/payments-api --timeout=90s
conds.sh httproute checkout shop
s() { # s <host> [pfad] [curl-Optionen ...]
curl -s --cacert "$CA" --resolve "$1:443:$GW_IP" "${@:3}" "https://$1${2:-/}"
}
s shop.gw.localtest.me /checkout -o /dev/null -w '%{http_code}\n'Erwartet (gekürzt):
deployment "payments-api" successfully rolled out
parent infra/web/https-shop:
Accepted=True (Accepted): Route is accepted
ResolvedRefs=False (RefNotPermitted): Failed to process route rule 0 backendRef 0:
Backend ref to Service payments/payments-api not permitted by any ReferenceGrant.
500
Die Route ist angenommen, der Backend-Verweis nicht: Envoy antwortet für diese Regel mit 500. Das Payments-Team gibt frei – in seinem Namespace:
cat > refgrant-backend.yaml <<'EOF'
# Payments erlaubt: HTTPRoutes aus shop dürfen auf Service payments-api zeigen
apiVersion: gateway.networking.k8s.io/v1
kind: ReferenceGrant
metadata:
name: shop-to-payments-api
namespace: payments
spec:
from:
- group: gateway.networking.k8s.io
kind: HTTPRoute
namespace: shop
to:
- group: ""
kind: Service
name: payments-api
EOF
kubectl apply -f refgrant-backend.yaml
sleep 5
conds.sh httproute checkout shop | grep ResolvedRefs
s shop.gw.localtest.me /checkout | jq -r '.service + " " + .namespace'Erwartet:
referencegrant.gateway.networking.k8s.io/shop-to-payments-api created
ResolvedRefs=True (ResolvedRefs): Resolved all the Object references for the Route
payments-api payments
to.name schränkt auf genau einen Service ein. Lässt du
name weg, gilt die Freigabe für alle Services in
payments.
Fortschritt speichern? Kostenlos registrieren
Drill 4: ReferenceGrant für ein Zertifikat
Das Shop-Team verwaltet ein eigenes Zertifikat. Das Plattform-Team
soll es an einem neuen Listener https-aktion nutzen – das
Secret bleibt in shop.
cat > shop-cert.yaml <<'EOF'
# Das Shop-Team verwaltet ein eigenes Zertifikat im eigenen Namespace
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: shop-own
namespace: shop
spec:
secretName: shop-own-tls
dnsNames:
- promo.gw.localtest.me
- aktion.gw.localtest.me
issuerRef:
name: lab-ca
kind: ClusterIssuer
EOF
kubectl apply -f shop-cert.yaml
kubectl -n shop wait certificate/shop-own --for=condition=Ready --timeout=60s
kubectl -n infra patch gateway web --type=json -p '[{"op":"add",
"path":"/spec/listeners/-","value":{"name":"https-aktion","protocol":"HTTPS",
"port":443,"hostname":"aktion.gw.localtest.me",
"tls":{"certificateRefs":[{"name":"shop-own-tls","namespace":"shop"}]},
"allowedRoutes":{"namespaces":{"from":"Selector",
"selector":{"matchLabels":{"gw-lab/team":"shop"}}}}}}]'
sleep 5
conds.sh gateway web infra | grep -A2 https-aktionErwartet:
certificate.cert-manager.io/shop-own condition met
gateway.gateway.networking.k8s.io/web patched
listener https-aktion (attachedRoutes=0):
ResolvedRefs=False (RefNotPermitted): No valid secrets exist: certificate refs 0:
Certificate ref to secret shop/shop-own-tls not permitted by any ReferenceGrant.
Das Gateway selbst meldet
Accepted=True (ListenersNotValid) – die übrigen Listener
laufen weiter. Freigabe durch den Besitzer des Secrets:
cat > refgrant-secret.yaml <<'EOF'
# Shop erlaubt: Gateways aus infra dürfen das Secret shop-own-tls nutzen
apiVersion: gateway.networking.k8s.io/v1
kind: ReferenceGrant
metadata:
name: infra-gateway-to-shop-cert
namespace: shop
spec:
from:
- group: gateway.networking.k8s.io
kind: Gateway
namespace: infra
to:
- group: ""
kind: Secret
name: shop-own-tls
EOF
kubectl apply -f refgrant-secret.yaml
sleep 5
conds.sh gateway web infra | grep -A3 https-aktion | grep ResolvedRefsErwartet:
referencegrant.gateway.networking.k8s.io/infra-gateway-to-shop-cert created
ResolvedRefs=True (ResolvedRefs): Listener references have been resolved
Achtung: Der cert-manager-Shim stellt für Listener mit
certificateRefsin einem fremden Namespace nichts aus. Das Zertifikat ist hier bewusst Sache des Shop-Teams.
Fortschritt speichern? Kostenlos registrieren
Drill 5: ListenerSet – Self-Service-Listener
Mit ListenerSet muss das Shop-Team gar nicht mehr beim Plattform-Team
anfragen. Das Gateway erlaubt es per allowedListeners
(Drill 2) – nur aus gw-lab/team=shop.
cat > listenerset.yaml <<'EOF'
# Self-Service: das Shop-Team bringt Listener und Zertifikat selbst mit
apiVersion: gateway.networking.k8s.io/v1
kind: ListenerSet
metadata:
name: shop-promo
namespace: shop
spec:
parentRef:
name: web
namespace: infra
kind: Gateway
group: gateway.networking.k8s.io
listeners:
- name: https-promo
protocol: HTTPS
port: 443
hostname: promo.gw.localtest.me
tls:
mode: Terminate
certificateRefs:
- kind: Secret
group: ""
name: shop-own-tls
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: promo
namespace: shop
spec:
parentRefs:
- name: shop-promo
kind: ListenerSet
group: gateway.networking.k8s.io
sectionName: https-promo
rules:
- backendRefs:
- name: shop-v2
port: 80
EOF
kubectl apply -f listenerset.yaml
sleep 5
kubectl get listenersets -A
conds.sh httproute promo shop
s promo.gw.localtest.me | jq -r .serviceErwartet:
listenerset.gateway.networking.k8s.io/shop-promo created
httproute.gateway.networking.k8s.io/promo created
NAMESPACE NAME ACCEPTED PROGRAMMED AGE
shop shop-promo True True 5s
parent /shop-promo/https-promo:
Accepted=True (Accepted): Route is accepted
ResolvedRefs=True (ResolvedRefs): Resolved all the Object references for the Route
shop-v2
Die Route hängt an der ListenerSet (kind: ListenerSet),
nicht am Gateway. Das Zertifikat liegt im selben Namespace wie die
ListenerSet – keine ReferenceGrant nötig.
Gegenprobe aus payments, das nicht im Selector
steht:
kubectl apply -f - <<'EOF'
apiVersion: gateway.networking.k8s.io/v1
kind: ListenerSet
metadata:
name: pay-extra
namespace: payments
spec:
parentRef: {name: web, namespace: infra}
listeners:
- {name: http-pay, protocol: HTTP, port: 80, hostname: pay.gw.localtest.me}
EOF
sleep 5
kubectl -n payments get listenerset pay-extra \
-o jsonpath='{.status.conditions[0].reason}: {.status.conditions[0].message}{"\n"}'
kubectl -n infra get gateway web -o jsonpath='{.status.attachedListenerSets}{"\n"}'Erwartet:
listenerset.gateway.networking.k8s.io/pay-extra created
NotAllowed: ListenerSet attachment from namespace payments not allowed by Gateway
infra/web
1
Tipp:
kubectl -n shop get listenerset shop-promo -o yamlzeigt am Listener zusätzlichOverlappingTLSConfig=True:aktionundpromonutzen dasselbe Zertifikat. Das ist ein Hinweis, kein Fehler.
Fortschritt speichern? Kostenlos registrieren
Drill 6: Konflikte und Vorrang
Zwei Teams beanspruchen denselben Pfad auf dem geteilten Listener
https-api:
mk() { # mk <name> <namespace> <PathPrefix|Exact> <pfad> <service>
kubectl apply -f - <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata: {name: $1, namespace: $2}
spec:
parentRefs:
- {name: web, namespace: infra, sectionName: https-api}
rules:
- matches:
- path: {type: $3, value: $4}
backendRefs:
- {name: $5, port: 80}
EOF
}
mk bestellung payments PathPrefix /bestellung payments-api
sleep 2
mk bestellung shop PathPrefix /bestellung shop-v1
sleep 5
s api.gw.localtest.me /bestellung/7 | jq -r .service
conds.sh httproute bestellung shop | grep OverlapErwartet:
httproute.gateway.networking.k8s.io/bestellung created
httproute.gateway.networking.k8s.io/bestellung created
payments-api
RouteRulesOverlap=True (RouteRulesOverlap): Overlapping match conditions with
route(s): HTTPRoute payments/bestellung
Gleich spezifische Regeln: Die älteste Route gewinnt
(danach alphabetisch nach Namespace/Name). Beide bleiben
Accepted=True; Envoy Gateway meldet die Überschneidung als
RouteRulesOverlap. Spezifischer schlägt älter:
mk bestellung-neu shop Exact /bestellung/neu shop-v2
sleep 5
s api.gw.localtest.me /bestellung/neu | jq -r .service
s api.gw.localtest.me /bestellung/7 | jq -r .serviceErwartet:
httproute.gateway.networking.k8s.io/bestellung-neu created
shop-v2
payments-api
| Vorrang (HTTPRoute) | Beispiel |
|---|---|
| 1. Exact vor längstem Prefix | Exact /bestellung/neu vor /bestellung |
| 2. Methode, dann mehr Header-, dann mehr Query-Matches | GET + Header vor nur Pfad |
| 3. Älteste Route | payments/bestellung vor
shop/bestellung |
4. Alphabetisch namespace/name |
a/x vor b/x |
Fortschritt speichern? Kostenlos registrieren
Drill 7: Status-Lagebild über alle Teams
Das Plattform-Team will auf einen Blick sehen, welche Routes irgendwo hängen:
for k in httproute grpcroute tlsroute tcproute udproute; do
kubectl get $k -A -o json | jq -r --arg k $k '.items[] | . as $r
| .status.parents[]?.conditions[]?
| select(.status == "False" or .type == "RouteRulesOverlap")
| "\($k) \($r.metadata.namespace)/\($r.metadata.name)"
+ " \(.type)=\(.status) \(.reason)"'
done
kubectl get listenersets -AErwartet (gekürzt, kann je nach Version abweichen):
httproute payments/bestellung RouteRulesOverlap=True RouteRulesOverlap
httproute rogue/kapern Accepted=False NotAllowedByListeners
httproute rogue/kapern ResolvedRefs=False BackendNotFound
httproute shop/bestellung RouteRulesOverlap=True RouteRulesOverlap
NAMESPACE NAME ACCEPTED PROGRAMMED AGE
payments pay-extra False False 2m
shop shop-promo True True 3m
| Condition / Reason | Bedeutung | Wer handelt |
|---|---|---|
Accepted=False /
NotAllowedByListeners |
Namespace oder Kind nicht erlaubt | Plattform-Team |
ResolvedRefs=False / RefNotPermitted |
ReferenceGrant fehlt | Besitzer des Ziels |
ResolvedRefs=False / BackendNotFound |
Service fehlt oder Tippfehler | App-Team |
RouteRulesOverlap=True |
Regeln überschneiden sich | beide Teams |
Dieselbe Abfrage gehört als Alarm ins Monitoring (Tag 11).
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
cd ~/gw-lab/tag07
check() { if eval "$2" >/dev/null 2>&1; then echo "✔ $1"; else echo "✘ $1"; fi; }
export GW_IP=$(gw-ip.sh) CA=~/gw-lab/tag04/lab-ca.crt
s() { curl -s --cacert "$CA" --resolve "$1:443:$GW_IP" "${@:3}" "https://$1${2:-/}"; }
check "App-Team darf Gateway nicht patchen" \
'! kubectl auth can-i patch gateways -n infra --as=sam --as-group=team-shop'
check "rogue abgewiesen" \
'conds.sh httproute kapern rogue | grep -q NotAllowedByListeners'
check "Checkout über ReferenceGrant" \
'[ "$(s shop.gw.localtest.me /checkout | jq -r .service)" = payments-api ]'
check "Listener https-aktion ResolvedRefs" \
'conds.sh gateway web infra | grep -A3 https-aktion | grep -q "ResolvedRefs=True"'
check "ListenerSet shop-promo liefert" \
'[ "$(s promo.gw.localtest.me | jq -r .service)" = shop-v2 ]'
check "ListenerSet aus payments abgewiesen" \
'kubectl -n payments get listenerset pay-extra -o json \
| jq -e ".status.conditions[] | select(.reason==\"NotAllowed\")"'Erwartet:
✔ App-Team darf Gateway nicht patchen
✔ rogue abgewiesen
✔ Checkout über ReferenceGrant
✔ Listener https-aktion ResolvedRefs
✔ ListenerSet shop-promo liefert
✔ ListenerSet aus payments abgewiesen
Challenge
Das Payments-Team soll ebenfalls ListenerSets anlegen dürfen. Passe
Gateway und RBAC an, bringe pay-extra auf
Accepted=True und hänge eine Route an, die
pay.gw.localtest.me auf payments-api schickt.
Räume danach rogue und die bestellung-Routes
auf.
Hinweis: allowedListeners kennt wie
allowedRoutes auch matchExpressions.
Lösung
kubectl -n infra patch gateway web --type=merge -p '{"spec":{"allowedListeners":
{"namespaces":{"from":"Selector","selector":{"matchExpressions":[
{"key":"gw-lab/team","operator":"In","values":["shop","payments"]}]}}}}}'
kubectl -n payments create role gw-app-dev --verb='*' \
--resource=httproutes.gateway.networking.k8s.io,listenersets.gateway.networking.k8s.io
kubectl -n payments create rolebinding gw-app-dev --role=gw-app-dev \
--group=team-payments
kubectl apply -f - <<'EOF'
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: pay
namespace: payments
spec:
parentRefs:
- {name: pay-extra, kind: ListenerSet, group: gateway.networking.k8s.io,
sectionName: http-pay}
rules:
- backendRefs:
- {name: payments-api, port: 80}
EOF
sleep 5
kubectl -n payments get listenerset pay-extra
curl -s --resolve pay.gw.localtest.me:80:$GW_IP http://pay.gw.localtest.me/ \
| jq -r .service
kubectl delete namespace rogue
kubectl -n shop delete httproute bestellung bestellung-neu
kubectl -n payments delete httproute bestellungErwartet (gekürzt, kann je nach Version abweichen):
gateway.gateway.networking.k8s.io/web patched
role.rbac.authorization.k8s.io/gw-app-dev created
rolebinding.rbac.authorization.k8s.io/gw-app-dev created
httproute.gateway.networking.k8s.io/pay created
NAME ACCEPTED PROGRAMMED AGE
pay-extra True True 6m
payments-api
namespace "rogue" deleted
...
Der Listener http-pay hat einen Hostname und ist damit
spezifischer als http mit dem HTTPS-Redirect –
pay.gw.localtest.me wird nicht umgeleitet.
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- Ein Gateway pro Umgebung und Sicherheitszone, nicht pro Team. Mandanten trennt man über Listener, allowedRoutes und ListenerSets – ein eigenes Gateway nur bei harter Isolation (eigene IP, eigene Envoy-Pods).
- Namespace-Labels sind die eigentliche Sicherheitsgrenze: per Admission-Policy schützen und nur über die Namespace-Provisionierung (GitOps) setzen.
- ReferenceGrants versionieren und reviewen wie Firewall-Regeln: immer
mit
to.name, nie pauschal für alle Services oder Secrets eines Namespaces. - ListenerSet erlaubt Self-Service-TLS, braucht aber Leitplanken: erlaubte Hostnames per Policy begrenzen, sonst beansprucht ein Team fremde Domains.
RouteRulesOverlapundAccepted=Falseals Alarm ins Monitoring – Konflikte fallen sonst erst auf, wenn ein Team „seinen” Traffic verliert.