Appendix A: Cheat Sheet
Everything important from Days 0–15 on a few pages. The number in
parentheses is the day on which you practiced it. When in doubt,
developer.konghq.com, the Admin API itself
(/schemas/plugins/<name>) and
deck --help are authoritative.
Start of the Day and Training Ground
source ~/kong-lab/setup/env.sh # LAB, ADMIN, PROXY, PROXYS, KC (0)
kreload # reload kong.yaml, without a database (1, 2)
ksync # apply kong.yaml via decK, with a database (8)
TOKEN=$(token) # access token from Keycloak (6)
ssh -N -L 8001:localhost:8001 -L 8002:localhost:8002 ubuntu@$KONG_IP # laptop (1)| Port | Purpose | Day |
|---|---|---|
| 8000 / 8443 | Proxy HTTP / HTTPS | 1, 10 |
| 8001 | Admin API (127.0.0.1 only) | 1 |
| 8002 | Kong Manager | 1 |
| 8005 | Cluster: data planes to the control plane | 13 |
| 8100 | Status and /metrics |
1, 12 |
Admin API
| Call | Purpose | Day |
|---|---|---|
GET / |
Version, configuration, plugins | 1 |
GET /status |
Connections, configuration_hash |
1 |
POST /config |
load the entire configuration (without DB, memory only) | 1 |
GET /services, /routes,
/consumers, /plugins |
read objects | 2, 5 |
POST /schemas/plugins/validate |
validate a plugin configuration | 11 |
GET /upstreams/<name>/health |
health of the targets (not on the CP in hybrid mode) | 9, 15 |
DELETE /proxy-cache |
purge the cache | 4 |
GET /clustering/data-planes |
data planes and sync_status |
13 |
decK
deck gateway ping | dump --skip-defaults | validate | diff | sync # (3, 7)
deck file validate kong.yaml # shape only (3)
deck file openapi2kong -s api.yaml | deck file namespace --path-prefix=/api/v2 # (3)
deck file merge a.yaml b.yaml -o neu.yaml # (3, 5)
deck file add-plugins -s kong.yaml plugins.yaml -o kong.yaml # (4)
deck file add-plugins -s kong.yaml --selector '<jsonpath>' --config '{…}' # (4, 11)
deck file patch -s kong.yaml --selector '<jsonpath>' --value 'feld:wert' # (3, 8)
deck file add-tags -s kong.yaml --selector '<jsonpath>' team-notes # (3)
deck file kong2kic -s kong.yaml --class-name kong # (14)JSONPath examples: $.services[?(@.name=="notes")],
$..routes[?(@.name=="notes-lesen")],
$..routes[?(@.name=="notes-schreiben")].plugins[?(@.name=="rate-limiting")].
Plugins in the Book
| Plugin | Priority | Purpose | Day |
|---|---|---|---|
correlation-id |
100001 | ID for every request | 4 |
cors |
2000 | browser access, OPTIONS preflight request |
4 |
jwt |
1450 | verify tokens (RS256, iss) |
6 |
jwt-identity |
1400 | custom plugin: name from the token as a header | 11 |
key-auth / basic-auth |
1250 / 1100 | key / password | 5 |
request-size-limiting |
951 | requests above a size: 413 | 8 |
acl |
950 | allow or block groups | 5 |
rate-limiting |
910 | requests per time window: 429 | 8 |
request-transformer |
801 | set, remove headers | 4, 5 |
proxy-cache |
100 | cache responses | 4 |
prometheus, file-log,
opentelemetry |
– | metrics, logs, traces | 12 |
request-termination |
2 | maintenance mode | 4 |
Kubernetes (KIC)
| Resource | Purpose | Day |
|---|---|---|
GatewayClass with
konghq.com/gatewayclass-unmanaged |
use Kong from Helm | 14 |
Gateway, HTTPRoute |
routes with the Gateway API | 14 |
KongPlugin + annotation
konghq.com/plugins |
plugin on a route | 14 |
KongConsumer + Secret with
konghq.com/credential |
consumer with a key | 14 |
Filters URLRewrite,
RequestHeaderModifier |
path and headers (instead of your own
request-transformer) |
14 |
Failure Modes
| Symptom | Cause | Fix |
|---|---|---|
no Route matched with those values |
no route matches | check path, method, host (2) |
404 page not found (backend text) |
strip_path or wrong prefix |
route and service path (2, 15) |
502 invalid response |
wrong port, backend gone, TLS verification | log, tls_verify, CA (2, 10) |
503 name resolution failed |
host is neither upstream nor in DNS | host in the service (2, 15) |
503 failure to get a peer from the ring-balancer |
no healthy target | backend, /healthz, DB (9, 15) |
504 upstream server is timing out |
read_timeout |
timeout or backend (2) |
405 cannot create … when not using a database |
DB-less | file + kreload (1, 3) |
HTTP 500 on ?tags= |
bug in 3.9.4 without DB | filter with DB (3, 7) |
Invalid signature / 403 with
anonymous |
token tampered with or key rotated | enter the key again (6, 15) |
{"exp":"token expired"} |
token expired | new token (6) |
426 Please use HTTPS protocol |
route HTTPS only | via 8443 (10) |
curl error 60 |
default certificate, SNI missing | add SNI (10, 15) |
| Kong does not start, plugin unknown | plugin in DB, not in KONG_PLUGINS |
KONG_PLUGINS (11) |
Permission denied for cluster.key |
key not owned by UID 1001 | chown 1001:1001 (13, 15) |
DP plugin_set_incompatible |
plugin missing on the DP | plugin on every DP (13, 15) |
| change does not reach the DP | policy: cluster in the DP |
local or redis (13, 15) |
| new route briefly 404 | worker or DP not yet updated | wait a few seconds (1, 7) |