Users & Access¶

Local accounts, roles (admin, developer, viewer) and paid seats, two-factor authentication, API keys, and cleaning up people who have left — including the recovery paths for when the thing you need to fix is the thing that is locked.

Tier: Free

What it does¶

Everyone who uses KubeManta signs in as themselves. Accounts come from one of three places: the local account you set at install, accounts an admin creates here, or accounts provisioned automatically the first time someone signs in through your identity provider.

There are three roles. A viewer can see everything the product observes about your cluster and change nothing. An admin can act — restart, scale, apply, run a terminal session, and manage KubeManta itself.

A developer sits between them, on the Pro and Enterprise plans. A developer sees what a viewer sees, and can also:

restart a Deployment, StatefulSet or DaemonSet, or restart a single pod by deleting it — only a pod a controller will replace, so nothing is lost;
scale a Deployment or StatefulSet;
open a shell in a pod, when an admin has turned Expert Mode on;
approve a restart or scale the AI assistant proposes. Any other change the assistant suggests still needs an admin.

A developer can never act in system or KubeManta namespaces (kube-system and the other kube-* namespaces, the namespace KubeManta runs in, and similar), even when an admin has chosen to show those namespaces. A developer cannot delete Deployments or other resources, apply YAML, run Helm operations, use the Terminal, change settings, or manage users, sign-in, licences or API keys other than their own. Everything a developer does is recorded under their name in the audit trail, exactly as for an admin.

The one thing a viewer does not see is the record of what people did: Activity Feed (the audit timeline, terminal command history and AI transcripts), the Terminal itself, and AI Context are admin-only. Those tabs are absent from a viewer's sidebar rather than shown and then refused, so nobody is offered a destination that cannot open.

A viewer also cannot list Secret names. The name, type and key-count of a Secret — never its values, which the product does not expose anywhere — is reconnaissance a delegated read-only user should not have across every namespace, so listing Secrets is admin-only. ConfigMap names, which are ordinary configuration rather than credentials, stay visible to viewers.

Viewers are free and unlimited at every tier. Admins and developers each occupy a paid seat — both can change your cluster — so the seat count only ever blocks assigning one of those roles. Running out of seats can never log anyone out, revoke an existing admin or developer, or interrupt an incident — it stops the promotion, and says so. Moving someone between admin and developer reuses the seat they already hold.

On the Free plan the roles are admin and viewer; Developer is shown in the role picker but cannot be chosen. If a paid plan lapses, existing developers are not removed or signed out — they act as viewers until the plan is renewed, and act as developers again from their next request after it is.

Two-factor authentication¶

A user with a local account can add a TOTP second factor: Two-factor auth in the account menu (top right), scan the QR code with an authenticator app, then enter one code to confirm. The enrolment is not active until that confirmation succeeds, so a mis-scanned code cannot lock you out of your own account.

If you sign in through SAML or OIDC, your identity provider handles this. Okta, Entra, Google and the rest authenticate you and enforce MFA there, so KubeManta does not ask for a second code on top — that is the point of federating identity. Turn MFA on at the provider, not here. The setup is hidden for those accounts rather than offered and ignored.

LDAP is the exception, and it is off by default. A directory sign-in checks the password against LDAP and nothing else — a simple bind does no MFA — so unless you enable it, those accounts are password-only. An admin switches it on in Admin → Auth (SSO) → Allow directory users to add two-factor (TOTP), and each user then chooses whether to enrol; nobody is forced, so enabling it cannot lock anyone out.

Switching it back off hides the setup from people who have not enrolled. Anyone who already confirmed a code keeps being asked for it — their authenticator still holds it, and quietly ignoring it would leave them believing they are protected when they are not. Removing one person's second factor is a deliberate action on their account, never a side effect of a switch.

TOTP is the only second factor and that is deliberate. Email, SMS and push each depend on something outside the cluster, and they fail precisely during the outage that a second factor on a break-glass login exists for.

Two behaviours are worth knowing because they occasionally surprise people. A code is single-use — a replay of the same code is refused even while it is still inside its time window, which is what makes a shoulder-surfed or phished code worthless seconds later. And the clock tolerance is one step either side (±30 seconds), so a phone whose clock has drifted by minutes will produce codes KubeManta rejects; fix the phone's time sync rather than retrying.

If someone loses their authenticator, an admin removes it from their account — see Recovering somebody else's account below. When no admin can sign in, an operator with cluster access clears it from the pod:

