From f24e8df1132fad44cbd9867423ca929dc9d93ee0 Mon Sep 17 00:00:00 2001
From: Ashleigh Brennan <abrennan@redhat.com>
Date: Tue, 28 Oct 2025 15:13:46 -0500
Subject: [PATCH] CNV-56853: Add RBAC permissions to allow users to manage VMs
 through the console

rh-pre-commit.version: 2.3.2
rh-pre-commit.check-secrets: ENABLED
---
 ...nfigure-rbac-console-subresources-api.adoc | 151 ++++++++++++++++++
 .../virt-controlling-vm-states.adoc           |   2 +
 2 files changed, 153 insertions(+)
 create mode 100644 modules/virt-configure-rbac-console-subresources-api.adoc

diff --git a/modules/virt-configure-rbac-console-subresources-api.adoc b/modules/virt-configure-rbac-console-subresources-api.adoc
new file mode 100644
index 000000000000..b42b08266f7d
--- /dev/null
+++ b/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
+----
diff --git a/virt/virtual_machines/virt-controlling-vm-states.adoc b/virt/virtual_machines/virt-controlling-vm-states.adoc
index efe8d51d9f82..e128c907c77d 100644
--- a/virt/virtual_machines/virt-controlling-vm-states.adoc
+++ b/virt/virtual_machines/virt-controlling-vm-states.adoc
@@ -10,6 +10,8 @@ You can stop, start, restart, and unpause virtual machines from the web console.
 
 You can use xref:../../virt/getting_started/virt-using-the-cli-tools.adoc#virt-using-the-cli-tools[`virtctl`] to manage virtual machine states and perform other actions from the CLI. For example, you can use `virtctl` to force stop a VM or expose a port.
 
+include::modules/virt-configure-rbac-console-subresources-api.adoc[leveloffset=+1]
+
 include::modules/virt-starting-vm-web.adoc[leveloffset=+1]
 
 include::modules/virt-stopping-vm-web.adoc[leveloffset=+1]