kongctl-declarative

kongctl declarative workflows

Goal

Author, update, review, and execute kongctl declarative configuration for Konnect without drifting into read-only query work or a different declarative toolchain.

Tool Positioning

• Use this skill when the repository already manages Konnect resources through kongctl YAML, _defaults.kongctl, or kongctl plan/apply workflows, or when the user explicitly asks for kongctl.
• Use the shared kong-konnect MCP server first when the task depends on live Konnect state and MCP is available.
• Use kongctl-query for read-only inspection, exact get syntax, output shaping, or CLI-shaped proof that should not mutate state.
• Preserve the repository's existing declarative toolchain. Do not convert decK or Terraform repositories to kongctl unless the user explicitly asks.
• Choose execution style from user intent:
  • User-run mode: explain the path and give commands.
  • Agent-run mode: execute the commands and report results.

References To Load

Load only the branch that matches the task:

• references/commands.md
  • Load for command selection, saved-plan versus inline execution, adopt/dump command shape, output mode behavior, and guardrail flags.
• references/resources.md
  • Load for ownership layout, _defaults, parent versus child metadata, !file, !ref, and schema discovery.
• references/apiops-openapi.md
  • Load when the task generates or updates apis resources from OpenAPI.
• references/cicd-github-actions.md
  • Load for GitHub Actions validation or deployment workflows.
• references/troubleshooting.md
  • Load when preview or execution fails, or when drift and namespace behavior are unclear.

This skill must stay portable across repositories. Do not assume the upstream kongctl repo layout or a local docs/ tree.

Validation Contract

Preflight

Before editing manifests or proposing execution:

• Confirm the repository already owns the target Konnect slice through kongctl rather than decK or Terraform.
• Confirm the CLI is available and authentication works with a small read command such as kongctl get organization -o json.
• Confirm namespace, profile, file scope, and whether !file usage will require --base-dir.
• If exact syntax is uncertain, check local help instead of guessing.

Preview

Use the smallest preview surface that matches intent:

• review or CI path: generate a saved plan or a scoped diff artifact
• apply/sync/delete execution path: run a scoped diff or inline --dry-run
• adopt path: read the target resource and its labels, then state the exact namespace label change
• inspect unexpected deletes, wrong namespace ownership, unresolved !ref values, and !file boundary issues before mutation

Execute

• Run live apply, sync, or delete only after a plan, diff, or --dry-run preview and the user confirms that previewed change in the conversation.
• For adopt, preview through read-only inspection of the target and its labels, state the exact label change, and wait for conversation confirmation. Using --overwrite-namespace needs its own confirmation.
• A request for direct execution does not skip these gates. In a CI deployment job, the pull-request plan/diff job and merge review are the preview and confirmation.
• State the intended effect in plain language before any mutating command.
• Keep execution aligned with the previewed path instead of switching tools or widening scope mid-task.

Prove

After a requested mutation:

• rerun the matching preview path and expect no remaining intended drift
• confirm the exact namespace and resource slice now reflect the intended state
• for adopt or dump workflows, prove the integrated declarative config is clean instead of stopping at a successful command

Operating Rules

• If live Konnect state matters and MCP is unavailable, say so early and continue with kongctl-based inspection as the fallback.
• Prefer explicit namespace, profile, and output flags when environment or profile defaults could obscure behavior.
• Treat sync and delete as destructive. Follow the Preview and Execute gates for every live mutation.
• Inspect environment variable names only, never their values. Do not read credential files or print, log, or commit tokens or config-file secrets.
• Use adopt only for existing unmanaged parent resources. adopt labels the resource for namespace ownership; it does not rewrite the resource fields.
• Keep OpenAPI files in their existing repository locations. Prefer !file extraction and !ref links over copied literals or hard-coded UUIDs.
• Keep resolved !file paths and --base-dir within the repository that owns the declarative config. Never use absolute paths that leave the repository or symlinks that escape it, or reference credential, key, or env files.
• Do not place non-resource YAML inside a --recursive declarative tree. If a directory mixes resource YAML with specs or docs, target specific files instead of the whole tree.
• When scope is unclear, inspect existing manifests or live state. Do not invent a default starter bundle of Konnect resources.
• If a required kongctl command appears blocked by the agent sandbox rather than by Konnect or the CLI, ask the user to run it or approve a retry outside the sandbox before diagnosing the command itself as broken.

Workflow

1. Identify the owned declarative root and target file scope. If the path is not provided, search for existing _defaults.kongctl, apis, portals, control_planes, or related kongctl resource keys instead of assuming konnect/resources/.
2. Classify the branch before editing:
   • general manifest authoring or repair: load references/resources.md
   • OpenAPI-driven API modeling: also load references/apiops-openapi.md
   • adopt or dump integration: also load references/commands.md
   • CI/CD workflow work: also load references/cicd-github-actions.md
3. Update manifests in place, preserving the repository's file layout, ownership boundaries, and existing reference patterns.
4. Run the validation gates in order: Preflight, Preview, Execute if confirmed, then Prove.
5. Report the files changed, the exact command path used, and the proof of the resulting state or remaining drift.

Validation Checklist

Before answering, verify that you can state:

• why kongctl is the correct implementation owner for this request
• which namespace, profile, and file scope the change owns
• which preview path proves the change safely
• whether the user confirmed the previewed change before live mutation
• how post-change proof will confirm the exact resource slice
• whether kongctl-query should provide read-only follow-up proof

Handoffs

• Hand off to kongctl-query when the real task is read-only inspection, auth checking, exact get syntax, or output formatting.
• Hand off to deck-gateway, terraform-konnect, or terraform-kong-gateway when the repository already uses those tools for the target resources.
• Hand off to the relevant Konnect domain skill, or to konnect-platform-router when the workflow owner is unclear, if the user first needs diagnosis or classification rather than declarative implementation.