Environments and labels¶

An environment puts clusters under one name, such as prod, pre or staging, says whether they are production and can carry rules for people's permissions. A label is a key: value pair on a cluster, such as team: payments or region: eu, as in Kubernetes. A cluster sits in one environment at most and carries up to 20 labels. Here's how to create environments, place clusters in them, give them rules, label clusters, use both to group the diagram and filter Clusters and Permissions, and grant one permission on every cluster of an environment or with a label.

The production mark changes no permission, and a label changes none by itself. An environment's rules, in Pro, limit how long the permissions of people last on its clusters: saving a stricter rule, or moving a cluster into an environment with a maximum, shortens what outlasts it, after a confirmation that lists it. A permission on a set, also Pro, follows an environment or a label: a cluster that enters it receives the permission, and one that leaves loses it.

Before you start¶

• You're a kubelatch administrator. Environments, labels and their filters are for administrators only.
• The clusters are registered (Register a cluster). A cluster not enrolled yet takes an environment and labels too.

The Environments list¶

Environments, under Clusters in the sidebar, lists every environment. Its first line counts them, the clusters they hold and the clusters in none: 4 environments for 12 clusters. 2 clusters have no environment. Each row has the environment's id, Production when it's marked, how many clusters it holds and the first three of them, then and N more, and under Rules its rules in one line (Max 8 h · default 2 h, or No rules). The environments marked as production come first, then the rest by id. The last row, No environment, counts the clusters that sit in none.

The row menu has Open, See in Permissions (the permissions on its clusters) and Delete.

Create an environment¶

1. In Environments, click New environment. The form opens in a panel on the right; the command palette (⌘K) has New environment too.
2. Fill in Id, its name, such as prod, pre or staging: 1 to 63 lowercase letters, digits or hyphens, starting with a letter or a digit.
3. Tick Production if its clusters are production.
4. Click Create. You land on its page with the notice Environment prod created.

The id is the environment's name and never changes. To rename one, create the new one, move its clusters to it and delete the old one. An id another environment has is refused: an environment with that id already exists.

The environment's page¶

Click an environment to open its page, /admin/environments/<id>. The header has the id, Production when it's marked, how many clusters it holds (3 clusters.) and, with a maximum lifetime, what it guarantees (No person's permission lasts longer than 8 h.), then Edit and Delete environment. Three cards follow:

• Rules shows its maximum lifetime and its default expiry, each with what it does, or No rules (Rules).
• Clusters of prod lists its clusters, each with the pill of its level (Ready, Warning…) and a menu with Open and Remove from prod.
• Permissions here counts the permissions in force on its clusters and the people who hold them, leaving disabled accounts out: 12 permissions in force on its clusters; 5 people hold at least one. A bot's permissions count among the permissions, not among the people. See in Permissions opens Permissions with Environment set to it.

Place clusters in an environment¶

A cluster sits in one environment at most. There are two ways to put it in one:

• From the environment: on its page, click Add a cluster, choose the Cluster and click Add to prod. Each cluster in the list says where it is now (in staging, no environment); one in another environment moves here, and the panel says so before you add it: eu-2 leaves staging: a cluster sits in one environment at most. Its labels stay as they are.
• From the cluster: Environment and labels, on its page (below).

When the environment has a maximum lifetime and the cluster holds permissions of people that outlast it, or when the move takes a permission on a set away from the cluster or gives it one, both ways ask first with the confirmation of the cut; with nothing to cut or move, they save at once.

Remove from prod, in a cluster's menu on the environment's page, leaves it without an environment: a cluster in no environment has no rules, so nothing is cut, and its permissions keep their expiry. Its labels stay. It saves at once, unless it moves a permission on a set: one that follows prod stops reaching the cluster, and one on a label that the maximum of prod refused may start to. The confirmation then says so first.

Mark an environment as production¶

Edit, on the environment's page, opens a panel with Production. Tick or untick it and click Save changes; the notice says prod is now marked as production. or prod is no longer marked as production.

The mark changes what kubelatch shows, never who can do what:

• Home: once an environment is marked, Sensitive access becomes Sensitive access in production and counts the clusters of the environments marked alone; with none marked, it counts every cluster (Home).
• Audit: Environment offers Production, every environment marked at once (Search cluster requests).
• The Production pill goes beside the environment wherever it's named, and a cluster's page says it in its header (prod · Production). The environments marked come first in every list.

Rules (Pro)¶

An environment can carry two rules, each optional:

A rule lasts from 1 hour to 365 days. The 8-hour rule of privileged access still applies on top of them.

The rules bind people's own permissions and group permissions, whoever the group's members are. They never bind a bot's own permissions: a bot keeps its 30 days by default and may have no end date, so a bot that needs permanent access to prod gets it through a direct grant. An AI agent acting for a person never outlasts that person's permission.

