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,188 @@
+# 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 Virtual Machines Instances (VMIs) in KubeVirt.
+
+### 1. Persist UUID in the VM's Spec Field
+
+**Description:** The UUID is generated when the VMI is being created and is then saved to the VM's spec field.
+
+**Pros:**
+- Straightforward implementation.
+- Avoids the need to introduce new API fields.
+- Fully backward compatible.
+
+**Cons:**
+- Potential misuse of the spec field, which ideally should only reflect the user’s intended configuration.
+- The majority of users may not consider the UUID part of the desired VM state, making this field irrelevant from their perspective.
+- Can lead to longer and more complex VM definitions, impacting readability and management.
+
+---
+
+### 2. Generate a Default UUID via Webhook and Set it to the Spec Field
+
+**Description:** A webhook generates a UUID if the user does not provide one. This UUID is then set in the VM's spec field.
+
+**Pros:**
+- Retains backward compatibility and avoids introducing new API fields.
+
+**Cons:**
+- Same concerns as above about the spec field.
+- Using webhooks to assign defaults can degrade performance, especially with high volumes of VMs, as `virt-api` may become a bottleneck.
+- May compromise scalability, as generating a UUID via webhook adds overhead when multiple VMs start simultaneously.
+
+---
+
+### 3. Create a New Firmware UUID Field in VM Status
+
+**Description:** A new field is added under VM status to store the generated firmware UUID upon first VM boot.
+
+**Pros:**
+- Keeps the spec clean, avoiding unnecessary fields in the user-defined configuration.
+- Provides a clear separation between user configuration (spec) and system-generated information (status).
+
+**Cons:**
+- Introduces a new API field, which could increase API surface area and requires long-term support.
+- New fields may impact system performance and resource load.
+- Adds to API complexity and may reduce readability.
+
+*Note:* To minimize this con, consider setting the UUID as a condition under VM status instead of introducing a separate field.
+
+---
+
+### 4. Introduce a Breaking Change to Ensure Universal Uniqueness
+
+**Description:** Modify UUID generation to a combination of `VM.Name`, `vm.Namespace`, and a random hash
+to ensure that UUIDs are universally unique, even across clusters.
+
+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.
+
+
+### 5. 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.
+
+
+---
+
+## Comparison Summary
+
+Each alternative presents unique advantages and limitations.
+Persisting UUIDs in the spec is simple but potentially misuses the spec field.
+Webhook-generated UUIDs keep compatibility but may degrade performance.
+Adding a new status field is clean but increases API complexity.
+The breaking change ensures uniqueness but demands user adaptation.
+The upgrade-specific persistence approach balances backward compatibility with simplicity
+by limiting changes to existing VMs and enabling a clean post-upgrade implementation.
+
+These alternatives aim to address the need for persistent, globally unique firmware UUIDs
+in a way that best balances stability, performance, and usability for KubeVirt users.
+
+
+## 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"
+```
+
+or persist via status condition
+
+```yaml
+apiVersion: kubevirt.io/v1alpha3
+kind: VirtualMachine
+metadata:
+  name: mytestvm
+status:
+   conditions:
+      - type: FirmwareUUIDPersisted
+        status: "123e4567-e89b-12d3-a456-426614174000"
+        reason: UUIDGenerated
+        message: "Firmware UUID has been generated and persisted"
+        lastTransitionTime: "2024-11-06T01:12:29Z"
+```
+
+
+## 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, or condition) 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, or conditions) 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