Tag 14: Kong Ingress Controller
Ziel: Kong als Ingress Controller in k3s betreiben, notes über die Gateway API veröffentlichen, mit Kong-Ressourcen absichern, ohne Ausfall aktualisieren und einen Blick auf Enterprise werfen. · Dauer: ca. 90 min · Voraussetzung: Tag 13
Briefing
- Der Kong Ingress Controller (KIC) liest
Kubernetes-Ressourcen und schreibt daraus die Konfiguration eines Kong
ohne Datenbank: ein
kong.yaml, das aus dem Cluster entsteht. - Routen beschreibst du mit der Gateway API
(
GatewayClass,Gateway,HTTPRoute), Kong-Eigenes mitKongPlugin,KongConsumerund Secrets. - Das Helm-Chart
kong/ingressinstalliert zwei Deployments:kong-controller(KIC) undkong-gateway(der Proxy). - Ein Upgrade ist ein
helm upgrademit neuem Image-Tag, Pod für Pod.
HTTPRoute, KongPlugin, KongConsumer ──► kong-controller ──Admin API──► kong-gateway
:80 (ServiceLB)
curl http://<IP von k3s>/api/v1/notes ─────────────────────────────────►┘ ─► notes-api
Drill 1: k3s auf einer VM
Auf dem Laptop:
multipass launch 24.04 --name k3s --cpus 2 --memory 3G --disk 20G
multipass shell k3sIn der VM k3s. Traefik bleibt aus, Kong übernimmt seine
Rolle:
curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION=v1.36.5+k3s1 sh -s - \
--disable traefik --write-kubeconfig-mode 644
mkdir -p ~/.kube && cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
kubectl wait --for=condition=Ready node --all --timeout=120sErwartet (gekürzt):
[INFO] systemd: Starting k3s
error: no matching resources found
Der Fehler ist harmlos: Direkt nach dem Start hat sich der Node noch
nicht angemeldet, es gibt nichts, worauf kubectl wait
warten könnte. Ein paar Sekunden später:
sleep 20
kubectl get nodesErwartet:
NAME STATUS ROLES AGE VERSION
k3s Ready control-plane 33s v1.36.5+k3s1
Fortschritt speichern? Kostenlos registrieren
Drill 2: Helm, Gateway API und Begleitcode
cd /tmp && V=v4.3.1
curl -fsSLO https://get.helm.sh/helm-$V-linux-amd64.tar.gz
curl -fsSLO https://get.helm.sh/helm-$V-linux-amd64.tar.gz.sha256sum
sha256sum -c helm-$V-linux-amd64.tar.gz.sha256sum
tar xzf helm-$V-linux-amd64.tar.gz linux-amd64/helm
sudo install linux-amd64/helm /usr/local/bin/helm && rm -rf linux-amd64 helm-$V*
helm version --short
GW=https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.3.0
kubectl apply -f $GW/standard-install.yaml | tail -1
git clone https://github.com/thomaszachmann/kong-zum-anfassen.git ~/kong-lab/codeErwartet (gekürzt; auf Apple Silicon arm64 statt
amd64):
helm-v4.3.1-linux-amd64.tar.gz: OK
v4.3.1+gc0d08d0
customresourcedefinition.apiextensions.k8s.io/referencegrants.gateway.networking.k8s.io
created
Cloning into '/home/ubuntu/kong-lab/code'...
KIC 3.5 baut auf Gateway API v1.3.0. Die Ressourcen der Gateway API bringt Kubernetes nicht mit; du installierst sie als CRDs.
Fortschritt speichern? Kostenlos registrieren
Drill 3: Das Image ohne Registry
k3s hat kein Docker. Das Image von notes-api baust du nicht neu,
sondern nimmst es von der VM kong mit. Dort:
docker save -o ~/notes-api.tar notes-api:0.2.0Auf dem Laptop:
multipass transfer kong:/home/ubuntu/notes-api.tar k3s:/home/ubuntu/In der VM k3s:
sudo k3s ctr images import ~/notes-api.tar
sudo k3s ctr images ls | grep notes-api | cut -c1-40Erwartet (gekürzt):
docker.io/library/notes api:0.2.0 saved
application/vnd.oci.image.index.v1+json sha256:7b0d2646bc6e…
Importing elapsed: 1.0 s total: 0.0 B (0.0 B/s)
docker.io/library/notes-api:0.2.0
containerd ergänzt notes-api:0.2.0 zu
docker.io/library/notes-api:0.2.0. Das Deployment holt das
Image mit imagePullPolicy: Never von dort.
Fortschritt speichern? Kostenlos registrieren
Drill 4: Kong Ingress Controller installieren
cd ~/kong-lab/code/tag14
grep -v '^#' kic-values.yaml
helm repo add kong https://charts.konghq.com
helm install kong kong/ingress --version 0.24.0 -n kong --create-namespace \
-f kic-values.yaml --wait --timeout 5m | grep -E 'STATUS|REVISION'
kubectl -n kong get pods
kubectl -n kong get svc kong-gateway-proxyErwartet (gekürzt, IP und Namen weichen bei dir ab):
controller:
ingressController:
image:
tag: "3.5.14"
gateway:
image:
repository: kong
tag: "3.9.3" # bewusst eine Version zurück: Upgrade in Drill 7
env:
plugins: bundled
"kong" has been added to your repositories
STATUS: deployed
REVISION: 1
NAME READY STATUS RESTARTS AGE
kong-controller-6985bb6dc4-bs5m8 1/1 Running 0 54s
kong-gateway-854656f547-mwlvt 1/1 Running 0 54s
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S)
kong-gateway-proxy LoadBalancer 10.43.101.109 192.168.64.9 80:30980/TCP,443:…
Das Chart setzt sonst gleitende Tags (3.9,
3.5); die Werte-Datei pinnt sie. ServiceLB von
k3s gibt dem Proxy die IP der VM auf Port 80.
Fortschritt speichern? Kostenlos registrieren
Drill 5: Gateway und Routes
cd ~/kong-lab/code/tag14/k8s
kubectl apply -f gateway.yaml
kubectl apply -f notes.yaml | tail -1
kubectl -n notes rollout status deploy/notes-api --timeout=120s
kubectl apply -f routes.yaml
sleep 8
kubectl get gateway -n kong
P=http://localhost
curl -s $P/api/v1/notes; echo
curl -s $P/echo/get | jq -r .urlErwartet (gekürzt):
gatewayclass.gateway.networking.k8s.io/kong created
gateway.gateway.networking.k8s.io/kong created
service/echo created
deployment "notes-api" successfully rolled out
httproute.gateway.networking.k8s.io/notes-lesen created
httproute.gateway.networking.k8s.io/echo created
NAME CLASS ADDRESS PROGRAMMED AGE
kong kong 192.168.64.9 True 16s
[]
http://localhost/get
gatewayclass-unmanaged in gateway.yaml sagt
dem KIC: Kong läuft schon, nimm den Proxy aus dem Helm-Chart. Die
HTTPRoute notes-lesen entspricht der Route aus Tag 2:
GET /api/v1/notes, umgeschrieben auf /notes
mit dem Filter URLRewrite.
Fortschritt speichern? Kostenlos registrieren
Drill 6: Schreiben mit Schlüssel
grep -E '^kind:|^plugin:|konghq.com/|name: X-API-Key' schreiben.yaml
kubectl apply -f schreiben.yaml
sleep 10
H='Content-Type: application/json'
curl -s -o /dev/null -w '%{http_code}\n' -X POST -H "$H" -d '{"text":"x"}' \
$P/api/v1/notes
curl -s -w ' %{http_code}\n' -X POST -H 'apikey: lab-key-anna-456' -H "$H" \
-d '{"text":"aus Kubernetes"}' $P/api/v1/notes
kubectl -n notes get kongconsumerErwartet (gekürzt):
kind: KongPlugin
plugin: key-auth
kind: Secret
konghq.com/credential: key-auth
kind: KongConsumer
kind: HTTPRoute
konghq.com/plugins: key-auth
- {name: X-API-Key, value: lab-api-key-123}
kongplugin.configuration.konghq.com/key-auth created
secret/anna-key created
kongconsumer.configuration.konghq.com/anna created
httproute.gateway.networking.k8s.io/notes-schreiben created
401
{"id":"b4b67efb-…","text":"aus Kubernetes"}
201
NAME USERNAME AGE PROGRAMMED
anna anna 8s True
Annas Schlüssel ist ein Secret mit dem Label
konghq.com/credential: key-auth, der Consumer verweist
darauf. Die Annotation konghq.com/plugins hängt
key-auth an die Route. Den Backend-Schlüssel setzt der
Standardfilter RequestHeaderModifier.
Achtung: Ein zusätzlicher
KongPluginvom Typrequest-transformerwirkt hier nicht. Der KIC setztURLRewriteselbst alsrequest-transformerum, und pro Route läuft nur eines dieser Plugins. Gateway-API-Filter haben Vorrang vor Handarbeit.
Frag die Liste ein paarmal:
for i in 1 2 3 4; do curl -s $P/api/v1/notes; echo; doneErwartet (die Reihenfolge schwankt):
[]
[{"id":"b4b67efb-…","text":"aus Kubernetes"}]
[]
[{"id":"b4b67efb-…","text":"aus Kubernetes"}]
Zwei Pods von notes-api, jeder mit eigenem Speicher. Ohne gemeinsame Datenbank („Kubernetes zum Anfassen”, Tag 7) sieht jeder Client je nach Pod andere Daten.
Fortschritt speichern? Kostenlos registrieren
Drill 7: Upgrade ohne Ausfall
Kong 3.9.3 läuft, 3.9.4 ist die aktuelle Version der Linie. Während des Upgrades zählt eine Schleife im Hintergrund jede Antwort:
curl -si $P/echo/get | grep -i '^via'
( ok=0; f=0; ende=$((SECONDS+90))
while [ $SECONDS -lt $ende ]; do
c=$(curl -s -o /dev/null -w '%{http_code}' --max-time 2 $P/echo/get)
[ "$c" = 200 ] && ok=$((ok+1)) || f=$((f+1)); sleep 0.2
done; echo "ok=$ok fehler=$f" ) &
helm upgrade kong kong/ingress --version 0.24.0 -n kong --reuse-values \
--set gateway.image.tag=3.9.4 --wait --timeout 5m | grep -E 'STATUS|REVISION'
wait
curl -si $P/echo/get | grep -i '^via'Erwartet (die Zahl schwankt):
Via: 1.1 kong/3.9.3
STATUS: deployed
REVISION: 2
ok=372 fehler=0
Via: 1.1 kong/3.9.4
Kein einziger Fehler: Kubernetes startet den neuen Pod, wartet auf
seine Bereitschaft und beendet erst dann den alten. Ohne Datenbank gibt
es keine Migrationen; mit Datenbank käme vor dem Wechsel
kong migrations up und danach
kong migrations finish.
Fortschritt speichern? Kostenlos registrieren
Drill 8: Von kong.yaml zu Kubernetes, und Enterprise
Zurück auf der VM kong. decK übersetzt deine
Konfiguration in KIC-Ressourcen:
cd ~/kong-lab/kong
deck file kong2kic -s kong.yaml --class-name kong -o /tmp/kic.yaml
grep '^kind:' /tmp/kic.yaml | sort | uniq -cErwartet:
8 kind: HTTPRoute
4 kind: KongClusterPlugin
4 kind: KongConsumer
16 kind: KongPlugin
2 kind: KongUpstreamPolicy
10 kind: Secret
6 kind: Service
Ein guter Start für einen Umzug, aber kein fertiges Ergebnis: Namespaces, die Services der Backends und die Secrets musst du noch prüfen und anpassen.
Und die Enterprise-Ausgabe? Sie läuft ohne Lizenz:
docker run -d --name ee -p 127.0.0.1:18001:8001 -e KONG_DATABASE=off \
-e KONG_ADMIN_LISTEN=0.0.0.0:8001 kong/kong-gateway:3.16.0.1 > /dev/null
sleep 20
curl -s localhost:18001 | jq -c '{version, edition,
plugins: (.plugins.available_on_server | length)}'
curl -s localhost:18001/license; echo
docker rm -f eeErwartet:
{"version":"3.16.0.1","edition":"enterprise","plugins":114}
{"message":"Not found"}
ee
Version 3.16 statt 3.9, 114 Plugins statt 45, aber keine Lizenz. Was davon ohne Lizenz nutzbar ist, regelt Kongs Lizenzmodell; für ein Labor bleibt OSS 3.9 die freie Wahl.
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
In der VM k3s:
kubectl get gateway -n kong kong \
-o jsonpath='{.status.conditions[?(@.type=="Programmed")].status}'; echoErwartet: Der KIC hat das Gateway übernommen.
True
kubectl -n kong get deploy kong-gateway \
-o jsonpath='{.spec.template.spec.containers[0].image}'; echoErwartet: die Version nach dem Upgrade.
kong:3.9.4
curl -s -o /dev/null -w '%{http_code}\n' -X POST -H 'apikey: lab-key-anna-456' \
-H 'Content-Type: application/json' -d '{"text":"Kontrolle"}' \
http://localhost/api/v1/notesErwartet: Schreiben mit Schlüssel klappt.
201
Challenge
Begrenz das Lesen auf fünf Anfragen pro Minute, wie in Tag 8, aber diesmal als Kubernetes-Ressource.
Hinweis: Ein KongPlugin vom Typ
rate-limiting und die Annotation
konghq.com/plugins an der HTTPRoute
notes-lesen.
Lösung
cat <<'EOF' | kubectl apply -f -
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
name: limit-lesen
namespace: notes
plugin: rate-limiting
config:
minute: 5
policy: local
EOF
kubectl -n notes annotate httproute notes-lesen konghq.com/plugins=limit-lesen
sleep 10
for i in $(seq 1 7); do
curl -s -o /dev/null -w '%{http_code} ' http://localhost/api/v1/notes
done; echoErwartet:
kongplugin.configuration.konghq.com/limit-lesen created
httproute.gateway.networking.k8s.io/notes-lesen annotated
200 200 200 200 200 429 429
Mit kubectl apply und einer Annotation, ohne Admin API
und ohne decK. Der KIC übersetzt, Kong setzt um.
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- Kong Operator (früher Gateway Operator) verwaltet Control Planes, Data Planes und ihre Upgrades in Kubernetes deklarativ, auch mit Konnect.
- DB-less im Cluster heißt: Die Wahrheit liegt in den Kubernetes-Ressourcen, also in Git und Argo CD oder Flux; Kong Manager zeigt nur an.
- Upgrades über Minor-Versionen (3.9 auf 3.10 und
weiter) folgen den Upgrade-Pfaden von Kong; bei Postgres mit
migrations up, Blue-Green oder neuen Knoten. - Gateway API zuerst: Für Routing und Header die Standardfilter, Kong-Ressourcen nur für das, was die Gateway API nicht kann (Auth, Rate Limits, eigene Plugins).