Glossary¶
The terms this documentation uses, in alphabetical order, with a link to where they're explained.
| Term | What it is |
|---|---|
| Administrator (role) | Person with the administrator role in kubelatch: manages clusters, permissions, accounts and trust rules. Not to be confused with the admin system role, nor with the roles a permission grants. See Users and bots. |
| Advanced rule | A rule an administrator writes into a custom role, for what no capability covers: API groups, resources, verbs and, optionally, object names. See Roles. |
| Agent session | kubelatch's record of one AI agent connected through the MCP server: whom it acts as, its credential, its conditions and its timeline. For a bot, one per credential; for a delegated agent, one per authorization. Cut from Agents. See AI agents. |
| AI agent | An MCP client, such as Claude Code or Cursor, that works on the clusters through kubelatch's MCP server, as a bot or on a person's behalf. See AI agents. |
| Approval (of an agent) | What an agent asks a person to decide: a write held for approval, or access to a role for a while. Agents lists the ones you can decide under Waiting for you, and each has its own page for deciding. See AI agents. |
| Audit log | kubelatch's two logs: audit_events (one row per proxy request) and control_events (control plane actions and login attempts). See Security model. |
| Audit-ID | Unique identifier (UUIDv7) kubelatch assigns to every proxy request. It goes in the response, in the audit row, and in the request to the cluster, which uses it as its auditID. See The journey of a request. |
| Bootstrap | Manifest kubelatch generates for each cluster: creates the kubelatch-system namespace, the proxy's and reconciler's ServiceAccounts, and the reconciler's jail. See Register a cluster. |
| Bootstrap version | Which bootstrap manifest a cluster has: 1, the previous one, or 2, the current one with the reconciler's jail. Custom roles need 2. See Update the bootstrap. |
| Bot | Subject for automation: no password or session, only credentials. Appears in the cluster as bot:<name>. See Users and bots. |
| Break-glass account | Account that can sign in with a password even while GitHub or OIDC login is active. Only set from the server CLI (kubelatch-server user set-break-glass), and has no two-factor. See Identity. |
| Capability | A named set of rules from kubelatch's catalogue (workloads.read, pods.exec…) that a custom role switches on. See Roles. |
| Ceiling | What a delegated agent may do: its derived permissions, each from one of its person's permissions. See AI agents. |
| CI exchange | Exchange of a GitHub Actions job's OIDC token for a short-lived bot credential, at /v1/ci/github-actions/token. See Credentials for GitHub Actions. |
| CLI session | The credential kubelatch login creates (kind cli), kept in ~/.config/kubelatch/session.json and valid for KUBELATCH_CLI_SESSION_TTL, 12 h by default. A new login revokes the previous one. See The CLI. |
| Cluster | A Kubernetes cluster registered in kubelatch, with an id (slug) that's part of the proxy URL: /clusters/<id>. See Register a cluster. |
| Control plane | kubelatch's JSON API and web interface. See Architecture. |
| Credential | A klt_… token, usually with the kubeconfig that uses it. Has an owner, an expiry, a last use, and can be revoked. See Get a credential. |
| Custom role | A role an administrator composes in Roles from capabilities and advanced rules. A Pro feature; it can be edited and deleted, and needs the current bootstrap on the cluster. See Roles. |
| Delegated mode | An AI agent acting as a person, with only the permissions the person chose when authorizing it, for hours. See AI agents. |
| Derived permission (from a group) | A permission kubelatch makes for each pair of a group's member and group permission. It expires at the earlier of the membership's and the group permission's expiry, and is changed or revoked only through its group. See Groups. |
| Derived permission (of an agent) | A permission of a delegated agent's session, made from one of its person's: same cluster and scope, the same role or viewer, never cluster-admin, ending with the session or the person's permission. See AI agents. |
| Disable | Cut off a subject's access: closes sessions, revokes credentials, and removes it from the clusters. Keeps its permissions in case it's re-enabled. See Identity. |
| Enroll | Run a cluster's enrollment command, once the cluster is registered. Register a cluster only creates its record, with the status Not enrolled; enrolling applies the bootstrap and sends kubelatch the tokens, and the cluster becomes Ready. See Register a cluster. |
| Enrollment link | One-time link (<base>/api/enroll/kle_…, 1 h) inside the enrollment command an admin generates on the cluster's page, where it can also be invalidated. The command applies the bootstrap and sends the tokens to kubelatch; the link is the only credential. See Register a cluster. |
| Environment | A name an administrator gives to some clusters, such as prod or staging, optionally marked as production. A cluster sits in one at most. It groups and filters the clusters, and its rules, in Pro, limit how long people's permissions last on them. See Environments and labels. |
| GitHub App | Your GitHub organization's application that people use to sign in to kubelatch and that enables automatic offboarding. See GitHub login. |
| Group | A named set of members (people and bots) and group permissions. Every member holds every group permission, as derived permissions kept in step with the group. Not to be confused with a Kubernetes group kubelatch:…. See Groups. |
| Group permission | A cluster, a role and a scope given to a group, with an optional expiry. Never cluster-admin. See Groups. |
Group kubelatch:… |
Group the proxy impersonates for each active permission: kubelatch:ns:<namespace>:<tier> or kubelatch:cluster:<tier>, with role-<id> in place of the tier for a custom role. The cluster's bindings point to these groups. See System roles and Roles. |
| Identity provider (IdP) | The service where your company's people sign in, such as Google Workspace, Microsoft Entra ID, Okta or Keycloak. kubelatch can use it for sign-in over OpenID Connect. See OIDC login (SSO). |
| Identity template | How a cluster names people in Impersonate-User: free text around one variable, {login}, {email}, {oidc_subject} or {github_login}. user:{login} by default; oidc:{email} gives oidc:ana@acme.com. One per cluster. See Identity in the cluster. |
| Impersonation | Kubernetes mechanism by which one identity (the proxy's ServiceAccount) acts on behalf of another, using Impersonate-* headers. See Why a proxy. |
| Instance | One deployment of kubelatch. Each cluster belongs to a single instance; the kubelatch.io/instance label, set from KUBELATCH_INSTANCE_ID, tells instances' objects apart in the cluster. See Move a cluster to another instance. |
| Invitation link | One-time link (<base>/account-link#kli_…, 72 h) a new person uses to set their password, or to link GitHub or the OIDC provider. See Identity. |
| kubeconfig | kubectl's configuration file. kubelatch's has one context per cluster, named kubelatch-<id>, all with server: https://<kubelatch>/clusters/<id> and the same token. See kubectl, k9s, Lens and Helm. |
| Label (of a cluster) | A key: value pair on a cluster in kubelatch, such as team: payments, one value per key and up to 20 per cluster. It groups and filters the clusters, and a permission on a set can follow it. Not to be confused with a Kubernetes object's labels. See Environments and labels. |
| Link | Associate a kubelatch account with a GitHub account's numeric id, or with an OIDC identity. See Identity and The OIDC identity. |
| Linking link | One-time link (24 h) an admin generates, from the account's page, to link an existing account with GitHub or the OIDC provider. Without an external login, or on a break-glass account, the same menu item is called Reset access and gives a reset link, which sets a new password. See Identity. |
| Management cluster | The cluster kubelatch runs on. It can be one of the clusters it manages. See Install. |
| MCP (Model Context Protocol) | The protocol AI agents use to call tools. kubelatch serves an MCP server at /mcp. See MCP server. |
| Member (of a group) | An account in a group, with an optional expiry of its own. A disabled account keeps its memberships, which don't count until it's enabled. See Groups. |
| Member sync | Hourly pass that disables accounts whose owner is no longer a member of the GitHub organization. See Identity. |
| Native audit log | The audit log of the cluster itself or its cloud provider. A second source, correlated by Audit-ID. See Security model. |
| Native role | A role that names groups the cluster's own SSO already knows. A permission of it is temporary membership in those groups: kubelatch impersonates them and writes no binding. Always sensitive and granted on the whole cluster. See Native roles. |
| OIDC (OpenID Connect) | The standard behind two unrelated things in kubelatch. OIDC login signs people in through your company's identity provider (OIDC login (SSO)). The CI exchange takes the OIDC token GitHub Actions gives a job and issues a bot's credential (CI: trust rules). They share no configuration: CI works with either login, or with none. |
| OIDC identity | What links an account to the identity provider: the provider's issuer, the name of the claim that identifies the person (sub, or oid for Entra ID) and its value. The e-mail address only finds the account on its first sign-in. See Identity. |
| Origin (source) | Where a permission comes from: granted to the account, or through a group. Every list of permissions says it in the Why column: direct, or via and the group. See Read a permission. |
| Permission (grant) | Subject + cluster + role + scope, with an optional expiry (required for cluster-admin). Active as long as it's not revoked or expired. See Grant permissions. |
| Permission on a set | A permission that gives a person, a bot or a group a role on every cluster of an environment or with a label, and follows the set: a cluster that enters it receives the permission, and one that leaves loses it. Pro. See Permissions on a set. |
| Person | Human subject: signs in to the interface and requests credentials. Appears in the cluster as user:<login>, or as the cluster's identity template names them. See Identity. |
| Privileged access | What a group or a user has when the cluster's RBAC gives it a capability that can lead to cluster-admin, such as running workloads or reading Secrets in a privileged namespace. Every permission that gives it needs an expiry of 8 h at most. See What counts as privileged. |
| Protected namespace | Namespace that admits no permission of any role: kube-system, kube-public, kube-node-lease, kubelatch-system, and those in KUBELATCH_PROTECTED_NAMESPACES. See System roles. |
| Proxy | The part of kubelatch that receives requests from kubectl and CI at /clusters/<id>/… and forwards them to the cluster with impersonation, acting as the subject. See The journey of a request. |
| Proxy's ServiceAccount | kubelatch-proxy, the identity the proxy uses to talk to each cluster; it can only impersonate. See Architecture. |
| PSA (Pod Security Admission) | Kubernetes control that limits which pods can be created in a namespace based on its pod-security.kubernetes.io/enforce label. developer, debugger, admin and the custom roles that need it require baseline or restricted. See System roles. |
| Reconciler | The part of kubelatch that keeps each cluster's ClusterRoles of tiers and custom roles, bindings, and the list of who the proxy can impersonate up to date. Runs when a permission changes, on request, and every 10 minutes. See Architecture. |
| Reconciler's jail | kubelatch-reconciler-jail, the admission policy in the bootstrap that keeps the reconciler's writes to kubelatch-* objects. Kubernetes 1.30 or later. See Security model. |
| Reconciler's ServiceAccount | kubelatch-reconciler, the identity the reconciler uses to write RBAC in each cluster. See Architecture. |
| Re-enroll | Run a cluster's enrollment command again from its page. Re-enroll replaces its two ServiceAccount tokens with new ones, with a command that carries --rotate; Re-enroll without changing the tokens applies the current bootstrap and keeps them. Rotating is needed after a change of KUBELATCH_ENCRYPTION_KEY or of the cluster's CA. See Rotate the ServiceAccount tokens. |
resourceNames |
List of names an RBAC rule is limited to. The proxy's ServiceAccount can only impersonate the users and groups on that list. See Security model. |
| Retention | How long the audit log is kept before the periodic retention job deletes it: KUBELATCH_AUDIT_RETENTION, 90 days by default (24 hours at most if the instance never had a key). See Audit and retention. |
| Revoke | Invalidate a credential or a permission before its expiry. A revoked credential fails on the next request and its streams are cut within 10 s. See Expiry and revocation. |
| Role | What a permission grants: a system role, a custom role or a native role. Not the administrator role. See Roles. |
| Scope | Where a permission is valid: a namespace or * (the whole cluster). See System roles. |
| Session | The web interface's __Host-kubelatch_session cookie (kubelatch_session on plain http), valid for 12 h. It doesn't work for talking to clusters. See Identity. |
| Subject | Anything that can have permissions: a person or a bot. See Identity. |
| System role | One of the six roles that ship with kubelatch, also called tiers. Read-only; all but admin and cluster-admin can be duplicated. See System roles. |
| Tier | Another name for a system role: viewer, developer, debugger, secrets-reader, admin or cluster-admin. See System roles. |
Token klt_ |
The secret part of a credential: klt_ plus 43 characters. Shown once only; kubelatch only stores its SHA-256. See Security model. |
| Trust rule | Rule that says which GitHub repository (and optionally which ref or environment) can exchange its OIDC token for which bot's credential. See CI: trust rules. |