Change the rules¶

1. On the environment's page, click Change rules in the Rules card. The panel Rules of prod opens.
2. Under Maximum lifetime, choose No maximum, 8 h, 1 day, 7 days, 30 days, 90 days or Other, which takes an amount in hours or days.
3. Under Default expiry, choose None of its own or a length the same way. A length longer than the maximum is disabled, with Longer than the maximum lifetime.
4. Click Save. When the new rules shorten nothing, they're saved at once and the notice says Rules of prod saved.

The rules then show in one line in the list of Environments, in each box of the diagram grouped by Environment and beside each environment in a cluster's Environment and labels panel: Max 8 h · default 2 h. To remove a rule, choose No maximum or None of its own.

The cut¶

A maximum holds for the permissions that exist, not only for new ones. Saving a shorter maximum, or one where there was none, shortens to now plus the maximum every active permission of a person or a group on the environment's clusters that ends later or never. Moving a cluster into an environment with a maximum does the same on that cluster. Nothing is ever lengthened, and bots' own permissions don't change. Group members follow their group permission.

Before saving, a confirmation lists what will be cut. Its title says the change (Change the rules of prod, Move eu-2 to prod or Save the environment and labels of eu-2) and its text counts it: Cuts 9 permissions of 6 people to Nov 6, 6:00 PM. Nothing is lengthened and bots do not change. A group permission counts once, and its members count among the people. The first five follow, each with who holds it (the account or the group), its role, where, its end now and the new one; See all 9 unfolds the rest. A disabled account's line is dimmed, with Account disabled. Save and cut 9 saves; Cancel sends nothing.

The confirmation shows what kubelatch found when you saved; the save acts on what holds at that moment, and the notice says what it really cut: Rules of prod saved. 9 permissions cut to Nov 6, 6:00 PM. kubelatch reconciles each cluster it touched. Each permission cut leaves its row in the control log, and the log shows the save and its cuts as one line (The control plane).

Relaxing a rule, with a longer maximum or none, lengthens nothing: the permissions keep the end they have.

A change that also moves permissions on a set lists them in the same confirmation.

Granting under the rules¶

On a cluster whose environment has rules, the forms that grant and extend permissions to people and groups follow them (Grant a permission, Extend permissions): they propose the default and offer neither Never nor anything past the maximum. The API refuses the same with 400 grant.environment_max (Errors).

Free and a lapsed key¶

Setting or changing a rule needs Pro. In Free, the Rules card carries Pro and See Pro, which opens Edition, and shows the saved rules with no Change rules.

The rules already saved keep applying in Free and with a lapsed key: they still refuse, propose and cut. Removing them never needs Pro: Remove the rules, in the card, asks first (Remove the rules of prod: The permissions that exist do not change; new ones have no maximum and get 30 days by default. Putting them back needs Pro.), and the notice says Rules of prod removed.

Delete an environment¶

Delete environment on its page, or Delete in its row menu in Environments, asks first and says what changes: Its 3 clusters are left with no environment; their labels and permissions do not change. Click Delete. The clusters stay, without an environment and with their labels.

If permissions on a set follow the environment, the delete revokes them, and the confirmation lists them first, together with what its clusters gain: a cluster out of the environment is out of its rules, so a permission on a label that the maximum refused now reaches it.

Labels¶

A label is a key: value pair, such as team: payments, region: eu or customer: acme. Use labels for what an environment doesn't say: the team, the region, the customer. A permission on a set can follow one. Labels follow the format of Kubernetes labels, in lowercase and without a prefix:

A cluster carries up to 20 labels, one value per key: a cluster belongs to one team and to one region. The keys environment and entorno are reserved, since the environment has its own field.

A cluster's environment and labels¶

The header of a cluster's page shows its environment next to the pill of its level, prod · Production for one marked as production or the id alone otherwise, and under it the cluster's labels (region: eu, team: payments) and Environment and labels. That button opens a panel:

1. Under Environment, choose one, or No environment. Those marked as production say so, and each one shows its rules (prod · Production · Max 8 h · default 2 h). With no environment created yet, the panel says There are no environments yet: create them in Environments.
2. Under Labels, each label is a row with Key and Value. Add label adds a row, and the × at its end removes it. Each row says what's wrong as you type: a key or a value off the format, a reserved key (environment is reserved: the environment has its own field.) or a key another row already has (There is another team label: one value per key.).
3. Click Save. When the environment chosen has a maximum that some permissions on the cluster outlast, or the change moves permissions on a set, the confirmation of the cut comes first. The notice says Environment and labels of prod-eu saved., and what was cut, if anything.

