Access Management

Description

Access management uses the RBAC (Role-Based Access Control) model — a model based on user roles. Instead of each user receiving an individual set of permissions, access rights are grouped into roles, and users gain access based on their roles.

How RBAC Works

1. Defining Roles: Roles are defined to correspond to different duties and functions within the system.
2. Defining Permissions for Roles: Permissions that should be granted to each role are defined.
3. Assigning Roles to Users: Users are assigned roles corresponding to their duties and functions.
4. Access Control: The system uses the role model to control access to resources based on the roles assigned to users.

Glossary

• Users — user accounts in the Deckhouse Commander database.
• Groups — group accounts in the Deckhouse Commander database.
• Service accounts — machine accounts for the Integration API. See Service Accounts.
• Roles — define a list of allowed actions on certain types of resources.
• Bindings — link roles to users, groups, or service accounts.
• Resources — Deckhouse Commander objects to which access permissions can be applied.
• Permissions — describe specific actions that can be performed on resources.

Supported Deckhouse Commander Resources

• users — Users
• groups — Groups
• globalroles — Global roles
• globalrolebindings — Global bindings
• globalserviceaccounts — Global service accounts
• workspaces — Workspaces
• workspaceroles — Workspace roles
• workspacerolebindings — Workspace role bindings
• workspaceserviceaccounts — Workspace service accounts
• clusters — Clusters
• changerequests — Cluster change requests
• clustertemplates — Cluster templates
• publicclustertemplates — Publishing cluster template versions; this resource can be granted only by a global role
• catalogs — Inventory
• projects — Projects
• projectrolebindings — Project member bindings
• billingdashboard — Billing: dashboard and analytics
• billingtariffs — Billing: tariff management
• billingresources — Billing: management of compute classes and storage classes
• billingreports — Billing: reports management
• billingaccounts — Billing: personal accounts management
• billingtransactions — Billing: personal account transactions (top-up, deduction, and history)

Read-Only

• workspaceroles/audit — Workspace roles change history
• workspacerolebindings/audit — Workspace bindings change history
• globalserviceaccounts/audit — Global service accounts change history
• workspaceserviceaccounts/audit — Workspace service accounts change history
• clusters/audit — Clusters change history
• clustertemplates/audit — Templates change history
• catalogs/audit — Inventory change history
• projects/audit — Projects change history
• billingaccounts/audit — Billing accounts change history: records of a workspace’s billing account being changed

Roles and Bindings

Global roles and bindings operate at the global level for all Deckhouse Commander resources, and Kubernetes resources are created in all clusters managed by Deckhouse Commander. For each role, a ClusterRole with specified Kubernetes rules is created, and for each binding, a ClusterRoleBinding is created. Resources are translated with the prefix d8:commander:. For example, the viewer role is created in all clusters as ClusterRole/d8:commander:viewer. The same rule applies to role bindings and their corresponding ClusterRoleBinding resource.

Workspace roles and bindings operate at the level of a specific workspace, and Kubernetes resources are created in all clusters of that workspace. For each role, a ClusterRole with specified Kubernetes rules is created, and for each binding, a ClusterRoleBinding is created. Workspace-level resources are translated with the prefix d8:commander:workspace:, e.g., the viewer role is created in all workspace clusters as ClusterRole/d8:commander:workspace:viewer. The same rule applies for workspace role bindings and the corresponding ClusterRoleBinding resource.

In clusters, a special resource group “Access Rights” is created, which is automatically populated with the current roles and bindings (both global and workspace level). These manifests — ClusterRole and ClusterRoleBinding — are kept up to date in the clusters by an agent (commander-agent module). All role bindings, changes, and deletions in clusters are updated automatically. The platform interface (Cluster → “Administration” tab) adapts according to the user’s permissions in that cluster.

UI

Global Permissions Settings Panel

This page is accessible from the Workspaces panel (/workspaces) by selecting the “Users and Permissions” menu item in the header.

• “Users” tab — view the list of users and their groups registered in Deckhouse Commander
• “Groups” tab — view the list of groups and their members registered in Deckhouse Commander
• “Service accounts” tab — management of global service accounts and their API keys
• “Roles” tab — role management
• “Bindings” tab — bindings management

Workspace Permissions Settings Panel

This page is accessible from the “Users and Permissions” menu item in the header inside a workspace.

