Tag 13: Hybrid-Modus
Ziel: Kong in eine Control Plane mit Datenbank und Data Planes ohne Datenbank teilen, eine zweite Data Plane auf einer eigenen VM anschließen und sehen, was bei Ausfall und unpassenden Plugins passiert. · Dauer: ca. 90 min · Voraussetzung: Tag 12
Briefing
- Die Control Plane (CP) hat Postgres, Admin API und Kong Manager, verarbeitet aber keinen Verkehr.
- Data Planes (DP) haben keine Datenbank. Sie verbinden sich über Port 8005 mit der CP, bekommen die ganze Konfiguration und halten sie im Speicher.
- CP und DP vertrauen einander über ein gemeinsames Cluster-Zertifikat (mTLS).
- Fällt die CP aus, arbeiten die DPs mit der letzten Konfiguration weiter.
VM kong VM dp
┌──────────────────────────────────┐ ┌────────────────────────┐
│ kong (CP) + kong-db :8001 :8005 ◄─── mTLS ───┤ kong-dp :8000 │
│ kong-dp (DP) :8000 ─► notes-api … │ notes-api, echo (lokal)│
└──────────────────────────────────┘ └────────────────────────┘
Drill 1: Das Cluster-Zertifikat
source ~/kong-lab/setup/env.sh
mkdir -p ~/kong-lab/tag13 && cd ~/kong-lab/kong
mkdir -p cluster
docker run --rm -u $(id -u):$(id -g) -v $PWD/cluster:/c -w /c kong:3.9.4 \
kong hybrid gen_cert cluster.crt cluster.key
openssl x509 -in cluster/cluster.crt -noout -subject -enddate
ls -l cluster | awk 'NR>1 {print $1, $3, $9}'Erwartet (gekürzt):
Successfully generated certificate/key pairs, they have been written to:
'/c/cluster.crt' and '/c/cluster.key'.
subject=CN = kong_clustering
notAfter=Oct 31 13:30:30 2029 GMT
-rw-r--r-- ubuntu cluster.crt
-rw------- ubuntu cluster.key
Ein selbst signiertes Zertifikat, drei Jahre gültig. CP und alle DPs
bekommen dasselbe Paar. Der Schlüssel ist nur für seinen Besitzer
lesbar, und das ist noch ubuntu. Ins Git gehört er
nicht:
echo 'cluster/' > .gitignore
git add .gitignore && git commit -qm "Cluster-Schlüssel nicht ins Git"
git status --short | wc -lErwartet:
0
Fortschritt speichern? Kostenlos registrieren
Drill 2: Control Plane und lokale Data Plane
cp ~/kong-lab/code/tag13/compose.yaml compose.yaml
grep -E 'KONG_ROLE|CLUSTER_LISTEN|CLUSTER_CONTROL_PLANE' compose.yaml
docker compose up -d --waitErwartet (gekürzt):
KONG_ROLE: control_plane
KONG_CLUSTER_LISTEN: "0.0.0.0:8005"
KONG_ROLE: data_plane
KONG_CLUSTER_CONTROL_PLANE: kong:8005
Container kong-kong-1 Error dependency kong failed to start
dependency failed to start: container kong-kong-1 exited (1)
Die CP startet nicht. Das Log sagt warum:
docker compose logs kong 2>&1 \
| grep -m1 -o 'cannot load certificate key.*Permission denied'
docker run --rm kong:3.9.4 idErwartet:
cannot load certificate key "/kong/cluster/cluster.key": BIO_new_file() failed (SSL:
error:8000000D:system library::Permission denied
uid=1001(kong) gid=1001(kong) groups=1001(kong)
Kong läuft im Container als UID 1001, der Schlüssel gehört UID 1000
(ubuntu) mit Modus 600. Im Container zählt die Nummer,
nicht der Name. Kopier das Paar zuerst für die zweite VM (Drill 5), dann
gib den Schlüssel an Kong:
cp cluster/cluster.crt cluster/cluster.key ~/kong-lab/tag13/
sudo chown 1001:1001 cluster/cluster.key
docker compose up -d --wait
docker compose ps --format "table {{.Service}}\t{{.Status}}"Erwartet (gekürzt):
Container kong-kong-1 Healthy
Container kong-kong-dp-1 Healthy
SERVICE STATUS
kong Up 13 seconds (healthy)
kong-db Up 50 minutes (healthy)
kong-dp Up 6 seconds (healthy)
Fortschritt speichern? Kostenlos registrieren
Drill 3: Wer macht was
curl -s $ADMIN | jq -r .configuration.role
curl -s $ADMIN/clustering/data-planes \
| jq -r '.data[] | [.hostname, .ip, .version, .sync_status] | @tsv'
curl -s -o /dev/null -w 'DP bereit: %{http_code}\n' localhost:8100/status/ready
curl -s $PROXY/api/v1/version | head -2
docker compose logs kong-dp 2>&1 \
| grep -m1 -o "in 'policy': expected one of: local, redis"Erwartet (gekürzt):
control_plane
4f93fe7c78f9 172.18.0.12 3.9.4 normal
DP bereit: 503
{
"message":"no Route matched with those values",
in 'policy': expected one of: local, redis
Die DP ist verbunden, aber nicht bereit, und sie kennt keine einzige
Route. Sie hat die Konfiguration der CP abgelehnt: In
Tag 8 hast du für rate-limiting am Schreiben
policy: cluster gesetzt, also Zähler in Postgres. Eine DP
hat keine Datenbank. Eine einzige ungültige Einstellung, und die DP
verwirft alles.
P='$..routes[?(@.name=="notes-schreiben")].plugins[?(@.name=="rate-limiting")].config'
deck file patch -s kong.yaml --selector "$P" --value 'policy:"local"' -o kong.yaml
ksync 2>/dev/null | tail -2
curl -s -o /dev/null -w 'DP bereit: %{http_code}\n' localhost:8100/status/ready
curl -s $PROXY/api/v1/version
curl -s -o /dev/null -w '%{http_code}\n' -H 'apikey: lab-key-anna-456' $PROXY/whoamiErwartet:
Updated: 1
Deleted: 0
DP bereit: 200
0.2.0
200
ksync spricht weiter mit localhost:8001,
also mit der CP. Den Verkehr verarbeitet jetzt die DP auf Port 8000.
Fortschritt speichern? Kostenlos registrieren
Drill 4: Die Control Plane fällt aus
docker compose stop kong
curl -s -o /dev/null -w 'Admin API: %{http_code}\n' $ADMIN
curl -s $PROXY/api/v1/version
curl -s -o /dev/null -w '%{http_code}\n' -H 'apikey: lab-key-anna-456' $PROXY/whoami
docker compose start kong
sleep 10
curl -s $ADMIN/clustering/data-planes \
| jq -r '.data[] | [.hostname, .sync_status] | @tsv'Erwartet (gekürzt):
Container kong-kong-1 Stopped
Admin API: 000
0.3.0
200
Container kong-kong-1 Started
4f93fe7c78f9 normal
Ohne CP keine Änderungen, aber der Verkehr läuft weiter. Das ist der Kern des Hybrid-Modus: Die Datenbank ist kein Ausfallpunkt mehr für Anfragen.
Fortschritt speichern? Kostenlos registrieren
Drill 5: Eine zweite VM als Data Plane
Leg auf dem Laptop die VM dp an und
bring das Zertifikat hinüber:
multipass launch 24.04 --name dp --cpus 1 --memory 2G --disk 15G
multipass exec dp -- mkdir -p /home/ubuntu/kong-lab/dp/cluster
multipass transfer kong:/home/ubuntu/kong-lab/tag13/cluster.crt \
kong:/home/ubuntu/kong-lab/tag13/cluster.key .
multipass transfer cluster.crt cluster.key dp:/home/ubuntu/kong-lab/dp/cluster/
rm cluster.keyIn der VM dp (per multipass shell dp):
Docker installieren wie in Tag 0, Drill 2, neu anmelden, dann
Begleitcode und Images:
git clone https://github.com/thomaszachmann/kong-zum-anfassen.git ~/kong-lab/code
cd ~/kong-lab/code/notes/notes-api
docker build -q --build-arg VERSION=0.2.0 -t notes-api:0.2.0 .
docker build -q --build-arg VERSION=0.3.0 -t notes-api:0.3.0 .
sudo chown 1001:1001 ~/kong-lab/dp/cluster/cluster.key
cp ~/kong-lab/code/tag13/dp/compose.yaml ~/kong-lab/dp/
cp -R ~/kong-lab/code/plugins ~/kong-lab/pluginsErwartet (gekürzt):
sha256:baf6911e6f76…
sha256:ed2077bac750…
Die Plugins kopierst du schon jetzt: Fehlt ein eingebundenes
Verzeichnis, legt Docker es beim Start als root an, und
spätere Kopien scheitern. dp/compose.yaml bringt die DP und
ein eigenes Backend: zwei notes-api ohne Datenbank und den Echo-Dienst,
wie an einem zweiten Standort. Die Adresse der CP kommt aus einer
Variablen, die IP der VM kong kennst du als
KONG_IP:
cd ~/kong-lab/dp
export CP_ADDR=192.168.64.7:8005
docker compose up -d --wait
sleep 5
curl -s -o /dev/null -w 'DP bereit: %{http_code}\n' localhost:8100/status/readyErwartet (gekürzt):
Container kong-dp-kong-dp-1 Healthy
DP bereit: 503
Auf der VM kong fragst du die CP:
curl -s $ADMIN/clustering/data-planes | jq -r '.data[] | [.ip, .sync_status] | @tsv'Erwartet (gekürzt):
172.18.0.12 normal
192.168.64.8 plugin_set_incompatible
Die neue DP kennt dein Plugin jwt-identity nicht
(KONG_PLUGINS steht dort auf bundled), und die
Konfiguration benutzt es. Die CP schickt ihr deshalb gar nichts. Eigene
Plugins müssen auf jeder DP liegen und dort
eingeschaltet sein. Zurück auf der VM dp:
grep -E 'DP_PLUGINS|kong-plugins' compose.yaml
export DP_PLUGINS=bundled,jwt-identity
docker compose up -d --wait
sleep 8
curl -s -o /dev/null -w 'DP bereit: %{http_code}\n' localhost:8100/status/ready
for i in 1 2 3 4; do curl -s localhost:8000/api/v1/version; done
curl -s -H 'apikey: lab-key-anna-456' localhost:8000/whoami \
| jq -c '.headers."X-Consumer-Username"'
curl -s localhost:8000/api/v1/notes; echoErwartet (gekürzt):
KONG_PLUGINS: ${DP_PLUGINS:-bundled}
KONG_LUA_PACKAGE_PATH: /kong-plugins/?.lua;;
- ../plugins:/kong-plugins:ro
Container kong-dp-kong-dp-1 Healthy
DP bereit: 200
0.3.0
0.2.0
0.3.0
0.2.0
["anna"]
[]
Dieselben Routes, Consumer, Schlüssel und Upstreams wie auf der VM
kong, aber eigene Backends: Die Liste der Notizen ist leer,
denn dieser Standort hat keine gemeinsame Datenbank.
Fortschritt speichern? Kostenlos registrieren
Drill 6: Metriken von der Data Plane
Die Proxy-Metriken entstehen jetzt in der DP, nicht mehr in der CP.
Auf der VM kong zeigt Prometheus auf
kong-dp:
cd ~/kong-lab/observability
sed -i 's/"kong:8100"/"kong-dp:8100"/' prometheus.yml
docker compose restart prometheus
for i in $(seq 1 10); do curl -s -o /dev/null $PROXY/api/v1/version; done
sleep 12
curl -s localhost:9090/api/v1/targets \
| jq -r '.data.activeTargets[] | [.labels.instance,
.health] | @tsv'Erwartet:
Container observability-prometheus-1 Started
kong-dp:8100 up
Die DP auf der VM dp erreicht Jaeger nicht (anderes
Netz) und protokolliert Fehler beim Senden der Traces. In Produktion hat
jeder Standort einen eigenen Collector.
Stand festhalten:
cd ~/kong-lab/kong
git add compose.yaml kong.yaml && git commit -qm "Tag 13: Hybrid mit zwei Data Planes"Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
curl -s $ADMIN/clustering/data-planes | jq -r '.data[] | .sync_status' | sort | uniq -cErwartet: zwei Data Planes im Takt (ältere Einträge aus Fehlversuchen verschwinden nach einiger Zeit von selbst).
2 normal
curl -s -o /dev/null -w '%{http_code}\n' localhost:8100/status/readyErwartet: Die lokale DP ist bereit.
200
curl -s http://192.168.64.8:8000/api/v1/versionErwartet: Die DP auf der VM dp antwortet auch von außen
(IP von dp einsetzen).
0.2.0
Challenge
Leg über die Admin API eine neue Route an und miss, wie lange es dauert, bis beide Data Planes sie kennen.
Hinweis: Die CP schickt Änderungen nach dem Speichern an alle DPs; frag beide in einer Schleife.
Lösung
curl -s -X POST $ADMIN/services -d name=neu -d url=http://echo:8080/anything \
| jq -r .name
curl -s -X POST $ADMIN/services/neu/routes -d 'paths[]=/neu' | jq -c .paths
t0=$(date +%s)
for dp in localhost 192.168.64.8; do
until [ "$(curl -s -o /dev/null -w '%{http_code}' http://$dp:8000/neu/get)" = 200 ]
do sleep 1; done
echo "$dp: $(( $(date +%s) - t0 )) s"
done
cd ~/kong-lab/kong && ksync 2>/dev/null | tail -1Erwartet (gekürzt, die Sekunden schwanken):
neu
["/neu"]
localhost: 6 s
192.168.64.8: 6 s
Deleted: 2
Beide DPs bekommen die Änderung im selben Schub. ksync
räumt den Versuch wieder ab, denn er steht nicht in
kong.yaml.
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- Konnect ist eine Control Plane als Dienst von Kong: Die DPs laufen bei dir, die CP mit Analytics und Portal in der Cloud.
- Zertifikate: Statt eines gemeinsamen Paars
(
shared) kann jede DP ein eigenes, von einer CA signiertes Zertifikat haben (cluster_mtls = pki). Dann lässt sich eine einzelne DP sperren. - Versionen: Die CP muss mindestens so neu sein wie die DPs. Beim Upgrade erst die CP, dann die DPs (Tag 14).
- Eigene Plugins gehören ins Image der DP, nicht in
ein eingebundenes Verzeichnis; sonst entsteht genau das
plugin_set_incompatibleaus Drill 5. - Rate Limits im Hybrid-Modus: nur
localoderredis. Für Grenzen über alle DPs hinweg braucht es Redis.