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/getErwartet (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/getErwartet:
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_hashErwartet (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.
Unter Gateway Services steht der Service
echo aus deiner Datei.
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.databaseErwartet: 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 -1Erwartet (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_PROCESSESlegt die Zahl fest, etwa in Containern mit CPU-Limit.