Tag 2: Services und Routes
Ziel: notes-api unter einem versionierten Pfad veröffentlichen, Routes nach Pfad, Methode und Host unterscheiden und die Fehlercodes von Kong lesen. · Dauer: ca. 60 min · Voraussetzung: Tag 1
Briefing
- Ein Service ist ein Backend: Protokoll, Host, Port,
optional ein Pfad, dazu Timeouts und Retries.
url:ist die Kurzform für alle vier. - Eine Route bindet Anfragen an einen Service, nach
paths,methods,hostsoderheaders. Alle angegebenen Bedingungen müssen passen. strip_path: true(Standard) schneidet den passenden Pfad ab, bevor Kong weiterleitet.- Passen mehrere Routes, gewinnt die genauere: mehr Bedingungen, längerer Präfix.
GET /api/v1/notes ──► Route notes-lesen (GET, /api/v1/notes)
strip_path ─► "" + Service-Pfad /notes
──► http://notes-api:8080/notes
Drill 1: Der erste Versuch mit notes-api
source ~/kong-lab/setup/env.sh
mkdir -p ~/kong-lab/tag02 && cd ~/kong-lab/kong
cat > kong.yaml <<'EOF'
_format_version: "3.0"
services:
- name: echo
url: http://echo:8080
routes:
- name: echo
paths: [/echo]
- name: notes
url: http://notes-api:8080
routes:
- name: notes
paths: [/notes]
EOF
kreload
curl -si $PROXY/notes | sed -n '1p;$p'
curl -s $ADMIN/routes/notes | jq -c '{paths, strip_path, preserve_host, methods}'Erwartet (gekürzt, IDs und Zeiten weichen bei dir ab):
Kong reloaded
HTTP/1.1 404 Not Found
404 page not found
{"paths":["/notes"],"strip_path":true,"preserve_host":false,"methods":null}
Eine 404, aber diesmal nicht von Kong:
404 page not found ist die Antwort von Go. Kong hat
/notes abgeschnitten und / an notes-api
geschickt. Mit strip_path: false reicht Kong den Pfad
unverändert durch:
sed -i 's| paths: \[/notes\]|&\n strip_path: false|' kong.yaml
kreload
curl -s $PROXY/notes | jq -c '.[0]'Erwartet:
Kong reloaded
{"id":"ba87895f-…","text":"vor dem Gateway"}
Tipp:
compose.yamlbindet das ganze Verzeichnis~/kong-lab/kongein, nicht nurkong.yaml.sed -iund viele Editoren schreiben eine neue Datei; eine einzeln eingebundene Datei würde der Container dann nicht mehr sehen.
Fortschritt speichern? Kostenlos registrieren
Drill 2: Ein versionierter Pfad
Nach außen soll die API /api/v1/notes heißen, intern
bleibt es /notes. Und Lesen und Schreiben bekommen eigene
Routes, damit du sie ab Tag 5 unterschiedlich schützen kannst:
cat > kong.yaml <<'EOF'
_format_version: "3.0"
services:
- name: echo
url: http://echo:8080
routes:
- name: echo
paths: [/echo]
- name: notes
url: http://notes-api:8080/notes
routes:
- name: notes-lesen
paths: [/api/v1/notes]
methods: [GET]
- name: notes-schreiben
paths: [/api/v1/notes]
methods: [POST]
EOF
kreload
curl -s $PROXY/api/v1/notes | jq -c '.[0]'
curl -s -X POST -H 'X-API-Key: lab-api-key-123' -H 'Content-Type: application/json' \
-d '{"text":"durch Kong"}' $PROXY/api/v1/notes; echoErwartet:
Kong reloaded
{"id":"ba87895f-…","text":"vor dem Gateway"}
{"id":"468ee201-…","text":"durch Kong"}
strip_path schneidet /api/v1/notes ab, Kong
hängt den Rest (nichts) an den Pfad des Services /notes. So
entkoppelst du die öffentliche URL von der internen.
Fortschritt speichern? Kostenlos registrieren
Drill 3: Methoden und der längste Präfix
Was passiert mit DELETE /api/v1/notes? Keine der beiden
Routes erlaubt DELETE. Häng eine Auffang-Route für /api an,
die zum Echo-Dienst führt:
cat >> kong.yaml <<'EOF'
- name: api-rest
url: http://echo:8080/anything
routes:
- name: api-rest
paths: [/api]
EOF
kreload
curl -s -X DELETE $PROXY/api/v1/notes | jq -c '{url, method}'
curl -s $PROXY/api/v2/x | jq -c '{url}'
curl -s $PROXY/api/v1/notes | jq -c '.[0].text'Erwartet:
Kong reloaded
{"url":"http://echo:8080/anything/v1/notes","method":"DELETE"}
{"url":"http://echo:8080/anything/v2/x"}
"vor dem Gateway"
GET landet weiter bei notes-api:
/api/v1/notes ist länger als /api und passt
genauer. DELETE passt nur zu /api und fällt
durch. Die Reihenfolge in der Datei spielt keine Rolle.
Fortschritt speichern? Kostenlos registrieren
Drill 4: Routing nach Host
Eine Route ohne Pfad, nur mit Hostnamen.
preserve_host: true reicht den Host des Clients an das
Backend durch:
cat > /tmp/host.yaml <<'EOF'
- name: echo-host
hosts: [echo.lab]
preserve_host: true
EOF
sed -i '/ paths: \[\/echo\]/r /tmp/host.yaml' kong.yaml
kreload
curl -s -H 'Host: echo.lab' $PROXY/headers | jq -c '.headers | {Host}'
curl -s $PROXY/echo/headers | jq -c '.headers | {Host, "X-Forwarded-Host"}'
curl -si -H 'Host: andere.lab' $PROXY/headers | head -1Erwartet:
Kong reloaded
{"Host":["echo.lab"]}
{"Host":["echo:8080"],"X-Forwarded-Host":["localhost"]}
HTTP/1.1 404 Not Found
Ohne preserve_host setzt Kong den Host des Services
(echo:8080) und gibt den ursprünglichen in
X-Forwarded-Host mit. Manche Backends bauen damit Links;
dann brauchst du preserve_host.
Fortschritt speichern? Kostenlos registrieren
Drill 5: Fehlercodes lesen
Drei absichtlich kaputte Services: falscher Port, unbekannter Name, zu langsam.
cat >> kong.yaml <<'EOF'
- name: kaputt-port
url: http://notes-api:9999
routes:
- name: kaputt-port
paths: [/kaputt/port]
- name: kaputt-dns
url: http://gibtsnicht:8080
routes:
- name: kaputt-dns
paths: [/kaputt/dns]
- name: langsam
url: http://echo:8080/delay/3
read_timeout: 1000
retries: 0
routes:
- name: langsam
paths: [/langsam]
EOF
kreload
for p in kaputt/port kaputt/dns langsam; do
curl -s -w ' %{http_code}\n' $PROXY/$p | tr -d '\n'; echo
doneErwartet (gekürzt):
Kong reloaded
{ "message":"An invalid response was received from the upstream server", … } 502
{ "message":"name resolution failed", … } 503
{ "message":"The upstream server is timing out", … } 504
| Code | Bedeutung bei Kong |
|---|---|
404 mit no Route matched |
keine Route passt |
| 502 | Backend nicht erreichbar oder Unsinn geantwortet |
| 503 | Name nicht auflösbar oder kein gesundes Target (Tag 9) |
| 504 | read_timeout überschritten |
Die Details stehen im Log von Kong, mit request_id:
docker compose logs kong 2>&1 | grep '\[error\]' | tail -3 | cut -c1-120Erwartet (gekürzt):
kong-1 | … [error] … connect() failed (111: Connection refused) while connecting to u…
kong-1 | … [error] … DNS resolution failed: dns server error: 3 name error. Tried: …
kong-1 | … [error] … upstream timed out (110: Connection timed out) while reading res…
Fortschritt speichern? Kostenlos registrieren
Drill 6: Aufräumen und festhalten
Die kaputten Services fliegen raus, dazu kommt die Version der API. Der Stand von heute liegt im Begleitcode:
cp ~/kong-lab/code/tag02/kong.yaml ~/kong-lab/kong/kong.yaml
docker compose exec kong kong config parse /kong/kong.yaml
kreload
curl -s $ADMIN/routes | jq -r '.data[] | [.name, (.paths // [] | join(",")),
(.methods // [] | join(",")), (.hosts // [] | join(","))] | @tsv' | sortErwartet (gekürzt):
parse successful
Kong reloaded
api-rest /api
echo /echo
echo-host echo.lab
notes-lesen /api/v1/notes GET
notes-schreiben /api/v1/notes POST
notes-version /api/v1/version GET
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
curl -s $PROXY/api/v1/notes | jq lengthErwartet: mindestens zwei Notizen, gelesen durch Kong.
2
curl -s $ADMIN/services/notes | jq -c '{host, port, path, retries, read_timeout}'Erwartet: der Service mit internem Pfad /notes und den
Standardwerten.
{"host":"notes-api","port":8080,"path":"/notes","retries":5,"read_timeout":60000}
curl -s -o /dev/null -w '%{http_code}\n' $PROXY/kaputt/portErwartet: Die kaputte Route gibt es nicht mehr; /kaputt
passt zu keiner Route.
404
Challenge
Veröffentliche /version von notes-api als
GET /api/v1/version. Ein POST auf denselben
Pfad darf nicht bei notes-api ankommen. Wohin geht er stattdessen?
Hinweis: Ein eigener Service mit Pfad
/version und eine Route mit methods.
Lösung
Der Stand aus Drill 6 enthält die Lösung bereits:
- name: notes-version
url: http://notes-api:8080/version
routes:
- name: notes-version
paths:
- /api/v1/version
methods:
- GETcurl -s $PROXY/api/v1/version
curl -s -X POST $PROXY/api/v1/version | jq -c '{url, method}'Erwartet:
0.2.0
{"url":"http://echo:8080/anything/v1/version","method":"POST"}
Der POST fällt auf die Auffang-Route /api.
In Produktion wäre das eine Lücke: Auffang-Routes führen zu einem
Dienst, der sauber 404 antwortet, nicht zu einem Echo.
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- Router: Kong 3.9 nutzt standardmäßig
router_flavor = traditional_compatible. Die Varianteexpressionserlaubt Regeln wiehttp.path ^= "/api" && http.method == "GET"mit festen Prioritäten. - Timeouts: 60 s für Verbinden, Lesen und Schreiben
sind für APIs zu lang. Setz sie pro Service passend zum Backend, dazu
retriesnur bei idempotenten Aufrufen. - Versionierte Pfade (
/api/v1) im Gateway erlauben es, eine v2 auf einen neuen Service zu legen, ohne Clients zu brechen. - Auffang-Routes gehören auf einen Dienst, der nichts verrät, oder weg.