design-proposal: persist-vmi-firmware-uuid

This proposal introduces a mechanism to make the firmware UUID of a
Virtual Machine in KubeVirt universally unique.
It ensures the UUID remains consistent across VM restarts, preserving
stability and reliability.

Signed-off-by: Daniel Sionov <[email protected]>

design-proposals/persist-vmi-firmware-uuid.md

@@ -0,0 +1,108 @@
+# Overview
+This proposal introduces a mechanism to make the firmware UUID of a Virtual Machine in KubeVirt universally unique.
+It ensures the UUID remains consistent across VM restarts, preserving stability and reliability.
+
+## Motivation
+* Duplicate UUIDs cause burden with third-party automation frameworks such as Gitops tools, making it difficult to maintain unique VM UUID. 
+  Such tools have to manually assign unique UUIDs to VMs, thus also manage them externally. (issue)
+* The non-persistent nature of UUIDs may trigger redundant cloud-init setup upon VM restore. (issue)
+* The non-persistent nature of UUIDs may trigger redundant license activation events during VM lifetime i.e. Windows key activation re-occur when power off and power on the VM.
+
+## Goals
+* Improve the uniqueness of the VMI firmware UUID to become independent of the VM name and namespace.
+* Maintain the UUID persistence over the VM lifecycle.
+* Maintain backward compatibility
+
+## Non Goals
+* Maintain UUID persistence with VM backup/restore.
+* Change UUID of currently existing VMs
+
+## Definition of Users
+VM owners: who require consistent firmware UUIDs for their applications.
+cluster-admin: to ensure VMs have universally unique firmware IDs
+
+## User Stories
+### Supported cases:
+* Creating and Starting a New VM
+* starting existing VM that was not running
+
+
+## Repos
+Kubevirt/kubevirt
+
+
+## Proposed Solution
+
+### Description
+The firmware UUID persistence mechanism will operate as follows:
+
+1. **New VMs**:
+    - If the firmware UUID is not explicitly defined in `vm.spec.template.spec.firmware.uuid`, the mutator webhook will automatically set the firmware UUID to the value of `vm.metadata.uid`.
+
+2. **Existing VMs**:
+    - For VMs created before the upgrade, the VM controller will patch the `vm.spec.template.spec.firmware.uuid` field,
+   with a value calculated using the legacy logic (based on the VM name).
+   This ensures backward compatibility.
+
+3. **Mitigation**:
+    - Backups created before the implementation of this mechanism will result in VMs receiving a new UUID upon restore, as the firmware UUID field will be absent in older backups.
+    - Users must be aware of this limitation and plan accordingly.
+
+### Workflow
+1. **Mutator Webhook**:
+    - During the creation of a new VM, if the `vm.spec.template.spec.firmware.uuid` field is not set, the webhook will set it to `vm.metadata.uid`.
+
+2. **Controller Logic**:
+    - For existing VMs:
+        - If the firmware UUID field is absent, the controller will calculate the UUID using the legacy logic and patch the VM template spec.
+        - This ensures backward compatibility without disrupting existing workflows.
+
+3. **Backup and Restore**:
+    - Backups created before this mechanism will not include the firmware UUID, leading to new UUIDs being generated upon restore.
+    - Users must be aware of this limitation and plan accordingly.
+
+--- 
+
+
+## Scalability
+The proposed changes have no anticipated impact on scalability capabilities of the KubeVirt framework
+
+## Update/Rollback Compatibility
+Backups created before implementing the persistent firmware UUID mechanism will not include the firmware UUID in the VM's spec.
+As a result, restoring such backups will generate a new UUID for the VM.
+This change may lead to compatibility issues for workloads or systems that rely on consistent UUIDs, such as licensing servers or configuration management systems.
+Users are advised to take this into consideration and plan backup and restore operations accordingly. 
+
+## Testing
+
+### Existing Tests
+- Verify that a newly created VMI has a unique firmware UUID assigned.
+- Ensure the UUID persists across VMI restarts.
+
+### Scenarios Needing Coverage
+
+1. **Old VM Patching**:  
+   Validate that old VMs without a firmware UUID receive one calculated using the legacy logic.
+
+2. **New VM Creation**:  
+   Verify that the firmware UUID is set to `vm.metadata.uid` when not explicitly defined.
+
+
+# Implementation Phases
+
+1. **Alpha Phase**
+    - Persist firmware UUID in the `VM` template spec field.
+    - Implement logic for:
+        - **New VMs**: Auto-generate and store UUID using `vm.metadata.uid` if not explicitly provided.
+        - **Existing VMs**: Patch the `vm.spec.template.spec.firmware.uuid` field using the legacy calculation.
+    - Cover implementation with unit tests.
+
+2. **Beta Phase**
+    - Ensure seamless upgrade compatibility for pre-existing VMs.
+    - Communicate changes through release notes and detailed documentation.
+
+3. **GA Phase**
+    - Consider deprecating the legacy logic in the future and communicate timelines accordingly.
+
+4. **Feature Gate**
+    - **No Feature Gate Protection**: The behavior will be enabled by default upon implementation.