diff --git a/design-proposals/persist-vmi-firmware-uuid.md b/design-proposals/persist-vmi-firmware-uuid.md new file mode 100644 index 00000000..c9b55ce7 --- /dev/null +++ b/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