Zum Inhalt springen
Trainingslager IT-Trainingslager

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 -l

Erwartet:

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 --wait

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

Erwartet:

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

Erwartet:

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

In 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/plugins

Erwartet (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/ready

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

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

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

Erwartet: Die lokale DP ist bereit.

200
curl -s http://192.168.64.8:8000/api/v1/version

Erwartet: 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 -1

Erwartet (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_incompatible aus Drill 5.
  • Rate Limits im Hybrid-Modus: nur local oder redis. Für Grenzen über alle DPs hinweg braucht es Redis.