CNV-46346: Adding docs for controller revisions

Author: abrennan89

modules/virt-about-instance-types.adoc

@@ -82,3 +82,10 @@ In addition to the required `cpu` and `memory` attributes, you can include the f
 `launchSecurity`:: Configure Secure Encrypted Virtualization (SEV).
 `nodeSelector`:: Specify node selectors to control the nodes where this VM is scheduled.
 `schedulerName`:: Define a custom scheduler to use for this VM instead of the default scheduler.
+
+[id="virt-about-instance-types-controller-revisions_{context}"]
+== Controller revisions
+
+When you create a VM by using an instance type, a `ControllerRevision` object retains an immutable snapshot of the instance type object. This snapshot locks in resource-related characteristics defined in the instance type object, such as the required guest CPU and memory. The VM status also contains a reference to the `ControllerRevision` object.
+
+This snapshot is essential for versioning, and ensures that the VM instance created when starting a VM does not change if the underlying instance type object is updated while the VM is running.

modules/virt-change-vm-instance-type-cli.adoc

@@ -0,0 +1,67 @@
+// Module included in the following assemblies:
+//
+// * virt/virtual_machines/creating_vm/virt-creating-vms-from-instance-types.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="virt-change-vm-instance-type-cli_{context}"]
+= Changing the instance type of a VM by using the CLI
+
+[role="_abstract"]
+To change the instance type of a VM, change the `name` field in the VM spec. This triggers the update logic, which ensures that a new, immutable controller revision snapshot is taken of the new resource configuration.
+
+.Prerequisites
+
+* You have installed the {oc-first}.
+* You created the VM by using an instance type, or have administrator privileges for the VM that you want to modify.
+
+.Procedure
+
+. Stop the VM.
+
+. Run the following command, and replace `<vm_name>` with the name of your VM, and `<new_instancetype>` with the name of the instance type you want to change to:
++
+[source,terminal]
+----
+$ oc patch vm/<vm_name> --type merge -p '{"spec":{"instancetype":{"name": "<new_instancetype>"}}}'
+----
+
+.Verification
+
+* Check the controller revision reference in the updated VM `status` field. Run the following command and verify that the revision name is updated in the output:
++
+[source,terminal]
+----
+$ oc get vms/<vm_name> -o json | jq .status.instancetypeRef
+----
++
+*Example output*
++
+[source,terminal]
+----
+{
+  "controllerRevisionRef": {
+    "name": "vm-cirros-csmall-csmall-3e86e367-9cd7-4426-9507-b14c27a08671-2"
+  },
+  "kind": "VirtualMachineInstancetype",
+  "name": "csmall"
+}
+----
+
+* Optional: Check that the VM instance is running the new configuration defined in the latest controller revision. For example, if you updated the instance type to use 2 vCPUs instead of 1, run the following command and check the output:
++
+[source,terminal]
+----
+$ oc get vmi/<vm_name> -o json | jq .spec.domain.cpu
+----
++
+*Example output that verifies that the revision uses 2 vCPUs*
++
+[source,terminal]
+----
+{
+  "cores": 1,
+  "model": "host-model",
+  "sockets": 2,
+  "threads": 1
+}
+----

modules/virt-change-vm-instance-type.adoc

@@ -4,9 +4,9 @@
 
 :_mod-docs-content-type: PROCEDURE
 [id="virt-change-vm-instance-type_{context}"]
+= Changing the instance type of a VM by using the web console
 
-= Changing the instance type of a VM
-
+[role="_abstract"]
 You can change the instance type associated with a running virtual machine (VM) by using the web console. The change takes effect immediately.
 
 .Prerequisites
@@ -36,4 +36,3 @@ You can change the instance type associated with a running virtual machine (VM)
 . Click *Reload*.
 
 . Review the VM YAML to confirm that the instance type changed.
-

modules/virt-creating-udn-namespace-cli.adoc

@@ -1,9 +1,9 @@
 // Module included in the following assemblies:
 //
-// * virt/vm_networking/virt-connecting-vm-to-primary-udn.adoc              
+// * virt/vm_networking/virt-connecting-vm-to-primary-udn.adoc
 
-:_mod-docs-content-type: PROCEDURE                                    
-[id="virt-creating-udn-namespace-cli_{context}"]                                   
+:_mod-docs-content-type: PROCEDURE
+[id="virt-creating-udn-namespace-cli_{context}"]
 = Creating a namespace for user-defined networks by using the CLI
 
 You can create a namespace to be used with primary user-defined networks (UDNs) by using the CLI.
@@ -33,4 +33,4 @@ metadata:
 [source, terminal]
 ----
 oc apply -f <filename>.yaml
-----
+----

virt/creating_vm/virt-creating-vms-from-instance-types.adoc

@@ -6,6 +6,7 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
+[role="_abstract"]
 You can simplify virtual machine (VM) creation by using instance types, whether you use the {product-title} web console or the CLI to create VMs.
 
 // special TP note for ROSA only:
@@ -40,4 +41,16 @@ ifndef::openshift-rosa,openshift-dedicated,openshift-rosa-hcp[]
 * xref:../../virt/monitoring/virt-exposing-downward-metrics.adoc#virt-configuring-downward-metrics_virt-exposing-downward-metrics[Configuring a downward metrics device]
 endif::openshift-rosa,openshift-dedicated,openshift-rosa-hcp[]
 
-include::modules/virt-change-vm-instance-type.adoc[leveloffset=+1]
+[id="virt-creating-vms-from-instance-types-changing-types_{context}"]
+== Changing the instance type for a VM
+
+As a cluster administrator or VM owner, you might want to change the instance type for an existing VM for the following reasons:
+
+* If a VM's workload has increased, you might change the instance type to one with more CPU, more memory, or specific hardware resources, to prevent performance bottlenecks.
+* If you are using specialized workloads, you might switch to a different instance type to improve performance, as some instance types are optimized for specific use cases.
+
+You can use the {product-title} web console or the {oc-first} to change the instance type for an existing VM.
+
+include::modules/virt-change-vm-instance-type.adoc[leveloffset=+2]
+
+include::modules/virt-change-vm-instance-type-cli.adoc[leveloffset=+2]