Zum Inhalt springen
Trainingslager IT-Trainingslager

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, hosts oder headers. 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.yaml bindet das ganze Verzeichnis ~/kong-lab/kong ein, nicht nur kong.yaml. sed -i und 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; echo

Erwartet:

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 -1

Erwartet:

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
done

Erwartet (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-120

Erwartet (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' | sort

Erwartet (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 length

Erwartet: 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/port

Erwartet: 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:
          - GET
curl -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 Variante expressions erlaubt Regeln wie http.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 retries nur 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.