Groups¶

A group gives several people and bots the same permissions. It has members, each with an optional expiry, and group permissions, each a cluster, a role and a scope with an expiry of its own. Here's how to create one, fill it and empty it in Groups, and what each change does on the clusters.

How a group works¶

kubelatch turns every combination of a member and a group permission into one permission of that member: a derived permission. Four members and five group permissions are twenty derived permissions, kept in step with the group:

• Whoever joins receives every group permission at once.
• A permission added to the group reaches every member at once.
• Whoever leaves, and whatever the group stops giving, is revoked at once.

Every change reconciles the clusters it touches, as a direct permission does. For the proxy, the reconciler, the CLI and the audit log a derived permission is a permission like any other. In Permissions it's read-only: you change it from its group.

Direct permissions still exist, for one-off access and for cluster-admin. A person can hold the same role on the same scope directly and through a group, or through two groups; that's valid, and Permissions points out the redundant one (Overlaps).

Groups have no edition limit.

Before you start¶

• You're a kubelatch administrator.
• A group permission follows the same rules as a direct one: protected namespaces, scope, PSA, custom roles on the current bootstrap (The rules).

Create a group¶

1. Open Groups and click Create a group. The form opens in a panel on the right. The command palette (⌘K) has Create a group too, and every group by name; the link Create it as a group, under the form in Permissions, opens the same panel.

2. Fill in the form:

   Field	What to put
   Name	What people read in the interface, up to 80 characters.
   Id	Proposed from the name as you type it. You can edit it until you create the group: lowercase letters, digits and hyphens, 1 to 63 characters, starting with a letter or a digit. It never changes afterwards, and it's never reused, not even after the group is deleted.
   Description	Optional, up to 200 characters.

3. Click Create. You land on the group's page with the notice Group "…" created.

The group's page has Edit (name and description) and Delete at the top, and four figures: Members and Group permissions (those not expired), Effective permissions (the derived permissions active now) and Clusters (where the group has active permissions). Below come the Members and Group permissions cards, and Details, with the id, the creation date and the link View the N effective permissions.

Add members¶

1. On the group's page, in Members, click Add members.
2. Under Accounts, pick one or more accounts in the Add an account… selector. Each shows as a chip you can remove. People and bots can join; disabled accounts and current members don't show up.
3. Under Membership expires, choose 8 h, 7 days, 30 days, 90 days, Date… or Never. Never is the default, because each group permission carries its own expiry. Every account you add at once gets the same expiry.
4. Click Add N members.

Each new member receives the group's permissions at once. The addition is all or nothing: if one account can't join, none does, and the panel says Refused at "…". under the button, with the reason.

Joining checks the group's permissions again, as if each were granted directly to the new member. If one no longer passes, for example because someone removed the PSA label from its namespace, nobody joins until you revoke that group permission or fix the namespace. The panel then names that permission instead of an account: This group permission blocks adding members: developer on shop in prod. Revoke or fix it first.

The Note column shows a member's note. The panel doesn't ask for one; only the API sets it (note in POST /api/groups/{id}/members).

To add one account, open its page in Users and use Add to a group in its Access card: choose the Group and when the membership expires (Never by default), and click Add. The card also lists the groups the account is in, each with the expiry of its membership.

Add group permissions¶

1. On the group's page, in Group permissions, click Add permissions.
2. Fill in the same form as Grant permissions, without accounts: Cluster, Scopes (several namespaces at once, or whole cluster (*)), the role under What, Until when (30 days by default) and Note.
3. A line counts what will be added, for example "2 group permissions: developer on apps, web in kind, until …". The ones the group already has are left out, and the form says so.
4. Click Grant N permissions.

Every member receives them at once. If one entry is refused, nothing is added, and the form names the entry under the summary.

Two expiries¶

A derived permission expires at the earlier of two dates: the membership's and the group permission's.

When the date passes, the derived permission moves to Expired in Permissions, like any other. An expired membership or group permission stays on the group's page marked Expired, so you can extend the membership or remove what's left over.

To extend a member, choose Extend in their row menu, pick the new expiry and click Save changes. The new date applies to every permission the group gives them, in place: the same permission, with its new expiry. An expired derived permission comes back to life the same way, and joining's check of the group's permissions runs again first. An AI agent's session whose derived permission came from the expired one doesn't come back: its own expiry was bounded by the old date.

To extend a group permission, choose Extend in its row menu. Every member gets the new expiry, capped by their own membership, and an expired permission comes back for them. kubelatch checks the permission again as if it were new: the role's maximum, Pod Security and protected namespaces. Until you revoke a permission, even expired, the group still has it, and the form leaves it out.

Remove a member or revoke a group permission¶

• Remove, in a member's row menu, asks first: Revokes the N permissions the group gives them.
• Revoke, in a group permission's row menu, asks first: Its N members lose the permission.

Both revoke the derived permissions involved and reconcile their clusters within seconds. The person's credentials keep working for the rest of their permissions. If they're left with none on a cluster, the proxy responds 403 … has no active permissions on cluster …. An AI agent whose ceiling came from a revoked permission loses it on its next call.

The audit log keeps the whole story: group.member.remove or group.grant.revoke, and one grant.revoke per derived permission, with the group, the member and the group permission (The control plane). The revoked permissions stay under Revoked in Permissions.

Delete a group¶

Delete, on the group's page or in its row menu in Groups, opens a confirmation with the real numbers, read when it opens: Removes 4 members and revokes 20 permissions. The clusters are reconciled at once. A group with nothing in it says The group has no members and gives no permission. The Delete button waits until the numbers are in.

Deleting removes every member, revokes every group permission and every derived permission, and reconciles the clusters. The id isn't reused. The audit rows and the revoked permissions stay.

Disabled accounts¶

A disabled account keeps its memberships and its derived permissions, as it keeps its direct ones. None of them count while it's disabled: the member shows Account disabled on the group's page. Enable brings them all back without touching the group (Disable and enable).

A disabled account can't join a group: it doesn't show up in the selectors, its page has no Add to a group, and the API answers 409 group.subject_disabled.

See where a permission comes from¶

• Permissions: the Source column shows direct, or the group's name as a link to the group. A derived permission's row menu offers View group instead of Revoke (Revoke a permission).
• The group's page: View the N effective permissions opens Permissions with only that group's derived permissions (?group=<id>).
• Users: the Access column, for example 2 groups · 1 direct, and the Access card of the account's page, which lists its groups with the expiry of each membership (Users and bots).
• Home: each permission in the cards of My access that comes from a group says via group … under the role.

Via the API¶

Every operation above exists in the JSON API under /api/groups, and GET /api/grants?group=<id> lists a group's derived permissions. The routes are in HTTP API and the errors in Errors.