Skip to content
Hands-on IT IT Drills

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/kong and kreload. deck gateway sync comes on Day 7.
  • From today on, kong.yaml is 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 ping

Expected:

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.yaml

Expected (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.yaml

Expected (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.yaml

Expected (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 --oneline

Expected (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.yaml

Expected:

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/version

Expected:

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 .url

Expected:

 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 --oneline

Expected:

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 -3

Expected: 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 -l

Expected: 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.yaml in the repository, pull request with deck file validate, deck gateway validate and deck gateway diff as check steps, roll out after the merge.
  • Separate teams: With a database and select_tags in 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 with patch and add-plugins.
  • Lint: deck file lint checks 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.