Skip to content

Commit 96a3cfb

Browse files
jillian-maroketjillian-maroket
authored
Merge pull request #244 from jillian-maroket/communityprs15
Port content from community doc PRs (1015, 1025)
2 parents 33cb652 + f8447f9 commit 96a3cfb

2 files changed

Lines changed: 306 additions & 0 deletions

File tree

‎versions/v1.8/modules/en/nav.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -141,6 +141,7 @@
141141
** Rancher Integration
142142
*** xref:integrations/rancher/rancher-integration.adoc[]
143143
*** xref:integrations/rancher/virtualization-management.adoc[]
144+
*** xref:integrations/rancher/rancher-rbac.adoc[]
144145
// Folder: integrations/rancher/node-driver/
145146
*** Node Driver
146147
**** xref:integrations/rancher/node-driver/node-driver.adoc[]

‎versions/v1.8/modules/en/pages/integrations/rancher/rancher-rbac.adoc‎

Lines changed: 305 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,305 @@
1+
= Rancher Role-Based Access Control
2+
:revdate: 2026-06-08
3+
:page-revdate: {revdate}
4+
5+
[NOTE]
6+
====
7+
The RBAC integration between {harvester-product-name} and {rancher-product-name} is available in {rancher-short-name} 2.14.1 as an experimental feature. While API-level permissions are fully enforced and tested, the UI remains under development. Notably, read-only users may see UI options they lack permissions to execute. {harvester-product-name} will reject any unauthorized actions with "permission denied" errors.
8+
9+
For more information, see GitHub issue https://github.com/harvester/harvester/issues/10241[#10241].
10+
====
11+
12+
{harvester-product-name} provides roles that govern the operational privileges of {rancher-short-name} users. A {rancher-short-name} administrator can assign these roles to team members, ensuring they have the cluster- and project-scoped permissions required for a multi-tenant environment.
13+
14+
These roles are defined using https://documentation.suse.com/cloudnative/rancher-manager/v2.14/en/rancher-admin/users/authn-and-authz/manage-role-based-access-control-rbac/custom-roles.html[role templates] derived from {rancher-short-name}'s built-in roles. They complement the existing {harvester-product-name} and {rancher-short-name} integration model, which seamlessly maps {rancher-short-name} user permissions to {harvester-product-name} resources.
15+
16+
== Installation
17+
18+
The RBAC integration is available as a Helm chart in {rancher-short-name} 2.14.1 and later, accessible directly from the https://documentation.suse.com/cloudnative/rancher-manager/v2.14/en/cluster-admin/helm-charts-in-rancher/helm-charts-in-rancher.html#_access_charts[charts catalog].
19+
20+
. Go to *☰ -> Cluster Management*.
21+
22+
. Locate the `local` cluster, and then click *Explore*.
23+
24+
. In the left navigation menu on the *Cluster Dashboard* screen, select *Apps -> Charts*.
25+
26+
. Search for "Harvester RBAC".
27+
28+
. Follow the on-screen instructions for installing the chart.
29+
30+
Once the chart is installed, the following roles are added to {rancher-short-name}:
31+
32+
|===
33+
| Role | Scope
34+
35+
| *View Virtualization Resources*
36+
| Cluster
37+
38+
| *Manage Virtualization Resources*
39+
| Cluster
40+
41+
| *View Virtualization Resources*
42+
| Project
43+
44+
| *Manage Virtualization Resources*
45+
| Project
46+
|===
47+
48+
You can view the permissions for each role on the *Role Template* screen (*Users & Authentication -> Role Template* -> *Cluster* or *Project* tab).
49+
50+
== Cluster roles
51+
52+
The following cluster-scoped roles are available:
53+
54+
* *View Virtualization Resources*: Provides cluster operators a unified, read-only view of cluster assets. This role automatically inherits the permissions of the built-in "View Cluster Member" role.
55+
56+
* *Manage Virtualization Resources*: Provides advanced users with full management access to all virtualization resources on a {harvester-product-name} cluster. This role automatically inherits the permissions of the built-in "Cluster Member" role.
57+
58+
The default aggregated permissions of these roles do not exceed those of their parent roles. Consequently, users assigned to these roles lack permissions to view or modify guest clusters they do not own. They also cannot modify global settings, such as {rancher-short-name} membership or node driver configuration.
59+
60+
|===
61+
| Object | *View Virtualization Resources* Role | *Manage Virtualization Resources* Role
62+
63+
| Workload resources (virtual machines, images, volumes, StorageClasses, and others)
64+
| View only
65+
| Modify
66+
67+
| Backup, restore, and snapshot resources
68+
| View only
69+
| Modify
70+
71+
| Infrastructure resources (hosts, disks, networks, and others)
72+
| View only
73+
| Modify
74+
75+
| Host devices (PCI, SR-IOV, vGPU, and others)
76+
| View only
77+
| Modify
78+
79+
| SSH keys, templates, and secrets
80+
| View only
81+
| Modify
82+
83+
| Projects and namespaces
84+
| View only
85+
| Modify
86+
87+
| Advanced cluster settings
88+
| View only
89+
| Modify
90+
91+
| Cluster membership
92+
| View only
93+
| Modify
94+
95+
| Project membership
96+
| View only
97+
| Modify
98+
99+
| Cluster and workload metrics
100+
| View only
101+
| View only
102+
103+
| Support bundles
104+
| Generate
105+
| Generate
106+
107+
| Cluster operating system
108+
| No access
109+
| Upgrade
110+
|===
111+
112+
Users with these roles _cannot_ perform the following actions:
113+
114+
* Access and modify resources in {harvester-product-name} clusters where they lack membership
115+
* Access and modify global {rancher-short-name} settings associated with membership, node driver configuration, and others
116+
117+
=== Assigning cluster roles
118+
119+
An administrator can add users to a {harvester-product-name} cluster using the *Virtualization Management* screen.
120+
121+
. Go to *☰ -> Virtualization Management*.
122+
123+
. Locate the target {harvester-product-name} cluster, and then click *Edit Config*.
124+
125+
. In the *Member Roles* section, click *Add*.
126+
127+
. In the *Member* list, select the target user.
128+
129+
. In the *Cluster Permissions* section, select an appropriate cluster role, and then click *Add*.
130+
131+
Alternatively, administrators can assign cluster roles during the import process. When importing a {harvester-product-name} cluster into {rancher-short-name}, user roles can be configured in the *Member Roles* section of the cluster creation screen.
132+
133+
== Project roles
134+
135+
The following project-scoped roles are available:
136+
137+
* *View Virtualization Resources*: Provides users a unified, read-only view of specific projects in {harvester-product-name}. This role automatically inherits the built-in "Read-Only" role.
138+
139+
* *Manage Virtualization Resources*: Inherits the permissions of the built-in "Project User" role.
140+
141+
Their default aggregated permissions do not exceed those of their parent roles. Consequently, these roles lack permissions to access resources in other projects on the same {harvester-product-name} cluster. They also cannot view or modify guest clusters that the users do not own.
142+
143+
|===
144+
| Object | *View Virtualization Resources* Role | *Manage Virtualization Resources* Role
145+
146+
| Virtualization resources within the project
147+
| View only
148+
| Modify
149+
150+
| SSH keys, templates, and secrets within the project
151+
| View only
152+
| Modify
153+
154+
| Namespaces within the project
155+
| View only
156+
| Modify
157+
158+
| Project membership
159+
| No access
160+
| No access
161+
162+
| Infrastructure resources
163+
| No access
164+
| No access
165+
166+
| Host devices (PCI, SR-IOV, vGPU, and others)
167+
| No access
168+
| No access
169+
170+
| Monitoring metrics
171+
| No access
172+
| No access
173+
|===
174+
175+
=== Assigning project roles
176+
177+
An administrator can add users to specific projects in {harvester-product-name} using the *Virtualization Management* screen.
178+
179+
. Go to *☰ -> Virtualization Management*.
180+
181+
. Locate the {harvester-product-name} cluster, and then click its name to access the {harvester-product-name} UI.
182+
183+
. Go to *Projects/Namespaces*.
184+
185+
. Locate the project, and then click *Edit Config*.
186+
187+
. In the *Members* section, click *Add*.
188+
189+
. In the *Member* list, locate the target user.
190+
191+
. In the *Cluster Permissions* section, select an appropriate cluster role, and then click *Add*.
192+
193+
== Adding new permissions
194+
195+
If the permissions provided by these roles are insufficient for your requirements, you can extend their scope by creating custom roles that inherit from the existing ones and include additional permissions.
196+
197+
[CAUTION]
198+
====
199+
Because the permission scopes of roles are additive, a user assigned multiple roles receives the combined permissions of all of them. When creating custom roles and appending permissions, carefully review the configuration to prevent unintentional privilege escalation.
200+
====
201+
202+
Example:
203+
204+
{harvester-product-name} does not allow non-administrators to create or modify logging output resources for security reasons. Only administrators and system service accounts can modify these resources. To allow specific cluster operators to manage logging resources, you can create a custom role that inherits from the *Manage Virtualization Resources* cluster role and append the necessary permissions to it.
205+
206+
. Go to *☰ -> Users & Authentication -> Role Template*.
207+
208+
. On the *Cluster* tab, click *Create Cluster Role*.
209+
210+
. Configure the following settings:
211+
+
212+
** *Name*: "Manage Logging Resources"
213+
** *Description*: "Cluster role for managing {harvester-product-name} logging output resources"
214+
** **Grant Resources**:
215+
*** *Verbs*: "*""
216+
*** *Resource*: "*""
217+
*** *API Groups*: "logging.banzaicloud.io"
218+
** *Inherit From*: "Manage Virtualization Resources"
219+
220+
. Click *Create*.
221+
222+
Assign this new role to the cluster operators who need to manage logging resources. They will inherit all privileges of the *Manage Virtualization Resources* role plus the additional permissions required for logging administration.
223+
224+
=== Custom settings
225+
226+
The {harvester-product-name}-{rancher-short-name} RBAC Helm chart also provides the following custom settings that enable you to append permissions to the existing roles:
227+
228+
|===
229+
| Role | Scope | Setting
230+
231+
| *View Virtualization Resources*
232+
| Cluster
233+
| `clusterRole.virtClusterView`
234+
235+
| *Manage Virtualization Resources*
236+
| Cluster
237+
| `clusterRole.virtClusterManage`
238+
239+
| *View Virtualization Resources*
240+
| Project
241+
| `projectRole.virtProjectView`
242+
243+
| *Manage Virtualization Resources*
244+
| Project
245+
| `projectRole.virtProjectManage`
246+
|===
247+
248+
For example, to allow _all_ users with the cluster-scoped *Manage Virtualization Resources* role to manage logging resources, you can add the following permissions to the `clusterRole.virtClusterManage` chart value:
249+
250+
[,yaml]
251+
----
252+
clusterRole:
253+
virtClusterManage:
254+
additionalRules:
255+
- apiGroups: ["logging.banzaicloud.io"]
256+
resources: ["*"]
257+
verbs: ["*"]
258+
----
259+
260+
[IMPORTANT]
261+
====
262+
Permissions added through Helm chart values apply to all users that were assigned that role. Ensure that the additional permissions align with the intended scope of the role.
263+
264+
Resources in the `default` and `harvester-public` namespaces are accessible to all cluster and project members.
265+
====
266+
267+
== Guest cluster permissions
268+
269+
By default, users only have access to guest clusters they own, allowing them to view and modify resources within those specific clusters.
270+
271+
|===
272+
| Role | Scope | Guest Cluster Creation
273+
274+
| *View Virtualization Resources*
275+
| Cluster
276+
| Not allowed
277+
278+
| *Manage Virtualization Resources*
279+
| Cluster
280+
| Allowed in any project on the {harvester-product-name} cluster
281+
282+
| *View Virtualization Resources*
283+
| Project
284+
| Not allowed
285+
286+
| *Manage Virtualization Resources*
287+
| Project
288+
| Allowed only within projects where membership is held
289+
|===
290+
291+
A {rancher-short-name} administrator can add users as members of existing guest clusters.
292+
293+
. Go to *☰ -> Cluster Management*.
294+
295+
. Locate the target guest cluster, and then click *Edit Config*.
296+
297+
. In the *Member Roles* section, click *Add*.
298+
299+
. In the *Member* list, select the target user.
300+
301+
. In the *Cluster Permissions* section, select an appropriate role, and then click *Add*.
302+
303+
== Support bundle permissions
304+
305+
Only cluster-scoped users can generate support bundles. Project-scoped users lack the necessary permissions because the controller requires access to system namespaces and underlying hosts for data collection. Granting project users access to these system namespaces and hosts introduces significant security risks.

0 commit comments

Comments
 (0)