Content is similar to the Global Permissions Settings Panel, but for the users and groups of the workspace. The “Service accounts” tab lists the workspace service accounts of this workspace; global service accounts are shown only in the global panel, even when they are bound to a role in this workspace.

Configuration

Requirements for Access Management in Deckhouse Commander

• Configured integration with an external IdP via dex-provider on the management cluster.
• A role and binding¹ created for a user or group in the Deckhouse Commander interface.
• User logged in via Dex.

For access to application clusters, Deckhouse Commander reuses the same identity — see Authentication in application clusters via DexProvider for how the trust link is established and which resources are managed automatically.

Initial Access Setup

On a fresh installation, when no administrators have been assigned yet, Deckhouse Commander automatically redirects the first authenticated user to the initial access setup page (/bootstrap). The page asks for the initial setup token — a one-time, time-limited value generated at deployment and stored in the bootstrap-token secret in the d8-commander namespace.

To read the token value, run:

d8 k -n d8-commander get secret bootstrap-token -o jsonpath='{.data.token}' | base64 -d

Alternatively, open the secret in the DKP web interface. Enter the token value on the setup page and click “Get access”. Administrator rights are granted immediately, and the token is invalidated after use.

After this, you can proceed to configure access permissions via the web interface.

Restoring Lost Administrator Access

If all administrator access to Deckhouse Commander is lost (for example, due to an IdP change or accidental role deletion), restore access using the initial setup token:

1. Delete the bootstrap-token secret in the d8-commander namespace:

   d8 k -n d8-commander delete secret bootstrap-token

2. Deckhouse Commander generates a new token and restarts automatically.

3. Read the new token value and open /bootstrap in the Deckhouse Commander web interface.

4. Enter the token and click “Get access”. Administrator rights are restored, and the token is invalidated.

Configuring Access Permissions in Deckhouse Commander Web Interface

To configure permissions, follow these steps:

1. Open the permissions settings panel.
2. Go to the “Roles” tab and create a role:
   1. Click the “Add Global Role” button.
   2. Specify the unique role name and description.
   3. Click “Add Deckhouse Commander Rule”.
   4. Specify permissions and resources.
   5. Optionally create multiple rules.
   6. Click “Save”.
3. Go to the “Bindings” tab and create a binding:
   1. Click the “Add Global Binding” button.
   2. Specify a name or enable the “Generate from role” toggle (which generates a name from the role plus a random string).
   3. Select a role.
   4. Select users or groups. If a user or group does not exist in Deckhouse Commander yet, you can specify them manually as user:<login> / group:<name>.
   5. Click “Save”.

Permissions have been applied.

Service Accounts

A service account is a machine identity for the Integration API. It is a binding subject, exactly like a user or a group, and it receives permissions only from the roles bound to it. Requests are authenticated with API keys that belong to the account: a key proves which account is calling and carries no permissions, scope, or mode of its own.

Deckhouse Commander supports two kinds of service accounts:

A workspace service account never leaves its workspace: it is not listed outside it, it cannot be given a global binding or a binding in another workspace, and its keys work only against the resources of that workspace. Access to all current and future workspaces is granted by a global binding of a global service account.

An account name is immutable and follows the DNS label format: 3 to 63 characters, lowercase Latin letters, digits, and hyphens, starting and ending with a letter or a digit. Names starting with migrated-token- are reserved for accounts created by the migration of access tokens. Names of different subject kinds do not conflict with each other, and neither do the names of workspace service accounts in different workspaces.

Service Accounts as Binding Subjects

In the role binding form, service accounts are selected in the same field as users and groups. Pick an account from the list, or type serviceaccount:<NAME>, where <NAME> is the exact account name. The list shows the account kind, so accounts of both kinds with the same name can be told apart; if a typed name matches more than one account, select the intended one from the list.

• A global binding accepts only global service accounts.
• A workspace binding accepts global service accounts and the workspace service accounts of that workspace.
• A binding accepts only an account that already exists — it never creates one implicitly.

All keys of an account get the same permissions: the union of the roles bound to the account. Revoking a key, removing a binding, and deleting an account take effect from the next request.

Permissions for Managing Service Accounts

Managing accounts and their keys is available only in the web interface and is not published in the Integration API, so a service account cannot issue keys for itself.

The globalserviceaccounts and globalserviceaccounts/audit resources are global by nature: permissions for them are granted only by a global binding. A workspace binding never grants them, even when it names those resources.

