Tag 4: Plugins
Ziel: Plugins global, am Service und an der Route einsetzen, Vorrang und Reihenfolge verstehen und mit CORS, Cache und Wartungsmodus typische Aufgaben lösen. · Dauer: ca. 60 min · Voraussetzung: Tag 3
Briefing
- Ein Plugin hängt sich in die Verarbeitung einer Anfrage. Es gilt global, für einen Service, eine Route oder einen Consumer (Tag 5).
- Gibt es dasselbe Plugin auf mehreren Ebenen, läuft nur das genaueste: Route vor Service vor global.
- Verschiedene Plugins laufen nach ihrer festen Priorität, nicht nach der Reihenfolge in der Datei.
- Plugins fügst du mit
deck file add-pluginsein; die Plugin-Dateien liegen im Begleitcode.
Anfrage ─► correlation-id (100001) ─► cors (2000) ─► … ─► proxy-cache (100)
global Service notes Route notes-lesen
─► request-termination (2) ─► Backend
Drill 1: Globale Plugins
source ~/kong-lab/setup/env.sh
mkdir -p ~/kong-lab/tag04 && cd ~/kong-lab/tag04
cp ~/kong-lab/code/tag04/*.yaml .
cat global.yaml
deck file add-plugins -s ~/kong-lab/kong/kong.yaml global.yaml -o neu.yaml
deck gateway diff neu.yaml | grep -E '^creating|Created'
cp neu.yaml ~/kong-lab/kong/kong.yaml && kreload
curl -s $PROXY/echo/headers | jq -c '.headers | {"X-Ebene", "X-Correlation-Id"}'
curl -si $PROXY/api/v1/version | grep -i correlationErwartet (gekürzt, IDs weichen bei dir ab):
# global.yaml – Plugins für alle Anfragen (Tag 4)
_format_version: "1.0"
add-plugins:
- plugins:
- name: correlation-id
…
creating plugin correlation-id (global)
creating plugin request-transformer (global)
Created: 2
Kong reloaded
{"X-Ebene":["global"],"X-Correlation-Id":["a6f247e0-…"]}
X-Correlation-ID: 9aa3ef58-…
Ohne selectors landen die Plugins in der obersten Liste
plugins: und gelten für jede Anfrage.
correlation-id gibt jeder Anfrage eine ID, die Backend
und Client sehen (echo_downstream).
Fortschritt speichern? Kostenlos registrieren
Drill 2: Das genaueste Plugin gewinnt
echo.yaml setzt request-transformer noch
einmal, diesmal nur am Service echo:
grep -A12 selectors echo.yaml
deck file add-plugins -s ~/kong-lab/kong/kong.yaml echo.yaml -o neu.yaml
cp neu.yaml ~/kong-lab/kong/kong.yaml && kreload
curl -s $PROXY/echo/headers | jq -c '.headers | {"X-Ebene", "User-Agent"}'
curl -s -X DELETE $PROXY/api/x | jq -c '.headers | {"X-Ebene", "User-Agent"}'Erwartet:
- selectors:
- $.services[?(@.name=="echo")]
plugins:
- name: request-transformer
config:
add:
headers: ["X-Ebene:service"]
remove:
headers: ["User-Agent"]
Kong reloaded
{"X-Ebene":["service"],"User-Agent":null}
{"X-Ebene":["global"],"User-Agent":["curl/8.5.0"]}
Für den Service echo läuft nur die Service-Variante:
X-Ebene: service, kein User-Agent. Die
Auffang-Route /api gehört zu einem anderen Service und
bekommt weiter die globale. Die beiden Konfigurationen werden
nicht zusammengeführt.
Fortschritt speichern? Kostenlos registrieren
Drill 3: Die Reihenfolge
curl -s $ADMIN | jq -r '.plugins.available_on_server | to_entries
| map(select(.key | IN("correlation-id","cors","jwt","key-auth","acl",
"rate-limiting","request-transformer","proxy-cache","request-termination")))
| sort_by(-.value.priority) | .[] | "\(.value.priority)\t\(.key)"'Erwartet:
100001 correlation-id
2000 cors
1450 jwt
1250 key-auth
950 acl
910 rate-limiting
801 request-transformer
100 proxy-cache
2 request-termination
Höhere Priorität läuft zuerst. Darum prüft Kong erst,
wer fragt (jwt, key-auth),
dann, ob er darf (acl), dann wie
oft (rate-limiting). cors liegt
davor, damit der Browser seine Vorabfrage ohne Schlüssel stellen
kann.
Fortschritt speichern? Kostenlos registrieren
Drill 4: CORS und die Vorabfrage
Eine Weboberfläche auf http://localhost:3000 soll die
API aus dem Browser aufrufen dürfen:
deck file add-plugins -s ~/kong-lab/kong/kong.yaml cors.yaml -o neu.yaml
cp neu.yaml ~/kong-lab/kong/kong.yaml && kreload
curl -si -X OPTIONS -H 'Origin: http://localhost:3000' \
-H 'Access-Control-Request-Method: POST' $PROXY/api/v1/notes \
| grep -i -E '^(HTTP|access-control)'Erwartet (gekürzt):
Kong reloaded
HTTP/1.1 200 OK
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, HEAD, PUT, DELETE, PATCH, QUERY, OPTIONS
Access-Control-Allow-Origin: http://localhost:3000
Access-Control-Max-Age: 3600
Sieht gut aus, ist aber falsch: Das sind nicht deine Werte
(max_age 600, nur GET und POST). Die Vorabfrage des
Browsers ist ein OPTIONS, und OPTIONS passt zu
keiner Route von notes. Sie fällt auf die Auffang-Route
/api und der Echo-Dienst antwortet selbst mit CORS-Headern.
Die Route notes-lesen muss OPTIONS
annehmen:
deck file patch -s ~/kong-lab/kong/kong.yaml \
--selector '$..routes[?(@.name=="notes-lesen")]' \
--value 'methods:["GET","OPTIONS"]' -o neu.yaml
cp neu.yaml ~/kong-lab/kong/kong.yaml && kreload
curl -si -X OPTIONS -H 'Origin: http://localhost:3000' \
-H 'Access-Control-Request-Method: POST' $PROXY/api/v1/notes \
| grep -i -E '^(HTTP|access-control)'Erwartet:
Kong reloaded
HTTP/1.1 200 OK
Access-Control-Allow-Origin: http://localhost:3000
Access-Control-Allow-Headers: Content-Type,X-API-Key
Access-Control-Allow-Methods: GET,POST
Access-Control-Max-Age: 600
Jetzt antwortet das Plugin cors selbst, ohne das Backend
zu fragen.
Achtung: Auch ein
Origin: http://boese.examplebekommtAccess-Control-Allow-Origin: http://localhost:3000zurück. Das ist richtig so: Der Browser vergleicht und blockiert. CORS schützt Benutzer im Browser, nicht die API vorcurl.
Fortschritt speichern? Kostenlos registrieren
Drill 5: Ein Cache vor der API
deck file add-plugins -s ~/kong-lab/kong/kong.yaml cache.yaml -o neu.yaml
cp neu.yaml ~/kong-lab/kong/kong.yaml && kreload
for i in 1 2 3; do
curl -si $PROXY/api/v1/notes \
| grep -i -E '^(x-cache-status|x-kong-upstream-latency)' | tr -d '\r' | tr '\n' ' '
echo
doneErwartet:
Kong reloaded
X-Cache-Status: Miss X-Kong-Upstream-Latency: 9
X-Cache-Status: Hit X-Kong-Upstream-Latency: 0
X-Cache-Status: Hit X-Kong-Upstream-Latency: 0
Der erste Aufruf geht zum Backend, die nächsten 30 Sekunden antwortet Kong aus dem Speicher. Der Preis: veraltete Daten.
curl -s $PROXY/api/v1/notes | jq length
curl -s -X POST -H 'X-API-Key: lab-api-key-123' -H 'Content-Type: application/json' \
-d '{"text":"neu im Cache?"}' $PROXY/api/v1/notes > /dev/null
curl -s $PROXY/api/v1/notes | jq length
curl -s -H 'Cache-Control: no-cache' $PROXY/api/v1/notes | jq length
curl -s -o /dev/null -w '%{http_code}\n' -X DELETE $ADMIN/proxy-cache
curl -s $PROXY/api/v1/notes | jq lengthErwartet:
2
2
2
204
3
Die neue Notiz fehlt, bis der Eintrag abläuft oder du den Cache über
die Admin API leerst. Auch Cache-Control: no-cache vom
Client hilft nicht: Das Plugin ignoriert es, solange
cache_control: false gesetzt ist (Standard).
Fortschritt speichern? Kostenlos registrieren
Drill 6: Wartungsmodus
wartung.yaml legt ein request-termination
an die Route notes-schreiben, aber mit
enabled: false. Einschalten heißt: ein Feld ändern.
deck file add-plugins -s ~/kong-lab/kong/kong.yaml wartung.yaml -o neu.yaml
SEL='$..routes[?(@.name=="notes-schreiben")].plugins[?(@.name=="request-termination")]'
deck file patch -s neu.yaml --selector "$SEL" --value 'enabled:true' -o an.yaml
cp an.yaml ~/kong-lab/kong/kong.yaml && kreload
curl -si -X POST -H 'X-API-Key: lab-api-key-123' -H 'Content-Type: application/json' \
-d '{"text":"jetzt?"}' $PROXY/api/v1/notes | sed -n '1p;$p'; echo
curl -s -o /dev/null -w '%{http_code}\n' $PROXY/api/v1/notesErwartet:
Kong reloaded
HTTP/1.1 503 Service Temporarily Unavailable
{"message":"Wartung bis 18 Uhr"}
200
Schreiben ist gesperrt, Lesen geht weiter.
request-termination hat Priorität 2 und läuft als letztes:
Authentifizierung und Rate Limits greifen auch im Wartungsmodus.
Fortschritt speichern? Kostenlos registrieren
Drill 7: Endstand
Für die nächsten Tage bleiben nur correlation-id und
cors mit der Route für OPTIONS. Den Stand
liefert der Begleitcode:
cp ~/kong-lab/code/tag04/kong.yaml ~/kong-lab/kong/kong.yaml
cd ~/kong-lab/kong && kreload
curl -s $ADMIN/plugins | jq -r '.data[] | [.name, (if .route then "route"
elif .service then "service" else "global" end)] | @tsv' | sort
git add kong.yaml && git commit -qm "Tag 4: correlation-id und cors"Erwartet:
Kong reloaded
correlation-id global
cors service
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
curl -si $PROXY/api/v1/notes | grep -i -c '^x-correlation-id'Erwartet: jede Antwort trägt eine Correlation-ID.
1
curl -si -X OPTIONS -H 'Origin: http://localhost:3000' \
-H 'Access-Control-Request-Method: POST' $PROXY/api/v1/notes \
| grep -i '^access-control-max-age'Erwartet: die Vorabfrage beantwortet das Plugin mit deinem
max_age.
Access-Control-Max-Age: 600
curl -s -o /dev/null -w '%{http_code}\n' -X POST -H 'X-API-Key: lab-api-key-123' \
-H 'Content-Type: application/json' -d '{"text":"Tag 4"}' $PROXY/api/v1/notesErwartet: kein Wartungsmodus mehr, Schreiben klappt.
201
Challenge
Alle Antworten, die über den Host echo.lab kommen,
sollen den Header X-Lab: Trainingslager tragen. Antworten
über /echo nicht.
Hinweis: response-transformer an der
richtigen Route; --config nimmt das Plugin als JSON.
Lösung
cd ~/kong-lab/tag04
deck file add-plugins -s ~/kong-lab/kong/kong.yaml \
--selector '$..routes[?(@.name=="echo-host")]' \
--config '{"name":"response-transformer",
"config":{"add":{"headers":["X-Lab:Trainingslager"]}}}' -o ch.yaml
deck gateway diff ch.yaml | grep -E '^creating|Created'
cp ch.yaml ~/kong-lab/kong/kong.yaml && kreload
curl -si -H 'Host: echo.lab' $PROXY/get | grep -i '^x-lab'
curl -si $PROXY/echo/get | grep -i -c '^x-lab'Erwartet:
creating plugin response-transformer for route echo-host
Created: 1
Kong reloaded
X-Lab: Trainingslager
0
Danach zurück zum Endstand:
git -C ~/kong-lab/kong checkout kong.yaml && kreload.
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- Reihenfolge ändern: Kong Enterprise erlaubt
orderingpro Plugin (dynamische Reihenfolge). In der freien Ausgabe gilt nur die feste Priorität. - Cache verteilt:
strategy: memorygilt pro Kong-Knoten. Mehrere Knoten haben getrennte Caches; Enterprise bietetproxy-cache-advancedmit Redis. - CORS gehört entweder ins Gateway oder ins Backend, nie in beide; doppelte Header bricht Browser.
- Wartungsfenster als vorbereitetes, inaktives Plugin im Git: Einschalten ist dann ein kleiner, prüfbarer Commit.
- Plugin Hub: Neben den 45 mitgelieferten gibt es Community-Plugins; jedes fremde Plugin läuft mit vollen Rechten im Gateway und gehört geprüft.