Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 3: Deklarativ mit decK

Ziel: Kongs Konfiguration mit decK exportieren, prüfen, vergleichen und aus einer OpenAPI-Beschreibung erzeugen, und sie mit Git versionieren. · Dauer: ca. 60 min · Voraussetzung: Tag 2

Briefing

  • decK hat zwei Gruppen von Befehlen: deck gateway … spricht mit der Admin API, deck file … bearbeitet nur Dateien.
  • Arbeitsablauf: Datei ändern → validate → diff → anwenden → committen.
  • Ohne Datenbank kann decK prüfen und vergleichen, aber nicht anwenden. Anwenden heißt heute: Datei nach ~/kong-lab/kong und kreload. deck gateway sync kommt in Tag 7.
  • kong.yaml ist ab heute ein Git-Repository.
 notes-openapi.yaml ─openapi2kong─► v2.yaml ─merge─► kong.yaml ─validate/diff─► Kong
                                                         │
                                                        git

Drill 1: decK verbinden

source ~/kong-lab/setup/env.sh
mkdir -p ~/kong-lab/tag03 && cd ~/kong-lab/tag03
echo $DECK_ANALYTICS
deck gateway ping

Erwartet:

off
Successfully connected to Kong!
Kong version:  3.9.4

decK spricht standardmäßig http://localhost:8001 an (--kong-addr). env.sh setzt DECK_ANALYTICS=off: Ohne diese Variable schickt decK anonyme Nutzungsdaten an Kong.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Was Kong wirklich hat

deck gateway dump -o dump.yaml
wc -l dump.yaml ~/kong-lab/kong/kong.yaml
sed -n '1,14p' dump.yaml
deck gateway dump --skip-defaults | sed -n '1,10p'

Erwartet (gekürzt):

 129 dump.yaml
  40 /home/ubuntu/kong-lab/kong/kong.yaml
 169 total
_format_version: "3.0"
services:
- connect_timeout: 60000
  enabled: true
  host: echo
  name: api-rest
  path: /anything
  port: 8080
  protocol: http
  read_timeout: 60000
  retries: 5
  routes:
  - https_redirect_status_code: 426
_format_version: "3.0"
services:
- host: echo
  name: api-rest
  path: /anything
  port: 8080
  routes:
  - name: api-rest
    paths:
    - /api

Aus 40 Zeilen werden 129: Kong ergänzt jeden Standardwert. --skip-defaults lässt sie weg und liefert eine Datei, die man lesen und versionieren mag.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Prüfen, offline und online

kaputt.yaml enthält drei Fehler. Finde sie mit decK:

cp ~/kong-lab/code/tag03/kaputt.yaml .
deck file validate kaputt.yaml

Erwartet (gekürzt):

Error: 1 errors occurred:
    reading file kaputt.yaml: validating file content: 1 errors occurred:
    validation error: object=["/echo"], err=services.0.routes.0: Additional property
pathes is not allowed

deck file validate prüft offline nur die Form: unbekannte Felder, falsche Typen. Den Tippfehler behoben, ist die Datei für decK in Ordnung:

sed -i 's/pathes/paths/' kaputt.yaml
deck file validate kaputt.yaml && echo "file: ok"
deck gateway validate kaputt.yaml

Erwartet (gekürzt):