Deleting a Service Account

Deleting an account archives it, revokes all of its active keys, and removes it from every binding it was a subject of. The action is irreversible: requests with the old keys stop working immediately.

The name of a deleted account can be used again. A new account with the same name is a new identity: it does not inherit the roles of the deleted one, and the change history keeps both records separately.

Deleting a workspace deletes its workspace service accounts along with their keys and bindings.

Service Accounts and Project Access

A service account manages projects through the Deckhouse Commander resources projects and projectrolebindings, using the same verbs as a user. Two boundaries apply:

• A service account does not become a project member. ProjectRoleBinding accepts only users and groups, so a service account with permissions on projectrolebindings changes the membership of other subjects but is never a subject itself.
• A service account gets no access to the resources inside a project’s cluster. For workloads, use a Kubernetes ServiceAccount of the project.

Project Access Management

Access management in Deckhouse Commander projects is organised on two levels:

1. Global Deckhouse Commander roles define permissions over projects as Deckhouse Commander resources: access to the “Projects” section, creating, updating, and deleting projects, managing project members.
2. Project-level roles define permissions over project resources in the target cluster. Bindings are translated into the AuthorizationRule manifest, which is applied in the cluster by the multitenancy-manager module as part of project resources.

Deckhouse Commander Resources for Managing Projects

The following entries are part of the list of supported resources:

• projects — projects.
• projectrolebindings — project member bindings. Access to managing projectrolebindings of a specific project is checked against the user’s membership in the Admin role of that project, not only against the global role.

The “Projects” section is shown in the web interface only to users who have at least the get verb on the projects resource and only when the projects feature is enabled in Deckhouse Commander.

Preset Global Roles

Deckhouse Commander ships two preset global roles for working with projects:

• autogenerated-projects-user — a role with the rule verbs: ["get"], resources: ["projects"]. Automatically granted to a user added to at least one project via the single workspace-level binding autogenerated-projects-users. It grants access to the “Projects” section and to project pages, but does not allow creating, updating, or deleting projects, nor managing members of projects where the user is not an Admin. The role and its binding are enforced by Deckhouse Commander: if deleted manually, they are recreated the next time a user is added to any project.
• projects-admin — a role with the rule verbs: ["*"], resources: ["projects"]. Intended for users who create, update, and delete projects. Assigned manually by a system administrator in the “Users and Permissions” section.

For finer-grained control, a system administrator can create custom global roles with arbitrary combinations of verbs on the projects and projectrolebindings resources.

Project Visibility in the List

The set of projects visible to a user in the list is determined by their permissions on the projects resource:

Billing Account Holders

Deckhouse Commander ships a preset global role for working with billing accounts:

• billing-account-user — a role with the single rule verbs: ["get"], resources: ["billingaccounts", "billingtransactions", "billingdashboard"] (read-only). Automatically granted to a user or group added as a holder of a specific billing account in the account form (the “Holders” field), via the single global binding autogenerated-billing-account-users that aggregates holders of all accounts. The role and its binding are enforced by Deckhouse Commander: if deleted manually, they are recreated the next time a holder is assigned to any account. The role’s rule set is authoritative — when the set of permissions changes in a new version, the outdated rule is removed instead of being kept alongside the new one.

Visibility of billing accounts and their transactions is determined by permissions on the billingaccounts/billingtransactions resources:

The billingdashboard permission in this role is narrowed by the same membership: a billing account holder sees dashboard data only for the workspaces of their own accounts.

The list of workspaces not linked to any billing account is available only to those who can create accounts (the create permission on billingaccounts): they are the ones who perform the linking, and the list does not expose other people’s workspaces to a billing account holder.

Billing account holders are assigned in the account form (create/edit), the “Holders” field. Removing the last holder revokes the corresponding access.

Project-Level Roles

Each project exposes four preset roles. Their names in Deckhouse Commander match the spec.accessLevel values in the AuthorizationRule manifest that Deckhouse Commander generates for each role:

The set of Kubernetes resources and actions corresponding to each accessLevel is defined by the user-authz module.

For each project-level role, Deckhouse Commander creates a dedicated AuthorizationRule in the target cluster (admins, editors, privileged-users, users). Members are listed in spec.subjects[]. Manifests are delivered by the Deckhouse Commander agent.

Separation of Duties