Save replaces the environment and every label at once, and waits until something changes (Nothing to save yet.). If someone else changed the cluster's environment or labels after the panel opened, Save writes nothing and says so, and the panel starts again from what the cluster has now; Remove from prod and Add a cluster do the same with what their page shows. Each save leaves a cluster.placement row in the control log, with the environment and the labels before and after and how many permissions it cut, even when nothing changed (The control plane).

Permissions on a set (Pro)¶

A permission on a set gives a person, a bot or a group a role on every cluster of an environment, such as staging, or on every cluster with a label, such as team: payments. It follows the set: a cluster that enters it receives the permission, and one that leaves loses it. viewer on all of staging is one permission, and a staging cluster you add next month is covered from the moment it's placed there.

The set is one environment or one label, never a combination, and cluster-admin is never granted on a set: it's personal and per cluster. On each cluster of the set the permission is a permission in force like any other: the proxy, the reconciler, the CLI, the AI agents and the expiry notices read it as they read a direct one.

Grant a permission on a set¶

1. In Permissions, click Grant permissions (Grant a permission). For a group, click Add permissions on its page (Add group permissions).
2. Under Where, choose An environment or A label. Specific clusters is the usual form. In Free, the two carry Pro and See Pro.
3. Choose the Environment, or the label's Key and Value. A line says which clusters are in it today (Clusters in it today: stg-a, stg-b., or No cluster is in it today.) and that the permission follows the set.
4. Choose the scopes: whole cluster (*), when the role allows it, or namespaces, which you type one by one in Namespace and add with Add, since the clusters of a set share no list of them. A protected namespace or a name off the format is refused as you type.
5. Choose the role, Until when and the Note.
6. Read the preview before you grant. It says It reaches 3 of 4 clusters. and, for each cluster it doesn't reach, It does not reach prod-eu: with the reason.
7. Click Grant N permissions. The notice says 2 permissions granted on staging.

The summary counts one permission per account and scope, at most 50 at a time, all or nothing: "2 permissions that follow staging: viewer on the whole cluster in the clusters of staging (4 today) to alice, bob, until Nov 11".

The expiry follows the rules of the environment. On an environment with a maximum lifetime, the form proposes its default and offers nothing past the maximum for a person or a group, as it does for a direct permission. On a label, each cluster has its own environment: where its maximum is shorter than the permission's expiry, the permission doesn't reach that cluster.

Which clusters it reaches¶

Each cluster of the set puts the permission through the checks a permission granted by hand there would pass (The rules): the namespace exists and enforces the Pod Security level the role requires, a custom role finds the bootstrap it needs, a native role's name doesn't clash, and the rules of the cluster's environment take the expiry. A cluster that fails one gets no permission from the set, and the permission's line says No effect there, with the reason; everywhere else it holds. A cluster kubelatch can't ask gets nothing either. Taking away never waits for a cluster: one that leaves the set loses the permission even if it doesn't answer.

When kubelatch decides again¶

kubelatch decides the clusters of a set again when:

• the permission is granted, extended or revoked (all its clusters);
• a cluster's environment or labels are saved (that cluster);
• an environment is created, changed or deleted (its clusters);
• a cluster is enrolled again, gets new tokens or has its identity template changed (that cluster).

A refusal is one of two kinds:

A rule refusal waits because trying it again by the clock would let a 7-day permission refused on prod enter by itself in its last 8 hours, with nobody deciding it.

Check again¶

Widening the clusters of a custom role, or a cluster moving to bootstrap v2, removes the cause of a rule refusal, but it isn't a moment of decision: nobody would have seen the access it gives. Check again, in the line's menu, does it. It shows what the permission would gain, Check again and give 2 with the clusters, and applies it when you confirm. When nothing changes it says Nothing new: the reasons remain. and sends nothing. After a check the notice reads Permission of "alice" on staging: it reaches 2 more clusters. It works in every edition.

Extend a permission on a set¶

Extend the permission on staging, in the line's menu, moves the end of the permission and of what it puts on each cluster. It needs Pro: in Free the item carries Pro and See Pro.

The cluster's rules apply. Where a cluster's environment has a maximum that the new date passes, the permission stops reaching it, and the confirmation lists it first (Stops reaching prod-eu: with the reason). An extension is never all or nothing: a cluster kubelatch can't ask keeps its date (prod-eu could not be checked: it keeps its date.) and kubelatch tries again on its own, until the cluster receives the new date or the permission leaves it. On an environment with a maximum, a person's or a group's permission can't go past it (400 grant.environment_max).

Revoke a permission on a set¶

Revoke the permission on staging, in the line's menu, asks first: Revoke the permission of "alice" on staging: it stops reaching 3 clusters. It revokes the permission and what it put on each cluster at once, in any edition.

What a set puts on a cluster has no Revoke of its own: DELETE /api/grants/{id} on it answers 409 grant.set_derived. To take it from one cluster, take the cluster out of the set.

