From aab28831f467fb7d56e948c8784b5adb1113fc83 Mon Sep 17 00:00:00 2001 From: Pan Ousley Date: Mon, 9 Jun 2025 00:59:59 -0400 Subject: [PATCH] CNV#54829: new default live migration permissions --- ...virt-about-live-migration-permissions.adoc | 15 ++++ modules/virt-canceling-vm-migration-cli.adoc | 1 + modules/virt-canceling-vm-migration-web.adoc | 4 + modules/virt-default-cluster-roles.adoc | 6 +- ...t-granting-live-migration-permissions.adoc | 37 +++++++++ modules/virt-initiating-vm-migration-cli.adoc | 1 + modules/virt-initiating-vm-migration-web.adoc | 5 +- modules/virt-preserving-lm-perms.adoc | 81 +++++++++++++++++++ .../virt-about-live-migration.adoc | 8 ++ .../virt-initiating-live-migration.adoc | 8 +- .../virt-hot-plugging-network-interfaces.adoc | 1 + 11 files changed, 163 insertions(+), 4 deletions(-) create mode 100644 modules/virt-about-live-migration-permissions.adoc create mode 100644 modules/virt-granting-live-migration-permissions.adoc create mode 100644 modules/virt-preserving-lm-perms.adoc diff --git a/modules/virt-about-live-migration-permissions.adoc b/modules/virt-about-live-migration-permissions.adoc new file mode 100644 index 0000000000..6d759739aa --- /dev/null +++ b/modules/virt-about-live-migration-permissions.adoc @@ -0,0 +1,15 @@ +// Module included in the following assemblies: +// +// * virt/live_migration/virt-about-live-migration.adoc + +:_mod-docs-content-type: CONCEPT +[id="virt-about-live-migration-permissions_{context}"] += About live migration permissions + +In {VirtProductName} 4.19 and later, live migration operations are restricted to users who are explicitly granted the `kubevirt.io:migrate` cluster role. Users with this role can create, delete, and update virtual machine (VM) live migration requests, which are represented by `VirtualMachineInstanceMigration` (VMIM) custom resources. + +Cluster administrators can bind the `kubevirt.io:migrate` role to trusted users or groups at either the namespace or cluster level. + +Before {VirtProductName} 4.19, namespace administrators had live migration permissions by default. This behavior changed in version 4.19 to prevent unintended or malicious disruptions to infrastructure-critical migration operations. + +As a cluster administrator, you can preserve the old behavior by creating a temporary cluster role before updating. After assigning the new role to users, delete the temporary role to enforce the more restrictive permissions. If you have already updated, you can still revert to the old behavior by aggregating the `kubevirt.io:migrate` role into the `admin` cluster role. diff --git a/modules/virt-canceling-vm-migration-cli.adoc b/modules/virt-canceling-vm-migration-cli.adoc index af7c0f5873..2af604b0de 100644 --- a/modules/virt-canceling-vm-migration-cli.adoc +++ b/modules/virt-canceling-vm-migration-cli.adoc @@ -12,6 +12,7 @@ Cancel the live migration of a virtual machine by deleting the .Prerequisites * You have installed the {oc-first}. +* You have the `kubevirt.io:migrate` RBAC role or you are a cluster administrator. .Procedure diff --git a/modules/virt-canceling-vm-migration-web.adoc b/modules/virt-canceling-vm-migration-web.adoc index 4a563f2ec7..da819b6043 100644 --- a/modules/virt-canceling-vm-migration-web.adoc +++ b/modules/virt-canceling-vm-migration-web.adoc @@ -8,6 +8,10 @@ You can cancel the live migration of a virtual machine (VM) by using the {product-title} web console. +.Prerequisites + +* You have the `kubevirt.io:migrate` RBAC role or you are a cluster administrator. + .Procedure . Navigate to *Virtualization* -> *VirtualMachines* in the web console. diff --git a/modules/virt-default-cluster-roles.adoc b/modules/virt-default-cluster-roles.adoc index 97e995003b..3729450b1e 100644 --- a/modules/virt-default-cluster-roles.adoc +++ b/modules/virt-default-cluster-roles.adoc @@ -6,7 +6,7 @@ [id="default-cluster-roles-for-virt_{context}"] = Default cluster roles for {VirtProductName} -By using cluster role aggregation, {VirtProductName} extends the default {product-title} cluster roles to include permissions for accessing virtualization objects. +By using cluster role aggregation, {VirtProductName} extends the default {product-title} cluster roles to include permissions for accessing virtualization objects. Roles unique to {VirtProductName} are not aggregated with {product-title} roles. .{VirtProductName} cluster roles [cols="1,1,4",options="header"] @@ -26,4 +26,8 @@ By using cluster role aggregation, {VirtProductName} extends the default {produc .^| `admin` .^|`kubevirt.io:admin` | A user that has full permissions to all {VirtProductName} resources, including the ability to delete collections of resources. The user can also view and modify the {VirtProductName} runtime configuration, which is located in the `HyperConverged` custom resource in the `openshift-cnv` namespace. + +.^| `N/A` +.^|`kubevirt.io:migrate` +| A user that can create, delete, and update VM live migration requests, which are represented by namespaced `VirtualMachineInstanceMigration` (VMIM) objects. This role is specific to {VirtProductName}. |=== \ No newline at end of file diff --git a/modules/virt-granting-live-migration-permissions.adoc b/modules/virt-granting-live-migration-permissions.adoc new file mode 100644 index 0000000000..d631486a7a --- /dev/null +++ b/modules/virt-granting-live-migration-permissions.adoc @@ -0,0 +1,37 @@ +// Module included in the following assemblies: +// +// * virt/live_migration/virt-about-live-migration.adoc + +:_mod-docs-content-type: PROCEDURE +[id="virt-granting-live-migration-permissions_{context}"] += Granting live migration permissions + +Grant trusted users or groups the ability to create, delete, and update live migration instances. + +.Prerequisites + +* The {product-title} CLI (`oc`) is installed. +* You have cluster administrator permissions. + +.Procedure + +* (Optional) To change the default behavior so that namespace administrators always have permission to create, delete, and update live migrations, aggregate the `kubevirt.io:migrate` role into the `admin` cluster role by running the following command: ++ +[source,terminal] +---- +$ oc label --overwrite clusterrole kubevirt.io:migrate rbac.authorization.k8s.io/aggregate-to-admin=true +---- + +* Bind the `kubevirt.io:migrate` cluster role to trusted users or groups by running one of the following commands, replacing ``, ``, ``, and `` with your own values. +** To bind the role at the namespace level, run the following command: ++ +[source,terminal] +---- +$ oc create -n rolebinding kvmigrate --clusterrole=kubevirt.io:migrate --user= --user= --group= +---- +** To bind the role at the cluster level, run the following command: ++ +[source,terminal] +---- +$ oc create clusterrolebinding kvmigrate --clusterrole=kubevirt.io:migrate --user= --user= --group= +---- diff --git a/modules/virt-initiating-vm-migration-cli.adoc b/modules/virt-initiating-vm-migration-cli.adoc index 834426544c..64d8f7ce07 100644 --- a/modules/virt-initiating-vm-migration-cli.adoc +++ b/modules/virt-initiating-vm-migration-cli.adoc @@ -11,6 +11,7 @@ You can initiate the live migration of a running virtual machine (VM) by using t .Prerequisites * You have installed the {oc-first}. +* You have the `kubevirt.io:migrate` RBAC role or you are a cluster administrator. .Procedure diff --git a/modules/virt-initiating-vm-migration-web.adoc b/modules/virt-initiating-vm-migration-web.adoc index e6ec554d81..91e6f607e4 100644 --- a/modules/virt-initiating-vm-migration-web.adoc +++ b/modules/virt-initiating-vm-migration-web.adoc @@ -15,8 +15,9 @@ The *Migrate* action is visible to all users but only cluster administrators can .Prerequisites -* The VM must be migratable. -* If the VM is configured with a host model CPU, the cluster must have an available node that supports the CPU model. +* You have the `kubevirt.io:migrate` RBAC role or you are a cluster administrator. +* The VM is migratable. +* If the VM is configured with a host model CPU, the cluster has an available node that supports the CPU model. .Procedure diff --git a/modules/virt-preserving-lm-perms.adoc b/modules/virt-preserving-lm-perms.adoc new file mode 100644 index 0000000000..084ca3139a --- /dev/null +++ b/modules/virt-preserving-lm-perms.adoc @@ -0,0 +1,81 @@ +// Module included in the following assemblies: +// +// * virt/live_migration/virt-about-live-migration.adoc + +:_mod-docs-content-type: PROCEDURE +[id="virt-preserving-lm-perms_{context}"] += Preserving pre-4.19 live migration permissions during update + +Before you update to {VirtProductName} {VirtVersion}, you can create a temporary cluster role to preserve the previous live migration permissions until you are ready for the more restrictive default permissions to take effect. + +.Prerequisites + +* The {product-title} CLI (`oc`) is installed. +* You have cluster administrator permissions. + +.Procedure + +. Before updating to {VirtProductName} {VirtVersion}, create a temporary `ClusterRole` object. For example: ++ +[source,yaml] +---- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + labels: + rbac.authorization.k8s.io/aggregate-to-admin=true #<1> + name: kubevirt.io:upgrademigrate +rules: +- apiGroups: + - subresources.kubevirt.io + resources: + - virtualmachines/migrate + verbs: + - update +- apiGroups: + - kubevirt.io + resources: + - virtualmachineinstancemigrations + verbs: + - get + - delete + - create + - update + - patch + - list + - watch + - deletecollection +---- +<1> This cluster role is aggregated into the `admin` role before you update {VirtProductName}. The update process does not modify it, ensuring the previous behavior is maintained. + +. Add the cluster role manifest to the cluster by running the following command: ++ +[source,terminal] +---- +$ oc apply -f .yaml +---- + +. Update {VirtProductName} to version {VirtVersion}. + +. Bind the `kubevirt.io:migrate` cluster role to trusted users or groups by running one of the following commands, replacing ``, ``, ``, and `` with your own values. +** To bind the role at the namespace level, run the following command: ++ +[source,terminal] +---- +$ oc create -n rolebinding kvmigrate --clusterrole=kubevirt.io:migrate --user= --user= --group= +---- +** To bind the role at the cluster level, run the following command: ++ +[source,terminal] +---- +$ oc create clusterrolebinding kvmigrate --clusterrole=kubevirt.io:migrate --user= --user= --group= +---- + +. When you have bound the `kubevirt.io:migrate` role to all necessary users, delete the temporary `ClusterRole` object by running the following command: ++ +[source,terminal] +---- +$ oc delete clusterrole kubevirt.io:upgrademigrate +---- ++ +After you delete the temporary cluster role, only users with the `kubevirt.io:migrate` role can create, delete, and update live migration requests. \ No newline at end of file diff --git a/virt/live_migration/virt-about-live-migration.adoc b/virt/live_migration/virt-about-live-migration.adoc index 57ee19c354..b036b6fe29 100644 --- a/virt/live_migration/virt-about-live-migration.adoc +++ b/virt/live_migration/virt-about-live-migration.adoc @@ -32,6 +32,13 @@ The default number of migrations that can run in parallel in the cluster is 5. * If a VM uses a host model CPU, the nodes must support the CPU. * xref:../../virt/vm_networking/virt-dedicated-network-live-migration.adoc#virt-dedicated-network-live-migration[Configuring a dedicated Multus network] for live migration is highly recommended. A dedicated network minimizes the effects of network saturation on tenant workloads during migration. +include::modules/virt-about-live-migration-permissions.adoc[leveloffset=+1] + +//TODO: Remove transition-to-lm-role module in 4.21; relevant in 4.20 due to EUS +include::modules/virt-preserving-lm-perms.adoc[leveloffset=+1] + +include::modules/virt-granting-live-migration-permissions.adoc[leveloffset=+1] + include::modules/virt-vm-migration-tuning.adoc[leveloffset=+1] [id="common-live-migration-tasks_virt-about-live-migration"] @@ -48,6 +55,7 @@ You can perform the following live migration tasks: [id="additional-resources_virt-about-live-migration"] == Additional resources +* xref:../../virt/about_virt/virt-security-policies.adoc#default-cluster-roles-for-virt_virt-security-policies[Default cluster roles for {VirtProductName}] * xref:../../virt/monitoring/virt-prometheus-queries.adoc#virt-live-migration-metrics_virt-prometheus-queries[Prometheus queries for live migration] * xref:../../virt/nodes/virt-node-maintenance.adoc#run-strategies[VM run strategies] * xref:../../virt/nodes/virt-node-maintenance.adoc#eviction-strategies[VM and cluster eviction strategies] \ No newline at end of file diff --git a/virt/live_migration/virt-initiating-live-migration.adoc b/virt/live_migration/virt-initiating-live-migration.adoc index 2ff3c84266..6544c8fe4b 100644 --- a/virt/live_migration/virt-initiating-live-migration.adoc +++ b/virt/live_migration/virt-initiating-live-migration.adoc @@ -27,4 +27,10 @@ include::modules/virt-initiating-vm-migration-cli.adoc[leveloffset=+2] include::modules/virt-canceling-vm-migration-web.adoc[leveloffset=+2] -include::modules/virt-canceling-vm-migration-cli.adoc[leveloffset=+2] \ No newline at end of file +include::modules/virt-canceling-vm-migration-cli.adoc[leveloffset=+2] + +[role="_additional-resources"] +[id="additional-resources_{context}"] +== Additional resources + +* xref:../../virt/live_migration/virt-about-live-migration.adoc#virt-about-live-migration-permissions_virt-about-live-migration[About live migration permissions] \ No newline at end of file diff --git a/virt/vm_networking/virt-hot-plugging-network-interfaces.adoc b/virt/vm_networking/virt-hot-plugging-network-interfaces.adoc index 54211b8245..d247b49b12 100644 --- a/virt/vm_networking/virt-hot-plugging-network-interfaces.adoc +++ b/virt/vm_networking/virt-hot-plugging-network-interfaces.adoc @@ -40,6 +40,7 @@ include::modules/virt-hot-unplugging-bridge-network-interface-cli.adoc[leveloffs == Additional resources * xref:../../virt/getting_started/virt-using-the-cli-tools.adoc#installing-virtctl_virt-using-the-cli-tools[Installing virtctl] +* xref:../../virt/live_migration/virt-about-live-migration.adoc#virt-about-live-migration-permissions_virt-about-live-migration[About live migration permissions] ifndef::openshift-rosa,openshift-dedicated,openshift-rosa-hcp[] * xref:../../virt/vm_networking/virt-connecting-vm-to-linux-bridge.adoc#creating-linux-bridge-nad[Creating a Linux bridge network attachment definition] * xref:../../virt/vm_networking/virt-connecting-vm-to-linux-bridge.adoc#configuring-vm-network-interface[Connecting a virtual machine to a Linux bridge network]