deck-gateway

---
name: deck-gateway
description: Manage Kong Gateway entities with decK. Use for `deck gateway` state files, validate/diff/sync/dump workflows, OpenAPI-derived Gateway config, or GitOps-style Gateway entity repos. Do not use for Konnect platform resources or HCL/kongctl repos.
license: MIT
metadata:
  product: deck
  category: declarative-gateway
  tags:
    - kong
    - deck
    - gateway
    - gitops
    - declarative
---

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

• SKILL.md 9 KB
• references/command-paths.md 1 KB
• references/dump-diff-sync-safety.md 1 KB
• references/openapi-generation.md 1 KB
• references/state-shaping-and-tags.md 1 KB