Docs

Roles

What this screen is for

A role is a job title made of policies. It is the only thing you assign to a user, and it is where permission → policy → role → user becomes visible: roles carry no permissions of their own, they carry policies, and the policies carry the permissions.

Three roles ship with every install — Admin, Developer, DevOps — and you can create as many more as you need.

Before you start

To do this You need
See the tab platform-settings.role.read
Create a role platform-settings.role.create
Edit a role platform-settings.role.update
Delete a role platform-settings.role.delete

Create the policies first. A role with no policies is valid, and grants nothing.

Opening it

  1. Settings › People & Access
  2. Select the Roles tab.

Creating or editing a role opens a full page rather than a dialog: /platform-settings/roles/new and /platform-settings/roles/edit/:roleId.

The interface

📸 Screenshot Placeholder: The role editor page. Mark: (1) the role name field, (2) the description field, (3) the Permission Policies section with its search box, (4) the selected-count line, (5) the Save button.

# Control What it does When you’d use it
1 Role name The name users are assigned by Always
2 Description What the role is for Worth filling in — it is the only place the intent is recorded
3 Policy list with search Selects which policies this role carries The substance of the role
4 Selected count How many policies are attached Sanity-checking before saving
5 Save Writes the role and its policy statements Finishing

The admin role is not a policy bundle

When the role is named admin, the editor replaces the policy list with a notice: the administrator role has automatic full access to all features, permissions, clusters and environments, including any added in future. Assigning admin is not a shortcut for “a lot of access” — it is unscoped, permanent, and grows on its own as the platform grows. Build a scoped role instead.

Walkthroughs

Create a role

Requires platform-settings.role.create.

  1. Settings › People & Access › Roles, click Add Role.
  2. Name it after the job, not the person.
  3. Write a description saying which environments and clusters it is meant to reach. This is the only record of intent, and it is what the next administrator will read.
  4. In Permission Policies, search and select the policies it should carry.
  5. Check the selected count, then Save.

Change what a role grants

Requires platform-settings.role.update.

  1. Open the role from the Roles tab.
  2. Add or remove policies, then save.

Every user holding the role is affected immediately, on their next request — they may need to reload to see menu changes. Editing a widely-held role is the fastest way to change access for many people, and also the easiest way to remove it from people you did not have in mind. Check who holds it first.

Delete a role

Requires platform-settings.role.delete.

Check who holds it before deleting. Users are not deleted with it; they simply lose whatever that role granted.

Scenario

Read-only access for an auditor, for two weeks.

An external auditor needs to see deployments and configuration across staging, and must not be able to change anything.

  1. Policies — create Audit Read, selecting only .read permissions. Scope the statement to the staging cluster and the staging environment.
  2. Roles — create Auditor, description: “Read-only across staging. Temporary — remove after the audit.” Assign only Audit Read.
  3. Users — create the auditor’s account with the Auditor role and the Dev profile.
  4. Verify in Access Explorer that a write permission resolves as denied for them. Do not verify by asking the auditor to try.
  5. After the audit, delete the user. Keep the role — it costs nothing and is ready for the next one.

Resisting the temptation to hand out admin “just for two weeks” is the point of this scenario: admin cannot be scoped, and it silently picks up every cluster added while the auditor still has an account.

When it doesn’t work

Symptom Cause How to check Fix
Role assigned, user still can do nothing The role carries no policies Open the role and read the selected count Attach at least one policy
Role grants more than intended A policy in it is unscoped Open each policy and check resources and conditions Scope the statement to specific clusters and environments
No policy list when editing a role The role is named admin, which has automatic full access The notice in the editor Expected; build a different role for scoped access
Save fails An error is shown at the top of the editor Read the message Fix and retry; nothing is written on failure
Removing a policy did not reduce access Another role the user holds still grants it Access Explorer for that user Check all their roles, not just the one you edited

Next