file: ok
Error: validate entity 'services (notes)': HTTP status 400 (message: "2 schema
violations (protocol: expected one of: grpc, grpcs, http, https, tcp, tls,
tls_passthrough, udp; read_timeout: value should be between 1 and 2147483646)")

deck gateway validate fragt Kong selbst, ohne etwas zu ändern. Erst Kongs Schema kennt erlaubte Protokolle und Wertebereiche. In einer CI laufen beide.

sed -i 's|htp://|http://|; /read_timeout: -5/d' kaputt.yaml
deck gateway validate kaputt.yaml && echo "gateway: ok"

Erwartet:

gateway: ok

Fortschritt speichern? Kostenlos registrieren

Drill 4: Vergleichen und anwenden

Plan eine Änderung: ein neuer Service, ohne den laufenden Kong anzufassen.

cp ~/kong-lab/kong/kong.yaml neu.yaml
cat >> neu.yaml <<'EOF'
  - name: echo-neu
    url: http://echo:8080/anything
    routes:
      - name: echo-neu
        paths: [/neu]
EOF
deck gateway diff neu.yaml
deck gateway sync neu.yaml

Erwartet (gekürzt):

creating service echo-neu
creating route echo-neu
Summary:
  Created: 2
  Updated: 0
  Deleted: 0
creating service echo-neu
Dropped creation route echo-neu
…
Error: 1 errors occurred:
    while processing event: Create service echo-neu failed: HTTP status 405 (message:
"cannot create or update 'services' entities when not using a database")

diff zeigt genau, was sich ändern würde. sync scheitert an derselben Grenze wie in Tag 1: ohne Datenbank keine einzelnen Objekte. Hier wendest du an, indem du die Datei lädst. Den neuen Service brauchst du nicht; neu.yaml bleibt liegen.

Fortschritt speichern? Kostenlos registrieren

Drill 5: kong.yaml unter Git

cd ~/kong-lab/kong
git config --global user.name >/dev/null || git config --global user.name "Lab"
git config --global user.email >/dev/null || git config --global user.email [email protected]
git init -q -b main
git add kong.yaml compose.yaml
git commit -qm "Stand Tag 2"
git log --oneline

Erwartet (der Hash weicht bei dir ab):

f70b3be Stand Tag 2

Ab jetzt ist jede Änderung an Kong ein Commit. Wer was wann geändert hat, sagt git log, und zurück geht es mit git checkout.

Fortschritt speichern? Kostenlos registrieren

Drill 6: Aus OpenAPI wird Kong

notes-openapi.yaml beschreibt die API von notes-api. decK macht daraus Services und Routes und legt sie unter /api/v2:

cd ~/kong-lab/tag03
cp ~/kong-lab/code/tag03/notes-openapi.yaml .
grep -E 'x-kong-name|operationId|url:' notes-openapi.yaml
deck file openapi2kong -s notes-openapi.yaml \
  | deck file namespace --path-prefix=/api/v2 -o v2.yaml
grep -E '^  name:|^    name:|~/api' v2.yaml

Erwartet:

x-kong-name: notes-v2
  - url: http://notes-api:8080
      operationId: notes-lesen
      operationId: notes-schreiben
      operationId: version
  name: notes-v2
    name: pre-function
    name: notes-v2_notes-lesen
    - ~/api/v2/notes$
    name: notes-v2_notes-schreiben
    - ~/api/v2/notes$
    name: notes-v2_version
    - ~/api/v2/version$

Pro Operation eine Route mit Regex-Pfad (~ am Anfang), der Service heißt nach x-kong-name. namespace setzt das Präfix davor und hängt ein kleines Plugin pre-function an, das /api/v2 vor dem Weiterleiten wieder entfernt.

Führ beide Dateien zusammen, prüfe, vergleiche und lade:

deck file merge ~/kong-lab/kong/kong.yaml v2.yaml -o merged.yaml
deck gateway validate merged.yaml && deck gateway diff merged.yaml | tail -4
cp merged.yaml ~/kong-lab/kong/kong.yaml && kreload
curl -s $PROXY/api/v2/notes | jq -c '.[0].text'
curl -s $PROXY/api/v2/version

Erwartet:

Summary:
  Created: 5
  Updated: 0
  Deleted: 0
Kong reloaded
"vor dem Gateway"
0.2.0

Die v2 war ein Versuch. Git bringt den alten Stand zurück:

cd ~/kong-lab/kong
git diff --stat
git checkout kong.yaml && kreload
curl -s $PROXY/api/v2/version | jq -r .url

Erwartet:

 kong.yaml | 119 +++++++++++++++++++++++++++++++++++++++++++-------------------
 1 file changed, 83 insertions(+), 36 deletions(-)
Updated 1 path from the index
Kong reloaded
http://echo:8080/anything/v2/version

/api/v2/version landet wieder auf der Auffang-Route aus Tag 2.

Fortschritt speichern? Kostenlos registrieren

Drill 7: Regeln für viele Services

Alle Services des Teams notes sollen ein Tag tragen und kürzere Timeouts bekommen. Statt von Hand: decK mit einem JSONPath-Selektor.

cd ~/kong-lab/tag03
SEL='$.services[?(@.name=="notes" || @.name=="notes-version")]'
deck file add-tags -s ~/kong-lab/kong/kong.yaml --selector "$SEL" team-notes -o t1.yaml
deck file patch -s t1.yaml --selector "$SEL" \
  --value 'read_timeout:10000' --value 'connect_timeout:2000' -o t2.yaml
deck gateway diff t2.yaml | grep -E '^(updating|[-+] )'

Erwartet (gekürzt):

updating service notes-version  {
-  "connect_timeout": 60000,
+  "connect_timeout": 2000,
-  "read_timeout": 60000,
+  "read_timeout": 10000,
+  "tags": [
+    "team-notes"
+  ]
updating service notes  {
-  "connect_timeout": 60000,
+  "connect_timeout": 2000,
-  "read_timeout": 60000,
+  "read_timeout": 10000,
+  "tags": [
+    "team-notes"
+  ]

Übernimm den Stand und committe ihn. Der Begleitcode enthält dieselbe Datei:

cp ~/kong-lab/code/tag03/kong.yaml ~/kong-lab/kong/kong.yaml
cd ~/kong-lab/kong && kreload
git add kong.yaml && git commit -qm "Tag 3: Tags und Timeouts"
git log --oneline

Erwartet:

Kong reloaded
2a7ef7f Tag 3: Tags und Timeouts
f70b3be Stand Tag 2

Achtung: Kong 3.9.4 ohne Datenbank antwortet auf Filter nach Tags (/services?tags=team-notes, deck gateway dump --select-tag) mit einem Fehler 500. Mit Datenbank funktioniert es (Tag 7).

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

deck gateway diff ~/kong-lab/kong/kong.yaml | tail -3

Erwartet: Datei und laufender Kong sind gleich.

  Created: 0
  Updated: 0
  Deleted: 0
curl -s $ADMIN/services/notes | jq -c '{read_timeout, connect_timeout, tags}'

Erwartet: die Werte aus Drill 7.

{"read_timeout":10000,"connect_timeout":2000,"tags":["team-notes"]}
git -C ~/kong-lab/kong status --short | wc -l

Erwartet: nichts Uncommittetes.

0

Challenge

Eine Kollegin hat „mal eben” eine Datei hotfix.yaml gebaut, die nur einen Service enthält. Was würde passieren, wenn du sie als kong.yaml lädst? Finde es heraus, ohne den laufenden Kong zu verändern.

Hinweis: Eine deklarative Datei beschreibt den ganzen Zustand.

Lösung

cd ~/kong-lab/tag03
cat > hotfix.yaml <<'EOF'
_format_version: "3.0"
services:
  - name: echo
    url: http://echo:8080
EOF
deck gateway diff hotfix.yaml | grep -E '^(deleting|Summary)|Deleted'

Erwartet (gekürzt):

deleting route echo-host
deleting route echo
deleting route notes-version
…
deleting service notes
deleting service notes-version
deleting service api-rest
Summary:
  Deleted: 9

Alles, was nicht in der Datei steht, wäre weg. diff vor jedem Laden ist darum Pflicht, in der CI wie von Hand.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • GitOps: kong.yaml im Repository, Pull Request mit deck file validate, deck gateway validate und deck gateway diff als Prüfschritte, nach dem Merge ausrollen.
  • Teams trennen: Mit Datenbank und select_tags in der Datei (_info) verwaltet jedes Team nur seine Objekte (Tag 7). Enterprise trennt zusätzlich mit Workspaces.
  • API-first: OpenAPI ist die Quelle, Kong-Konfiguration wird daraus erzeugt (openapi2kong), Regeln kommen per patch und add-plugins dazu.
  • Lint: deck file lint prüft Dateien gegen eigene Regeln, etwa „jede Route braucht ein Auth-Plugin”.
  • Konnect: Dieselben Befehle verwalten mit --konnect-token die Control Plane in Kongs Cloud.