Deck CLI

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

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

1. Always diff before sync: Use deck gateway diff to preview changes
2. Use tags for segmentation: Organize configs by team, environment, or API
3. Version control: Keep decK files in Git
4. Environment-specific configs: Use separate files for dev/staging/prod
5. Validate early: Run deck file validate before committing
6. Test in non-prod first: Validate changes in lower environments
7. Use workspace isolation: Leverage workspaces for multi-tenancy
8. 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