terraform-kong-gateway

Use when editing or reviewing Terraform that manages self-managed Kong Gateway Admin API entities with the official kong/kong-gateway provider; not for Konnect resources, decK-native Gateway GitOps, or gateway troubleshooting before tool choice.

Goal

Author or revise Terraform-managed self-managed Kong Gateway entities while preserving the repository’s current module layout, provider model, and state ownership.

Use this skill once Terraform is already the right tool for Admin API-backed self-managed Gateway work. Do not use it as the default for Konnect platform resources or for design and troubleshooting work that should happen before tool-specific HCL changes.

Tool Positioning

• Use this skill when the repository already uses Terraform for self-managed Gateway resources or the user explicitly asks for Terraform.
• This skill owns HCL authoring, import-first adoption, plan review, and Terraform-native proof after the Terraform path is chosen.
• Preserve existing Terraform modules, variables, backend settings, and workspaces.
• Use the official kong/kong-gateway provider for self-managed Gateway resources reachable through the Admin API.
• Hand off to deck-gateway when the user wants file-based Gateway GitOps, dump/diff workflows, or a decK-native repository.
• Hand off to terraform-konnect when the target resources actually belong to Konnect rather than a self-managed Admin API surface.
• Hand off to Gateway or product-specific diagnosis skills when the harder problem is gateway health, plugin behavior, or design intent rather than HCL ownership.

References To Load

Load only the reference file that matches the active branch:

• references/provider-and-import.md
  • Load when provider inputs, existing live resources, or import-first handling is the main question.
• references/entity-patterns.md
  • Load when the user is deciding how self-managed Gateway entities should be grouped or modeled in the existing HCL layout.
• references/plan-safety-and-state.md
  • Load when the main issue is how to inspect plan impact safely before applying to a live Admin API surface.
• references/provider-schema-debugging.md
  • Load when nested resource shape is unclear, validation reports object-vs-string or similar type mismatches, or provider behavior does not line up cleanly with docs or example HCL.

Validation Contract

Preflight

Before writing HCL or proposing a plan:

• Confirm Terraform is installed and runnable.
• Confirm the target Admin API endpoint and auth method already exist.
• Inspect provider blocks, backend settings, workspace selection, and module conventions before adding HCL.
• Keep Admin API tokens and secrets out of committed files.
• Confirm whether existing live Gateway entities must be imported before planning.
• Use terraform providers schema -json as the default source of truth when nested resource shape is unclear before guessing from docs or examples

Preview

Use Terraform’s native preview surface before apply:

• run the repo’s normal format and validation checks when they exist
• run terraform validate
• run terraform plan
• import first when a live Service, Route, plugin, or other entity already exists and should be brought under state
• check the exact resource addresses, environment, and create-update-destroy shape before considering apply

Execute

• Describe the intended effect before any mutating command.
• Run terraform apply only when the user explicitly asked for live mutation.
• Keep apply scoped to the same directory, workspace, and variable inputs that were previewed.

Prove

After a requested apply:

• confirm the intended resource addresses are now present in Terraform state
• inspect key addresses with terraform state show <address> or the repo’s normal output surface
• when practical, run a follow-up terraform plan and expect no remaining intended changes for the touched slice
• do not treat apply success by itself as proof that the live Gateway matches intent

Operating Rules

• Preserve existing HCL layout, resource grouping, and variable usage.
• Use terraform providers schema -json as the default source of truth for unknown nested resource shape before guessing HCL from docs or examples.
• Prefer terraform plan before terraform apply unless the user explicitly asks for direct execution.
• If terraform providers schema -json, provider startup, terraform validate, or terraform plan fails in a way that suggests sandbox interference, retry outside the sandbox with approval before treating it as a provider, auth, or schema problem.
• Prefer importing existing Gateway resources over recreating them.
• Keep the scope limited to the Gateway entities requested by the user.
• Do not mix self-managed Gateway assumptions into Konnect tasks.
• When the repository already uses decK, do not switch it to Terraform unless migration is the task.
• Do not treat a successful terraform apply as proof by itself; follow with state or plan-based verification of the touched addresses.

