Awesome-omni-skill deck-cli

Manage Kong Gateway and Konnect declaratively using decK CLI. Use when working with Kong Gateway configurations, syncing state, converting OpenAPI specs to Kong config, validating configurations, or automating Kong deployments. Handles declarative configuration files, API lifecycle automation, and Kong entity management.

install

source · Clone the upstream repo

git clone https://github.com/diegosouzapw/awesome-omni-skill

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/diegosouzapw/awesome-omni-skill "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/tools/deck-cli" ~/.claude/skills/diegosouzapw-awesome-omni-skill-deck-cli && rm -rf "$T"

manifest: skills/tools/deck-cli/SKILL.md

source content

decK CLI Agent Skill

Overview

decK is Kong's declarative configuration tool for API Lifecycle Automation. It allows you to manage Kong Gateway and Konnect configurations as code.

Use this skill when:

Configuring or updating Kong Gateway declaratively
Converting OpenAPI specs to Kong configuration
Syncing local configuration to Kong Gateway/Konnect
Validating Kong configurations
Managing Kong entities (Services, Routes, Plugins, Consumers, etc.)
Setting up CI/CD for Kong configurations
Comparing local vs. live Kong state

Quick Reference

Common Commands

Command	Purpose
`deck gateway sync`	Apply local config to Kong Gateway
`deck gateway diff`	Compare local config with Kong state
`deck gateway dump`	Export current Kong state to file
`deck file validate`	Validate configuration file locally
`deck file openapi2kong`	Convert OpenAPI to Kong config
`deck file render`	Render final configuration

Getting Started

1. Check decK Installation

deck version

If decK is not installed, guide the user to install it via:

macOS:
```
brew install deck
```
Linux: Download from GitHub releases
Docker:
```
docker run kong/deck
```

2. Verify Connectivity

For Kong Gateway (default: localhost:8001):

deck gateway ping

For Konnect:

deck gateway ping --konnect-token $KONNECT_TOKEN --konnect-control-plane-name <cp-name>

Core Workflows

Workflow 1: Export Current Kong Configuration

Export everything:

deck gateway dump -o kong.yaml

Export specific workspace:

deck gateway dump --workspace dev -o dev-workspace.yaml

Export with tags:

deck gateway dump --select-tag production -o production.yaml

Workflow 2: Apply Configuration Changes

Preview changes first (dry run):

deck gateway diff -s kong.yaml

Apply changes:

deck gateway sync -s kong.yaml

Apply without deleting (add/update only):

deck gateway apply -s kong.yaml

Workflow 3: Convert OpenAPI to Kong Configuration

deck file openapi2kong -s openapi.yaml -o kong-config.yaml

With additional options:

deck file openapi2kong \
  -s openapi.yaml \
  -o kong-config.yaml \
  --select-tag api-v1 \
  --uuid-base my-api

Workflow 4: Validate Configuration

Local validation (no Kong connection needed):

deck file validate -s kong.yaml

Validate against live Kong Gateway:

deck gateway validate -s kong.yaml

Workflow 5: Lint Configuration

Check for best practices and potential issues:

deck file lint -s kong.yaml

Configuration Files

Basic Structure

decK uses YAML files with Kong entity definitions:

_format_version: "3.0"
_konnect:
  control_plane_name: my-control-plane

services:
- name: example-service
  url: http://example.com
  routes:
  - name: example-route
    paths:
    - /api
    methods:
    - GET
    - POST
  plugins:
  - name: rate-limiting
    config:
      minute: 100
      policy: local

plugins:
- name: cors
  config:
    origins:
    - "*"

Multiple Files

Split configuration across files:

deck gateway sync -s kong.yaml -s plugins.yaml -s routes.yaml

Merge files for rendering:

deck file merge -o combined.yaml kong.yaml plugins.yaml routes.yaml

Authentication Configuration

Kong Gateway (On-Prem)

Using Admin API URL:

deck gateway sync --kong-addr http://localhost:8001 -s kong.yaml

With RBAC token:

deck gateway sync \
  --kong-addr https://admin.kong.example.com \
  --headers "Kong-Admin-Token:$KONG_ADMIN_TOKEN" \
  -s kong.yaml

Kong Konnect

Using personal access token:

export KONNECT_TOKEN=kpat_xxx...
deck gateway sync \
  --konnect-token $KONNECT_TOKEN \
  --konnect-control-plane-name production \
  -s kong.yaml

