Feature: investigate declarative user assignments and system-account lifecycle support

[rspurgeon]

Purpose

Investigate and plan organization users and system accounts as separate
declarative capabilities. The desired direction is full system-account
declarative configuration, including dump. For users, establish the usefulness
of exporting access assignments independently of identity lifecycle management.

Supersedes #2125, which incorrectly assumed sync selector registration enabled
primary dump support. Both dump declarative --resources=organization.users
and dump declarative --resources=organization.system-accounts fail with
unsupported resource type. Only organization teams have primary dump support.
This requires design and feature work, not just additional E2E assertions.
No implementation changes were made during the investigation.

Current behavior

Findings are based on commit
08a6e4fd12b96793a0b48a42b16ccb5b120471f3 and its pinned SDK.

Capability	Users	System accounts
Select existing identity	Exactly one of email or ID	Exactly one of name or ID
Declaratively create/invite	No	No
Update identity fields	No	No
Delete identity through sync	No	No
Manage team memberships and direct roles	Yes	Yes
Primary declarative dump	No	No
Export via team dump with child resources	Yes	Yes

Users

Users must already exist. Email and ID are lookup keys, not editable fields.
Email matching is case-insensitive; unresolved selectors fail planning.
Selecting by ID cannot update email or profile properties. Apply adds
assignments and sync can remove assignments in scope, but cannot delete users.

Users are often invited by email. Determine the boundary between imperative
invitation/identity administration and declarative access management. A user
dump could export memberships and direct roles without managing identities;
establish concrete use cases before committing to primary dump support.

System accounts and ownership

System accounts are selectors for existing identities. Changing a selector
name does not rename an account. The declarative model has no editable
description or labels.

The pinned SDK system-account read/create/update models do not expose labels.
Repository documentation explicitly identifies this as the reason accounts
remain selector-only: namespace ownership cannot be persisted using the
existing label-based model. Verify current upstream capabilities in this study.

Name resolution lists accounts across the organization and rejects ambiguous
names. ID resolution fetches the specified account. Listing all accounts for
lookup does not mean reconciling all accounts: assignment planning acts on
identities explicitly selected in the manifest, with no organization-wide
account deletion sweep.

A selector's kongctl.namespace organizes local planning; it is not persisted
as namespace metadata on the remote account.

Assignment sync scope

Both user and system-account planners use similar rules:

• Membership sync considers manifest-declared selectors and restricts removals
  to managed teams in the namespace being planned.
• Direct-role sync considers selectors in the planning namespace and resolved
  entity IDs from APIs, portals, and control planes declared in that namespace.
• Wildcard entity_id: "*" roles are also included in removal scope, despite
  lacking namespace ownership labels.
• Omitting a selector does not make the identity a deletion candidate.

Review and document omission versus empty collections, wildcard roles,
external teams, and multiple manifests/namespaces managing the same identity.

Investigation and design requirements

User access configuration

• Define declarative assignment management versus invitations and identity
  administration; explicitly decide whether identity lifecycle stays outside
  declarative scope.
• Decide whether primary user dump is useful, with documented use cases.
• Define filtering, assignment coverage, dependencies, and round-trip behavior.
• Specify apply/sync/delete and omission semantics, distinguishing assignment
  removal from deleting a user or removing organization membership.

Full system-account declarative support

• Verify API/SDK CRUD, label support, and restrictions on Konnect-managed
  accounts.
• Design ownership and namespace handling. Use labels if supported; otherwise
  evaluate an explicit alternative ownership mechanism. Do not implicitly
  manage every system account in the organization.
• Define matching, duplicate names, adoption, rename/update, protection,
  account deletion, and assignment reconciliation.
• Specify primary dump filtering and dependency representation, including
  zero-change apply-mode plan-from-dump behavior.
• Consider account lifecycle and assignment-only dump as separate deliverables.
• Treat access-token lifecycle and secret export as an explicit separate scope
  decision rather than automatically including them in account management.

Planning acceptance criteria

• Document separate capability matrices verified against current API/SDK
  behavior for users and system accounts.
• Record the decision and use cases for primary user assignment dump.
• Produce a system-account ownership/namespace design, including any
  dependency on API labels or an alternative ownership mechanism.
• Specify apply/sync/delete, omission, empty collections, wildcard roles,
  external teams, and cross-namespace behavior.
• Define dump filtering, dependencies, and round-trip guarantees for
  approved features.
• Create scoped implementation follow-ups with compatibility considerations
  and unit/integration/E2E validation plans. Preserve existing team-centric
  scenario assertions.

This is an investigation and planning issue, not a test-only task or a decision
to enable organization-wide account deletion.

References and code evidence

