Skip to content
Hands-on IT IT Drills

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)