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/kongundkreload.deck gateway synckommt in Tag 7. kong.yamlist 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 pingErwartet:
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.yamlErwartet (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.yamlErwartet (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.yamlErwartet (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 --onelineErwartet (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.yamlErwartet:
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/versionErwartet:
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 .urlErwartet:
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 --onelineErwartet:
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 -3Erwartet: 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 -lErwartet: 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.yamlim Repository, Pull Request mitdeck file validate,deck gateway validateunddeck gateway diffals Prüfschritte, nach dem Merge ausrollen. - Teams trennen: Mit Datenbank und
select_tagsin 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 perpatchundadd-pluginsdazu. - Lint:
deck file lintprüft Dateien gegen eigene Regeln, etwa „jede Route braucht ein Auth-Plugin”. - Konnect: Dieselben Befehle verwalten mit
--konnect-tokendie Control Plane in Kongs Cloud.