Kong/kongctl v1.0.0

on GitHub

kongctl Release Highlights

kongctl v1.0.0 — General Availability 🎉

This is the first stable release of kongctl, the CLI for managing Kong Konnect resources declaratively and imperatively. It brings a broad set of new capabilities, significant performance improvements, and a suite of fixes to make day-to-day Konnect operations reliable and scriptable.

kongctl is Kong’s command-line tool for managing Kong Konnect resources programmatically. This 1.0.0 release marks the first generally available release of kongctl, built for developers, platform engineers, CI/CD systems, and AI coding agents that need a clear, automatable way to manage API platform resources.

With kongctl, teams can:

• Manage Konnect resources from the terminal with human-readable, JSON, or YAML output.
• Define API platform infrastructure as simple YAML and use plan-based workflows to preview, review, and apply changes using a state free declarative configuration engine.
• Work with platform resources such as APIs, Dev Portals, application auth strategies, control planes, analytics dashboards, organization teams and assignments, audit-log listeners, and related Konnect resources.
• Use commands such as get, list, view, api, plan, diff, apply, sync, dump, and extension commands in local, scripted, and CI/CD workflows.

kongctl is also designed for agent-assisted platform work. Bundled skills can be installed with kongctl install skills so supported coding agents can discover schemas with kongctl explain, generate starter manifests with kongctl scaffold, create declarative configuration from API specs, integrate decK flows, and work through plan, diff, apply, sync, delete, and adopt workflows. kongctl also includes an extension-builder skill for local CLI extensions.

Get started with the docs at https://developer.konghq.com/kongctl/. The documentation covers installation, authentication, declarative configuration, the command reference, examples, and troubleshooting.

⚠️ Breaking Changes