kubectl exec -n kubemanta-system deploy/kubemanta-agent -- \
  python3 -m app.reset_mfa --list
kubectl exec -n kubemanta-system deploy/kubemanta-agent -- \
  python3 -m app.reset_mfa --principal user:3

--root clears the factor on the built-in admin password login instead. The command grants nothing new — anyone who can kubectl exec into the agent already holds its database — and the removal is recorded in the audit trail.

Recovering somebody else's account¶

Admin → Users & Groups → Users, then Account recovery on a local account. Two separate actions, because they are two different decisions:

Set one-time password. You choose it and pass it on; the user must choose their own at their next sign-in, so what you typed stops working the moment they use it. Their current sessions are signed out, and the reset is recorded against you, not them.

That one-time property is the point. Setting somebody's password hands you a working credential for their account, and anything done with it would be attributed to them. Expiring it on first use bounds that window and makes it visible: either they sign in and change it, or the credential you hold stops working. The same applies to accounts you create — the password you choose is one-time.

Remove second factor, for the lost-phone case. Removing your own requires a current code — correctly, so a stolen session cannot strip it — which makes the self-service control useless in exactly the situation that needs it. This hands over no credential, only removes a factor, and is recorded as its own event.

An account that signs in through an identity provider has no password here to reset, and says so rather than appearing to work.

If nobody can sign in at all, recovery is pod-side — see Locked out of everything below.

Changing your own password¶

Change password in the account menu (top right). It asks for your current password first: without that, anyone who got hold of your open session could change the credential and lock you out of your own account — the same reason removing a second factor requires a live code.

Changing it signs out your other sessions and leaves the one you are using alone. Rotating a password usually means "somebody else may have had it", so sessions minted with the old one should not outlive it; being signed out of the screen you are standing on, as a reward for improving your security, would just teach people not to bother.

An account that signs in through an identity provider has no password here to change, and is told so rather than being shown a form that would do nothing.

Sessions end for several different reasons, and the login screen names which one. The distinction matters: a session that timed out overnight is not the same as one an administrator revoked, and without the reason the last thing you clicked looks like the cause.

You will see one of:

You were signed out after N hours of inactivity. The ordinary one. Idle sessions end after SESSION_IDLE_TIMEOUT (8 hours by default), and the message names the actual window rather than a guess. Signing back in is all it needs.
Your session reached its maximum age. The absolute lifetime, separate from idleness — nothing you could have done would have kept it, which is why it is worded differently from a timeout.
Your session was ended by an administrator, or because the account password changed. Somebody did this deliberately. If it was not you, ask who.
This account is no longer active. Signing in will not help; it needs an administrator to re-enable it.

Two of these are worth knowing apart. An idle timeout is not a security event — nobody did anything to you. A revoked session means somebody did. Reading the first as the second sends people hunting for a setting to change when the answer is a conversation, and reading the second as the first hides a change somebody made to your account.

A session belonging to a different account is never affected by what happens to yours. Resetting a local account's password ends that account's sessions and nothing else — including when the same person also signs in through an identity provider, which is a separate account with a separate credential.

Signing in with a one-time password¶

If your password was set by somebody else — an admin created or recovered your account — the first thing you see after signing in is the change-password form, with no way past it. Until you choose your own, every other part of KubeManta answers "your password was set for you and must be changed", including the API: the limit is enforced by the server, not by hiding buttons, because a one-time password that still works from a script is not one-time.

Signing out always works. So does the form itself — those are the only two things that do.

API keys¶

Everyone creates their own, under Account → API keys in the account menu (top right). An admin cannot mint a key for somebody else: a key acts as its owner, so one issued on your behalf would do things as you while the audit trail named you. An admin can see any key's name, prefix and last use — never its secret — and can revoke it at any time.

The secret is shown once, when the key is created. KubeManta stores only a hash, so there is no way to display it again; copy it then, or create a new key.

It appears in a dialog of its own that has to be dismissed deliberately — neither Escape nor a click outside it will close it — because dismissing by reflex would discard the only readable copy of a credential nobody can reissue.