Using configuration file (

~/.deck.yaml

konnect-token: kpat_xxx...
konnect-control-plane-name: production

Advanced Features

Working with Tags

Select specific tags:

deck gateway sync --select-tag team-a --select-tag production -s kong.yaml

Add tags to all entities:

deck file add-tags -s kong.yaml -o tagged.yaml team-b,staging

Remove tags:

deck file remove-tags -s kong.yaml -o cleaned.yaml old-tag

Workspace Management (Enterprise)

Sync to specific workspace:

deck gateway sync --workspace production -s kong.yaml

Dump workspace:

deck gateway dump --workspace staging -o staging.yaml

De-duplicate Plugin Configuration

Reference shared plugin configs:

_format_version: "3.0"

plugins:
- name: rate-limiting
  _plugin_config_reference: global-rate-limit

_plugin_configs:
  global-rate-limit:
    minute: 100
    hour: 5000

Using Environment Variables

Reference environment variables in config files:

services:
- name: api-service
  url: $(BACKEND_URL)
  routes:
  - name: api-route
    paths:
    - /api

Render with values:

export BACKEND_URL=http://api.example.com
deck file render -s kong.yaml -o rendered.yaml

File Conversion & Transformation

Convert Kong 2.x to 3.x Format

deck file convert \
  --from kong-gateway-2.x \
  --to kong-gateway-3.x \
  --input-file kong-2x.yaml \
  --output-file kong-3x.yaml

Convert to Kubernetes Ingress Controller

deck file kong2kic -s kong.yaml -o k8s-manifests/

Convert to Terraform (Konnect Only)

deck file kong2tf -s kong.yaml -o terraform/

Patch Configuration

Update specific values:

deck file patch -s kong.yaml -o patched.yaml \
  --selector "services[*].retries" \
  --value "5"

Add Plugins

Add plugin to all services:

deck file add-plugins -s kong.yaml -o with-plugins.yaml \
  --selector "services[*]" \
  rate-limiting minute=100

Apply Namespace

Prefix routes by path:

deck file namespace -s kong.yaml -o namespaced.yaml \
  --path-prefix /v1

CI/CD Integration

Basic Pipeline Example

#!/bin/bash
# 1. Validate locally
deck file validate -s kong.yaml || exit 1

# 2. Lint for best practices
deck file lint -s kong.yaml || exit 1

# 3. Preview changes
deck gateway diff -s kong.yaml

# 4. Require approval, then sync
deck gateway sync -s kong.yaml

GitHub Actions

- name: Setup decK
  uses: kong/setup-deck@v1
  with:
    deck-version: 1.38.1

- name: Validate Configuration
  run: deck file validate -s kong.yaml

- name: Sync to Kong
  run: deck gateway sync -s kong.yaml
  env:
    KONNECT_TOKEN: ${{ secrets.KONNECT_TOKEN }}

Troubleshooting

Common Issues

Connection errors:

# Test connectivity
deck gateway ping --verbose

# Check Admin API endpoint
curl http://localhost:8001/

Format validation errors:

Ensure
```
_format_version
```
is set correctly (
```
3.0
```
for Kong 3.x)
Check YAML syntax with a validator
Run
```
deck file validate
```
for detailed errors

Entity conflicts:

Use
```
deck gateway diff
```
to see what will change
Use
```
--select-tag
```
to limit scope
Check for duplicate names or IDs

Authentication issues:

Verify token is valid and not expired
Check RBAC permissions for the token
Ensure control plane name is correct (Konnect)

Debug Mode

Enable verbose output:

deck gateway sync -s kong.yaml --verbose 3

Best Practices

Always diff before sync: Use
```
deck gateway diff
```
to preview changes
Use tags for segmentation: Organize configs by team, environment, or API
Version control: Keep decK files in Git
Environment-specific configs: Use separate files for dev/staging/prod
Validate early: Run
```
deck file validate
```
before committing
Test in non-prod first: Validate changes in lower environments
Use workspace isolation: Leverage workspaces for multi-tenancy
Back up before major changes: Run
```
deck gateway dump
```
first

Important Notes

decK manages Kong Gateway state declaratively - it will delete entities not in your config file (unless using
```
apply
```
instead of
```
sync
```
)
Always use
```
--select-tag
```
in production to limit the scope of operations
decK does not manage:
- Kong configuration properties (kong.conf)
- Key-auth credentials (stored separately for security)
- Some Enterprise-only features (requires special flags)

Quick Checklist

Before running

deck gateway sync

Run
```
deck file validate -s <file>
```
Run
```
deck gateway diff -s <file>
```
to preview
Backup current state:
```
deck gateway dump -o backup.yaml
```
Verify authentication works:
```
deck gateway ping
```
Consider using
```
--dry-run
```
flag first
Have rollback plan ready

Next Steps

For detailed command reference and advanced scenarios, consult:

Official decK documentation
decK GitHub repository
The
```
references/
```
directory in this skill for command-specific details