Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 1: Erster Start ohne Datenbank

Ziel: Kong ohne Datenbank starten, Admin API, Proxy und Status unterscheiden, eine erste Route veröffentlichen und verstehen, warum die Konfiguration in eine Datei gehört. · Dauer: ca. 60 min · Voraussetzung: Tag 0

Briefing

  • Kong ist nginx mit Lua (OpenResty). Es lauscht auf mehreren Ports mit getrennten Aufgaben: Proxy 8000/8443 für Clients, Admin API 8001 für dich, Kong Manager 8002 als Oberfläche, Status 8100 für Monitoring.
  • DB-less: Kong liest seine ganze Konfiguration aus einer YAML-Datei und hält sie im Speicher. Die Admin API ist dann nur lesbar.
  • Ein Service beschreibt ein Backend, eine Route sagt, welche Anfragen dorthin gehen.
 Client ──► :8000 Proxy ──► Route /echo ──► Service echo ──► echo:8080
 du     ──► :8001 Admin API (nur 127.0.0.1)
 Browser ─► :8002 Kong Manager (über SSH-Tunnel)

Drill 1: Kong starten

source ~/kong-lab/setup/env.sh
cp -R ~/kong-lab/code/kong ~/kong-lab/kong && cd ~/kong-lab/kong
cat kong.yaml
docker compose up -d --wait
docker compose ps --format "table {{.Name}}\t{{.Image}}\t{{.Status}}"

Erwartet (gekürzt):

# kong/kong.yaml – deklarative Konfiguration, Stand Tag 1 (leer)
_format_version: "3.0"
 Container kong-kong-1 Healthy
NAME          IMAGE        STATUS
kong-kong-1   kong:3.9.4   Up 12 seconds (healthy)

~/kong-lab/kong ist ab heute dein Kong. Sieh dir compose.yaml an: KONG_DATABASE: "off" schaltet die Datenbank ab, KONG_DECLARATIVE_CONFIG zeigt auf die eingebundene kong.yaml. Admin API und Kong Manager sind nur an 127.0.0.1 veröffentlicht.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Die Admin API

curl -s $ADMIN | jq '{version, hostname, database: .configuration.database,
  plugins: (.plugins.available_on_server | length)}'
curl -s $ADMIN/services | jq -c .
curl -s $ADMIN/endpoints | jq '.data | length'

Erwartet (gekürzt, IDs und Zeiten weichen bei dir ab):

{
  "version": "3.9.4",
  "hostname": "982ef110d770",
  "database": "off",
  "plugins": 45
}
{"data":[],"next":null}
141

Kong 3.9.4 ohne Datenbank, 45 mitgelieferte Plugins, noch kein Service. Die Admin API hat 141 Endpunkte; jedes Kong-Objekt ist eine Ressource mit GET, POST, PATCH, DELETE.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Der Proxy ohne Route

curl -si $PROXY/echo/get

Erwartet (gekürzt):

HTTP/1.1 404 Not Found
…
X-Kong-Response-Latency: 1
Server: kong/3.9.4
X-Kong-Request-Id: b2125431af0d135323c16d3c1cad392f

{
  "message":"no Route matched with those values",
  "request_id":"b2125431af0d135323c16d3c1cad392f"
}

Die 404 kommt von Kong selbst, nicht von einem Backend: X-Kong-Response-Latency steht nur an Antworten, die Kong selbst erzeugt. Die request_id taucht auch im Log auf und verbindet Client und Gateway bei der Fehlersuche.

Fortschritt speichern? Kostenlos registrieren

Drill 4: DB-less heißt nur lesen

Versuch, einen Service über die Admin API anzulegen:

curl -s -X POST $ADMIN/services -d name=echo -d url=http://echo:8080 | jq .

Erwartet:

{
  "name": "operation unsupported",
  "message": "cannot create 'services' entities when not using a database",
  "code": 12
}

Ohne Datenbank gibt es nichts, wohin Kong einzelne Objekte schreiben könnte. Es gibt nur einen Weg: die ganze Konfiguration auf einmal ersetzen, per POST /config.

Fortschritt speichern? Kostenlos registrieren

Drill 5: Konfiguration im Speicher

mkdir -p ~/kong-lab/tag01 && cd ~/kong-lab/tag01
cat > echo.yaml <<'EOF'
_format_version: "3.0"
services:
  - name: echo
    url: http://echo:8080
    routes:
      - name: echo
        paths:
          - /echo
EOF
curl -s -X POST $ADMIN/config -F [email protected] | jq -c keys
curl -s $PROXY/echo/get | jq -c '{url, via: .headers.Via}'

Erwartet:

["routes","services"]
{"url":"http://echo:8080/get","via":["1.1 kong/3.9.4"]}

Die erste Route lebt. Kong hat /echo abgeschnitten (strip_path, Tag 2) und /get an echo weitergereicht. Jetzt starte Kong neu:

