From 68769fc73f67da5aad0193a103438a574402d929 Mon Sep 17 00:00:00 2001 From: Ashleigh Brennan Date: Thu, 23 Apr 2026 12:23:45 -0500 Subject: [PATCH] DOCPLAN-139: CQA updates for virt node placement docs --- ...-about-node-placement-virt-components.adoc | 8 +- ...rt-apply-nodeselector-placement-rules.adoc | 36 +++++++ .../virt-applying-node-placement-rules.adoc | 20 +++- .../virt-hpp-object-node-placement-rules.adoc | 37 +++++++ modules/virt-installing-virt-operator.adoc | 2 +- .../virt-node-placement-rule-examples.adoc | 102 ++---------------- modules/virt-subscribing-cli.adoc | 77 +++++++++++-- .../virt-node-placement-virt-components.adoc | 4 +- ...rt-configuring-local-storage-with-hpp.adoc | 1 + 9 files changed, 172 insertions(+), 115 deletions(-) create mode 100644 modules/virt-apply-nodeselector-placement-rules.adoc create mode 100644 modules/virt-hpp-object-node-placement-rules.adoc diff --git a/modules/virt-about-node-placement-virt-components.adoc b/modules/virt-about-node-placement-virt-components.adoc index 26cd9ab6a5f2..d8e6e2cd34c9 100644 --- a/modules/virt-about-node-placement-virt-components.adoc +++ b/modules/virt-about-node-placement-virt-components.adoc @@ -9,14 +9,8 @@ [role="_abstract"] You can use node placement rules to deploy virtual machines only on nodes intended for virtualization workloads, to deploy Operators only on infrastructure nodes, or to maintain separation between workloads. -Depending on the object, you can use one or more of the following rule types: - -`nodeSelector`:: Allows pods to be scheduled on nodes that are labeled with the key-value pair or pairs that you specify in this field. The node must have labels that exactly match all listed pairs. -`affinity`:: Enables you to use more expressive syntax to set rules that match nodes with pods. Affinity also allows for more nuance in how the rules are applied. For example, you can specify that a rule is a preference, not a requirement. If a rule is a preference, pods are still scheduled when the rule is not satisfied. -`tolerations`:: Allows pods to be scheduled on nodes that have matching taints. If a taint is applied to a node, that node only accepts pods that tolerate the taint. - ifdef::openshift-enterprise[] -If you are running an {ibm-z-title} or {ibm-linuxone-title} (`s390x`) cluster with mixed hypervisors, refer to the following table for the supported nodes to run the virtual machines. +If you are running an {ibm-z-title} or {ibm-linuxone-title} (`s390x`) cluster with mixed hypervisors, refer to the following table for the supported nodes to run the virtual machines. .{ibm-z-name} node options [cols="1,1,1,1,1",options="header"] diff --git a/modules/virt-apply-nodeselector-placement-rules.adoc b/modules/virt-apply-nodeselector-placement-rules.adoc new file mode 100644 index 000000000000..60e2376b677d --- /dev/null +++ b/modules/virt-apply-nodeselector-placement-rules.adoc @@ -0,0 +1,36 @@ +// Module included in the following assemblies: +// +// * virt/post_installation_configuration/virt-node-placement-virt-components.adoc + +:_mod-docs-content-type: PROCEDURE +[id="virt-apply-nodeselector-placement-rules_{context}"] += Apply nodeSelector node placement rules + +[role="_abstract"] +You can configure `nodeSelector` node placement rules to allow pods to be scheduled on nodes that are labeled with the key-value pair, or pairs, that you specify in this field. The node must have labels that exactly match all listed pairs. + +.Prerequisites + +* You have installed the {oc-first}. +* You are logged in with cluster administrator permissions. + +.Procedure + +ifndef::openshift-rosa,openshift-dedicated[] +. Edit a `Subscription`, `HyperConverged`, or `HostPathProvisioner` object using the {oc-first}, by running the following command: ++ +[source,terminal,subs="attributes+"] +---- +$ oc edit -n {CNVNamespace} +---- +endif::openshift-rosa,openshift-dedicated[] +ifdef::openshift-rosa,openshift-dedicated[] +. Edit a `HyperConverged` or `HostPathProvisioner` object using the {oc-first}, by running the following command: ++ +[source,terminal,subs="attributes+"] +---- +$ oc edit -n {CNVNamespace} +---- +endif::openshift-rosa,openshift-dedicated[] + +. Save the file to apply the changes. diff --git a/modules/virt-applying-node-placement-rules.adoc b/modules/virt-applying-node-placement-rules.adoc index 606064e4a8a2..c08e71c55faa 100644 --- a/modules/virt-applying-node-placement-rules.adoc +++ b/modules/virt-applying-node-placement-rules.adoc @@ -8,13 +8,16 @@ ifndef::openshift-rosa,openshift-dedicated[] [role="_abstract"] -You can apply node placement rules by editing a `Subscription`, `HyperConverged`, or `HostPathProvisioner` object using the command line. +You can apply node placement rules by editing a `Subscription`, `HyperConverged`, or `HostPathProvisioner` object using the {oc-first}. endif::openshift-rosa,openshift-dedicated[] ifdef::openshift-rosa,openshift-dedicated[] [role="_abstract"] -You can apply node placement rules by editing a `HyperConverged` or `HostPathProvisioner` object using the command line. +You can apply node placement rules by editing a `HyperConverged` or `HostPathProvisioner` object using the {oc-first}. endif::openshift-rosa,openshift-dedicated[] +`affinity`:: Enables you to use more expressive syntax to set rules that match nodes with pods. Affinity also allows for more nuance in how the rules are applied. For example, you can specify that a rule is a preference, not a requirement. If a rule is a preference, pods are still scheduled when the rule is not satisfied. +`tolerations`:: Allows pods to be scheduled on nodes that have matching taints. If a taint is applied to a node, that node only accepts pods that tolerate the taint. + .Prerequisites * You have installed the {oc-first}. @@ -22,11 +25,22 @@ endif::openshift-rosa,openshift-dedicated[] .Procedure -. Edit the object in your default editor by running the following command: +ifndef::openshift-rosa,openshift-dedicated[] +. Edit a `Subscription`, `HyperConverged`, or `HostPathProvisioner` object using the {oc-first}, by running the following command: + [source,terminal,subs="attributes+"] ---- $ oc edit -n {CNVNamespace} ---- +endif::openshift-rosa,openshift-dedicated[] +ifdef::openshift-rosa,openshift-dedicated[] +[role="_abstract"] +. Edit a `HyperConverged` or `HostPathProvisioner` object using the {oc-first}, by running the following command: ++ +[source,terminal,subs="attributes+"] +---- +$ oc edit -n {CNVNamespace} +---- +endif::openshift-rosa,openshift-dedicated[] . Save the file to apply the changes. diff --git a/modules/virt-hpp-object-node-placement-rules.adoc b/modules/virt-hpp-object-node-placement-rules.adoc new file mode 100644 index 000000000000..99820f3edd41 --- /dev/null +++ b/modules/virt-hpp-object-node-placement-rules.adoc @@ -0,0 +1,37 @@ +// Module included in the following assemblies: +// +// * virt/storage/virt-configuring-local-storage-with-hpp.adoc + +:_mod-docs-content-type: REFERENCE +[id="virt-hpp-object-node-placement-rules_{context}"] += HostPathProvisioner object node placement rule example + +[role="_abstract"] +After you deploy a virtual machine (VM) with the HPP storage class, you can remove the hostpath provisioner pod from the same node by using the node selector. However, you must first revert that change, at least for that specific node, and wait for the pod to run before trying to delete the VM. + +[WARNING] +==== +You must schedule the hostpath provisioner (HPP) and the {VirtProductName} components on the same nodes. Otherwise, virtualization pods that use the hostpath provisioner cannot run. You cannot run virtual machines. +==== + +You can configure node placement rules by specifying `nodeSelector`, `affinity`, or `tolerations` for the `spec.workload` field of the `HostPathProvisioner` object that you create when you install the hostpath provisioner. + +Example `HostPathProvisioner` object with `nodeSelector` rule: + +[source,yaml] +---- +apiVersion: hostpathprovisioner.kubevirt.io/v1beta1 +kind: HostPathProvisioner +metadata: + name: hostpath-provisioner +spec: + imagePullPolicy: IfNotPresent + pathConfig: + path: "" + useNamingPrefix: false + workload: + nodeSelector: + example.io/example-workloads-key: example-workloads-value +---- + +In the previous example, workloads are placed on nodes labeled `example.io/example-workloads-key = example-workloads-value`. diff --git a/modules/virt-installing-virt-operator.adoc b/modules/virt-installing-virt-operator.adoc index 00b0623d0cba..f9a6f7c42c08 100644 --- a/modules/virt-installing-virt-operator.adoc +++ b/modules/virt-installing-virt-operator.adoc @@ -54,7 +54,7 @@ Because {VirtProductName} is only supported when used with the corresponding {pr . Optional: Configure *Infra* and *Workloads* node placement options for {VirtProductName} components. -. Click *Create* to launch {VirtProductName}. +. Click *Create*. .Verification diff --git a/modules/virt-node-placement-rule-examples.adoc b/modules/virt-node-placement-rule-examples.adoc index 8db43d229b54..c2e21a0b6237 100644 --- a/modules/virt-node-placement-rule-examples.adoc +++ b/modules/virt-node-placement-rule-examples.adoc @@ -15,71 +15,13 @@ ifdef::openshift-rosa,openshift-dedicated[] You can specify node placement rules for a {VirtProductName} component by editing a `HyperConverged` or `HostPathProvisioner` object. endif::openshift-rosa,openshift-dedicated[] -ifndef::openshift-rosa,openshift-dedicated[] -[id="subscription-object-node-placement-rules_{context}"] -== Subscription object node placement rule examples - -To specify the nodes where OLM deploys the {VirtProductName} Operators, edit the `Subscription` object during {VirtProductName} installation. - -Currently, you cannot configure node placement rules for the `Subscription` object by using the web console. - -The `Subscription` object does not support the `affinity` node placement rule. - -Example `Subscription` object with `nodeSelector` rule: - -[source,yaml,subs="attributes+"] ----- -apiVersion: operators.coreos.com/v1alpha1 -kind: Subscription -metadata: - name: hco-operatorhub - namespace: {CNVNamespace} -spec: - source: {CNVSubscriptionSpecSource} - sourceNamespace: openshift-marketplace - name: {CNVSubscriptionSpecName} - startingCSV: kubevirt-hyperconverged-operator.v{HCOVersion} - channel: "stable" - config: - nodeSelector: - example.io/example-infra-key: example-infra-value ----- - -OLM deploys the {VirtProductName} Operators on nodes labeled `example.io/example-infra-key = example-infra-value`. - -Example `Subscription` object with `tolerations` rule: - -[source,yaml,subs="attributes+"] ----- -apiVersion: operators.coreos.com/v1alpha1 -kind: Subscription -metadata: - name: hco-operatorhub - namespace: {CNVNamespace} -spec: - source: {CNVSubscriptionSpecSource} - sourceNamespace: openshift-marketplace - name: {CNVSubscriptionSpecName} - startingCSV: kubevirt-hyperconverged-operator.v{HCOVersion} - channel: "stable" - config: - tolerations: - - key: "key" - operator: "Equal" - value: "virtualization" - effect: "NoSchedule" ----- - -OLM deploys {VirtProductName} Operators on nodes labeled `key = virtualization:NoSchedule` taint. Only pods with the matching tolerations are scheduled on these nodes. -endif::openshift-rosa,openshift-dedicated[] - [id="hyperconverged-object-node-placement-rules_{context}"] == HyperConverged object node placement rule example -To specify the nodes where {VirtProductName} deploys its components, you can edit the `nodePlacement` object in the `HyperConverged` custom resource (CR) file that you create during {VirtProductName} installation. - +.. To specify the nodes where {VirtProductName} deploys its components, you can edit the `HyperConverged` custom resource (CR). ++ Example `HyperConverged` object with `nodeSelector` rule: - ++ [source,yaml,subs="attributes+"] ---- apiVersion: hco.kubevirt.io/v1beta1 @@ -97,7 +39,9 @@ spec: nodeSelector: example.io/example-workloads-key: example-workloads-value ---- - ++ +In this example: ++ * Infrastructure resources are placed on nodes labeled `example.io/example-infra-key = example-infra-value`. * Workloads are placed on nodes labeled `example.io/example-workloads-key = example-workloads-value`. @@ -167,37 +111,3 @@ spec: ---- Nodes reserved for {VirtProductName} components are labeled with the `key = virtualization:NoSchedule` taint. Only pods with matching tolerations are scheduled on reserved nodes. - -[id="hostpathprovisioner-object-node-placement-rules_{context}"] -== HostPathProvisioner object node placement rule example - -You can edit the `HostPathProvisioner` object directly or by using the web console. - -[WARNING] -==== -You must schedule the hostpath provisioner (HPP) and the {VirtProductName} components on the same nodes. Otherwise, virtualization pods that use the hostpath provisioner cannot run. You cannot run virtual machines. -==== - -After you deploy a virtual machine (VM) with the HPP storage class, you can remove the hostpath provisioner pod from the same node by using the node selector. However, you must first revert that change, at least for that specific node, and wait for the pod to run before trying to delete the VM. - -You can configure node placement rules by specifying `nodeSelector`, `affinity`, or `tolerations` for the `spec.workload` field of the `HostPathProvisioner` object that you create when you install the hostpath provisioner. - -Example `HostPathProvisioner` object with `nodeSelector` rule: - -[source,yaml] ----- -apiVersion: hostpathprovisioner.kubevirt.io/v1beta1 -kind: HostPathProvisioner -metadata: - name: hostpath-provisioner -spec: - imagePullPolicy: IfNotPresent - pathConfig: - path: "" - useNamingPrefix: false - workload: - nodeSelector: - example.io/example-workloads-key: example-workloads-value ----- - -Workloads are placed on nodes labeled `example.io/example-workloads-key = example-workloads-value`. diff --git a/modules/virt-subscribing-cli.adoc b/modules/virt-subscribing-cli.adoc index 1126c63ecc8d..c0b37a6ee1b5 100644 --- a/modules/virt-subscribing-cli.adoc +++ b/modules/virt-subscribing-cli.adoc @@ -22,7 +22,6 @@ To subscribe, configure `Namespace`, `OperatorGroup`, and `Subscription` objects ifdef::openshift-enterprise,openshift-rosa,openshift-dedicated,openshift-rosa-hcp[] . Create a YAML file that contains the following manifest: -//Note that there are two versions of the following YAML file; the first one is for openshift-enterprise and the second is for openshift-origin (aka OKD). + [source,yaml,subs="attributes+"] ---- @@ -53,13 +52,76 @@ spec: name: {CNVSubscriptionSpecName} startingCSV: kubevirt-hyperconverged-operator.v{HCOVersion} channel: "stable" + config: + nodeSelector: + example.io/example-infra-key: example-infra-value ---- + -Using the `stable` channel ensures that you install the version of -{VirtProductName} that is compatible with your {product-title} version. +[IMPORTANT] +==== +In the `Subscription` object, use the `"stable"` channel to install the version of {VirtProductName} that is compatible with your {product-title} version. +==== endif::openshift-enterprise,openshift-rosa,openshift-dedicated,openshift-rosa-hcp[] +ifdef::openshift-enterprise[] + +. Optional. To specify the nodes where {olm-first} deploys the {VirtProductName} Operators, configure the `nodeSelector` or `tolerations` rule in the `Subscription` object. ++ +[IMPORTANT] +==== +The `Subscription` object does not support the `affinity` node placement rule. +==== ++ +Example `Subscription` object with `nodeSelector` rule: ++ +[source,yaml,subs="attributes+"] +---- +apiVersion: operators.coreos.com/v1alpha1 +kind: Subscription +metadata: + name: hco-operatorhub + namespace: {CNVNamespace} +spec: + source: {CNVSubscriptionSpecSource} + sourceNamespace: openshift-marketplace + name: {CNVSubscriptionSpecName} + startingCSV: kubevirt-hyperconverged-operator.v{HCOVersion} + channel: "stable" + config: + nodeSelector: + example.io/example-infra-key: example-infra-value +---- ++ +In the previous example, {olm} deploys the {VirtProductName} Operators on nodes labeled `example.io/example-infra-key = example-infra-value`. ++ +Example `Subscription` object with `tolerations` rule: ++ +[source,yaml,subs="attributes+"] +---- +apiVersion: operators.coreos.com/v1alpha1 +kind: Subscription +metadata: + name: hco-operatorhub + namespace: {CNVNamespace} +spec: + source: {CNVSubscriptionSpecSource} + sourceNamespace: openshift-marketplace + name: {CNVSubscriptionSpecName} + startingCSV: kubevirt-hyperconverged-operator.v{HCOVersion} + channel: "stable" + config: + tolerations: + - key: "key" + operator: "Equal" + value: "virtualization" + effect: "NoSchedule" +---- ++ +In the previous example, {olm} deploys {VirtProductName} Operators on nodes labeled `key = virtualization:NoSchedule` taint. Only pods with the matching tolerations are scheduled on these nodes. + +endif::openshift-enterprise[] + ifdef::openshift-origin[] . Create a YAML file that contains the following manifest: @@ -91,13 +153,14 @@ spec: channel: "stable" ---- + -Using the `stable` channel ensures that you install the version of -{VirtProductName} that is compatible with your {product-title} version. +[IMPORTANT] +==== +In the `Subscription` object, use the `"stable"` channel to install the version of {VirtProductName} that is compatible with your {product-title} version. +==== endif::openshift-origin[] -. Create the required `Namespace`, `OperatorGroup`, and `Subscription` objects -for {VirtProductName} by running the following command: +. Create the required `Namespace`, `OperatorGroup`, and `Subscription` objects for {VirtProductName} by running the following command: + [source,terminal] ---- diff --git a/virt/post_installation_configuration/virt-node-placement-virt-components.adoc b/virt/post_installation_configuration/virt-node-placement-virt-components.adoc index 239a9bcb996c..86eb9d59a39b 100644 --- a/virt/post_installation_configuration/virt-node-placement-virt-components.adoc +++ b/virt/post_installation_configuration/virt-node-placement-virt-components.adoc @@ -1,7 +1,7 @@ :_mod-docs-content-type: ASSEMBLY include::_attributes/common-attributes.adoc[] [id="virt-node-placement-virt-components"] -= Specifying nodes for {VirtProductName} components += Specify nodes for {VirtProductName} components :context: virt-node-placement-virt-components toc::[] @@ -16,6 +16,8 @@ You can configure node placement rules for some components after installing {Vir include::modules/virt-about-node-placement-virt-components.adoc[leveloffset=+1] +include::modules/virt-apply-nodeselector-placement-rules.adoc[leveloffset=+1] + include::modules/virt-applying-node-placement-rules.adoc[leveloffset=+1] include::modules/virt-node-placement-rule-examples.adoc[leveloffset=+1] diff --git a/virt/storage/virt-configuring-local-storage-with-hpp.adoc b/virt/storage/virt-configuring-local-storage-with-hpp.adoc index 25e6a5784826..c5e9ce8edf1d 100644 --- a/virt/storage/virt-configuring-local-storage-with-hpp.adoc +++ b/virt/storage/virt-configuring-local-storage-with-hpp.adoc @@ -21,3 +21,4 @@ include::modules/virt-about-storage-pools-pvc-templates.adoc[leveloffset=+1] include::modules/virt-creating-storage-pool-pvc-template.adoc[leveloffset=+2] +include::modules/virt-hpp-object-node-placement-rules.adoc[leveloffset=+1]