Day 3: Declarative with decK
Goal: Export Kong’s configuration with decK, validate it, compare it and generate it from an OpenAPI description, and version it with Git. · Duration: approx. 60 min · Prerequisite: Day 2
Briefing
- decK has two groups of commands:
deck gateway …talks to the Admin API,deck file …works on files only. - Workflow: change the file →
validate→diff→ apply → commit. - Without a database, decK can validate and compare, but not apply.
Applying means for today: file to
~/kong-lab/kongandkreload.deck gateway synccomes on Day 7. - From today on,
kong.yamlis a Git repository.
notes-openapi.yaml ─openapi2kong─► v2.yaml ─merge─► kong.yaml ─validate/diff─► Kong
│
git
Drill 1: Connect decK
source ~/kong-lab/setup/env.sh
mkdir -p ~/kong-lab/tag03 && cd ~/kong-lab/tag03
echo $DECK_ANALYTICS
deck gateway pingExpected:
off
Successfully connected to Kong!
Kong version: 3.9.4
By default, decK talks to http://localhost:8001
(--kong-addr). env.sh sets
DECK_ANALYTICS=off: without this variable, decK sends
anonymous usage data to Kong.
Save your progress? Sign up for free
Drill 2: What Kong Really Has
deck gateway dump -o dump.yaml
wc -l dump.yaml ~/kong-lab/kong/kong.yaml
sed -n '1,14p' dump.yaml
deck gateway dump --skip-defaults | sed -n '1,10p'Expected (shortened):
129 dump.yaml
40 /home/ubuntu/kong-lab/kong/kong.yaml
169 total
_format_version: "3.0"
services:
- connect_timeout: 60000
enabled: true
host: echo
name: api-rest
path: /anything
port: 8080
protocol: http
read_timeout: 60000
retries: 5
routes:
- https_redirect_status_code: 426
_format_version: "3.0"
services:
- host: echo
name: api-rest
path: /anything
port: 8080
routes:
- name: api-rest
paths:
- /api
40 lines become 129: Kong adds every default value.
--skip-defaults leaves them out and produces a file you
actually want to read and version.
Save your progress? Sign up for free
Drill 3: Validate, Offline and Online
kaputt.yaml contains three errors. Find them with
decK:
cp ~/kong-lab/code/tag03/kaputt.yaml .
deck file validate kaputt.yamlExpected (shortened):
Error: 1 errors occurred:
reading file kaputt.yaml: validating file content: 1 errors occurred:
validation error: object=["/echo"], err=services.0.routes.0: Additional property
pathes is not allowed
deck file validate checks only the shape offline:
unknown fields, wrong types. Once the typo is fixed, the file is fine as
far as decK is concerned:
sed -i 's/pathes/paths/' kaputt.yaml
deck file validate kaputt.yaml && echo "file: ok"
deck gateway validate kaputt.yamlExpected (shortened):
file: ok
Error: validate entity 'services (notes)': HTTP status 400 (message: "2 schema
violations (protocol: expected one of: grpc, grpcs, http, https, tcp, tls,
tls_passthrough, udp; read_timeout: value should be between 1 and 2147483646)")
deck gateway validate asks Kong itself, without changing
anything. Only Kong’s schema knows the allowed protocols and value
ranges. In CI, both run.
sed -i 's|htp://|http://|; /read_timeout: -5/d' kaputt.yaml
deck gateway validate kaputt.yaml && echo "gateway: ok"Expected:
gateway: ok
Save your progress? Sign up for free
Drill 4: Compare and Apply
Plan a change: a new service, without touching the running Kong.
cp ~/kong-lab/kong/kong.yaml neu.yaml
cat >> neu.yaml <<'EOF'
- name: echo-neu
url: http://echo:8080/anything
routes:
- name: echo-neu
paths: [/neu]
EOF
deck gateway diff neu.yaml
deck gateway sync neu.yamlExpected (shortened):
creating service echo-neu
creating route echo-neu
Summary:
Created: 2
Updated: 0
Deleted: 0
creating service echo-neu
Dropped creation route echo-neu
…
Error: 1 errors occurred:
while processing event: Create service echo-neu failed: HTTP status 405 (message:
"cannot create or update 'services' entities when not using a database")
diff shows exactly what would change. sync
fails at the same limit as on Day 1: without a database, no individual
objects. Here you apply by loading the file. You do not need the new
service; neu.yaml stays where it is.
Save your progress? Sign up for free
Drill 5: kong.yaml Under Git
cd ~/kong-lab/kong
git config --global user.name >/dev/null || git config --global user.name "Lab"
git config --global user.email >/dev/null || git config --global user.email [email protected]
git init -q -b main
git add kong.yaml compose.yaml
git commit -qm "Stand Tag 2"
git log --onelineExpected (your hash will differ):
f70b3be Stand Tag 2
From now on, every change to Kong is a commit. git log
tells you who changed what and when, and git checkout takes
you back.
Save your progress? Sign up for free
Drill 6: From OpenAPI to Kong
notes-openapi.yaml describes the notes-api API. decK
turns it into services and routes and puts them under
/api/v2:
cd ~/kong-lab/tag03
cp ~/kong-lab/code/tag03/notes-openapi.yaml .
grep -E 'x-kong-name|operationId|url:' notes-openapi.yaml
deck file openapi2kong -s notes-openapi.yaml \
| deck file namespace --path-prefix=/api/v2 -o v2.yaml
grep -E '^ name:|^ name:|~/api' v2.yamlExpected:
x-kong-name: notes-v2
- url: http://notes-api:8080
operationId: notes-lesen
operationId: notes-schreiben
operationId: version
name: notes-v2
name: pre-function
name: notes-v2_notes-lesen
- ~/api/v2/notes$
name: notes-v2_notes-schreiben
- ~/api/v2/notes$
name: notes-v2_version
- ~/api/v2/version$
One route per operation with a regex path (~ at the
start); the service is named after x-kong-name.
namespace puts the prefix in front and attaches a small
pre-function plugin that removes /api/v2 again
before forwarding.
Merge both files, validate, compare and load:
deck file merge ~/kong-lab/kong/kong.yaml v2.yaml -o merged.yaml
deck gateway validate merged.yaml && deck gateway diff merged.yaml | tail -4
cp merged.yaml ~/kong-lab/kong/kong.yaml && kreload
curl -s $PROXY/api/v2/notes | jq -c '.[0].text'
curl -s $PROXY/api/v2/versionExpected:
Summary:
Created: 5
Updated: 0
Deleted: 0
Kong reloaded
"vor dem Gateway"
0.2.0
The v2 was an experiment. Git brings back the old state:
cd ~/kong-lab/kong
git diff --stat
git checkout kong.yaml && kreload
curl -s $PROXY/api/v2/version | jq -r .urlExpected:
kong.yaml | 119 +++++++++++++++++++++++++++++++++++++++++++-------------------
1 file changed, 83 insertions(+), 36 deletions(-)
Updated 1 path from the index
Kong reloaded
http://echo:8080/anything/v2/version
/api/v2/version lands on the catch-all route from Day 2
again.
Save your progress? Sign up for free
Drill 7: Rules for Many Services
All services of the notes team should carry a tag and get shorter timeouts. Instead of doing it by hand: decK with a JSONPath selector.
cd ~/kong-lab/tag03
SEL='$.services[?(@.name=="notes" || @.name=="notes-version")]'
deck file add-tags -s ~/kong-lab/kong/kong.yaml --selector "$SEL" team-notes -o t1.yaml
deck file patch -s t1.yaml --selector "$SEL" \
--value 'read_timeout:10000' --value 'connect_timeout:2000' -o t2.yaml
deck gateway diff t2.yaml | grep -E '^(updating|[-+] )'Expected (shortened):
updating service notes-version {
- "connect_timeout": 60000,
+ "connect_timeout": 2000,
- "read_timeout": 60000,
+ "read_timeout": 10000,
+ "tags": [
+ "team-notes"
+ ]
updating service notes {
- "connect_timeout": 60000,
+ "connect_timeout": 2000,
- "read_timeout": 60000,
+ "read_timeout": 10000,
+ "tags": [
+ "team-notes"
+ ]
Take over the state and commit it. The companion code contains the same file:
cp ~/kong-lab/code/tag03/kong.yaml ~/kong-lab/kong/kong.yaml
cd ~/kong-lab/kong && kreload
git add kong.yaml && git commit -qm "Tag 3: Tags und Timeouts"
git log --onelineExpected:
Kong reloaded
2a7ef7f Tag 3: Tags und Timeouts
f70b3be Stand Tag 2
Warning: Kong 3.9.4 without a database answers filters by tags (
/services?tags=team-notes,deck gateway dump --select-tag) with a 500 error. With a database it works (Day 7).
Save your progress? Sign up for free
Checkpoint
deck gateway diff ~/kong-lab/kong/kong.yaml | tail -3Expected: file and running Kong are the same.
Created: 0
Updated: 0
Deleted: 0
curl -s $ADMIN/services/notes | jq -c '{read_timeout, connect_timeout, tags}'Expected: the values from Drill 7.
{"read_timeout":10000,"connect_timeout":2000,"tags":["team-notes"]}
git -C ~/kong-lab/kong status --short | wc -lExpected: nothing uncommitted.
0
Challenge
A colleague “quickly” built a file hotfix.yaml that
contains only one service. What would happen if you loaded it as
kong.yaml? Find out without changing the running Kong.
Note: A declarative file describes the entire state.
Solution
cd ~/kong-lab/tag03
cat > hotfix.yaml <<'EOF'
_format_version: "3.0"
services:
- name: echo
url: http://echo:8080
EOF
deck gateway diff hotfix.yaml | grep -E '^(deleting|Summary)|Deleted'Expected (shortened):
deleting route echo-host
deleting route echo
deleting route notes-version
…
deleting service notes
deleting service notes-version
deleting service api-rest
Summary:
Deleted: 9
Everything that is not in the file would be gone. That is why
diff before every load is mandatory, in CI as well as by
hand.
Save your progress? Sign up for free
Enterprise Note
- GitOps:
kong.yamlin the repository, pull request withdeck file validate,deck gateway validateanddeck gateway diffas check steps, roll out after the merge. - Separate teams: With a database and
select_tagsin the file (_info), each team manages only its own objects (Day 7). Enterprise additionally separates with workspaces. - API-first: OpenAPI is the source, the Kong
configuration is generated from it (
openapi2kong), rules are added withpatchandadd-plugins. - Lint:
deck file lintchecks files against your own rules, such as “every route needs an auth plugin”. - Konnect: With
--konnect-token, the same commands manage the control plane in Kong’s cloud.