You choose what each key can do. At mint you pick its scopes — named permissions like workloads:read, alerts:write or helm:write. Nothing is pre-selected: grant only what the integration needs, because a leaked key can do exactly that much and no more. A CI job that restarts a pod needs workloads:write and nothing else; a Prometheus scraping KubeManta's own /metrics needs scrape:read, which opens that one endpoint and accepts the key as a Bearer token, the way Prometheus sends it. metrics:read is for reading KubeManta's metrics views through the API and does not open /metrics — a scrape key created with it before upgrading needs replacing with a scrape:read key. The picker says which of the two each one is for.

Two limits apply together, and both can only narrow:

Scopes decide which surfaces the key may reach.
The owner's role, re-read on every request. Demote someone and their key immediately acts as a viewer whatever its scopes say; deactivate them and it stops working. A key can never do more than the person who holds it — a developer's key with workloads:write can restart and scale, and is refused a delete exactly as the developer would be.

The picker only offers scopes your role can use, so a viewer is not offered workloads:write and a developer is not offered helm:write.

Each key's scopes are listed beside it in Account → API keys, so "what could this key do if it leaked?" is answerable at a glance.

Some surfaces no key can reach, at any scope. Identity and credentials (users, groups, SSO, other API keys, your password, your second factor), the licence, expert mode, the audit feed, and the terminal. There is no scope that opens them — a key can never mint another key, disable a safety control, widen its own reach, or read the shell history of everyone who used the terminal. Those need an interactive login.

Mint one for yourself from the account menu → API keys. The secret is shown once. If you are upgrading from a release before scoped keys, your existing keys were revoked on upgrade and need re-minting with the scopes they actually need — there was no safe way to guess what an old key was meant to do.

What to do with it: everything the dashboard reads, a script can read. The API reference documents the X-API-Key header, the endpoints behind each screen — namespaces and pods, incidents, CPU/memory/network history, application sizing, API-server latency, security posture and findings — with worked request examples and the scope each endpoint requires. Your own cluster can also serve its OpenAPI schema at /api/agent/openapi.json, so you can generate a typed client rather than hand-writing one — that endpoint is off by default, and is exposed (along with /docs and /redoc) by setting KUBEMANTA_ENABLE_API_DOCS=true on the agent.

Connected apps¶

When you connect an AI client such as Claude Desktop or claude.ai to KubeManta over OAuth, you approve it once in the browser and it keeps a grant that acts as you. Connected apps in the account menu (top right) lists every app you have authorized, with when you authorized it, and Revoke takes a grant back immediately.

It is there for every account — local, SAML, OIDC and LDAP alike. Whether you have a password here has nothing to do with whether you have connected an app, so the list does not depend on one. The list is yours alone: an admin does not see other people's connected apps here.

OAuth clients (admins)¶

An AI client that connects over OAuth first registers itself with KubeManta. Admin → Users & Groups → OAuth clients lists every client that has registered: its name and client ID, when and from which IP address it registered, the redirect URIs it gave, and Active grants — how many people currently have it approved. Registering grants nothing on its own; a client can act only for someone who approved it on the consent screen, and only with that person's role.

Disable cuts a client off for everyone at once. It revokes every grant the client holds, for every user, together with every access and refresh token issued under them, and the client's connections stop working on their next request. Disabling cannot be undone. It does not prevent the same app from registering again as a new client — registration is open so that clients can connect without an admin in the loop — but a re-registered client can do nothing until someone approves it again. Disabled clients stay in the list, marked with when they were disabled.

Removing people who have left¶

Deactivating an account is the normal action: the person can no longer sign in, their sessions stop working on their next request, and everything they did stays attributed in the audit trail. Bulk actions handle the common cleanup of thirty stale accounts at once.

Bulk is deliberately not all-or-nothing. Each account is attempted independently and the result tells you what happened to every one, because a batch that fails wholesale on one already-deleted id teaches you nothing about the other twenty-nine. Two guards always apply: the last active admin cannot be removed — checked per account as the batch runs, so selecting every admin at once still refuses at the final one — and you cannot remove yourself in bulk, since revoking your own session midway would leave the rest half-done and you locked out. The single-user route is still there when that is genuinely what you want.

For a legal erasure request rather than an offboarding, see the erasure plan on the user's own row: it shows exactly what will be deleted, what will be pseudonymised, and what KubeManta refuses to erase and on what grounds.

Roles that come from your identity provider¶

If you run SSO, roles come from groups, and the split is deliberate: your directory decides who is in a group, KubeManta decides what a group grants.

