deck_man.md

decK Documentation: Managing Kong Gateway Configuration

Overview

decK (Declarative Configuration for Kong) is a CLI tool for managing Kong Gateway configurations using declarative YAML files. It supports backup, restore, drift detection, and synchronization.

---

Key Commands

1. Backup Configuration

Export your current Kong configuration to a YAML file:

deck gateway dump -o kong-backup.yaml

• Workspace support: Add -w <workspace_name> for specific workspaces
• Konnect backup:

  deck gateway dump --konnect-control-plane-name <cp_name> \
    --konnect-token <token> -o konnect-backup.yaml

2. Restore Configuration

Apply a YAML configuration file to Kong:

deck gateway sync -s kong-config.yaml

• Partial updates: Only modifies entities changed in the YAML file
• Dry run: Add --dry-run to preview changes without applying

3. Apply Rate Limit to Specific Consumer

Use the rate-limiting-advanced plugin with consumer reference:

_format_version: "3.0"
consumers:
- username: premium_user
  custom_id: cust_123

plugins:
- name: rate-limiting-advanced
  consumer: premium_user  # Reference specific consumer
  config:
    limit: 100
    window_size: 60
    window_type: sliding
    sync_rate: 1

Apply with:

deck gateway sync -s rate-limit.yaml

4. Diff Configuration

Compare live Kong state with a YAML file:

deck gateway diff -s target-config.yaml

• Output shows additions (green +), removals (red -), and modifications
• Use --selector-tags to filter by tags:

  deck gateway diff -s config.yaml --selector-tags team=finance

---

Sample YAML Configuration

_format_version: "3.0"
services:
- name: api-service
  url: http://backend:3000
  routes:
  - name: api-route
    paths: ["/api"]

consumers:
- username: service_account
  keyauth_credentials:
  - key: "secret-key-123"

plugins:
- name: rate-limiting-advanced
  consumer: service_account
  config:
    limit: 500
    window_size: 3600

---

Workflow Diagram

graph TD
    A[Start] --> B[Backup Config]
    B --> C[Modify YAML]
    C --> D[Diff Changes]
    D --> E{Changes OK?}
    E -->|Yes| F[Sync to Kong]
    E -->|No| C

Loading

---

Best Practices

1. Version Control: Store YAML files in Git
2. CI/CD Integration:

   # Sample CI pipeline
   - deck gateway diff -s config.yaml
   - deck gateway sync -s config.yaml

3. Tagging Strategy: Use tags for environment separation:

   services:
   - name: payment-service
     tags: ["env:prod", "team:finance"]

4. Secret Management: Never store credentials in YAML - use _transform: true for references

---

Troubleshooting

• Validation errors:

  deck gateway validate -s config.yaml

• Connection issues: Verify $KONG_ADMIN_URL or use --kong-addr
• Permission errors: Use --headers "Kong-Admin-Token: <token>"