Organization Support GA Planning Report (Epic #257)

[rspurgeon]

Date: 2026-04-03

This report uses Organization as the product grouping term. The Konnect API and older issue text still use Identity in endpoint names.

Executive Summary

• sdk-konnect-go already exposes almost the full organization API surface. The main gap is kongctl implementation and resource design, not SDK availability.
• Of the 10 sub-issues, only #260 is close to genuinely complete. #258 is closed, but it is only read-only imperative support today.
• Teams are the only organization resource that currently fits kongctl's declarative ownership model cleanly because teams support labels.
• System accounts and identity providers do not expose labels in the current API models. Under the current declarative model, they are not good top-level declarative resources.
• User-centric features are feasible declaratively only if kongctl introduces a selector pattern for existing users, most likely by email or id. Users themselves should remain imperative-only.
• System-account access tokens are a poor declarative fit for GA because the secret token value is only returned at creation time.
• Strong GA candidates from this set are: #261 team roles, #263 team membership, and #267 auth settings.
• #262 user roles is also feasible for GA if the external user selector design is accepted early.
• #258, #259, #264, #265, and #266 should be treated as imperative-first. Declarative support is either blocked or materially less clear.

Scope

This is a first-pass assessment of epic #257 Feat: Organization support and its 10 sub-issues.

Sources used:

• GitHub epic and sub-issues: #257, #258 through #267
• Local spec: ./.tmp/konnect-organization.json
• Current SDK: github.com/Kong/sdk-konnect-go v0.25.0
• Current kongctl implementation and tests

Key local evidence:

• Declarative organization support currently only documents teams: docs/declarative-resource-reference.md
• Declarative organization grouping currently only contains teams: internal/declarative/resources/organization.go
• The only organization declarative resource in ResourceSet is organization_team: internal/declarative/resources/types.go
• Teams have declarative planner and executor support: internal/declarative/resources/organization_team.go internal/declarative/planner/organization_team_planner.go internal/declarative/executor/organization_team_adapter.go
• Imperative system-account and team commands currently wire only get/list: internal/cmd/root/products/konnect/organization/systemaccount/systemaccount.go internal/cmd/root/products/konnect/organization/team/team.go
• System-account e2e coverage explicitly says create/delete are unsupported: test/e2e/scenarios/org/system-accounts/scenario.yaml

Cross-Cutting Findings

• The current epic is narrower than the current API surface. The local spec and SDK now include: POST /invites, GET/PUT /identity-provider/team-mappings, GET/PATCH /identity-provider/team-group-mappings, and GET/PATCH /organizations/impersonation. None of these are covered by the 10 sub-issues.
• The epic body says team-mapping endpoints were awaiting API work. That appears outdated relative to the local spec and SDK as of 2026-04-03.
• Declarative support should be split into three categories: top-level labelable resources, child relation resources, and organization-scoped singletons.
• Under that split: teams are labelable top-level resources, roles and memberships are child relation resources, and auth settings is an organization-scoped singleton.
• Invitations are operationally important for user workflows, but they are not a good declarative primitive. They should be tracked as imperative-only if Kong wants kongctl user onboarding support.

Issue-by-Issue Assessment

#258 System account resource support

• GitHub state: CLOSED
• Current milestone: Initial Beta Release: 0.4.0
• API surface: GET/POST /system-accounts, GET/PATCH/DELETE /system-accounts/{accountId}
• Current kongctl support: read-only imperative get/list
• Evidence: internal/cmd/root/products/konnect/organization/systemaccount/systemaccount.go internal/cmd/root/products/konnect/organization/systemaccount/getSystemAccount.go internal/konnect/helpers/system_accounts.go test/e2e/scenarios/org/system-accounts/scenario.yaml
• Assessment: not actually complete
• Why: the closed issue only delivered read/list behavior. There is no imperative create/update/delete, no adopt flow, and no declarative resource.
• Imperative support for GA: yes, path is clear
• Imperative notes: the SDK already supports full CRUD for system accounts. This is mostly helper expansion, command wiring, output shaping, and tests.
• Declarative support for GA: no, not under the current ownership model
• Declarative notes: system accounts do not expose labels in the current API model. That means kongctl cannot safely namespace or identify ownership of a top-level declarative system-account resource.
• Recommendation: reopen this issue or create a follow-up for imperative CRUD. Keep declarative system-account management out of 1.0.0 unless the API adds labels or kongctl adopts a new non-label ownership model.

#259 System account access token resource support

• GitHub state: OPEN
• API surface: GET/POST /system-accounts/{accountId}/access-tokens, GET/PATCH/DELETE /system-accounts/{accountId}/access-tokens/{tokenId}
• Current kongctl support: none
• Assessment: open and not started
• Imperative support for GA: yes, path is clear
• Imperative notes: the SDK already supports list/create/get/update/delete for system-account access tokens.
• Declarative support for GA: probably no
• Declarative notes: this is a child resource, so label support is not the core problem. The real issue is that the secret token value is only returned on create. Read operations expose metadata, not the secret itself. That makes declarative reconcile, dump, and rotation semantics awkward and potentially unsafe for GA.
• Recommendation: treat this as imperative-only for 1.0.0. If product wants declarative behavior later, it likely needs a separate design for secret output and rotation rather than normal state convergence.

#260 Team resource support

• GitHub state: CLOSED
• Current milestone: Initial Beta Release: 0.4.0
• API surface: GET/POST /teams, GET/PATCH/DELETE /teams/{teamId}
• Current kongctl support: imperative get/list, team adoption, and declarative CRUD with tests and docs
• Evidence: internal/cmd/root/products/konnect/organization/team/team.go internal/cmd/root/products/konnect/organization/team/getTeam.go internal/cmd/root/products/konnect/adopt/organization/team/team.go internal/declarative/resources/organization_team.go internal/declarative/planner/organization_team_planner.go internal/declarative/executor/organization_team_adapter.go test/e2e/scenarios/org/teams docs/declarative-resource-reference.md
• Assessment: mostly complete, but not complete for full imperative parity
• Why: teams are the only organization resource with real declarative support today. However, imperative create/update/delete commands are still missing.
• Imperative support for GA: yes, path is clear
• Declarative support for GA: yes, already implemented
• Declarative notes: teams expose labels in both create and update models, so they fit the current top-level ownership model cleanly.
• Recommendation: keep this closed for declarative scope. If GA requires imperative write parity, create a follow-up issue for create/update/delete team commands rather than reopening the declarative work.

#261 Team Role resource support

• GitHub state: OPEN
• API surface: GET/POST /teams/{teamId}/assigned-roles, DELETE /teams/{teamId}/assigned-roles/{roleId}
• Current kongctl support: none for organization teams
• Assessment: strong GA candidate
• Imperative support for GA: yes, path is clear
• Imperative notes: the SDK already supports listing team roles, assigning a role, and removing a role.
• Declarative support for GA: yes, path is clear
• Declarative notes: this is a child relation under a team. Labels are not required on the child. A stable identity can be derived from: team + role_name + entity_type_name + entity_id + entity_region. Existing portal_team_role support is a useful implementation pattern.
• Recommendation: include this in the 1.0.0 milestone. It is a natural next step after team resource support.

#262 User role resource support

• GitHub state: OPEN
• API surface: GET /users, GET /users/{userId}, GET/POST /users/{userId}/assigned-roles, DELETE /users/{userId}/assigned-roles/{roleId}
• Current kongctl support: none
• Assessment: feasible, but requires a user-selector design
• Imperative support for GA: yes, path is clear
• Imperative notes: the SDK already supports listing users, getting a user, assigning a role, and removing a role.
• Declarative support for GA: yes, with design work
• Declarative notes: users are not good declarative parent resources. User onboarding happens through invitations and registration, and user objects do not expose labels. That said, role assignments can still be declared against an existing user selected by email or id. GET /users supports exact email filtering, which is enough for lookups.
• Recommendation: include this in 1.0.0 if the team accepts an external user selector pattern. Otherwise, ship imperative support first and defer declarative support.

#263 Team membership resource support

• GitHub state: OPEN
• API surface: GET/POST /teams/{teamId}/users, DELETE /teams/{teamId}/users/{userId}, GET /users/{userId}/teams
• Current kongctl support: none
• Assessment: strong GA candidate
• Imperative support for GA: yes, path is clear
• Imperative notes: the SDK already supports list/add/remove membership operations.
• Declarative support for GA: yes, with the same user-selector design required by #262
• Declarative notes: this is a simple relation resource and is a natural nested child under a declarative team. Users can be resolved by email or id. The main operational caveat is that invitations and registration happen outside declarative management, so apply must fail clearly if a referenced user does not exist yet.
• Recommendation: include this in 1.0.0. This is one of the cleaner user-related declarative additions.

#264 System account role resource support

• GitHub state: OPEN
• API surface: GET/POST /system-accounts/{accountId}/assigned-roles, DELETE /system-accounts/{accountId}/assigned-roles/{roleId}
• Current kongctl support: none
• Assessment: imperative-first
• Imperative support for GA: yes, path is clear
• Declarative support for GA: yes, but only with a system-account selector pattern
• Declarative notes: roles are child relations, so labels are not required on the role object. The missing piece is how declarative config references an existing system account safely, most likely by name or id. This is viable, but it depends on a design decision that does not exist in the codebase yet.
• Recommendation: target imperative support for 1.0.0. Declarative support can follow if Kong wants selectors for unmanaged system accounts.

#265 System account team membership resource support

• GitHub state: OPEN
• API surface: GET/POST /teams/{teamId}/system-accounts, DELETE /teams/{teamId}/system-accounts/{accountId}, GET /system-accounts/{accountId}/teams
• Current kongctl support: none
• Assessment: imperative-first
• Imperative support for GA: yes, path is clear
• Declarative support for GA: yes, but only with a system-account selector pattern
• Declarative notes: this is a relation between a team and an existing system account. Teams are already declaratively addressable. System accounts are not. Once there is a reliable external selector for system accounts by name or id, this feature becomes straightforward.
• Recommendation: target imperative support for 1.0.0. Defer declarative support until the selector pattern exists.

#266 Identity provider resource support

• GitHub state: OPEN
• API surface: GET/POST /identity-providers, GET/PATCH/DELETE /identity-providers/{id}
• Current kongctl support: none
• Assessment: imperative is clear, declarative is not a good GA fit
• Imperative support for GA: yes, path is clear
• Imperative notes: the SDK already supports full list/create/get/update/delete behavior.
• Declarative support for GA: no, not recommended under the current model
• Declarative notes: identity providers are top-level organization resources, but they do not expose labels in the current API model. Multiple providers can exist, the config contains sensitive fields, and safe ownership semantics are unclear without labels or explicit takeover rules. The related IdP team-mapping endpoints now exist in the spec and SDK, but they are not represented by the 10 sub-issues, which makes the declarative boundary even less clear.
• Recommendation: make this imperative-only for 1.0.0. Revisit declarative support only after either the API adds labels or kongctl adopts an explicit organization-singleton ownership model.

#267 Auth settings resource support

• GitHub state: OPEN
• API surface: GET/PATCH /authentication-settings
• Current kongctl support: none
• Assessment: strong GA candidate
• Imperative support for GA: yes, path is clear
• Declarative support for GA: yes, likely clear
• Declarative notes: this is not a normal top-level collection resource. It is a singleton settings object for the current organization. That makes it much closer to existing singleton child resources such as portal auth settings than to top-level label-managed resources. A declarative organization.auth_settings block should be feasible if it is treated as profile-scoped, non-deletable, and not namespaced.
• Recommendation: include this in 1.0.0 for both imperative and declarative support.

Recommended GA Scope

Recommended to target in kongctl GA Release: 1.0.0:

• #261 Team Role resource support
• #263 Team membership resource support
• #267 Auth settings resource support
• #262 User role resource support, if external user selectors are accepted
• Follow-up imperative write parity for #260 team resource support, if desired for GA

Recommended as imperative-only for 1.0.0:

• #258 System account resource support
• #259 System account access token resource support
• #264 System account role resource support
• #265 System account team membership resource support
• #266 Identity provider resource support

Recommended out of scope for declarative 1.0.0:

• top-level declarative system-account management
• top-level declarative identity-provider management
• declarative system-account access-token management

Suggested Follow-Up Work Items

• Decide whether GA requires imperative create/update/delete parity for organization teams.
• Decide on a selector pattern for existing unmanaged principals: users by email or id, system accounts by name or id.
• Split user lifecycle from user relations: invitations remain imperative, user memberships and user roles can still be declarative.
• Decide whether organization-scoped singletons without labels are acceptable declarative resources. If yes, auth settings is the best first candidate.
• Decide whether to track the now-present IdP team-mapping APIs separately. They are in the current spec and SDK, but not in the 10 sub-issues.

[Prashansa-K]

Thanks for this Rick! I reviewed the parent issue as well as model's review.

Here's my understanding for the issues.

Completed work:

1. #258 We have read-only support for system accounts via imperative get commands. This is because labels aren't supported.
2. #257 We have declarative support + imperative get support for teams.

In Progress:

1. #263 #265 Team membership (users and system-accounts). There's a PR but I need to add modifications to account for the new declarative UX as suggested by Rick. I am planning to push the changes this week.

To be picked up:

1. #261 Team role support - adding role for a team. This could be a child entity for the team.

Out of scope:
The following would be out of scope for kongctl work in my opinion.

1. #262 Assigning a role (eg; admin, viewer) to a user. We don't support user creation or updates due to lack of labelling. Thus, this task shouldn't be a part of kongctl either.
2. #264 Assigning a role to a system-account. Same reason as above.
3. #259 System account access tokens support - need labels for declarative stuff.

#266 #267 Model has suggested imperative support for identity providers and auth settings. The current APIs don't support labels. Thus, we can only implement GET support for now. I am unsure on how useful would that be.