Manage roles¶

A custom role is a set of permissions you compose from capabilities and, when needed, advanced rules, and then grant like any system role. Here's how to create, duplicate, edit, delete and grant one in Roles. What a role can hold, what kubelatch refuses and why are in Roles.

Roles is in the sidebar, next to Permissions, for administrators only.

Before you start¶

• The administrator role in kubelatch.
• To grant a custom role on a cluster, the cluster runs the current bootstrap manifest. A cluster registered before custom roles existed says Bootstrap v1: custom roles cannot be granted on this cluster. in the Enrollment and health card of its page in Clusters: update its bootstrap first. You can create the role before that.

Custom roles are a Pro feature: in Free, the six system roles are available and Roles says so. A lapsed or removed key keeps existing custom roles working; they can be deleted, not created or edited, and Roles says so while any exist. See Editions and license.

The Roles page¶

The table lists every role, with the segments All, System and Custom:

The actions menu at the end of each row has Open, Duplicate (all but admin and cluster-admin), and, for custom roles, Edit and Delete. Open shows the role as a page: its figures, What it grants, Where it applies and its summary with the YAML, with Duplicate, Edit and Delete in the header. The command palette (⌘K) also has New role and every role by name.

Create a role¶

1. In Roles, click New role. The builder opens as a page: on the left, what you compose, in the order of the decisions; on the right, on a wide screen, what the role grants in the Summary and YAML tabs. On a phone the summary is a bar at the bottom of the page with the risk, "N resources · M problems" and Summary, which opens it in a panel.

2. Under Role, choose where to Start from: Blank, one of viewer, developer, debugger and secrets-reader, or one of your custom roles. The chip copies that role's capabilities, rules and scope, and a line under the chips names the start; a copy of viewer or developer is an approximation (Duplicate a role). If you had already composed something, the builder asks before replacing it. Then fill in:

   Field	What to put
   Name	What people will read in the lists, up to 80 characters.
   Identifier	Shown under the name and derived from it: 2 to 39 lowercase letters, digits and hyphens. Click Change to type your own. It can't change once the role exists, and is never used again.
   Description	One line about what the role is for. People holding it see it on their Home.

3. Under Where it applies, choose Namespaces (granted on one namespace at a time; every capability is available) or Namespaces and whole cluster (also grantable with scope *; the role reads only, never Secrets, and reaches kube-system and kubelatch-system too: why). Decide it first: it fixes which capabilities are available. Under Clusters, keep Every cluster or choose Only some… and tick them.

4. Under Capabilities, tick what the role needs, domain by domain. Search capabilities filters by name. What the scope rules out folds into one line per domain: with Namespaces, the cluster-wide capabilities, with Change to switch the scope; with the whole cluster, the capabilities that write or read Secrets. A ticked capability that stops fitting after a scope change stays visible and marked, and a line at the top offers to switch them all off at once. Ticking a write capability without the read one it presumes (Write ConfigMaps without Read ConfigMaps) shows a note: kubectl edit and kubectl apply need get. Its button adds the read; the role saves either way.
5. Under Advanced rules, only for what no capability covers, click Add rule. Each rule has an API group (type one, or pick Core group for Pods, ConfigMaps and the rest of the core), Resources (type each and press Enter), Verbs (press the chips, or Read and Write for the usual sets) and, optionally, Names (optional). Suggest from cluster reads a ready cluster's API and offers its groups, resources and verbs in those fields; a verb the cluster doesn't serve for the chosen resources is drawn dashed. Without a ready cluster, type groups and resources by hand.
6. Read the summary, which is kubelatch's own reading of the draft: what to fix, What it grants in words, Look twice, Requirements, the resources table with Read, Create, Update and Delete (folded at eight rows), and Impact of saving. A problem shows next to its field, and under To fix before saving as a link to it, once you've touched that field or tried to save; under Create role, a line says Valid: nothing to fix or how many problems are left.
7. Click Create role. Roles opens with the notice "Role "…" created.".

A new role grants nothing until you grant it to someone (below).

Example: deploy with Argo CD, no Secrets¶

