Mini Content Journey

Who is your target persona?

VM owners - this isn’t specific in the docs. Need to confirm if they need admin permissions.

What stage of the user journey are you targeting?

Expand

Why is this content important?

Hint: Provide a brief summary of how of this content will impact the end user

• When a VirtualMachine is created with an instance type or preference, ControllerRevision objects automatically save a copy of those definitions. This ensures that the VM's configuration, derived from its instance type and preference, remains consistent throughout its lifecycle, including during snapshots and subsequent restores.
• All existing VM lifecycle behavior, including snapshot and restore, is retained when using instance types and preferences. ControllerRevision objects are crucial for this, as they store copies of VirtualMachineInstanceType and VirtualMachinePreference objects at the time of VM creation, maintaining consistent VM behavior across restarts, snapshot restores, or cloning operations.

What is the main user goal aka job to be done?

• As a VM owner, I want to use declarative management of ControllerRevision references for instance types and preferences in the VirtualMachine's status field.
• As a VM owner, I want to easily switch between different instance types or preferences, or update to a newer version of an existing one.

What high level steps does the user need to take to accomplish the goal?

1. Understand the Role of ControllerRevisions.
2. Create your VirtualMachine YAML, referencing the desired VirtualMachineInstancetype and/or VirtualMachinePreference by their kind and name.
3.  Modify the VirtualMachine's spec, to switch to a new instance type or refresh the current one.
4. To Update to a Newer Version of the Current Instance Type or Preference:
   1. Force the system to create a new ControllerRevision.
   2. Stop the VirtualMachine.
   3. Clear the revisionName from the instancetype or preference section in your VirtualMachine's spec.
   4. Start the VirtualMachine again. This triggers the creation of a new ControllerRevision object using the latest definition of the instance type or preference.
5. To Switch to a Different Instance Type or Preference:
   1. For KubeVirt >= v1.5.0: Simply update the name of the referenced instancetype in the VirtualMachine's spec.
   2. For KubeVirt <= v1.4.0: You need to update the name and also explicitly clear the revisionName of the referenced instancetype in the VirtualMachine's spec.
6. Continue using regular commands for snapshotting, restoring, and cloning VMs. The underlying system will automatically use the ControllerRevision information to ensure the restored or cloned VM behaves as expected, based on the definitions captured at its creation or explicit revision. The feature is designed to work seamlessly without additional configuration for this goal.

Links to existing content 

• https://github.com/openshift/openshift-docs/pull/98464
• https://issues.redhat.com/browse/CNV-46277
• https://docs.redhat.com/en/documentation/openshift_container_platform/4.19/html/virtualization/creating-a-virtual-machine

People:

• SME: [SME name]
• QE: [QE name]

Release Note: Yes / No

Documentation Outline

• Module Title (Concept)
• Overview of content required

• Module Title (Concept)
• Overview of content required

• Module Title (Procedure)
• Prerequisites
• Outline of steps

• Module Title (Procedure)
• Prerequisites
• Outline of steps

• Module Title (Reference)
• Outline of parameters/options/data to be included

• Module Title (Reference)
• Outline of parameters/options/data to be included