v1.28.0

kongctl Release Highlights

✨ What's New

Bring existing resources into declarative management (#2749)

Adoption now combines ownership management, previews, and declarative configuration output. Adopt existing resources and save their declarations in one command with --declarative-output, replacing the separate adopt-then-dump workflow.

• Parent and child exports: Declarative output is available across all supported adoption commands, covering 11 parent resource types and 17 child types. Parent resources include AI Gateways, Kong Identity directories and auth servers, portals, APIs, and control planes.
• AI Gateway children: Added explicit adoption for all 12 independently owned child families, including models, model providers, MCP servers, and consumers. Select individual resources, all children in a family with --all, or a filtered set with --name-pattern.
• Kong Identity: Existing directory, auth server, and child adoption commands gain the shared preview and export capabilities. Groups, OAuth clients, and basic-auth usernames also gain bulk and name-pattern selection. Principals and principal identities retain individual adoption by UUID with an explicit --ref.
• Ownership previews: Every adoption command supports --dry-run, which defaults to off. Preview ownership changes without remote writes in text, JSON, or YAML; combine it with --declarative-output to save proposed configuration.
• Parent references: Child exports include external parent declarations by default. Supply --parent-ref to link children to a parent declaration already in your inputs.

Set AI_GATEWAY_ID and PRINCIPAL_ID to existing resource IDs:

# Preview adoption of all models in an existing AI Gateway
kongctl adopt ai-gateway models --all \
  --gateway-id "$AI_GATEWAY_ID" --namespace team-ai --dry-run

# Adopt the parent gateway and save its declaration
kongctl adopt ai-gateway "$AI_GATEWAY_ID" --namespace team-ai \
  --declarative-output gateway.yaml

# Adopt the models and link them to the gateway declaration saved above
# The exported gateway's default ref is its remote ID
kongctl adopt ai-gateway models --all \
  --gateway-id "$AI_GATEWAY_ID" --namespace team-ai \
  --parent-ref "$AI_GATEWAY_ID" --declarative-output models.yaml

# Adopt a Kong Identity principal and export it with an external directory reference
kongctl adopt identity principal "$PRINCIPAL_ID" \
  --directory-name default --ref existing-user --namespace team-identity \
  --declarative-output principal.yaml

Use new output paths for the saved YAML files, then include them in your declarative inputs. AI Gateway and Kong Identity are the supported families for explicit child adoption. Adopting a parent does not recursively adopt its independently owned children; run the appropriate child commands separately.

Imported principal API keys in declarative configuration (#2753)

Declarative manifests now support type: imported for Identity principal API keys with deferred secret: !secret {...} expressions. Plans retain expressions and execution validates material before remote writes. Imported keys are create-only — reapply preserves them, and metadata updates can omit the source. Rotation requires a new key/ref with explicit retirement.

Lint expanded declarative configuration (#2746)

Raw-file linting misses configuration introduced by !file, templates, and overrides. The new --expand flag lets lint rules inspect the fully composed configuration using the existing declarative preprocessing pipeline.

kongctl lint --expand -f ./templates -f ./team -r rules.yaml

Without --expand, lint behavior is unchanged. Expansion does not resolve !env, !ref, !secret, or contact Konnect — rules must account for unresolved values.

🐛 Fixes & Improvements

• Dependency update: Updated internal SDK module to v1.27.0 (#2747)
• Test coverage: Added smoke tests for Kong Identity lifecycles, directory bootstrap, and adoption workflows (#2750, #2751)

🤝 Community

Thanks to @bhatikuldeep for contributing the lint --expand feature in #2746!

🔗 Commit References

Features

• 640bb98 feat(lint): add --expand to lint expanded declarative configuration (#2746)
• 10f197e feat(cmd): adopt children and export declarative configuration (#2749)
• e59f6c0 feat(declarative): support imported principal API keys (#2753)

Fixes

• 402d0d3 fix(deps): update module github.com/kong/kongctl to v1.27.0 (#2747)

Other Changes

• 391b9a1 test(smoke): cover Kong Identity lifecycles and directory bootstrap (#2750)
• df83ca7 test(cmd): add adoption smoke coverage (#2751)

---

Full Changelog: v1.27.0...v1.28.0

Generated by Release · claude · opus46 · ~39 AIC · ⌖ ~18 AIC · ⊞ 3.3K