deck-gateway

decK gateway workflows

Goal

Generate, inspect, and apply Kong Gateway entity configuration with decK without losing track of live state, scope, or deployment model.

Use this skill for Gateway entities and Gateway-oriented GitOps. Do not use it as a replacement for Konnect platform workflows that belong in kongctl or Terraform.

Tool Positioning

• Use the shared kong-konnect MCP server first for live Konnect inspection when the target Gateway entities live in Konnect and MCP is available.
• Use this skill when the repository already uses decK, _format_version, or deck gateway commands, or when the user explicitly asks for decK.
• Use a domain skill or kongctl-query first when the real task is incident diagnosis, live-state discovery, or Konnect inspection before a repo-owned decK slice is identified.
• Preserve the existing decK layout, file split, tags, and CI patterns in the repository.
• Do not convert a Terraform or kongctl repository to decK unless the user explicitly asks for that migration.
• Hand off to terraform-kong-gateway, terraform-konnect, or kongctl-declarative when the user wants HCL or kongctl rather than decK.

References To Load

Load only the reference file that matches the active branch:

• references/command-paths.md
  • Load when choosing between validate, diff, sync, dump, or file-generation paths.
• references/openapi-generation.md
  • Load when the user is starting from an OpenAPI document and wants Gateway entities derived from it.
• references/state-shaping-and-tags.md
  • Load when file split, tags, include boundaries, or ownership shape matters more than the entity content itself.
• references/dump-diff-sync-safety.md
  • Load when the main question is how to inspect live state safely before mutating it.

Validation Contract

Preflight

Before editing files or proposing a live sync:

• Confirm deck is installed and runnable: deck version
• Confirm the target deployment model and live target:
  • self-managed Gateway via Admin API
  • Konnect-managed control plane via the appropriate Konnect auth flags
• Confirm credentials are already available through environment variables, config files, or secure host settings. Never echo or commit secrets.
• Inspect the current file structure before writing new files.
• Confirm the ownership boundary:
  • which state file, directory, include path, or wrapper script is in scope
  • whether tags are used to scope ownership
  • which environment or control plane the commands should touch
• Confirm whether the task is declarative authoring, preview, export, or live mutation before choosing a decK path.

Preview

• Validate the exact file, directory, or include path being edited.
• Run the smallest scoped diff that shows only the intended entity slice.
• Use scoped dump only when live inspection is required.
• Check file scope, include boundaries, tag scope, and unintended deletes before any sync.

Execute

• Describe the intended live effect before any mutating command.
• Run deck gateway sync only when the user explicitly asked for mutation.
• Keep sync aligned with the already previewed file, directory, tags, or include boundary.

Prove

• Rerun the same scoped deck gateway diff and expect no remaining intended changes.
• Verify the exact entity slice touched when the change is narrower than the whole repo.
• Do not treat sync success alone as proof that the live Gateway now matches intent.

Operating Rules

• Treat decK as the source-controlled representation of Gateway entities, not as proof that the live Gateway currently matches it.
• If a required deck command appears blocked by the agent environment rather than the live product or CLI itself, request an unsandboxed retry with approval before assuming auth or command failure.
• Treat deck gateway validate plus a scoped deck gateway diff as the required preview surface before sync.
• Preserve existing file segmentation and tags when the repository already has them.
• Prefer additive or scoped changes over broad re-dumps of an entire control plane unless the user asks for a full export.
• Prefer repository-owned state files as the source of intended config. Use live dumps to inspect or recover, not as the default authoring format.
• Keep Konnect platform resources out of decK files. decK is for Gateway entities, not the full Konnect product surface.
• Use OpenAPI-driven generation when the user is starting from an API spec and wants Gateway entities derived from it.
• Do not assume decK is the right answer for DB-less runtime loading, identity or team management, or non-Gateway Konnect resources.

Workflow

1. Inspect the existing decK shape

Identify:

• whether the repo already has one or more decK state files
• whether config is split by environment, workspace, or service
• whether tags are used to scope ownership
• whether CI uses deck gateway diff, deck gateway sync, or wrapper scripts

Match the existing conventions before adding new files or commands.

2. Confirm the target Gateway surface

Pin down:

• self-managed Gateway versus Konnect control plane
• which Gateway entities are in scope: services, routes, plugins, consumers, consumer groups, upstreams, targets, certificates, or vault-related config
• whether the task is create, update, dump, validate, drift review, or import

Do not treat platform resources such as teams, portals, or access rules as Gateway entities.

3. Preview with decK's native safety surface

Pick the smallest decK path that answers the request:

• validate structure or file shape before drift review
• diff the owned slice before proposing mutation
• dump live state only when inspection or recovery requires it
• sync only when the user requested live mutation
• use the OpenAPI generation path only when the source of truth is a spec

Load references/command-paths.md when several decK paths could fit and you need a sharper decision rule.

4. Author or update state files

When editing state:

• preserve the repository's existing split-by-file or split-by-domain layout
• keep entity names and tags stable when possible
• avoid unnecessary reordering or formatting churn
• add only the entities needed for the requested change

Load references/state-shaping-and-tags.md when the repo's split, tags, or include boundaries are the main constraint.

5. Execute only when requested

• State the intended live effect before presenting or running a mutating command.
• Use deck gateway sync only when the user explicitly asked for live mutation.
• Keep the command scoped to the file, tags, select-tags, or include boundary already previewed.

Load references/dump-diff-sync-safety.md when the user needs a safer inspection-first path or is about to use a broad dump/sync flow.

6. Prove the result with decK

After any requested sync:

• rerun the same scoped deck gateway diff and expect no remaining intended changes
• when the task is narrower than the repo, verify the target entity slice rather than trusting a broad sync success message
• call out any remaining drift outside the owned slice instead of hiding it
• do not treat sync exit status alone as proof that the live Gateway now matches the intended state

7. Report the exact effect

State:

• which files changed
• which Gateway entities are affected
• whether the result is only declarative authoring, a drift review, or a live sync
• what the next user-visible verification step is

Kong-Specific Gotchas

• decK is strongest for Gateway entities, not the broader Konnect platform.
• A decK file in Git does not prove the live control plane matches it.
• Broad sync runs can overwrite adjacent entity changes when file scope or tag scope is too loose.
• Konnect control planes still use decK for Gateway-entity workflows, but the surrounding platform resources may belong in another tool.
• If a user really wants HCL plus Terraform state, forcing decK adds unnecessary translation.

Validation Checklist

Before answering, verify that you can state:

• why decK is the right tool for this repository or request
• which repo-owned file, include boundary, or tag boundary is authoritative
• which Gateway entities are in scope
• which deck preview commands prove the intended change safely
• whether the task is authoring, diffing, dumping, or syncing
• which environment the commands should target
• whether a live mutation was requested or only a declarative change
• how the post-change proof step will confirm the exact affected slice
• whether another tool skill should own the implementation instead

Handoffs

• Use terraform-kong-gateway when the repository already manages self-managed Gateway config in HCL.
• Use terraform-konnect when the repository already manages Konnect-hosted Gateway entities or surrounding Konnect resources in HCL.
• Use kongctl-declarative when the task is really Konnect platform YAML rather than Gateway-entity decK.
• Use kongctl-query or the relevant domain skill when the user first needs live inspection rather than config authoring.