From b7735b091ca322f01958bd4d4e658d8622a1d054 Mon Sep 17 00:00:00 2001
From: dsionov <dsionov@redhat.com>
Date: Wed, 6 Nov 2024 03:23:53 +0200
Subject: [PATCH] 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 <dsionov@redhat.com>
---
 design-proposals/persist-vmi-firmware-uuid.md | 91 +++++++++++++++++++
 1 file changed, 91 insertions(+)
 create mode 100644 design-proposals/persist-vmi-firmware-uuid.md

diff --git a/design-proposals/persist-vmi-firmware-uuid.md b/design-proposals/persist-vmi-firmware-uuid.md
new file mode 100644
index 00000000..e1f28ff3
--- /dev/null
+++ b/design-proposals/persist-vmi-firmware-uuid.md
@@ -0,0 +1,91 @@
+# 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
+In the current implementation, the firmware UUID of a Virtual Machine Instance (VMI) is generated dynamically during the creation of the VMI. This means that if the generation logic is changed in the future, the VMI may be assigned a different firmware UUID. This behavior can cause issues for applications that depend on a stable UUID.
+Furthermore, we plan to enhance the firmware UUID generation logic to include the VM's Name and Namespace, ensuring uniqueness across different namespaces. However, changing the generation logic could inadvertently assign new UUIDs to existing VMs upon restart, leading to potential disruptions.
+By persisting the firmware UUID in the VM's status, we can maintain consistency across restarts and future-proof existing VMs against changes in the UUID generation logic.
+
+## Goals
+- Persist Firmware UUID: Store the firmware UUID within the VM's status to ensure it remains consistent across VMI restarts.
+- Maintain Backward Compatibility: Ensure that existing VMIs without a persisted firmware UUID continue to operate without issues.
+- Prepare for Future Enhancements: Allow for future changes to the firmware UUID generation logic without impacting existing VMIs.
+
+## Non Goals
+- Changing Firmware UUID Generation Logic Now: This proposal does not include modifying the current firmware UUID generation to incorporate vm.Name and vm.Namespace.
+- Altering VM Spec: No changes will be made to the VM specification or require user intervention to set or manage the firmware UUID.
+
+## 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
+We will introduce a new field FirmwareUUID in the status section of the VirtualMachine resource.
+The virt-controller will use this field to persist the firmware UUID (if its empty)
+
+## API Examples
+**Example VM Status**
+
+```yaml
+apiVersion: kubevirt.io/v1alpha3
+kind: VirtualMachine
+metadata:
+  name: mytestvm
+spec:
+  runningStrategy: Halted
+  template:
+    spec:
+      architecture: arm64
+      domain:
+        devices:
+          disks:
+          - name: disk1
+            disk:
+              bus: virtio
+          interfaces:
+          - name: network1
+            bridge: {}
+      networks:
+              - name: network1
+                multus:
+                  networkName: mytestvm/mytestvm
+      volumes:
+           - name: disk1
+             emptyDisk:
+               capacity: 50G
+status:
+  created: true
+  desiredGeneration: 2
+  observedGeneration: 2
+  printableStatus: ErrImagePull
+  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
+New API so should not affect updates / rollbacks.
+
+## Functional Testing Approach
+first create a vm, start the vm, ensure vm.Status contains firmwareUUID field, and it is populated correctly,
+restart the vmi and verify firmwareUUID has been reused using unit test.
+
+# Implementation Phases
+1. API Extension:
+Add the FirmwareUUID field to the VirtualMachineStatus struct.
+
+2. Controller Logic Update:
+Modify the virt-controller to check for vm.Status.FirmwareUUID.
+Implement logic to persist the UUID when necessary.
+
+3. Testing:
+add unit tests for the new controller logic.
+add functional tests to validate end-to-end functionality.