docs: VMO refactor (#3040)

* docs: organize vmo structure

* docs: fix broken links

* fix redirect issue

* docs: fix broken link

* docs: fix broken link

* docs: fix broken link

* docs: start refactoring VMO pages

* docs: refactor create and manage VMs

* Update the VMO index page and document its architecture (#3073)

* docs: Update the VMO index page

* docs: Document the VMO architecture (WIP)

* docs: Finish the VMO arch draft and update the higl-level topic structure

* chore: Fix formatting

* Optimised images with calibre/image-actions

* Optimised images with calibre/image-actions

* chore: Fix typos flagged by Vale

---------

Co-authored-by: vault-token-factory-spectrocloud[bot] <133815545+vault-token-factory-spectrocloud[bot]@users.noreply.github.com>

* docs: progress on vmo

* docs: document options in update configurations

* docs: edit prerequisites

* docs: Update the VMO architecture, add the environment setup topic, other refactoring work

* Optimised images with calibre/image-actions

* docs: fix broken link

* Optimised images with calibre/image-actions

* docs: inclusive language

* docs: fix ablism terms

* docs: address review comments

* Apply suggestions from code review

Co-authored-by: Karl Cardenas <29551334+karl-cardenas-coding@users.noreply.github.com>

* docs: clarify cpu specifications

* docs: webp conversion

* docs: minor edit

* Optimised images with calibre/image-actions

* Optimised images with calibre/image-actions

* docs: fix broken admonition

---------

Co-authored-by: Lenny Chen <lenny.chen@spectrocloud.com>
Co-authored-by: Yuliia Horbenko <31223054+yuliiiah@users.noreply.github.com>
Co-authored-by: vault-token-factory-spectrocloud[bot] <133815545+vault-token-factory-spectrocloud[bot]@users.noreply.github.com>
Co-authored-by: Yuliia Horbenko <horbenko.yuliya@gmail.com>
Co-authored-by: Karl Cardenas <29551334+karl-cardenas-coding@users.noreply.github.com>

docs/docs-content/clusters/cluster-management/palette-webctl.md

@@ -19,9 +19,9 @@ Use the following steps to connect to your host cluster with the kubectl CLI.
 
 If you are using Palette Virtual Machine (VM) Management, you can find steps on how to connect to your virtual machines
 with the [virtctl CLI](https://kubevirt.io/user-guide/user_workloads/virtctl_client_tool/) in the
-[Access VM Cluster with virtctl](../../vm-management/create-manage-vm/access-cluster-with-virtctl.md) guide. The virtctl
-CLI facilitates some of the VM operations you will perform, such as copying, pasting, or transferring files to and from
-a virtual machine using Secure Copy Protocol (SCP).
+[Access VM Cluster with virtctl](../../vm-management/create-manage-vm/advanced-topics/access-cluster-with-virtctl.md)
+guide. The virtctl CLI facilitates some of the VM operations you will perform, such as copying, pasting, or transferring
+files to and from a virtual machine using Secure Copy Protocol (SCP).
 
 :::
 

docs/docs-content/vm-management/architecture.md

@@ -0,0 +1,90 @@
+---
+sidebar_label: "Architecture"
+title: "Architecture"
+description: "Learn about Palette VMO pack and the architecture behind it."
+hide_table_of_contents: false
+sidebar_position: 0
+tags: ["vmo", "architecture"]
+---
+
+The Palette Virtual Machine Orchestrator (VMO) pack consolidates all components that you need to deploy and manage
+Virtual Machines (VMs) alongside containers in a Kubernetes host cluster. You can deploy VMO as an
+[add-on cluster profile](../profiles/cluster-profiles/create-cluster-profiles/create-addon-profile/create-addon-profile.md)
+on top of an existing data center or edge cluster.
+
+![Diagram that explains the architecture behind Palette VMO.](/vm-management_architecture_vmo-architecture.webp)
+
+For more detailed information about the technical architecture of VMO, refer to
+[Palette VMO Reference Architecture](https://www.spectrocloud.com/resources/whitepaper/vmo-architecture-pdf).
+
+## Palette VMO Components
+
+By default, Palette VMO includes the following components:
+
+- **Descheduler**. Enables VM live migration to different nodes in the node pool when the original node is in
+  maintenance mode.
+
+- **Snapshot Controller**. Enables you to create VM snapshots. This component is automatically installed when you
+  initiate or schedule cluster backups.
+
+  :::info
+
+  Palette installs a snapshot controller into every cluster where backups are scheduled or have been created on-demand
+  in the past. To prevent resource conflicts, you can disable the VMO snapshot controller in the pack YAML
+  configuration.
+
+  ```yaml
+  charts:
+    virtual-machine-orchestrator:
+      snapshot-controller:
+        enabled: false
+  ```
+
+  :::
+
+- **Spectro VM Dashboard**. Enables you to create, manage, and monitor VMs from Palette. The dashboard becomes available
+  once the VMO pack is successfully deployed as part of your cluster profile.
+
+- **KubeVirt**. This open-source solution enables you to create and manage VMs within Kubernetes clusters. KubeVirt
+  extends Kubernetes with additional virtualization resource types using Kubernetes Custom Resource Definitions (CRD)
+  API.
+
+  With KubeVirt, you can use the Kubernetes API to manage VM resources in the same way you would manage standard
+  Kubernetes resources.
+
+  :::tip
+
+  Palette VMO is pre-configured to use a number of KubeVirt feature gates out of the box, and you can configure
+  additional feature gates as necessary. Refer to the [Feature Gates](#feature-gates) section for more information.
+
+  :::
+
+- **KubeVirt CDI**. Provides persistent storage for Kubernetes clusters and enables the use of Persistent Volume Claims
+  (PVCs) as disks for KubeVirt VMs.
+
+- **Volume Snapshot Controller**. Watches VolumeSnapshot CRD objects and manages the creation and deletion of volume
+  snapshots. A snapshot represents a point-in-time copy of a volume.
+
+- **Multus CNI**. Enables multiple network interfaces to attach to Kubernetes pods. In the context of VMO, Multus
+  Controller Network Interface (CNI) automatically creates VLAN interfaces onto which you can place VMs.
+
+### Feature Gates
+
+Palette VMO includes the following KubeVirt feature gates by default:
+
+- LiveMigration
+- Snapshot
+- HotplugVolumes
+- VMExport
+- ExpandDisks
+- HotplugNICs
+- VMLiveUpdateFeatures
+- [CPU Hotplug](./create-manage-vm/enable-cpu-hotplug.md)
+
+For more information on KubeVirt feature gates, refer to the
+[KubeVirt Activating feature gates](https://kubevirt.io/user-guide/cluster_admin/activating_feature_gates/) guide.
+
+## Next Steps
+
+Now that you understand the architecture behind Palette VMO, you can continue exploring it by reviewing our
+[Environment Setup](./environment-setup.md) and [Create a VMO Profile](./create-vmo-profile.md) pages.

docs/docs-content/vm-management/create-manage-vm/_category_.json

@@ -1,3 +1,3 @@
 {
-  "position": 10
+  "position": 40
 }

docs/docs-content/vm-management/create-manage-vm/advanced-topics/_category_.json

@@ -0,0 +1,3 @@
+{
+  "position": 100
+}

docs/docs-content/vm-management/create-manage-vm/access-cluster-with-virtctl.md → docs/docs-content/vm-management/create-manage-vm/advanced-topics/access-cluster-with-virtctl.md

@@ -1,6 +1,6 @@
 ---
-sidebar_label: "Access VM Cluster with virtctl"
-title: "Set up virtctl"
+sidebar_label: "Access VM Cluster with Virtctl"
+title: "Set up Virtctl"
 description: "Set up KubeVirt virtctl to facilitate VM operations in Palette Virtual Machine Orchestrator"
 icon: " "
 hide_table_of_contents: false

docs/docs-content/vm-management/create-manage-vm/advanced-topics/advanced-topics.md

@@ -0,0 +1,23 @@
+---
+sidebar_label: "Advanced Topics"
+title: "Advanced Topics"
+description: "Advanced topics for Palette Virtual Machine Orchestrator."
+icon: " "
+hide_table_of_contents: false
+sidebar_position: 60
+tags: ["vmo"]
+---
+
+Beyond the standard Virtual Machine (VM) operations such as deployment, clone, and migration, Palette Virtual Machine
+Orchestrator (VMO) supports further customization and advanced use cases.
+
+This section discusses advanced topics such as creating and modifying VM template and disk templates. You will also
+learn how to perform standard VM operations via the command-line tool, virtctl, and how to maximize your VM performance
+by over-committing CPU and memory.
+
+## Resources
+
+- [Access VM Cluster with Virtctl](./access-cluster-with-virtctl.md)
+- [Create VM Templates](./create-vm-template.md)
+- [Create DISK Templates](./create-disk-templates.md)
+- [Over-commit Resources to Enhance VM Performance](./vm-oversubscription.md)

docs/docs-content/vm-management/create-manage-vm/create-disk-templates.md → docs/docs-content/vm-management/create-manage-vm/advanced-topics/create-disk-templates.md

@@ -19,16 +19,16 @@ This guide demonstrates how to implement your own disk and VM templates using Ku
 
 ## Prerequisites
 
-- A VMO profile. Check out the [Create a VMO Profile](../vm-packs-profiles/create-vmo-profile.md) guide to learn how you
-  can create this profile.
+- A VMO profile. Check out the [Create a VMO Profile](../../create-vmo-profile.md) guide to learn how you can create
+  this profile.
 - A cluster deployed with this VMO profile. Check out the
-  [Deploy a Cluster](../../clusters/public-cloud/deploy-k8s-cluster.md) tutorial for detailed steps on how you can
+  [Deploy a Cluster](../../../clusters/public-cloud/deploy-k8s-cluster.md) tutorial for detailed steps on how you can
   deploy clusters to a public cloud.
 
 ## Create a Template
 
 1.  Create a new **Add-on Profile** with the following manifest. Check out the
-    [Add a Manifest](../../profiles/cluster-profiles/create-cluster-profiles/create-addon-profile/create-addon-profile.md)
+    [Add a Manifest](../../../profiles/cluster-profiles/create-cluster-profiles/create-addon-profile/create-addon-profile.md)
     guide for more information.
 
     The provided manifest defines a `DataVolume` that imports the example disk template for Ubuntu 22.04 into the
@@ -173,7 +173,7 @@ This guide demonstrates how to implement your own disk and VM templates using Ku
 
 3.  When the CDI clones a PVC, it runs under the `default` service account in the namespace of the target PVC. When the
     source PVC is in a different namespace, you must give the required permissions to the service account. The
-    [VMO pack](../vm-management.md) version 4.2.0 (or higher) does this automatically through its default pack
+    [VMO pack](../../vm-management.md) version 4.2.0 (or higher) does this automatically through its default pack
     specification. This configuration uses the `vmEnabledNamespaces` option to specify the namespaces for which the
     permissions are configured.
 
@@ -327,16 +327,14 @@ This guide demonstrates how to implement your own disk and VM templates using Ku
     ![Add-on Profile](/create-disk-templates-guide/vm-management_create-manage-vm_create-disk-templates_add-on-disk-template-profile.webp)
 
 4.  Once the cluster updates, this VM template is available to the VMs you create on your cluster. Check out the
-    [Deploy VM From a Template](./standard-vm-operations/deploy-vm-from-template.md) guide for more information.
+    [Deploy VM From a Template](../deploy-vm-from-template.md) guide for more information.
 
     ![Create VM from template](/create-disk-templates-guide/vm-management_create-manage-vm_create-disk-templates_create-vm-from-template.webp)
 
 ## Resources
 
 To learn more about the Palette VMO, we encourage you to check out the reference resources below.
 
-- [Virtual Machine Orchestrator Pack](../vm-packs-profiles/vm-packs-profiles.md)
+- [Palette VMO](../../vm-management.md)
 
-- [Standard VM Operations](../create-manage-vm/standard-vm-operations/standard-vm-operations.md)
-
-- [Deploy VM From a Template](../create-manage-vm/standard-vm-operations/deploy-vm-from-template.md)
+- [Deploy VM From a Template](../deploy-vm-from-template.md)

docs/docs-content/vm-management/create-manage-vm/vm-oversubscription.md → docs/docs-content/vm-management/create-manage-vm/advanced-topics/vm-oversubscription.md

@@ -1,6 +1,6 @@
 ---
-sidebar_label: "VM Performance"
-title: "VM Performance"
+sidebar_label: "Over-commit Resources to Enhance VM Performance"
+title: "Over-commit Resources to Enhance VM Performance"
 description: "Learn how to improve VM performance by maximizing virtual machine CPU and memory using Palette."
 icon: " "
 hide_table_of_contents: false
@@ -15,40 +15,52 @@ VM workloads typically have varying resource demands and peak utilization patter
 possible to allocate them flexibly and take advantage of the fact that not all VMs will require their maximum allocation
 simultaneously.
 
-The hypervisor automatically overcommits CPU and memory. This means that more virtualized CPU and memory can be
+The hypervisor automatically over-commits CPU and memory. This means that more virtualized CPU and memory can be
 allocated to VMs than there are physical resources on the system.
 
-## CPU Overcommit
+## Over-commit CPUs
 
 Kubevirt offers the `cpuAllocationRatio` in its Custom Resource Definitions (CRD). This ratio is used to normalize the
 amount of CPU time the pod will request based on the number of virtual CPUs (vCPUs).
 
-Using the following algorithm, when `cpuAllocationRatio` is set to 1, the full amount of vCPUs are requested for the
-pod: `pod CPU request = number of vCPUs * 1/cpuAllocationRatio`.
+### Prerequisites
 
-The `cpuAllocationRatio` is global, so setting it to greater than 1 has the effect of requesting less CPU from
-Kubernetes for each VM.
+- An active VMO cluster in Palette.
 
-Certain workloads that require a predictable latency and enhanced performance would benefit from obtaining dedicated CPU
-resources. KubeVirt relies on the Kubernetes CPU manager to pin vCPUs to the physical host’s CPUs. To learn more, refer
-to [Dedicated CPU Resources](https://kubevirt.io/user-guide/compute/dedicated_cpu_resources/) and
-[Resources Requests and Limits](https://kubevirt.io/user-guide/compute/virtual_hardware/#resources-requests-and-limits)
-Kubevirt documentation.
+### Procedure
+
+1. Log in to [Palette](https://console.spectrocloud.com).
+
+2. From the left **Main Menu**, click on **Profiles**.
+
+3. Select the profile you use to create the cluster with the VMO pack.
+
+4. Select the VMO add-on layer of the cluster profile.
+
+5. Using the following algorithm, when `cpuAllocationRatio` is set to 1, the full amount of vCPUs are requested for the
+   pod: `pod CPU request = number of vCPUs * 1/cpuAllocationRatio`. The `cpuAllocationRatio` is global, so setting it to
+   greater than 1 has the effect of requesting less CPU from Kubernetes for each VM.
+
+   Certain workloads that require a predictable latency and enhanced performance would benefit from obtaining dedicated
+   CPU resources. KubeVirt relies on the Kubernetes CPU manager to pin vCPUs to the physical host’s CPUs. To learn more,
+   refer to [Dedicated CPU Resources](https://kubevirt.io/user-guide/compute/dedicated_cpu_resources/) and
+   [Resources Requests and Limits](https://kubevirt.io/user-guide/compute/virtual_hardware/#resources-requests-and-limits)
+   Kubevirt documentation.
 
 :::warning
 
-- We do not recommend overcommitting CPUs in a production environment without extensive testing. Applications that use
-  100 percent of processing resources may become unstable in overcommitted environments.
+- We do not recommend over-committing CPUs in a production environment without extensive testing. Applications that use
+  100 percent of processing resources may become unstable in over-committed environments.
 
-- Ensure you don't overcommit guest VMs on more than the physical number of processing cores. For example, a guest VM
+- Ensure you don't over-commit guest VMs on more than the physical number of processing cores. For example, a guest VM
   with four vCPUs should only be deployed on a host physical machine with a quad-core processor instead of a dual-core
   processor.
 
   We recommend no more than 10 total allocated vCPUs per physical processor core.
 
 :::
 
-## Memory Overcommit
+## Over-Commit Memory
 
 KubeVirt allows you to assign more or less memory to a VM than a VM requests to Kubernetes. You may want to overcommit
 VM memory if you have a cluster or a few nodes that are dedicated to running VMs. In this case, overcommitting memory
@@ -57,9 +69,13 @@ makes use of all the memory in the nodes regardless of reserved or requested mem
 To learn about options for memory overcommitment, refer to
 [Node Overcommit](https://kubevirt.io/user-guide/compute/node_overcommit/) KubeVirt resource.
 
-You can make several changes to reduce the memory footprint and overcommit the per-VMI memory overhead.
+### Prerequisites
+
+### Procedure
+
+You can make several changes to reduce the memory footprint and over-commit the per-VMI memory overhead.
 
-- Enable guest overhead overcommit by setting `spec.domain.resources.overcommitGuestOverhead` to true.
+- Enable guest overhead over-commit by setting `spec.domain.resources.overcommitGuestOverhead` to true.
 
 - Enable guest memory by setting `spec.domain.memory.guest` to a value higher than
   `spec.domain.resources.requests.memory`, as shown in the example.

docs/docs-content/vm-management/create-manage-vm/clone-vm.md

@@ -0,0 +1,56 @@
+---
+sidebar_label: "Clone a VM"
+title: "Clone a VM"
+description: "Learn how to clone a VM from a template using Palette Virtual Machine Orchestrator."
+icon: " "
+hide_table_of_contents: false
+sidebar_position: 40
+tags: ["vmo"]
+---
+
+A VM clone is a copy of an existing virtual machine (VM). The cloned VM has the same configuration settings and
+identifiers as the parent VM. After you clone a VM, the cloned VM acts as a separate virtual machine.
+
+Cloning is a quick way to create a new virtual machine that shares the same properties as the parent. You may want to
+clone a VM for the following reasons:
+
+- Software testing. Developers can clone an active VM to test new changes to their code.
+
+- Forensics. Security administrators can clone an infected machine and connect it to an air-gaped network to investigate
+  the source of the infection while the parent VM can be destroyed or remediated.
+
+## Prerequisites
+
+- An active cluster in Palette with the Virtual Machine Orchestrator (VMO) pack.
+
+- Outbound internet connectivity for port 443 is allowed so that you and your applications can connect with the Spectro
+  Cloud reverse proxy.
+
+- Users or groups must be mapped to a Virtual Machine RBAC role. You can create a custom role through a manifest and use
+  Palette's RoleBinding feature to associate users and groups with the role. Refer to the
+  [Create Role Bindings](../../clusters/cluster-management/cluster-rbac.md#create-role-bindings) guide to learn more.
+
+- A namespace for VMs. Although you can deploy VMs from the default namespace, we recommend creating at least one
+  namespace dedicated to VMs as a way to organize and manage them. To learn how to create a namespace, check out
+  [Create a Namespace](../../clusters/cluster-management/namespace-management.md#create-a-namespace).
+
+## Clone a VM
+
+1. Log in to [Palette](https://console.spectrocloud.com).
+
+2. From the left **Main Menu**, click **Clusters** and click on your cluster.
+
+3. Click on the **Virtual Machine** tab.
+
+4. Select the VM to clone and click either the **three-dot Menu** or **Actions**.
+
+5. Power off the parent VM and click **Clone**. If you forget to power it off, the parent VM will automatically be
+   powered off while cloning is in progress.
+
+6. Give the clone a name, an optional description, and select a namespace.
+
+7. Optionally, you can enable the checkbox to start the cloned VM automatically when cloning is complete.
+
+## Validate
+
+From the **Virtual Machines** tab, verify the cloned VM is listed and displays **Running** status.