Groups are not typed in. They appear under Admin → Users & Groups → Groups the first time somebody signs in carrying them, with a member count and when they were last seen — which is what makes an opaque identifier recognisable, because several directories send group GUIDs rather than names. A group grants viewer until you set it to developer or admin. When someone belongs to several groups, the most privileged role any of them grants applies.

Two consequences worth knowing:

Removing somebody from a group at your IdP demotes them at their next sign-in. Membership is re-read from the claim on every login, so your directory stays the one place you deprovision.
Promoting one person in Admin → Users & Groups → Users pins them. A pinned role survives logins and is not overwritten by their groups — that is the escape hatch for the person who needs admin without the whole group having it.

If nothing appears under Groups after people have signed in, the group claim is not reaching KubeManta; check the groups attribute in the SSO settings. A directory with no groups at all can grant admin by email address instead.

Security posture¶

Admin → Security shows the four install settings that decide what KubeManta is able to do to your cluster, as they are actually in effect:

Workload changes (rbac.allowWrites) — whether KubeManta may restart, scale and delete workloads when a person asks for or approves it, and in which namespaces.
Secret read (rbac.readSecrets) — whether KubeManta can read Secrets, and where: every namespace, or only the ones named.
Expert Mode (expertMode.enabled) — shown as its two separate gates: whether the privileged component is installed (and answering), and whether an admin has switched it on in Admin → System.
Air-gap mode (security.airgap.enabled) — whether outbound internet traffic is blocked, including whether the network policy that blocks it is present. Egress rules add up across network policies, so any other policy in KubeManta's namespace that allows traffic to any address cancels the block; the page names such a policy instead of reporting the traffic as blocked.

The permissions are checked with your cluster, not read from the install's configuration. If another role binding grants KubeManta more than the install asked for — Secret read in every namespace when the install named two, for example — this page shows what the cluster actually allows and points out the difference.

Each row says what the setting means and what changing it would cost. When a check cannot be answered (the cluster refused the question, or a component did not respond), the row says Unknown and gives the reason; it never falls back to showing the setting as off. Results are cached for up to a minute; Check again forces a fresh check.

The page is read-only and visible to admins only. The settings themselves are changed in your Helm values. The same summary is included in every support bundle.

Configuration backup: moving or reinstalling KubeManta¶

Admin → System → Configuration backup saves every admin setting to one encrypted file and loads it into another install — so a reinstall, or a move to a new cluster, does not mean entering every integration, alert rule and SSO setting again.

What the file carries: alert integrations and their credentials, alert rules, AI provider and guardrail settings, AI Context documents, SSO settings and group-to-role mappings, access-control lists, branding, applications, scanner and observability configuration, runbooks and scanner risk exclusions. What it does not: history (audit trail, alerts fired, scans, incidents), local user accounts and passwords, two-factor secrets, API keys, sessions, and the licence key, which comes from your Helm values.

Export. Choose a password of at least 12 characters and type it twice. The file is encrypted with it (AES-256-GCM, key derived with scrypt); KubeManta never stores the password, so keep it with the file's other secrets — without it the file cannot be opened. Credentials inside are decrypted only while the file is being written, and are re-encrypted with the new install's own key when you import.

Import. Choose the file and enter its password, then Check file: you see which settings are new or would change and how many rows each list holds, and nothing has changed yet. Untick anything you want to keep as it is, then Import and restart. Settings in the file overwrite the same settings here; each ticked list (alert rules, AI Context documents, …) replaces this install's list. KubeManta then restarts itself to apply everything — the page reconnects in about a minute. A wrong password or a damaged file changes nothing.

An import never switches on something this install's licence does not cover — it follows the same rule as the settings screen it came from. On an install without the plan, the file's settings are still imported, but:

Single sign-on (Enterprise): any sign-in method that was not already on here arrives switched off, ready to switch on once the licence allows. Methods already on stay on.
Login-page branding (Enterprise) is not imported; the login page stays as it is.
The AI egress allow-list (Enterprise) is not imported; the rest of the AI guardrails are.
PagerDuty, Datadog, CloudWatch and webhook alert destinations (Pro) arrive switched off unless they were already on here. Slack, Telegram and email import as they are.
AI diagnosis of alerts, incident ticketing and Slack inbound (Pro) arrive switched off, with their settings in place.

Check file lists each of these before anything changes, the result of the import repeats it, and the audit entry for the import records it.

