Cluster and Project Roles

The projects and clusters accessible to non-administrative users is determined by membership. Membership is a list of users who have access to a specific cluster or project based on the roles they were assigned in that cluster or project. Each cluster and project includes a tab that a user with the appropriate permissions can use to manage membership.

When you create a cluster or project, Rancher automatically assigns you as the Owner for it. Users assigned the Owner role can assign other users roles in the cluster or project.

Cluster roles are roles that you can assign to users, granting them access to a cluster. There are two primary cluster roles: Owner and Member.

After an administrator sets up a custom cluster role, cluster owners and admins can then assign those roles to cluster members.

To assign a custom role to a new cluster member, you can use the Rancher UI. To modify the permissions of an existing member, you will need to use the Rancher API view.

To assign the role to a new cluster member,

Result: The member has the assigned role.

To assign any custom role to an existing cluster member,

Result: The member has the assigned role.

Project roles are roles that can be used to grant users access to a project. There are three primary project roles: Owner, Member, and Read Only.

As previously mentioned, custom roles can be defined for use at the cluster or project level. The context field defines whether the role will appear on the cluster member page, project member page, or both.

When defining a custom role, you can grant access to specific resources or specify roles from which the custom role should inherit. A custom role can be made up of a combination of specific grants and inherited roles. All grants are additive. This means that defining a narrower grant for a specific resource will not override a broader grant defined in a role that the custom role is inheriting from.

By default, when a standard user creates a new cluster or project, they are automatically assigned an ownership role: either cluster owner or project owner. However, in some organizations, these roles may overextend administrative access. In this use case, you can change the default role to something more restrictive, such as a set of individual roles or a custom role.

There are two methods for changing default cluster/project roles:

You can change the cluster or project role(s) that are automatically assigned to the creating user.

Result: The default roles are configured based on your changes. Roles assigned to cluster/project creators display a check in the Cluster/Project Creator Default column.

If you want to remove a default role, edit the permission and select No from the default roles option.

When you revoke the cluster membership for a standard user that’s explicitly assigned membership to both the cluster and a project within the cluster, that standard user loses their cluster roles but retains their project roles. In other words, although you have revoked the user’s permissions to access the cluster and its nodes, the standard user can still:

If you want to completely revoke a user’s access within a cluster, revoke both their cluster and project memberships.

In Rancher v2.9.0 and later, external RoleTemplate objects can only be created if the backing ClusterRole exists in the local cluster or the ExternalRules is set in your configuration.

For context, the backing ClusterRole holds cluster rules and privileges, and shares the same metadata.name used in the RoleTemplate in your respective cluster referenced by the ClusterRoleTemplateBinding/ProjectRoleTemplateBinding. Additionally, note that escalate permissions on RoleTemplates are required to create external RoleTemplates with ExternalRules.