From 825f0151db6fce377f46bf5686e65c70eb8f5093 Mon Sep 17 00:00:00 2001 From: Michael Henriksen Date: Tue, 17 Dec 2024 20:33:06 -0500 Subject: [PATCH] Proposal for inject/eject CD-ROM Signed-off-by: Michael Henriksen --- design-proposals/cdrom-inject-eject.md | 173 +++++++++++++++++++++++++ 1 file changed, 173 insertions(+) create mode 100644 design-proposals/cdrom-inject-eject.md diff --git a/design-proposals/cdrom-inject-eject.md b/design-proposals/cdrom-inject-eject.md new file mode 100644 index 00000000..4cda9559 --- /dev/null +++ b/design-proposals/cdrom-inject-eject.md @@ -0,0 +1,173 @@ +# Overview +Proposal for for adding inject/eject CD-ROM support to KubeVirt + +## Motivation +In a world where all of our knowledge has been collected, indexed, and can be served up via a network connection, the humble CD-ROM is still a "thing." And to the dedicated hangers-on of this once ubiquitous technology, KubeVirt's CD-ROM support is lacking in a very fundamental way. Today, a user must reboot a VM in order to change the media in a CD-ROM. That is just. not. right. Fortunately, the virtualization technology that underpins KubeVirt has had this functionality for a long time and we can easily plug it into the KubeVirt API to unleash the full power of the CD-ROM + +## Goals +- Extend existing APIs to support inject/eject CD-ROM operations +- Extend virtctl to have cdrom specific commands +- Support for PersistentVolumeClaim/DataVolume based disk images + +## Non Goals +- Support for any volume type other than DavaVolume/PersistentVolumeClaim + +## Definition of Users +KubeVirt end user, may not be a namespace/cluster admin + +## User Stories +- As a VM owner, I want to be able to attach a CD-ROM for the purposes of installing an operating system, then be able eject the CD and perform a guest-side reboot to use the operating system. +- As a VM Owner I want to attach an ISO/CD-ROM from my desktop to the VM without the need to reboot the VM +- As a VM Owner I want to attach a PVC which contains an ISO to my VM without the need to reboot the VM +- As a VM Owner I want to be able to "eject" (remove) the ISO/CD from my VM without the need to reboot the VM + +## Repos +kubevirt/kubevirt + +# Design +Like most new features in KubeVirt, the building blocks already exist, just have to wire everything together + +## VirtualMachineInstance API +Currently, every disk in a KubeVirt VM must have a corresponding volume. That restriction will be lifted for CD-ROM disks, i.e., it will be possible to define a VMI that has no corresponding volume for a CD-ROM. For Example: + +```yaml +apiVersion: kubevirt.io/v1 +kind: VirtualMachine +... +spec: + domain: + devices: + disks: + - cdrom: + bus: sata + name: cdrom + - disk: + bus: virtio + name: root +... + volumes: + - dataVolume: + name: fedora-root + name: root + networks: +... +``` + +## Volume Hotplug Subresource API +This feature leverages the Volume Hotplug API in order to add/remove disk images in running Pods. Hence, the restriction on PersistentVolumeClaim and DataVolume volume types. + +Hotplug operations are wrapped in the `VirtualMachineVolumeRequest` struct which looks like this: + +```golang +type VirtualMachineVolumeRequest struct { + // AddVolumeOptions when set indicates a volume should be added. The details + // within this field specify how to add the volume + AddVolumeOptions *AddVolumeOptions `json:"addVolumeOptions,omitempty" optional:"true"` + // RemoveVolumeOptions when set indicates a volume should be removed. The details + // within this field specify how to add the volume + RemoveVolumeOptions *RemoveVolumeOptions `json:"removeVolumeOptions,omitempty" optional:"true"` +} +``` + +One of `AddVolumeOptions` or `RemoveVolumeOptions` is expected to be set + +### AddVolumeOptions +`AddVolumeOptions` as currently defined: + +```golang +type AddVolumeOptions struct { + // Name represents the name that will be used to map the + // disk to the corresponding volume. This overrides any name + // set inside the Disk struct itself. + Name string `json:"name"` + // Disk represents the hotplug disk that will be plugged into the running VMI + Disk *Disk `json:"disk"` + // VolumeSource represents the source of the volume to map to the disk. + VolumeSource *HotplugVolumeSource `json:"volumeSource"` + DryRun []string `json:"dryRun,omitempty"` +} +``` + +Currently the `disk` field is required. That restriction will be removed. However, when the `addVolume` request is received, we will validate that the corresponding disk is in fact a CD-ROM. The following request will be valid for the VirtualMachine defined above: + +```yaml +addVolumeOptions: + name: cdrom + volumeSource: + persistentVolumeClaim: + claimName: windows11-iso + hotpluggable: true +``` + +### RemoveVolumeOptions +`RemoveVolumeOptions` as currently defined: + +```golang +type RemoveVolumeOptions struct { + // Name represents the name that maps to both the disk and volume that + // should be removed + Name string `json:"name"` + DryRun []string `json:"dryRun,omitempty"` +} +``` + +Since we don't want to remove the CD-ROM when ejecting a disk, a new field will be added to `RemoveVolumeOptions` to specify whether to keep/remove a disk. + +```golang +// DiskRetentionPolicy defines how removevolume subresource API +// requests should handle the corresponding disk +type DiskRetentionPolicy string + +// DiskRetentionDelete specifies that removevolume should +// delete the matching disk in the VirtualMachineInstance spec +const DiskRetentionDelete = "delete" + +// DiskRetentionKeep specifies that removevolume should +// keep the matching disk in the VirtualMachineInstance spec +const DiskRetentionKeep = "keep" +``` + +A `DiskRetentionPolicy` field will be added to `RemoveVolumeOptions`. It will be optional and if excluded, the default is `DiskRetentionDelete` in order to be compatible with old clients + +This would be the API for ejecting a CD-ROM in the VirtualMachine defined above + +```yaml +removeVolumeOptions: + name: cdrom + diskRetentionPolicy: keep +``` + +## virtctl +A couple new convenience commands will be added to virtctl + +### virtctl cdrom inject +Inject a cdrom + +```bash +virtctl cdrom intect myvm --volume-name=cdrom --claim-name=windows-iso +``` + +### virtctl cdrom eject +Eject a cdrom + +```bash +virtctl cdrom eject myvm --volume-name=cdrom --claim-name=windows-iso +``` + +## Scalability +Nothing new here that should effect system scalability + +## Update/Rollback Compatibility +API changes are backwards compatible +- One field is no longer required +- One field is new + +Rollback would be a problem given the `VirtualMachineInstance` API change. Do we currently support rollback? + +## Functional Testing Approach +- Inject a CD-ROM to a running VM +- Eject a CD-ROM from a running VM +- Boot with hotplug CD-ROM, eject, and inject a different CD-ROM + +# Implementation Phases +This is a small change and will be implemented in one phase