Bug 1369753

It is important to understand the difference between the CDROM device and the CDROM disk. The operations that you most likely want to perform is inserting, changing or ejecting the CDROM disk. To do so you should always use the /vms/{vm:id}/cdrom/{cdrom:id} resource, and the PUT method. It is also important to understand that you can manage the CDROM disk that is currently visible to the running VM, the "current" CDROM disk, and the CDROM disk that will be visible next time the VM is started.

To insert/change a disk visible to the running VM:

  PUT /vms/{vm:id}/cdroms/{cdrom:id};current=true
  <cdrom>
    <file id="mycd.iso"/>
  </cdrom>

To eject the disk currently visible to the running VM:

  PUT /vms/{vm:id}/cdroms/{cdrom:id};current=true
  <cdrom>
    <file id=""/>
  </cdrom>

None of these persists, it only affects the currently running VM. To make the change persistent, after the next boot of the virtual machine, add the "current=false" parameter (or just omit it).

To persistently set the CDROM disk visible after next boot:

  PUT /vms/{vm:id}/cdrom/{cdrom:id}
  <cdrom>
    <file id="mycd.iso"/>
  </cdrom>

To persistently remove the CDROM visible after next boot:

  PUT /vms/{vm:id}/cdrom/{cdrom:id}
  <cdrom>
    <file id=""/>
  </cdrom>

Note that in all cases you should use the PUT method.

The POST and DELETE methods should work with the CDROM devices, but the don't because virtual machines have exactly one CDROM device. These methods try instead to insert and eject the disks, which causes confusion. They should probably be removed.

The DELETE method has also other problem, derived from its implementation in Resteasy, it won't be selected if you specify a "Content-Type" header. You can try it without header, and should work, but it isn't the recommended way to eject the disk, try PUT with an empty <file id=""/> instead.

With the Python SDK the way to do this is to first get the CDROM device:

  cd = vm.cdroms.list()[0]

And then update it.

To insert/change the current disk:

  cd.set_file(params.File(id="mycd.iso"))
  cd.update(current=True)
  
To eject the current disk:

  cd.set_file(params.File(id=""));
  cd.update(current=True)

To insert/change the persisted disk:

  cd.set_file(params.File(id="mycd.iso"))
  cd.update()

To eject the persisted disk:

  cd.set_file(params.File(id=""))
  cd.update()

Please check if this works correctly.

I'm trying to clarify the usage of this part of the API here:

  Improve the documentation of the VM CDROMs services
  https://gerrit.ovirt.org/62848

(In reply to Juan Hernández from comment #3)
> It is important to understand the difference between the CDROM device and
> the CDROM disk. The operations that you most likely want to perform is
> inserting, changing or ejecting the CDROM disk. To do so you should always
> use the /vms/{vm:id}/cdrom/{cdrom:id} resource, and the PUT method. It is
> also important to understand that you can manage the CDROM disk that is
> currently visible to the running VM, the "current" CDROM disk, and the CDROM
> disk that will be visible next time the VM is started.
> 
> To insert/change a disk visible to the running VM:
> 
>   PUT /vms/{vm:id}/cdroms/{cdrom:id};current=true
>   <cdrom>
>     <file id="mycd.iso"/>
>   </cdrom>
> 
> To eject the disk currently visible to the running VM:
> 
>   PUT /vms/{vm:id}/cdroms/{cdrom:id};current=true
>   <cdrom>
>     <file id=""/>
>   </cdrom>
> 
> None of these persists, it only affects the currently running VM. To make
> the change persistent, after the next boot of the virtual machine, add the
> "current=false" parameter (or just omit it).
> 
> To persistently set the CDROM disk visible after next boot:
> 
>   PUT /vms/{vm:id}/cdrom/{cdrom:id}
>   <cdrom>
>     <file id="mycd.iso"/>
>   </cdrom>
> 
> To persistently remove the CDROM visible after next boot:
> 
>   PUT /vms/{vm:id}/cdrom/{cdrom:id}
>   <cdrom>
>     <file id=""/>
>   </cdrom>
> 
> Note that in all cases you should use the PUT method.
> 
> The POST and DELETE methods should work with the CDROM devices, but the
> don't because virtual machines have exactly one CDROM device. These methods
> try instead to insert and eject the disks, which causes confusion. They
> should probably be removed.
> 
> The DELETE method has also other problem, derived from its implementation in
> Resteasy, it won't be selected if you specify a "Content-Type" header. You
> can try it without header, and should work, but it isn't the recommended way
> to eject the disk, try PUT with an empty <file id=""/> instead.
> 
> With the Python SDK the way to do this is to first get the CDROM device:
> 
>   cd = vm.cdroms.list()[0]
> 
> And then update it.
> 
> To insert/change the current disk:
> 
>   cd.set_file(params.File(id="mycd.iso"))
>   cd.update(current=True)
>   
> To eject the current disk:
> 
>   cd.set_file(params.File(id=""));
>   cd.update(current=True)
> 
> To insert/change the persisted disk:
> 
>   cd.set_file(params.File(id="mycd.iso"))
>   cd.update()
> 
> To eject the persisted disk:
> 
>   cd.set_file(params.File(id=""))
>   cd.update()
> 
> Please check if this works correctly.

Works as as explained. Thank you.

The documentation has been improved in the specification of the API. This bug will be moved to MODIFIED when the server is updated to use the version 4.1.11 or newer of the specification.

Verified on ovirt-engine-setup-4.1.1-0.0.master