# 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. - **Type:** Skill - **Install:** `agentstack add skill-kong-ai-marketplace-terraform-kong-gateway` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [Kong](https://agentstack.voostack.com/s/kong) - **Installs:** 0 - **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [Kong](https://github.com/Kong) - **Source:** https://github.com/Kong/ai-marketplace/tree/main/plugins/kong-konnect/skills/terraform-kong-gateway - **Website:** https://konghq.com ## Install ```sh agentstack add skill-kong-ai-marketplace-terraform-kong-gateway ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Terraform for self-managed Kong Gateway ## 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 ` 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 ` 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. ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [Kong](https://github.com/Kong) - **Source:** [Kong/ai-marketplace](https://github.com/Kong/ai-marketplace) - **License:** MIT - **Homepage:** https://konghq.com Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-kong-ai-marketplace-terraform-kong-gateway - Seller: https://agentstack.voostack.com/s/kong - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.