design-proposal: persist-vmi-firmware-uuid

This proposal introduces a mechanism to persist the firmware UUID of a
Virtual Machine Instance (VMI) in KubeVirt. By storing the firmware
UUID, we ensure that it remains consistent across VMI restarts, which is
crucial for applications and services that rely on the UUID for
identification or licensing purposes.

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

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

@@ -0,0 +1,167 @@
+# Overview
+This proposal introduces a mechanism to persist the firmware UUID of a Virtual Machine Instance (VMI) in KubeVirt.
+By storing the firmware UUID, we ensure that it remains consistent across VMI restarts.
+which is crucial for applications and services that rely on the UUID for identification or licensing purposes.
+
+## 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
+* Maintain UUID persistence with VM backup/restore.
+
+## Non Goals
+
+
+## Definition of Users
+End Users: Individuals or organizations running VMs and VMIs on KubeVirt who require consistent firmware UUIDs for their applications.
+
+## User Stories
+As an end-user, I expect my VMI to maintain its identity across restarts.
+
+## Repos
+Kubevirt/kubevirt
+
+# Design
+
+This section provides a range of alternative solutions for implementing a persistent, universally unique firmware UUID for VMIs.
+
+### 1. Persist UUID in the VM's Spec Field
+
+**Description:**
+
+The firmware UUID is generated when the VMI is created and stored in `vm.spec.template.spec.firmware.uuid`.
+
+To prevent disruptions caused by introducing a new generation logic for firmware UUIDs, we propose a multiphase approach:
+* Continue with the current firmware UUID calculation, but store the UUID in spec.
+* use alerts / VM conditions in order to notify the users to restart VMs that do not have firmware UUID in their spec.
+* After a while, let the community know (i.e. via a mail to mailing list) that in the next version firmware UUID must reside in spec.
+* Switch to using vm.metadata.uid as the new firmware UUID (unless a UUID is already provided in the VM's spec, therefore keeping backward compatibility).
+
+This phased approach ensures a smooth transition for users while maintaining backward compatibility and minimizing disruptions to workloads.
+
+**Pros:**
+
+- **Simple Implementation:** Requires minimal changes to existing logic.
+- **Backward Compatibility:** Preserves existing UUIDs by storing them in the spec.
+- **No New API Fields:** Avoids adding new fields to the API.
+
+**Cons:**
+
+- **Spec Misuse:** Spec fields should not store system-generated data.
+- **Low Relevance:** Users may not see the UUID as part of the desired state.
+
+---
+
+### 2. Persist Firmware UUID in VM Status Field
+
+**Description:**
+
+Introduce a new field, vm.status.firmwareUUID, to store the firmware UUID of a VMI.
+The VM controller stores the firmware UUID in `vm.status.firmwareUUID`. This ensures the UUID remains consistent across VM restarts.
+
+- If `vm.spec.template.spec.firmware.uuid` is set, the controller propagates it to `vmi.spec.firmware.uuid`.
+- If not, the controller:
+  - Generates a UUID using `vm.metadata.uid` for new VMs.
+  - Uses `vm.status.firmwareUUID` for restarts.
+- During sync, the controller updates `vm.status.firmwareUUID` using `vmi.spec.firmware.uuid`.
+
+this approach will also be multiphase same as the one above.
+
+**Pros:**
+
+- **Backward Compatibility:** Works with existing VMs without disruption.
+- **GitOps Friendly:** Keeps the spec clean and uses status for system data.
+
+**Cons:**
+
+- **API Expansion:** Adds a new status field, requiring long-term support.
+
+---
+
+### 3. Introduce a Breaking Change to Ensure Universal Uniqueness
+
+**Description:** Modify UUID generation to be taken from `vm.metadata.uid`.
+
+Users would be notified of this change in advance through logs or alerts,
+and optional tooling could be provided to help users preserve their current firmware UUIDs by adding them to the spec.
+
+**Pros:**
+- Ensures universally unique UUIDs, meeting the UUID standard and avoiding conflicts when migrating VMs across clusters.
+- Keeps the spec clean without repurposing fields.
+- Simple to implement without introducing new API fields.
+
+**Cons:**
+- This approach is a breaking change, requiring user intervention to preserve existing UUIDs.
+- Requires additional communication and support, as users may need to update or reconfigure their VMs to prevent disruptions.
+- May necessitate tooling to facilitate UUID preservation for compatibility with existing workloads.
+
+---
+
+### 4. Upgrade-Specific Persistence of Firmware UUID
+
+**Description:** Before upgrading KubeVirt, persist the `Firmware.UUID` of existing VMsin `vm.spec`.
+After the upgrade, any VM without `Firmware.UUID` is considered new.
+For these new VMs, use `vm.metadata.uid` as the firmware UUID if `vm.spec.template.spec.Firmware.UUID` is not defined.
+
+**Pros:**
+- Upgrade-specific code can be removed after two or three releases.
+- Maintains a straightforward logic post-upgrade, with minimal changes required.
+- Limits disturbance to GitOps workflows to pre-existing VMs that had potentially buggy UUID behavior.
+
+**Cons:**
+- Requires additional code (likely in `virt-operator`) to handle the upgrade-specific persistence.
+- Code should be added to the computation of the "restart required" condition, so that it is not raised if vm.Template.Firmware.UUID equals vmi.Firmware.UUID.
+
+---
+
+## What Happens to the Firmware UUID During a Restore?
+* The firmware UUID is part of the VM's spec, or dynamically generated by the VM controller if it is not defined.
+* Snapshots created before implementing the firmware UUID persistence mechanism will not include this field.
+* As a result, during a restore, a new UUID may be generated if the vm.spec.template.spec.firmware.uuid field is absent.
+
+**Note:** Focusing on persistence ensures that existing behavior remains unchanged, avoiding restore issues while laying a foundation for future UUID management enhancements.
+
+
+## API Examples
+**Example uuid persistence within VM Status**
+
+```yaml
+apiVersion: kubevirt.io/v1alpha3
+kind: VirtualMachine
+metadata:
+  name: mytestvm
+status:
+   conditions:
+      - lastProbeTime: "2024-11-06T01:12:29Z"
+        lastTransitionTime: "2024-11-06T01:12:29Z"
+        message: Guest VM is not reported as running
+        reason: GuestNotRunning
+        status: "False"
+        type: Ready
+   created: true
+   runStrategy: Once
+   firmwareUUID: "123e4567-e89b-12d3-a456-426614174000"
+```
+
+## Scalability
+The proposed changes have no anticipated impact on scalability capabilities of the KubeVirt framework
+
+## Update/Rollback Compatibility
+should not affect updates / rollbacks.
+
+## Functional Testing Approach
+Verify that a newly created VMI has a unique firmware UUID assigned and that this UUID persists across VMI restarts.
+Validate that the selected persistence mechanism (spec field, status field) stores the UUID.
+Include unit tests for any logic introduced in controllers to ensure the UUID is generated and persisted correctly.
+
+# Implementation Phases
+- Based on the selected design, either introduce a new field or utilize an existing one 
+(such as in spec, status) to store the firmware UUID.
+- Update controller logic to check for and persist the UUID, ensuring it is generated only once per VM.
+- Testing: add unit and functional tests