• Superseded E2E proposal: [e2e-scan] Test: Improve e2e coverage for org user and system-account dump as primary resource selectors (expand scenario) #2125
• Earlier ownership analysis: Organization Support GA Planning Report (Epic #257) #748
• docs/examples/declarative/organization/README.md: selector limitations.
• internal/declarative/resources/organization_user.go: user model.
• internal/declarative/resources/organization_system_account.go: account model.
• internal/declarative/planner/planner.go: identity resolution.
• internal/declarative/planner/organization_user_assignments.go: assignment
  planning and shared role scope.
• internal/declarative/planner/organization_system_account_assignments.go:
  system-account assignment planning.
• internal/cmd/root/verbs/dump/declarative.go: dump allowlist and collectors.
• Existing E2E scenarios: test/e2e/scenarios/org/users/assignments,
  test/e2e/scenarios/org/system-accounts/assignments, and corresponding
  sync and plan scenarios.

[github-actions]

🎯 Agentic Issue Triage

This is a well-scoped investigation and design issue for extending declarative support to organization users (assignment management) and system accounts (full lifecycle). It supersedes #2125, which was closed as not-planned because the dump paths for these resource types require design work, not just E2E assertions.

Current state: Users and system accounts are selector-only resources — they reference existing identities but cannot create, update, or delete them. Assignment planning (team memberships and roles) works for both. Neither resource type has primary dump support; they are only collected indirectly as children of organization.teams via --include-child-resources.

Code Evidence and Dump Gap Analysis

Dump allowlist (internal/cmd/root/verbs/dump/declarative.go:48-58): The declarativeAllowedResources map includes 9 resource types but excludes organization.users and organization.system_accounts. Attempting dump declarative --resources=organization.users or --resources=organization.system-accounts fails with unsupported resource type.

Resource models:

• internal/declarative/resources/organization_user.go: Selector with Ref, Email, ID, Kongctl metadata, and nested Teams/Roles. No Labels field.
• internal/declarative/resources/organization_system_account.go: Selector with Ref, Name, ID, Kongctl metadata, and nested Teams/Roles. No Labels field.

Planners:

• internal/declarative/planner/organization_user_assignments.go: Plans team membership and role creates/deletes within namespace scope.
• internal/declarative/planner/organization_system_account_assignments.go: Same pattern. Role scoping limited to entities in current namespace.

Key blocker: Neither resource model supports labels, so kongctl namespace ownership cannot be persisted on the remote identity. This is explicitly noted in the issue and is the central design question for system accounts.

Related Issues and Context

Issue	Status	Relevance
#2125	Closed (not planned)	Superseded E2E proposal — closed because dump paths need design, not just tests
#1640	Open	dump --all-resources support — depends on which resource types are in the allowlist
#1156	Closed (fixed by #1159)	System account assignment example bug — resolved with doc clarification
#265	Closed	System account team membership support — completed
#264	Closed	System account role support — completed
#258	Closed	System account resource support — completed
Discussion #748	—	Earlier ownership analysis referenced by this issue

Suggested Investigation Approach

Phase 1: API/SDK capability verification

• Verify current Konnect API support for system account CRUD operations and label fields against the pinned SDK version and any newer SDK releases.
• Check whether the labels field has been added to system-account read/create/update models upstream since the issue was filed.
• Document which API operations are available for users vs. system accounts and any restrictions on Konnect-managed accounts.

Phase 2: User assignment dump design

• Decide whether a primary user dump exporting memberships and direct roles (without identity lifecycle) is a useful standalone deliverable.
• Key use case to validate: "export which teams and roles a set of users have, re-apply to a different org or after a reset."
• Design filtering: by email, by team membership, by role scope.
• Define round-trip guarantees: dump → plan --mode apply should produce zero changes.

Phase 3: System account ownership design

• If the API now supports labels: design kongctl.namespace label-based ownership, similar to how other declarative resources use labels.
• If labels are still unsupported: evaluate alternatives — e.g., a side-channel ownership file, name-prefix conventions, or explicit managed-by field in the manifest.
• Define adoption semantics: how does kongctl adopt work for existing system accounts?
• Define protection: which accounts (e.g., Konnect-managed) cannot be deleted or modified?

Phase 4: Scoped implementation follow-ups

• Create separate issues for: (a) user assignment dump, (b) system account full lifecycle, (c) system account dump, (d) access-token lifecycle (explicit separate scope decision).
• Each follow-up should include compatibility considerations, unit/integration/E2E validation plans, and preserve existing team-centric scenario assertions.

Suggested Sub-task Checklist

• Verify current API/SDK CRUD capabilities for system accounts (labels, create, update, delete)
• Verify current API/SDK capabilities for users (invitation vs. declarative boundary)
• Document capability matrices for both resource types against current API behavior
• Record decision on primary user assignment dump with concrete use cases
• Produce system-account ownership/namespace design (label-based or alternative)
• Specify apply/sync/delete semantics (omission, empty collections, wildcard roles, external teams, cross-namespace)
• Define dump filtering, dependencies, and round-trip guarantees
• Create scoped implementation follow-up issues with E2E validation plans
• Decide on access-token lifecycle scope (in or out of account management)

Labels applied: triaged, medium-priority (in addition to existing enhancement, declarative, kong-identity)

Generated by Opened Issue Triage for #2205 · opus46 · 117.9 AIC · ⌖ 28.2 AIC · ⊞ 3.8K · ◷

_{Add this agentic workflow to your repo}

To install this agentic workflow, run

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