Zum Inhalt springen
Trainingslager IT-Trainingslager

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 mit KongPlugin, KongConsumer und Secrets.
  • Das Helm-Chart kong/ingress installiert zwei Deployments: kong-controller (KIC) und kong-gateway (der Proxy).
  • Ein Upgrade ist ein helm upgrade mit 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 k3s

In 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=120s

Erwartet (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 nodes

Erwartet:

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/code

Erwartet (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.0

Auf 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-40

Erwartet (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-proxy

Erwartet (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 .url

Erwartet (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 kongconsumer

Erwartet (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 KongPlugin vom Typ request-transformer wirkt hier nicht. Der KIC setzt URLRewrite selbst als request-transformer um, 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; done

Erwartet (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 -c

Erwartet:

      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 ee

Erwartet:

{"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}'; echo

Erwartet: Der KIC hat das Gateway übernommen.

True
kubectl -n kong get deploy kong-gateway \
  -o jsonpath='{.spec.template.spec.containers[0].image}'; echo

Erwartet: 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/notes

Erwartet: 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; echo

Erwartet:

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).