CNV-56853: Add RBAC permissions to allow users to manage VMs through the web console

modules/virt-configure-rbac-console-subresources-api.adoc

@@ -0,0 +1,151 @@
+// Module included in the following assemblies:
+//
+// * virt/managing_vms/virt-controlling-vm-states.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="virt-configure-rbac-console-subresources-api_{context}"]
+= Configuring RBAC permissions for managing VM states by using the web console
+
+[role="_abstract"]
+To allow users to manage virtual machine (VM) states by using the {product-title} web console, you must create an RBAC cluster role and cluster role binding.
+The cluster role uses the `subresources.kubevirt.io` API to define which resources can be controlled by certain users or groups.
+
+.Prerequisites
+
+* You have cluster administrator access to an {product-title} cluster where {VirtProductName} is installed.
+* You have installed the {oc-first}.
+
+.Procedure
+
+. Create a `ClusterRole` object that allows the target user or group to manage VM states:
++
+[source,yaml]
+----
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: vm-manager-access
+rules:
+  - apiGroups:
+      - subresources.kubevirt.io
+    resources:
+      - virtualmachines/start
+      - virtualmachines/stop
+    verbs:
+      - put
+# ...
+----
+
+. Run the following command to apply the cluster role:
++
+[source,terminal]
+----
+$ oc apply -f <filename>.yaml
+----
+
+. Confirm that the cluster role was created by running the following command and observing the output:
++
+[source,terminal]
+----
+$ oc get clusterrole <name>
+----
++
+Example output:
++
+[source,terminal]
+----
+NAME                AGE
+vm-manager-access   15s
+----
+
+. Inspect the details of the cluster role, and ensure the intended rules for `subresources.kubevirt.io` are present, specifically the `virtualmachines/start` and `virtualmachines/stop` subresources.
++
+Run the following command and observe the output:
++
+[source,terminal]
+----
+$ oc describe clusterrole <name>
+----
++
+Example output:
++
+[source,terminal]
+----
+Name:         vm-manager-access
+Labels:       <none>
+Annotations:  <none>
+PolicyRule:
+  Resources  Non-Resource URLs  Resource Names  Verbs
+  ---------  -----------------  --------------  -----
+  virtualmachines/start, virtualmachines/stop with subresources.kubevirt.io group  []  []  [put]
+----
+
+. Create a `ClusterRoleBinding` object to bind the cluster role you have created to the target user or group:
++
+[source,yaml,subs="attributes+"]
+----
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  name: vm-manager-access-binding
+subjects:
+  - kind: User
+    name: test-user
+    apiGroup: rbac.authorization.k8s.io
+roleRef:
+  kind: ClusterRole
+  name: vm-manager-access
+  apiGroup: rbac.authorization.k8s.io
+----
+
+. Run the following command to apply the cluster role binding:
++
+[source,terminal]
+----
+$ oc apply -f <filename>.yaml
+----
+
+. Confirm that the cluster role binding was created by running the following command and observing the output:
++
+[source,terminal]
+----
+$ oc get clusterrolebinding <name>
+----
++
+Example output:
++
+[source,terminal]
+----
+NAME                        AGE
+vm-manager-access-binding   15s
+----
+
+.Verification
+
+. Check if the user can start a VM by running the following command:
++
+[source,terminal]
+----
+$ oc auth can-i update virtualmachines/start --namespace=<namespace> --as=<user_name> --subresource=subresources.kubevirt.io
+----
++
+Example output:
++
+[source,terminal]
+----
+yes
+----
+
+. Check if the user can stop a VM by running the following command:
++
+[source,terminal]
+----
+$ oc auth can-i update virtualmachines/stop --namespace=<namespace> --as=<user_name> --group=subresources.kubevirt.io
+----
++
+Example output:
++
+[source,terminal]
+----
+yes
+----

virt/managing_vms/virt-controlling-vm-states.adoc

@@ -10,6 +10,8 @@ You can use xref:../../virt/getting_started/virt-using-the-cli-tools.adoc#virt-u
 
 You can stop, start, restart, pause, and unpause virtual machines from the web console.
 
+include::modules/virt-configure-rbac-console-subresources-api.adoc[leveloffset=+1]
+
 include::modules/virt-enable-vm-action-confirmation-web.adoc[leveloffset=+1]
 
 include::modules/virt-starting-vm-web.adoc[leveloffset=+1]