cd ~/kong-lab/kong
docker compose restart
sleep 5
curl -s -o /dev/null -w '%{http_code}\n' $PROXY/echo/get

Erwartet:

 Container kong-kong-1 Started
404

Weg. POST /config lädt nur in den Speicher; beim Start liest Kong wieder die leere kong.yaml. Die Datei ist die Wahrheit, nicht die Admin API.

Fortschritt speichern? Kostenlos registrieren

Drill 6: Die Datei ist die Wahrheit

Schreib die Route in kong.yaml, prüfe die Datei und lade sie ohne Neustart:

cd ~/kong-lab/kong
cat > kong.yaml <<'EOF'
# kong.yaml – Stand Ende Tag 1
_format_version: "3.0"
services:
  - name: echo
    url: http://echo:8080
    routes:
      - name: echo
        paths:
          - /echo
EOF
docker compose exec kong kong config parse /kong/kong.yaml
docker compose exec kong kong reload
sleep 5
curl -s -o /dev/null -w '%{http_code}\n' $PROXY/echo/get
curl -s $ADMIN/status | jq -r .configuration_hash

Erwartet (gekürzt):

parse successful
Kong reloaded
200
06468d6efe65ef19809b539c729c6487

kong config parse findet Tippfehler, bevor Kong sie lädt. kong reload startet die nginx-Worker sanft neu, laufende Verbindungen bleiben. Der configuration_hash war vorher 0000…; nach einem Neustart steht dort derselbe Hash, die Route bleibt.

Der Befehl kehrt zurück, bevor die neuen Worker übernommen haben; für einen Moment antwortet noch die alte Konfiguration. Darum das sleep 5. Ab Tag 2 erledigt das die Funktion kreload aus setup/env.sh: kong reload, dann fünf Sekunden warten.

Fortschritt speichern? Kostenlos registrieren

Drill 7: Kong Manager

Kong Manager ist die Oberfläche der freien Ausgabe. Sie spricht vom Browser aus mit der Admin API, also brauchst du beide Ports. Auf dem Laptop, in einem zweiten Terminal:

ssh -N -L 8001:localhost:8001 -L 8002:localhost:8002 ubuntu@$KONG_IP

Öffne http://localhost:8002 im Browser. Erwartet: die Übersicht mit Edition community, Version 3.9.4 und den Ports wie in der Abbildung.

Kong Manager OSS: Übersicht mit Version und Ports

Unter Gateway Services steht der Service echo aus deiner Datei.

Der Service echo in Kong Manager

Im DB-less-Modus kannst du hier schauen, aber nichts dauerhaft ändern. Beende den Tunnel mit Ctrl+C.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

curl -s $ADMIN | jq -r .configuration.database

Erwartet: Kong läuft ohne Datenbank.

off
curl -s $ADMIN/routes | jq -r '.data[] | [.name, .paths[0]] | @tsv'

Erwartet: die Route aus kong.yaml.

echo    /echo
curl -si $PROXY/echo/get | grep -i '^via'

Erwartet: die Antwort kam durch Kong.

Via: 1.1 kong/3.9.4

Challenge

Ein Kollege behauptet, Kong habe seine Konfiguration „irgendwo gespeichert”. Beweise mit einem einzigen curl gegen die Admin API, dass Kong genau den Inhalt deiner kong.yaml kennt, und finde die Stelle in den Logs, an der Kong die Datei beim Start liest.

Hinweis: GET /config gibt es auch; die Logs liest docker compose logs.

Lösung

curl -s $ADMIN/config | jq -r .config | head -6
docker compose logs kong 2>&1 | grep -i declarative | tail -1

Erwartet (gekürzt):

_format_version: '3.0'
_transform: false
services:
- write_timeout: 60000
  name: echo
  connect_timeout: 60000
kong-1  | … [notice] … init.lua:590 declarative config loaded from /kong/kong.yaml,
context: init_worker_by_lua*

GET /config zeigt die Konfiguration mit allen Standardwerten, die Kong ergänzt hat. Gespeichert ist sie nur im Speicher, gelesen wird sie aus der Datei.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Admin API schützen: Nie offen ins Netz. In der freien Ausgabe gibt es keine Anmeldung an der Admin API; schütze sie per Netz (nur 127.0.0.1, Tunnel) oder über Kong selbst als Route mit Authentifizierung (Tag 10).
  • DB-less in Produktion: Beliebt bei Kubernetes und GitOps: keine Datenbank, die ausfallen kann, jede Instanz liest dieselbe Datei. Dafür keine Änderungen zur Laufzeit.
  • Kong Manager Enterprise hat Anmeldung, Rollen und Workspaces. Die OSS-Variante ist eine reine Ansicht ohne Benutzerverwaltung.
  • Worker: Kong startet einen nginx-Worker pro CPU. KONG_NGINX_WORKER_PROCESSES legt die Zahl fest, etwa in Containern mit CPU-Limit.