Zum Inhalt springen
Trainingslager IT-Trainingslager

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-plugins ein; 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 correlation

Erwartet (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.example bekommt Access-Control-Allow-Origin: http://localhost:3000 zurück. Das ist richtig so: Der Browser vergleicht und blockiert. CORS schützt Benutzer im Browser, nicht die API vor curl.

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
done

Erwartet:

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 length

Erwartet:

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

Erwartet:

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

Erwartet: 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 ordering pro Plugin (dynamische Reihenfolge). In der freien Ausgabe gilt nur die feste Priorität.
  • Cache verteilt: strategy: memory gilt pro Kong-Knoten. Mehrere Knoten haben getrennte Caches; Enterprise bietet proxy-cache-advanced mit 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.