diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index 535bb19261..955c27783e 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -4925,6 +4925,8 @@ Topics: File: virt-configuring-shared-volumes-for-vms - Name: Migrating VM disks to a different storage class File: virt-migrating-storage-class + - Name: Inserting CD-ROMs in virtual machines + File: virt-inserting-cd-roms-in-virtual-machines - Name: Networking Dir: vm_networking Topics: diff --git a/modules/virt-inserting-a-cd-rom-in-a-vm-by-using-the-command-line.adoc b/modules/virt-inserting-a-cd-rom-in-a-vm-by-using-the-command-line.adoc new file mode 100644 index 0000000000..93c794c701 --- /dev/null +++ b/modules/virt-inserting-a-cd-rom-in-a-vm-by-using-the-command-line.adoc @@ -0,0 +1,85 @@ +:_newdoc-version: 2.18.5 +:_template-generated: 2025-09-11 +:_mod-docs-content-type: PROCEDURE + +// Module included in the following assemblies: +// +// * virt/managing_vms/virtual_disks/virt-inserting-cd-roms-in-virtual-machines.adoc + +[id="virt-inserting-a-cd-rom-in-a-vm-by-using-the-command-line_{context}"] += Inserting a CD-ROM in a live VM by using the command line + +[role="_abstract"] +To make data on a CD-ROM storage device available to a running virtual machine (VM), create a virtual CD-ROM drive in the VM and insert the CD-ROM into the drive as an ISO image. + +Setting up a virtual CD-ROM drive requires rebooting the VM, but afterwards, you can insert and eject ISO images in the drive while the VM is running. +// See https://kubevirt.io/user-guide/storage/hotplug_volumes/#inject-cd-rom for upstream info + +:FeatureName: Inserting and ejecting CD-ROMs in running VMs +include::snippets/technology-preview.adoc[] + +.Prerequisites + +include::snippets/virt-cdrom-feature-gate-requirements.adoc[] + +* You have an ISO image of a CD-ROM available in the cluster. + +.Procedure + +. Run the following command to edit the configuration of the VM in which you want to insert the CD-ROM: ++ +[source,terminal] +---- +$ oc edit vm -n +---- ++ +where: + +* `` is the name of the VM +* `` is the name of the project name space that contains the VM + +. Add a `cdrom` disk to the `spec.template.spec.domains.devices.disks` section of the VM configuration. For example: ++ +[source,yaml] +---- +apiVersion: kubevirt.io/v1 +kind: VirtualMachine +metadata: + name: example-vm +spec: + runStrategy: Always + template: + spec: + domain: + devices: + disks: + - cdrom: + bus: sata + name: cdrom +---- + +. If the VM is running, shut it down. + +. Insert a CD-ROM volume in the `spec.template.spec.volumes` section of the VM configuration. For example: ++ +[source,yaml] +---- +apiVersion: kubevirt.io/v1 +kind: VirtualMachine +metadata: + name: example-vm +spec: + template: + spec: + volumes: + - dataVolume: + name: cdrom-example + hotpluggable: true + name: cdrom +---- ++ +You can insert a CD-ROM this way while the VM is running, but the dataVolume must have the `hotpluggable: true` parameter set. + +. Optional: In the guest operating system, verify that the CD-ROM has been detected. + +. Optional: Eject the CD-ROM volume. To do so, remove the `cdrom` volume from the `spec.template.spec.volumes` section of the VM configuration. You can do this while the VM is running. \ No newline at end of file diff --git a/modules/virt-inserting-a-cd-rom-in-a-vm-by-using-the-web-console.adoc b/modules/virt-inserting-a-cd-rom-in-a-vm-by-using-the-web-console.adoc new file mode 100644 index 0000000000..4d9719530a --- /dev/null +++ b/modules/virt-inserting-a-cd-rom-in-a-vm-by-using-the-web-console.adoc @@ -0,0 +1,60 @@ +:_newdoc-version: 2.18.5 +:_template-generated: 2025-09-11 +:_mod-docs-content-type: PROCEDURE + +// Module included in the following assemblies: +// +// * virt/managing_vms/virtual_disks/virt-inserting-cd-roms-in-virtual-machines.adoc + +[id="virt-inserting-a-cd-rom-in-a-vm-by-using-the-web-console_{context}"] += Inserting a CD-ROM in a live VM by using the web console + +[role="_abstract"] +To make data on a CD-ROM storage device available to a running virtual machine (VM), create a virtual CD-ROM drive in the VM and insert the CD-ROM into the drive as an ISO image. + +Setting up a virtual CD-ROM drive requires rebooting the VM, but you can insert and eject ISO images in the drive while the VM is running. + +:FeatureName: Inserting and ejecting CD-ROMs in running VMs +include::snippets/technology-preview.adoc[] + +.Prerequisites + +include::snippets/virt-cdrom-feature-gate-requirements.adoc[] + +.Procedure + +. In the {product-title} web console, go to *Virtualization* → *VirtualMachines*. + +. Click the name of the VM in which you want to insert the CD-ROM. + +. On the VM details page, click the *Configuration* tab. + +. Open the *Storage* pane. + +. Click *Add*. ++ +A drop-down menu opens. + +. Click *CD-ROM*. + +. In the *Name* field, add a name for the CD-ROM drive device. + +. Select the ISO image to add to the drive as a CD-ROM volume. To do so, click the drop-down button, and select from the volumes available in the cluster. ++ +Alternatively, you can upload a new ISO file and insert it into the CD-ROM drive after it is created. To do so: + +.. Ensure that the *Upload a new ISO file to the cluster* line is checked. +.. Drag and drop an ISO file in the *Upload ISO* field, or click *Upload* and select the ISO image that you want to upload. +.. In the *Upload mode* field, select *Mount uploaded ISO as DataVolume*. + +. Click *Add*. ++ +The CD-ROM drive is added to the *Storage* list. + +. If the VM is running, shut it down or restart it. + +. To insert the ISO file attached to the CD-ROM drive as a CD-ROM volume into the VM, click the Options menu {kebab} next to the CD-ROM drive, and click *Inject*. You can do this while the VM is running. + +. Optional: In the guest operating system, verify that the CD-ROM has been detected. + +. Optional: To eject the CD-ROM from the VM, click the Options menu {kebab} next to the CD-ROM device in the web console, and select *Eject*. You can do this while the VM is running. diff --git a/snippets/virt-cdrom-feature-gate-requirements.adoc b/snippets/virt-cdrom-feature-gate-requirements.adoc new file mode 100644 index 0000000000..0d59ce1e05 --- /dev/null +++ b/snippets/virt-cdrom-feature-gate-requirements.adoc @@ -0,0 +1,34 @@ +//This snippet appears in the following modules & assemblies: +// +// * modules/virt-inserting-a-cd-rom-in-a-vm-by-using-the-command-line.adoc +// * modules/virt-inserting-a-cd-rom-in-a-vm-by-using-the-command-line.adoc + +:_mod-docs-content-type: SNIPPET + +* The `DeclarativeHotplugVolumes` feature gate must be enabled. To ensure this, the `HyperConverged` CR must contain the `declarativeHotplugVolumes: true` line in the `spec.featureGates` configuration section: ++ +[source,yaml,subs="attributes+"] +---- +apiVersion: hco.kubevirt.io/v1 +kind: HyperConverged +metadata: + name: kubevirt-hyperconverged + namespace: {CNVNamespace} +spec: + featureGates: + declarativeHotplugVolumes: true +---- + +* The `HotplugVolumes` feature gate must be disabled. This feature gate is required for using ephemeral volumes, but is incompatible with `DeclarativeHotplugVolumes`. ++ +[source,yaml,subs="attributes+"] +---- +apiVersion: hco.kubevirt.io/v1 +kind: HyperConverged +metadata: + name: kubevirt-hyperconverged + namespace: {CNVNamespace} +spec: + featureGates: + HotplugVolumes: false +---- diff --git a/virt/managing_vms/virtual_disks/virt-inserting-cd-roms-in-virtual-machines.adoc b/virt/managing_vms/virtual_disks/virt-inserting-cd-roms-in-virtual-machines.adoc new file mode 100644 index 0000000000..23d687b27a --- /dev/null +++ b/virt/managing_vms/virtual_disks/virt-inserting-cd-roms-in-virtual-machines.adoc @@ -0,0 +1,36 @@ +:_newdoc-version: 2.18.5 +:_template-generated: 2025-09-11 +:_mod-docs-content-type: ASSEMBLY + +[id="virt-inserting-cd-roms-in-virtual-machines"] += Inserting CD-ROMs in live virtual machines + +include::_attributes/common-attributes.adoc[] +:context: virt-inserting-cd-roms-in-virtual-machines + +toc::[] + +[role="_abstract"] +To attach a storage device to a virtual machine (VM) without rebooting the VM, you can configure a VM to use a virtual CD-ROM drive, and insert an ISO image in the drive. + +This also makes it possible to install an operating system from a CD-ROM in the VM. + +:FeatureName: Inserting and ejecting CD-ROMs in running VMs +include::snippets/technology-preview.adoc[] + +//// +Ticket: https://issues.redhat.com/browse/CNV-7383 + +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/CDROM from my desktop to the VM without the need to reboot the VM +* As a VM Owner I want to attach a Container-Disk-ISO from the registry to my 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 +//// + + +include::modules/virt-inserting-a-cd-rom-in-a-vm-by-using-the-command-line.adoc[leveloffset=+1] + +include::modules/virt-inserting-a-cd-rom-in-a-vm-by-using-the-web-console.adoc[leveloffset=+1] +