Access Control
Cluster mode (overview) needs its own identity and authorization model — independent of Kubernetes RBAC, and independent of any external system. An access binding is that model: a row in hyve-api’s own datastore (Postgres or SQLite, internal/orgdb — not a Kubernetes object) mapping one external identity to one role, resolved fresh on every authenticated request.
Roles
| Role | Grants |
|---|---|
admin | Full read/write over the API’s resources in its own organization’s namespace |
read-only | Read-only, same namespace scope |
custom | Whatever a custom ServiceAccount you point it at is bound to — for anything the two built-in roles don’t fit |
superadmin | The one intentionally cluster-scoped role — see below |
Users and memberships
A user is one account per person — a username, an email, and a password, all unique across the install. Their access is a set of memberships (bindings): one per organization (and optionally environment) they belong to, each with its own role. One login reaches all of them; see Multi-Tenancy.
Add users from the web console’s Users page, while viewing the organization:
- New user — a username, email, password, and role. They’re emailed that their account exists (send the password separately); the console tells you if that email couldn’t be sent.
- Existing user — just a username and role: someone who already has a login (in another organization) is added here and keeps their own password and email.
Removing a user from an organization removes that membership; their account is deleted once they belong to no organization at all. A user’s email and password are shared by every organization they’re in, so an organization’s admin can only change them for someone who belongs to that organization alone — otherwise only the user or a superadmin can.
From inside the hyve-api pod:
hyve cluster-config api create-user alice --role admin --namespace acmeThis is a real database write, not something kubectl apply -f - can create: it adds alice’s membership in --namespace’s organization (and optionally one of its environments via --env), and creates the user with the given (or interactively-prompted) password — or, for an existing user, sets that as their password. Safe to re-run.
How it’s resolved
Every authenticated request re-resolves the caller’s role from their own binding row, nothing is cached in the session token itself. Change a binding’s role, and the effect is immediate on that user’s next request, not their next login.
What a role actually gets you
The built-in admin/read-only roles each point at a real Kubernetes ServiceAccount (hyve-access-admin/hyve-access-readonly), scoped by a RoleBinding to your own tenant namespace — so an “admin” login is admin of that namespace, never the whole shared cluster.