• Declarative sync scope is now defined by present keys only — resources omitted from your configuration file are no longer deleted. Scope is controlled by the keys present in the file, giving you fine-grained partial-sync control. (#1014)

✨ What's New

Declarative Resource Management

New resource types are now fully supported in declarative configuration (plan/apply/sync/dump):

• Organization Team Roles — Manage team role assignments across your Konnect org (#1001)
• Organization User Assignments — Declaratively assign users to your org (#1009)
• Organization System Account Assignments — Manage system account resource assignments (#1015)
• Portal Team Group Mappings — Map IdP groups to portal teams (#1035)
• Custom Dashboards — Manage Analytics custom dashboard configurations (#1053)

Performance: Concurrent Declarative Engine

The declarative engine now executes plans concurrently, dramatically reducing apply/sync time for large configurations.

# Control concurrency via flag
kongctl apply --plan plan.json --max-concurrency 10

# Or set it in your config file
max_concurrency: 10

(#967, #1030)

HTTP Client with Retry

A new custom HTTP client with automatic retry logic improves reliability against transient API errors. (#1072)

Helm Output for Control Planes

Export control plane details in Helm-compatible YAML format:

kongctl get control-planes --output helm

(#1045)

Usage Data Collection (Opt-Out)

kongctl now collects anonymous usage data to help improve the CLI. You can opt out at any time. See README.md for details.

(#1022)

🐛 Fixes & Improvements

• Declarative explain and scaffold commands improved with better output and portal auth settings support (#1100, #1119)
• Control plane group removal now correctly plans removal before constituent control planes (#1101)
• Empty list results now emit "No resources found." in text output mode instead of blank output (#1117)
• Bare declarative commands now show valid, actionable errors (#1080)
• get / list profile commands improved for accuracy and output (#1076)
• Verb commands now list subcommands when invoked without arguments (#1079)
• Analytics dashboard guidance improved in declarative management (#1113)
• Team list skipped for API-only plans to avoid unnecessary API calls (#1128)
• Security: Updated golang.org/x/net to address CVE (#1007)

📚 Docs & DX

• Improved error reporting and usage output clarity across all commands (#1062, #1067)
• Improved command help text and examples for declarative management (#1060)
• Improved default terminal color palette for better readability (#1108)

🔗 Commit References

Features

• 8dfb726 Feat: Add declarative organization team roles resource support (#1001)
• 046ad66 Feat: add organization user assignments declarative resource support (#1009)
• a702e82 feat: Add concurrent execution to declarative engine (#967)
• 329bcbb Feat: Add organization system account assignments resource support (#1015)
• 5927b17 feat: support passing max concurrency using config file (#1030)
• 53a0067 Feat: Add declarative portal team group mappings (#1035)
• a998aa0 Feat: Add helm format to get cps command --output flag (#1045)
• fb6b798 Feat: Add declarative custom dashboard resource configuration management (#1053)
• 6cf38d3 Feat: implement custom http client with retry (#1072)
• cc04556 Feat: add initial usage data collection and opt-out capabilities (#1022)

Fixes

• 3af4185 Fix: [Breaking Change] declarative sync scope defined by present keys only (#1014)
• 4143b4c Fix: tidy up example apis for full portal docs/example
• 069458f Fix: tidy up declarative management command help examples (#1060)
• fcc2f72 Fix: improve get / list profile commands (#1076)
• 208341d Fix: list subcommands for bare verb command runs (#1079)
• b00618b Fix: ensure bare declarative commands show valid errors (#1080)
• 1c276f0 Fix: plan control plane group removal before constituent control planes (#1101)
• f674722 Fix: Improve declarative explain and scaffold commands (#1100)
• 9ad8ce8 Fix: improve analytics dashboard declarative management guidance (#1113)
• ec5b1db Fix: emit "No resources found." for empty list results in text output mode (#1117)
• 95a6b20 Fix: portal auth settings explain and scaffold output (#1119)
• e986444 Fix: skip team list for API-only plans (#1128)
• 3788c84 Fix: release Docker username env (#1131)
• d5088f4 fix(deps): update module golang.org/x/sys to v0.44.0 (#1005)
• 6133f65 fix(deps): update module github.com/daveshanley/vacuum to v0.26.3 (#1004)
• 9dc7aa2 fix(deps): update module github.com/mattn/go-isatty to v0.0.22 (#1011)
• 4218387 fix(deps): update module github.com/daveshanley/vacuum to v0.26.4 (#1017)
• 6ada067 fix(deps): update module github.com/alecthomas/chroma/v2 to v2.24.0 (#1012)
• 4437ea4 fix(deps): update module github.com/kong/go-apiops to v0.4.1 (#1028)
• 20a59fb fix(deps): update module github.com/alecthomas/chroma/v2 to v2.24.1 (#1029)
• 47dbdfc fix(deps): update module github.com/masterminds/semver/v3 to v3.5.0 (#1033)
• 7ca37a7 fix(deps): update module github.com/oapi-codegen/oapi-codegen/v2 to v2.7.0 (#1044)
• 6252cc9 fix(deps): update module github.com/kong/kongctl to v0.10.0 (#1098)

Other Changes

• b4a1a8b test(e2e): add dump coverage for event-gateway listener, listener policy, and cluster policy (#954)
• d1596be Simplifier: rename portalIDFromExecutionContext → getPortalID in PortalIPAllowListAdapter (#997)
• 7696114 Task: Adds release preview local dev feature (#999)
• 8c718b6 Task: gh-aw upgrade of all agentic workflows (#1003)
• a05495c test: add e2e scenario environment assignments (#1008)
• 34524e4 chore(deps): update module golang.org/x/net to v0.53.0 [security] (#1007)
• f17593a chore(deps): update github/gh-aw-actions action to v0.71.2 (#1023)
• 1c70899 Simplify: align executor adapter style with established codebase patterns (#1013)
• 4389ff5 test(e2e): add scenario for org user assignment incremental sync lifecycle (#1025)
• 4014e6b test(e2e): add plan workflow scenarios for organization user assignments (#1024)
• 9f81d37 deps: update sdk-konnect-go to v0.36.0 (#1031)
• ff36719 test: add e2e concurrency controls (#1034)
• 199ba17 chore(deps): update github/gh-aw-actions action to v0.71.3 (#1041)
• 4bf5d0f Simplify: extract prepareScope helper, unify shouldPlanRoot signature, add ChildScopes capacity hint (#1037)
• fa5d9c8 test(e2e): add sync and plan workflow scenarios for system account assignments (#1036)
• 9eb4548 test(e2e): add sync-partial-scope scenario for omitted-key no-deletion behavior (#1049)
• 7413bcd chore(deps): update step-security/harden-runner action to v2.19.1 (#1057)
• f25f5ad test(e2e): add scenario for get control-plane --output helm (#1058)
• 928953a Simplify: getControlPlane.go — Go 1.26 idioms, dedup TrimSpace, drop trivial comments (#1059)
• e7d353d Task: improve error reporting and usage output clarity (#1062)
• e8fc142 Task: improve command error, help, and usage text display (#1067)
• 1706828 Simplify: bindings-loop pattern in del.go, shared KonnectFirstPreRunE helper, align export.go (#1074)
• 247acaa test(e2e): add single-item get-by-name and get-by-id coverage for event-gateway child resources (#1075)
• 14a33e4 Task: add feature user agent eval workflow (#1084)
• d5e79a6 chore(deps): update github/gh-aw-actions action to v0.71.6 (#1082)
• 7833731 Simplify: idiomatic error handling and slice init in profile and usage_error (#1083)
• 3d8bf14 Simplify: extract sourcesForCommand helper to eliminate 4 duplicate blocks (#1089)
• ff4ab47 chore(deps): update github/gh-aw-actions action to v0.72.0 (#1097)
• 04e9844 Task: Removes unhelpful kongctl-query skill (#1099)
• 66b1530 Task: Removes unhelpful kongctl-query skill remaining items
• 837cfe6 test(e2e): add bare declarative command coverage for ErrNoSources error (#1092)
• 06d0bf8 test(e2e): add flag-conflict error scenarios for --mode+--plan and --require-namespace+--plan (#1093)
• 54912be Task: refines behavior of the user agent workflow (#1085)
• 58bb40b Task: improve default colors for terminal backgrounds (#1108)
• c207271 test(e2e): add dump round-trip and delete-cleanup to portal custom-domain scenario (#1105)
• d3364bb test(e2e): add dump round-trip and delete-cleanup to api_docs_with_children scenario (#1106)
• a344390 Task: disable Pulse workflow and site publishing (#1109)
• 6f600f8 Task: schedule weekday user agent eval workflow (#1110)
• dc58b91 Task: user agent eval improvement. Record replay prompts in improvement issue (#1114)
• 7aca01e Task: hydrate agent eval replay prompts to feedback issue (#1116)
• 2f98e4b chore(deps): update github/gh-aw-actions action to v0.72.1 (#1118)
• 6ea828b test(e2e): add dump round-trip step to portal/email-templates scenario (#1125)
• 09a3ed9 Simplify: extract repeated boolean expression to local variable in ResolveExplainSubject (#1123)
• 48eda22 test(e2e): add dump round-trip step to app-auth-strategy scenario (#1124)
• adfd6a6 Task: upgrade gh-aw and workflows (#1126)
• 2000276 Task: GA repository preparation (#1112)

Full Changelog: Initial release

Generated by Release · ● 2.5M