Feat: AI Gateway Providers declarative and get/list support

[rspurgeon]

Parent: #737

Tracks the AI Gateway Providers API group from the current AI Gateway OpenAPI spec.

Scope

• Add declarative configuration support for this resource group in kongctl
• Add imperative read support (get/list) for this resource group
• Wire the resource into kongctl explain, kongctl scaffold, docs, and tests

API surface

• GET /ai-gateways/{gatewayId}/providers
• POST /ai-gateways/{gatewayId}/providers
• GET /ai-gateways/{gatewayId}/providers/{providerId}
• PUT /ai-gateways/{gatewayId}/providers/{providerId}
• DELETE /ai-gateways/{gatewayId}/providers/{providerId}

Acceptance criteria

• Declarative resource support covers the lifecycle exposed by this API group
• Resource matching, planning, and execution handle gateway-scoped relationships where applicable
• Imperative get and list commands are available for this resource group
• kongctl explain and kongctl scaffold include this resource
• docs/declarative-resource-reference.md and related CLI docs are updated
• Tests cover declarative behavior and imperative read flows

Notes

• Imperative write commands are out of scope for this issue.
• This is a gateway-scoped child resource under AI Gateways.
• Declarative support should follow the existing nested child-resource patterns used by the engine.

[github-actions]

🎯 Agentic Issue Triage

This is a well-scoped feature issue tracking AI Gateway Providers declarative config and imperative read (get/list) support in kongctl. It is a child of the umbrella issue #737 and follows the same implementation pattern as sibling issues #738–#746.

No spam indicators. Issue is actionable and clearly defined.

---

📋 Summary & Scope

Resource: AI Gateway Providers — a gateway-scoped child resource under AI Gateways.

API surface:

Method	Path
GET	/ai-gateways/{gatewayId}/providers
POST	/ai-gateways/{gatewayId}/providers
GET	/ai-gateways/{gatewayId}/providers/{providerId}
PUT	/ai-gateways/{gatewayId}/providers/{providerId}
DELETE	/ai-gateways/{gatewayId}/providers/{providerId}

Out of scope: Imperative write commands (create, update, delete).

🗺️ Implementation Checklist

• Review planning/DECLARATIVE_RESOURCE_IMPLEMENTATION_GUIDE.md for the canonical step-by-step guide
• Implement the Konnect API client methods for the Providers endpoints (under internal/konnect/)
• Register the resource type in the declarative engine (internal/declarative/)
  • Add resource loader/parser support
  • Add planner logic (create/update/delete lifecycle)
  • Wire gateway-scoped parent reference (gatewayId) into resource matching
• Add imperative get/list commands (internal/cmd/)
• Wire into kongctl explain and kongctl scaffold
• Update docs/declarative-resource-reference.md with the new resource
• Add unit/integration tests for declarative behavior and imperative read flows

🔍 Key Patterns to Follow

• Nested child resource pattern: This resource is scoped under AI Gateways (gatewayId), similar to how other gateway-scoped resources are handled. Look at sibling implementations (e.g., Feat: AI Gateway Nodes declarative and get/list support #740 AI Gateway Nodes, Feat: AI Gateway Agents declarative and get/list support #741 AI Gateway Agents) for the nested child-resource pattern once those land.
• Declarative engine: Follow planning/DECLARATIVE_RESOURCE_IMPLEMENTATION_GUIDE.md exactly — it covers resource registration, loader, planner, and executor wiring.
• Imperative commands: Follow the verb-noun pattern (kongctl get ai-gateway-providers, kongctl list ai-gateway-providers or similar); look at existing get/list commands in internal/cmd/ for the structure.
• OpenAPI spec: Pull the current AI Gateway OpenAPI spec to get the exact request/response schemas for the Providers resource group.

🛠️ Debugging & Development Tips

• Use --log-level trace to inspect HTTP requests/responses when testing against Konnect:

  kongctl get ai-gateway-providers --log-level trace

• Run quality gates before opening a PR:

  go fix ./...
  make format
  make build
  make lint
  make test
  make test-integration

• Use CGO_ENABLED=0 (handled by make build) — never build without it.
• Integration tests require -tags=integration; E2E tests require -tags=e2e.

🔗 Relevant Resources

• Parent epic: Feat: AI Gateway Support #737 — AI Gateway Support
• Sibling issues: Feat: AI Gateways declarative and get/list support #738 (AI Gateways), Feat: AI Gateway DataPlane Certificates declarative and get/list support #739 (DataPlane Certificates), Feat: AI Gateway Nodes declarative and get/list support #740 (Nodes), Feat: AI Gateway Agents declarative and get/list support #741 (Agents), Feat: AI Gateway Consumers declarative and get/list support #742 (Consumers), Feat: AI Gateway Consumer Groups declarative and get/list support #743 (Consumer Groups), Feat: AI Gateway Models declarative and get/list support #744 (Models), Feat: AI Gateway Policies declarative and get/list support #745 (Policies), Feat: AI Gateway MCP Servers declarative and get/list support #746 (MCP Servers)
• planning/DECLARATIVE_RESOURCE_IMPLEMENTATION_GUIDE.md — primary implementation guide
• docs/declarative-resource-reference.md — docs to update
• [Kong Konnect API Docs]((developer.konghq.com/redacted) — for AI Gateway OpenAPI spec reference

Generated by Opened Issue Triage for issue #747 · ◷

To install this agentic workflow, run

gh aw add githubnext/agentics/workflows/issue-triage.md@69b5e3ae5fa7f35fa555b0a22aee14c36ab57ebb