• System administrator manages project settings on the “Configuration” tab of the project page, including the “Administrators” field.
• Project administrator (a user in the Admin role) manages User, PrivilegedUser, and Editor bindings on the “Accesses” tab of the project page. Admin bindings are shown on that tab in read-only mode and are changed on the “Configuration” tab.
• Users in the Editor, PrivilegedUser, or User role do not see the “Accesses” tab.

If one user combines both functions (for example, a system administrator is also assigned as Admin of a project), both tabs are available in the interface.

Maintenance of the autogenerated-projects-users Binding

When a user is added to any project, Deckhouse Commander adds them as a subject of the single workspace-level binding autogenerated-projects-users. One such binding is created per workspace and aggregates members of all projects of that workspace.

When a user is removed from a project, their subject is not removed from autogenerated-projects-users automatically, so that users who remain members of other projects do not lose access. If needed, a system administrator can remove the subject manually in the “Users and Permissions” section. If the autogenerated-projects-users binding is deleted entirely, it is recreated the next time a user is added to any project of the workspace.

Validation

• A project must have at least one administrator (the Admin role): the last Admin binding cannot be removed.
• If a user is a member through multiple paths (several groups, or a group and a direct assignment), the effective permissions in the cluster are determined by the user-authz module by priority: Admin > Editor > PrivilegedUser > User.

Limitations

• Projects of kind deckhouse are DKP projects created directly in the target cluster and not managed by Deckhouse Commander. They appear in the project list with a dedicated icon. For such projects, the Deckhouse Commander web interface does not provide an edit form or an “Accesses” tab — these projects are managed directly in Deckhouse using the multitenancy-manager module, including through the AuthorizationRule manifest.
• In this version, project membership and the preset roles (autogenerated-projects-user, projects-admin) can be managed only through the Deckhouse Commander web interface.

Cluster Creation Approval

When cluster creation approval is enabled for a workspace, installing a cluster produces an approval request that someone has to approve or reject. Access to these requests is governed by the changerequests resource, which is part of the list of supported resources and works at the workspace level.

Preset Role and Binding

Deckhouse Commander ships a preset role for deciding on cluster creation approval requests:

• cluster-change-approver — a role with the rules verbs: ["get", "update"], resources: ["changerequests"] and verbs: ["get"], resources: ["clusters"]. It is automatically assigned through the workspace-level binding autogenerated-cluster-change-approvers to the users and groups selected as approvers on the workspace “Parameters” page. Any member of an assigned group can approve a request.

The role and its binding are enforced by Deckhouse Commander when approvers are saved: being selected as an approver automatically grants the required permissions, and removing a user or group from the list revokes them. This is the standard way to appoint an approver — the permissions and the appointment are the same act, and no separate manual grant is needed.

The list of approvers is edited on the workspace “Parameters” page, in the section for cluster creation approval. That section is governed by the workspacerolebindings resource: get to see it, update to change it. The same binding can also be edited through the regular bindings editor — it is the same list of subjects.

Only users and groups can be approvers. A service account cannot decide on a request: the Integration API refuses approval-flow requests outright.

Approvers Granted by Another Role

The permission is the appointment: any role with update on changerequests makes its subjects approvers, not only the preset one. The “Approvers” field reflects that — it is built from the permissions, not from a single binding:

• subjects of the autogenerated-cluster-change-approvers binding are shown as editable entries;
• subjects that hold the right through another workspace role are shown as non-removable entries with a hint naming the role. Revoke them in access management, not in this field;
• of those, only subjects present in the workspace’s “Users” and “Groups” lists are shown, so approvers of other workspaces never leak into the field;
• global role bindings are not shown at all. They grant the right just the same, so a global role with update on changerequests makes its subjects approvers in every workspace, invisibly to this field.

Because subjects from another role already hold the permission, the section allows saving with an empty own list when at least one of them exists — the workspace still has an approver.

Self-Approval and Read-Only Access

• An initiator who holds update on changerequests can approve their own request. An initiator without that permission cannot: the attempt is rejected.
• A user with only get on changerequests is an observer — they see the queue and the counter, but no decision buttons.
• Approvers do not need permissions to modify clusters. Reviewing a configuration requires get on clusters, which the preset role includes. A user who is an approver but has no update on clusters can approve an installation, but cannot edit the cluster configuration and does not get the manual-mode confirmation button on the cluster page — that one requires update on clusters.

Audit

All role and binding changes are logged. Information is available in the “Change History” tab at the workspace level.