diff --git a/design-proposals/generated-disk-serial.md b/design-proposals/generated-disk-serial.md new file mode 100644 index 00000000..7892adf7 --- /dev/null +++ b/design-proposals/generated-disk-serial.md @@ -0,0 +1,120 @@ +# 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 + +- User wants to use the automated disk serial number assignment to reduce manual configuration. +- User wants each disk to have a unique serial number for applications that need it. + +## 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 + +A 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 + +A new functional test will enable the `generateDiskSerials` option, then it will +run a command in the VM guest to check the serial. + +## Design questions + +- 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?