Custom Images

If you are running your own custom images you must adhere to our https://stfc.atlassian.net/l/cp/pB1CEqNQ and our https://stfc.atlassian.net/l/cp/8P9KTje2 policies

Image Metadata

We recommend setting the following image metadata to ensure that your instances run as smoothly as possible

Metadata items are key value pairs. These are shown on the command line as <key>='<value>' in the properties field

These can be added to your images through the OpenStack web interface as Custom items of via the command line with openstack image set --property <property> <image-name-or-uuid> . You can add multiple items at by adding the --property flag multiple times

UEFI Boot Mode

UEFI Boot mode is faster to boot and should be reduce the likelihood of a GPU being disconnected from the VM it is attached to

Check if your image supports UEFI boot mode. The easiest way to tell is to boot the image and run df

If the result includes a /boot/efi partition then it is likely that UEFI boot is supported

The metadata to add for this is

key	value

key	value
hw_firmware_type	'uefi'

QEMU Tools

To try and ensure that VMs shutdown gracefully it is recommended to install qemu-guest-agent within your images. This allows OpenStack to capture certain logs (like dmesg) from your VM and to more cleanly execute shutdown and restart operations. Add the following metadata items to your images

key	value

key	value
hw_qemu_guest_agent	'yes'
os_require_quiesce	'True'

These tell openstack that the image has the guest agent and that it should pause to allow the guest agent to quiesce the disk before shutdown.

Disk configuration

The default disk configuration for an image in OpenStack is not the most optimal

These metadata items tell OpenStack to use the virtio disk controller which is currently the best performing and most reliable

key	value

key	value
hw_scsi_model	'virtio-scsi'
hw_disk_bus	'virtio'

VIF Multiqueue

By default VMs will only use a single vCPU core for networking which limits the throughput of data transfers and the number that can run concurrently. Adding the following metadata tells OpenStack that the VMs can use all of their cores for networking

key	value

key	value
hw_vif_multiqueue_enabled	'True'

Example

To add all of the above to your image ( metadata-test ) you would run:

openstack image set metadata-test \
  --property hw_disk_bus='virtio' \
  --property hw_firmware_type='uefi' \
  --property hw_qemu_guest_agent='yes' \
  --property hw_scsi_model='virtio-scsi' \
  --property hw_vif_multiqueue_enabled='True' \
  --property os_require_quiesce='True'