Workflow

1. Classify the ownership boundary

Establish whether the task is actually:

• self-managed Gateway Admin API configuration that this skill should own
• Konnect platform configuration that belongs to terraform-konnect
• a decK-native Gateway workflow that belongs to deck-gateway
• gateway behavior or design diagnosis that should be resolved before Terraform-specific implementation

Do not write HCL until that split is clear.

2. Inspect the Terraform shape

Identify:

• root and child modules
• provider aliases
• backend or remote state configuration
• variable files and secrets conventions
• existing ownership boundaries for services, routes, plugins, consumers, or certificates

3. Confirm the target Gateway surface

Pin down:

• which Admin API endpoint is in scope
• which Gateway entities are being managed
• whether the task is create, update, import, or drift correction

Load references/provider-and-import.md when provider inputs, import-first adoption, or Admin API targeting is the real uncertainty.

4. Choose the narrow implementation path

Default paths:

• new managed entity: add HCL in the existing module layout
• existing unmanaged entity: import first, then normalize the HCL
• large-scale file-based Gateway GitOps: consider deck-gateway instead of forcing Terraform if that matches the user’s intent better

Load references/entity-patterns.md when repo ownership shape is the harder question. Load references/provider-schema-debugging.md when resource shape is the main uncertainty.

5. Author HCL with minimal churn

• reuse existing variables and locals
• keep names and identifiers stable
• avoid broad refactors while making a narrow Gateway change
• add outputs only when another module or pipeline consumes them
• inspect terraform providers schema -json before guessing nested block or attribute structure

6. Preview before any apply path

• run the repo’s normal format and validation checks when they exist
• run terraform validate
• run terraform plan
• import first if the plan would recreate an entity that already exists live
• inspect whether the plan touches only the intended addresses and workspace

Load references/plan-safety-and-state.md when the operator needs a safer inspection-first path before touching a live Gateway.

7. Execute only when requested

• Describe the intended live effect before presenting or running terraform apply.
• Use the same directory, workspace, and variable inputs that produced the reviewed plan.
• Run terraform apply only when the user explicitly asked to mutate live Gateway state.

8. Prove the result with Terraform-native checks

After any requested terraform apply:

• confirm the touched resource addresses now appear in terraform state list
• inspect key addresses with terraform state show <address> or the repo’s normal outputs
• when practical, run a follow-up terraform plan and expect no remaining intended changes for the affected slice
• call out remaining drift or ownership surprises instead of hiding them behind apply success

9. Report config and state impact

State:

• which files or modules changed
• which Gateway entities are affected
• whether import is required
• whether the next step is plan, apply, or external verification

Kong-Specific Gotchas

• Terraform state is not a substitute for checking what the live Gateway already has; import matters.
• Recreating existing plugins, services, or routes can cause avoidable identifier churn.
• Provider docs and Gateway examples can describe intent, but the Terraform provider schema is the authoritative shape for nested HCL.
• Some teams use Terraform for infrastructure but decK for Gateway entities; preserve the established split if it already exists.
• A self-managed Admin API workflow is not the same as a Konnect control plane workflow even if the resource names look similar.

Validation Checklist

Before answering, verify that you can state:

• why Terraform is the right tool for this repository or request
• which Admin API-backed Gateway surface is in scope
• which module or file owns the resources
• whether import is required
• which preview commands prove the intended change before mutation
• whether provider schema inspection is needed before guessing nested HCL shape
• whether the task stops at HCL authoring or continues to plan/apply
• how the touched resource addresses will be proved after apply
• whether deck-gateway would be a better fit for the user’s intent

Handoffs

• Use deck-gateway when the user wants decK-native Gateway GitOps or live Gateway export/diff workflows.
• Use terraform-konnect when the resources actually belong to Konnect.
• Use Gateway or product-specific domain skills when the user first needs troubleshooting or design help rather than HCL authoring.