A team that deploys through Argo CD needs to see its workloads, restart them and read its Argo Applications, without Secrets:

• Capabilities: Read workloads, Scale, Delete Pods, Read logs, Read events.
• An advanced rule: API group argoproj.io, Resources applications, Verbs Read (get, list, watch).

The summary marks it Sensitive, because argoproj.io is a group outside Kubernetes (What kubelatch can't know), and it requires no Pod Security: nothing in it creates pods.

Duplicate a role¶

To start from an existing role, pick it under Start from in the builder, or choose Duplicate in its row menu or on its page: both open the builder with that chip pressed, the same content, and " (copy)" after its name; change the name and the identifier follows.

admin and cluster-admin bind Kubernetes' own roles and can't be duplicated. A copy of viewer or developer is an approximation, and the line under the chips says so: those two also aggregate Kubernetes' view role and the labelled ClusterRoles of each cluster, which a copy doesn't inherit (System roles as capabilities). Check the copy against what the person needs before granting it in place of the original.

A copy of viewer keeps Namespaces and whole cluster, because its cluster-wide capabilities need it. For a namespace-only reader, choose Namespaces: the four cluster-wide capabilities stay ticked and marked until you switch them off, which Switch off the 4 does at once.

Edit a role¶

1. In Roles, choose Edit in the role's row menu, or Open it and click Edit.
2. Change what you need. The identifier is fixed.
3. Click Save changes. It waits for the summary to reflect what's on screen.

If no permission uses the role, it's saved at once. If some do, kubelatch asks first: Save role "…" says how many permissions on how many clusters change, and lists Capabilities added, Capabilities removed and, if so, The advanced rules change. On Save, those clusters are reconciled right away: within seconds the holders have the new rules, with the credentials they already have.

kubelatch refuses an edit that would leave active permissions the role no longer allows:

The summary says these before you save: the whole-cluster card, the cluster's box or the capabilities show the problem with the number of permissions, and Against the stored role lists No longer grantable to a whole cluster. or Removes the clusters: …; the confirmation repeats them. A permission granted between the summary and the save is still refused on saving, with the same message.

These count the permissions of disabled accounts too, which Usage leaves out. Find them in Permissions under Active, marked Account disabled.

If someone else saved the role after you opened it, saving says Someone saved this role after you opened it. Click Load the latest version: your changes stay on screen, the summary shows how they differ from the saved version, and you save again.

Every edit is a role.update in the control plane log, with the revision before and after, the capabilities added and removed, and the rules before and after (Audit and retention).

Delete a role¶

1. In Roles, choose Delete in the role's row menu, or Delete on the role's page.
2. Delete role "…" checks which permissions use it:
   • None: click Delete.
   • Some: the dialog lists every active permission, those of disabled accounts included, and offers Revoke all and delete. It revokes them and deletes the role in one step, and their clusters are reconciled at once. It also revokes the group permissions that name the role, and the permissions derived from them, so no group gives it again.

The identifier is never used again. Past permissions and the audit log keep the role's identifier, and the lists show it in place of the name. System roles can't be deleted.

Grant a custom role¶

In Permissions, Grant permissions works as for a system role (Grant permissions). Under What, System roles come first and Custom roles after. A custom role is disabled when the chosen cluster can't take it:

The same rules as for a system role apply: no protected namespace, the namespace must exist, and a role that requires Pod Security needs the pod-security.kubernetes.io/enforce label set to baseline or restricted. Scope whole cluster (*) only works for a role that can be granted to a whole cluster. A custom role has no expiry limit, so Never is available.

On the cluster, the permission is the group kubelatch:ns:<namespace>:role-<id>, or kubelatch:cluster:role-<id> for scope *. To check what it allows, use kubectl auth can-i with that group (Check what someone can do).

What someone without the admin role sees¶

People and bots without the admin role don't see Roles. On Home, the card of each cluster has a row per permission, and each row names its role: a custom role by its name, with its description under it. Through the API, any session can read the roles, their capabilities, rules and risk, but not their usage or the clusters they are limited to (HTTP API).