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,129 @@
+# 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
+By definition, UUID must be a universally-unique identifier.
+The current implementation for the automatically-computed Firmware UUID is not universally unique: 
+Two VMs with the same name get the same UUID, even if they reside in different namespace or different clusters.
+This proposal discusses how to fix this, while ensuring that already-identified VMs keep their current ID.
+
+## Goals
+Generate and persist universally-unique Firmware.UUID for new VMs
+Keep the Firmware.UUID of pre-existing VMs
+
+## 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
+There are a few possible solutions:
+
+1. **Persist UUID in the VM’s Spec Field**  
+   **Description:** The UUID would be generated upon the VM’s first boot and stored in the VM’s spec field.
+
+   **Pros:**
+   - Straightforward to implement.
+   - Avoids adding a new API field, fully backward compatible.
+
+   **Cons:**
+   - This approach "abuses" the spec by storing data not representing the user's desired state.
+   - It may lead to cluttered and harder-to-read VM definitions.
+
+
+2. **Generate UUID via Webhook and Store in the Spec Field**  
+   **Description:** If no UUID is specified by the user, a webhook generates a random UUID and assigns it to the VM’s spec field.
+
+   **Pros:**
+   - Similar to the first option (no new API field, backward compatible).
+
+   **Cons:**
+   - Adds complexity by involving webhooks, which could slow down performance if numerous VMs start simultaneously.
+   - May potentially bottleneck `virt-api`.
+
+
+3. **Add a Firmware UUID Field to VM Status**  
+   **Description:** Store the generated UUID within the VM’s status.
+
+   **Pros:**
+   - Keeps the spec clean.
+   - Focuses on VM status for generated information.
+
+   **Cons:**
+   - Depends on where the uuid will be saved might introduce a new API field, which has implications for long-term maintenance and potential API bloat.
+
+
+4. **Introduce a Breaking Change by Modifying UUID Generation to Include Namespace**  
+   **Description:** The UUID is generated using both VM name and namespace, which would require users to update workloads to prevent conflicts.
+
+   **Pros:**
+   - Maintains a clean spec.
+   - Easy to implement.
+
+   **Cons:**
+   - Requires user action to avoid breaking workloads.
+   - May necessitate warning mechanisms or tooling for transition.
+
+## 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 VMIs 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