Export and import are available to admins signed in to KubeManta only — not to API keys — and both are recorded in the audit trail (never the file's contents).

First-run setup¶

The first time an admin signs in to a new install, KubeManta opens a short guided setup instead of the getting-started tour. Every step is optional, and nothing in the product waits for it: Skip setup closes it for good, Go to Workloads leaves it where it is, and it stays under Admin → System → First-run setup (Open setup or Resume setup) to pick up later. Only admins see it; everyone else gets the tour as before. An existing install that is upgraded does not show it on its own.

It covers two kinds of setting:

Settings KubeManta keeps — AI provider, alert notifications, the vulnerability scanner, namespaces, access control, single sign-on, branding and data retention. Each step opens the screen that already holds the setting, and a Continue setup button brings you back. Reinstalling? Start with Import a configuration file: a file exported from your previous install restores all of these at once.
Settings your Helm release owns — how KubeManta is reached (Ingress, a LoadBalancer with TLS terminated in the UI pod, plain LoadBalancer or NodePort), the TLS certificate, workload changes (rbac.allowWrites), Secret read (rbac.readSecrets), Expert Mode (expertMode.enabled) and the volume size (persistence.size). KubeManta cannot change its own release, so it never applies these. It shows what it can see in the cluster — cloud, ingress classes in use, cert-manager, the current volume and permissions — and Generate command writes the exact helm upgrade … --reset-then-reuse-values --set … for you to run, pinned to the version you have installed. When Flux or Argo CD deploys KubeManta, you get the values to commit to Git instead, because a hand-run upgrade would be undone on the next sync.

Looking at the cluster only reads it. Progress is saved as you go, and every change to it is recorded in the audit trail.

Setup¶

Admin → Users & Groups → Users. Create an account, set its role, and share the credentials through whatever channel you normally use — KubeManta does not email them.

If you run SSO, prefer provisioning through your IdP and use local accounts only for break-glass. Local password login can be turned off entirely once SSO works; that switch is one-way from the browser on purpose, and re-enabling it is a pod-side command:

kubectl exec -n kubemanta-system deploy/kubemanta-agent -- \
  python3 -m app.enable_local_login --admin-only

Enabling it is audited, so the recovery leaves a record rather than living only in someone's shell history.

Switching an SSO sign-in method on — SAML, OIDC or LDAP — needs an Enterprise licence. If the licence lapses, the methods that are already on keep working, and you can still edit them or turn SSO off; switching on another method waits until the licence is renewed. Keeping a live SAML method working stays available too: refreshing the identity provider's metadata after it rotates its signing certificate, and generating a new SP certificate, both work while SAML is on, whatever the licence. Local accounts, including viewers, are available on every plan.

Troubleshooting¶

"All N paid seat(s) are in use" when promoting someone. Every paid seat is in use — admins and developers each take one. Make someone who no longer needs to change anything a viewer, or add seats. Nothing else is affected — the person can still sign in as a viewer, and every existing admin and developer keeps working.

A developer is refused an action they expect to have. Check three things: the plan (on Free, or after a lapse, developers act as viewers — the refusal says so); the namespace (developers never act in system or KubeManta namespaces); and, for a pod shell, that an admin has turned Expert Mode on. Deleting a pod with no controller to replace it is also refused — ask an admin.

Someone deactivated can still load a page. Deactivating takes effect on that account's very next request, so there is no cache to wait out. A browser keeps rendering the page it already has; what matters is whether new requests are still being answered. If they are, the account is probably still active — check the row rather than assuming the check failed.

Locked out of everything. One pod-side command fixes every gate at once, because from the login page they are indistinguishable — a forgotten password, a lost authenticator, a deactivated account, an IP ban and disabled password login all produce the same refusal, and working out which is the hard part exactly when you have least patience for it:

printf '%s' "$NEW_PASSWORD" | kubectl exec -i -n kubemanta-system \
    deploy/kubemanta-agent -c agent -- python3 -m app.recover_admin --password-stdin

It recreates the account if it was deleted, resets the password, removes any second factor, reactivates, clears IP bans and re-enables password login. You supply the password — nothing is generated, because a generated password has to be printed and a printed credential outlives its terminal. kubectl exec is the real boundary: whoever has it already owns the database.

The narrower tools remain for when you know exactly which gate is stuck: python3 -m app.clear_bans and python3 -m app.enable_local_login.

Generated from KubeManta 1.5.0 — this page is rendered from the product's own documentation, so it cannot drift from what ships. Manifest built 2026-11-03T12:53:14Z.