design-proposal: Generating disk serial numbers

This design introduces automatic generation of serial
numbers for disks.

Signed-off-by: Andrej Krejcir <[email protected]>

design-proposals/generated-disk-serial.md

@@ -0,0 +1,151 @@
+# Overview
+This proposal introduces a new feature in KubeVirt to automatically
+generate serial numbers for each disk attached to a virtual machine.
+
+## Motivation
+Some applications running in the VM require the disk serial number to be defined and persistent across reboots.
+Generating the serial reduces manual configuration, and in the future it can be part of a `VirtualMachinePreference` for the OS. 
+
+## Goals
+- Add an option to the VM's `.spec` that will enable automatic serial number generation for disks that
+  don't have a serial number specified.
+
+- Generate unique serial numbers for each disk. The number has to be unique compared to all other disks attached
+  to all VMs with this disk.
+
+- Don't store the serial number in the VM's `.spec`. It would confuse gitops operators.
+
+- The serial number should remain the same across storage migration.
+
+## Non Goals
+
+- No customization options for serial number format.
+
+## Definition of Users
+
+- VM owners
+
+## User Stories
+
+- As a VM owner, I want to use the automated disk serial number assignment to reduce manual configuration.
+- As a VM owner, I want each disk to have a unique serial number for applications that need it.
+- As a VM owner, I want to use a `VirtualMachinePreference` that is properly configured for the OS without
+  knowing about disk serial numbers.
+
+## Repos
+- [kubevirt](https://github.com/kubevirt/kubevirt)
+
+# Design
+
+A new boolean option `generateDiskSerials` will be added to the VMI `.spec`. 
+When it is set to `true`, kubevirt will generate a serial number for each disk, that does not have one specified.
+These serial numbers will then be set in the libvirt domain xml.
+
+## Persistence of generated serial numbers  
+
+The serial number has to be the same across VM restarts and storage migration,
+so it has to be stored somewhere, or generated deterministically.
+
+One possibility is to store it in an annotation on the PVC object.
+The annotation would be created when the VMI is created. 
+Then it will be read by `virt-handler` when creating libvirt domain XML.
+
+### Other persistence options
+There are several other options where to persist the serial number:
+
+- **Deterministic generation**: We can use name and namespace, or UID fields of the PVC
+  to deterministically generate a serial number. This could be an issue for storage migration,
+  if these values change.
+
+- **Storing the serial in a ConfigMap**: We can create a ConfigMap that would store all disk serials for a VM.
+  Then it would be simple to generate serials for disks that don't use PVC source. However, creating a ConfigMap
+  and keeping it in sync with the VM is additional complexity.
+
+- **Storing the serial inside the disk**: The serial could be stored as a file inside the disk.
+  This would probably only work for filesystem PVCs.
+
+## API Examples
+
+### Existing API to set serial number manually
+
+The serial number can be specified manually in VM spec here:
+```yaml
+apiVersion: kubevirt.io/v1
+kind: VirtualMachine
+metadata:
+  name: example-vm
+spec:
+  template:
+    spec:
+      domain:
+        devices:
+          disks:
+            - name: disk
+              serial: 1234567890 # <-- serial number
+              disk:
+                bus: virtio
+      volumes:
+        - name: disk
+          persistentVolumeClaim:
+            claimName: example-pvc
+```
+
+### New API
+
+To enable the serial generation, new filed `generateDiskSerials` will be added to the VMI `.spec`:
+```yaml
+apiVersion: kubevirt.io/v1
+kind: VirtualMachine
+metadata:
+  name: example-vm
+spec:
+  template:
+    spec:
+      domain:
+        devices:
+          generateDiskSerials: true # <-- new field
+          disks:
+            - name: disk
+              disk:
+                bus: virtio
+      volumes:
+        - name: disk
+          persistentVolumeClaim:
+            claimName: example-pvc
+```
+
+The generated serial will be stored as an annotation in the PVC:
+```yaml
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: example-pvc
+  annotations:
+    kubevirt.io/disk-serial: 123456789 # <-- new annotation
+spec:
+  accessModes:
+    - ReadWriteMany
+  resources:
+    requests:
+      storage: 10Gi
+```
+
+## Scalability
+Serials are generated during VMI creation, if the annotation does not exist.
+
+## Update/Rollback Compatibility
+The feature is backward compatible. Existing VMs remain unaffected unless the new field is set.
+Rollback ignores the new field.
+
+## Functional Testing Approach
+
+There are already functional tests to check disk serial that
+is specified manually. We can copy these tests and enable `generateDiskSerials`
+field instead of specifying serial manually.
+
+## Design questions
+
+- Do we want the serials to be generated by default on all VMs,
+  or do we want a configuration option to enable it?
+- Where is a good place for the `generateDiskSerials` field?
+- It is a good idea to store the serial in an annotation, or a different approach is better?