Disabled accounts¶

A permission on a set can't be granted to a disabled account (409 account.disabled). If the account is disabled later, what the set put on its clusters stays and counts for nothing, as its direct permissions do; enabling it brings it back with no change. A disabled account's line keeps only Revoke: it can't be extended or checked again until the account is enabled.

When something the set depends on goes¶

• An environment deleted: the permissions on it are revoked (Delete an environment).
• A group deleted: the permissions on a set that it holds are revoked with it, and its members lose what those permissions gave them.
• A custom role deleted: the permissions on a set that name it are revoked with the others the deletion revokes.
• A custom role edited: unlike direct and group permissions, permissions on a set never block the edit. Where it leaves the role not allowed on a cluster of the set, because the cluster is taken out of Only some…, the whole cluster is switched off or Pod Security becomes required, the permission stops reaching that cluster as a rule refusal and keeps working on the others. The confirmation of the edit lists it: 2 permissions on team: payments stop reaching prod-eu. (Edit a role).
• The last cluster with a label loses it: the permissions on that label stay, reaching no cluster, and reach the first cluster that carries it again.

When a cluster moves or a rule changes¶

Changing a cluster's environment or labels moves it in and out of sets: it receives the permissions on the sets it enters and loses those on the sets it leaves. Relaxing a rule can bring in permissions on a label that its maximum refused. Both ask first, with the confirmation of the cut, which lists after what it cuts a line for each cluster that stops getting a permission (Stops reaching prod-eu: the permission of "alice" on team: payments, followed by the sentence of the reason when a rule causes it) and for each that starts to (Reaches prod-eu: the permission of "alice" on team: payments). With a group, it reads the permission of the group "payments" on …. The first five of each come first, and See all N shows the rest. A permission on a set that the cut shortens reads like the others, plus via prod. When the change cuts nothing and only moves permissions on a set, the button reads Save. After saving, the notice adds N permissions on a set change., from what the save did.

How the lists count them¶

A permission on a set is one permission for the administrator who grants it and one on each cluster for the people who hold it, so each list counts it by what it lists:

• Where a list goes by account, it's one line and counts once: the list in Permissions, By account, its figures and chips, an account's page and the marks in the sidebar. The line shows the role and the set, the scope, 3 of 4 clusters, follows the environment or follows the label, its end and a menu. A button unfolds one line per cluster: its end where it holds the permission, No effect: and the reason where it doesn't (Read a permission).
• Where a list goes by cluster, each cluster counts its own and reads via staging: By cluster, the map, a cluster's page, an environment's page, My clusters on Home and the confirmation of the cut.

A line with a temporary refusal counts once in Showing only the permissions without effect. and in the N permissions without effect that Home shows for a cluster in error. A rule refusal is deliberate (prod doesn't take more than 8 h), so it's read in the unfolded line and counts as nothing pending.

In Free and with a lapsed key¶

Granting and extending a permission on a set need Pro. In Free, An environment and A label under Where carry Pro and See Pro, and so does Extend. What is already granted keeps working in Free and with a lapsed key: the permissions keep following their sets, being checked and tried again, and nothing is deleted. Revoking, Check again and deleting an environment, a group or a role work in every edition, since none of them gives more access than there was.

Group and filter¶

Group the diagram¶

In Clusters, Group by, beside the tabs while Diagram is open, chooses the diagram's boxes:

• Provider: one box per provider, as The diagram describes.
• Environment: one box per environment, those marked as production first, with Production, then by id. No environment, with a dashed border, comes last.
• A label key, such as team: one box per value, by value, and No team, dashed, last.

The diagram opens on Environment once a cluster has one, and on Provider otherwise. A cluster not enrolled yet sits in the box of its environment or its label. The choice stays in the address (?by=environment, ?by=label:team); a key no cluster carries any more opens the default.

Filter Clusters and Permissions¶

Environment and Label keep the clusters of one environment, or those with one label. They sit beside the tabs in Clusters and after the chips in Permissions, and each shows once there's something to choose: All environments and every environment, All labels and every key: value in use. Both at once keep the clusters that pass both. They stay in the address (?environment=prod, ?label=team:payments), so a link opens them too.

• In Clusters, they narrow the diagram and the List, and the List's chips count within them.
• In Permissions, every view keeps the permissions on those clusters alone.

A view left with no cluster says No cluster matches. with Clear, which lifts the filters.

Via the API¶

Every operation above exists in the JSON API: /api/environments, PUT /api/clusters/{id}/placement, GET /api/cluster-labels and, for permissions on a set, /api/cluster-set-grants. POST /api/environments/{id}/preview and POST /api/clusters/{id}/placement/preview say what a change would cut, writing nothing. The routes are in HTTP API and permissions on a set, and the errors in Errors and Permissions on a set.