manage: Add image_property commands

This adds an image property show and image property set command to
nova-manage to allow users to update image properties stored for an
instance in system metadata without having to rebuild the instance.
This is intended to ease migration to new machine types, as updating
the machine type could potentially invalidate the existing image
properties of an instance.

Co-Authored-By: melanie witt <[email protected]>

Blueprint: libvirt-device-bus-model-update

Change-Id: Ic8783053778cf4614742186e94059d5675121db1

Author: lyarwood

doc/source/admin/hw-machine-type.rst

@@ -25,6 +25,10 @@ hw_machine_type - Configuring and updating QEMU instance machine types
 
    Added ``nova-manage`` commands to control the machine_type of an instance.
 
+.. versionchanged:: 25.0.0 (Yoga)
+
+   Added ``nova-manage`` commands to set the image properties of an instance.
+
 .. note::
 
    The following only applies to environments using libvirt compute hosts.
@@ -135,3 +139,30 @@ Once it has been verified that all instances within the environment or specific
 cell have had a machine type recorded then the
 :oslo.config:option:`libvirt.hw_machine_type` can be updated without impacting
 existing instances.
+
+Device bus and model image properties
+-------------------------------------
+
+.. versionadded:: 25.0.0 (Yoga)
+
+Device bus and model types defined as image properties associated with an
+instance are always used when launching instances with the libvirt driver.
+Support for each device bus and model is dependent on the machine type used and
+version of QEMU available on the underlying compute host. As such, any changes
+to the machine type of an instance or version of QEMU on a host might suddenly
+invalidate the stored device bus or model image properties.
+
+It is now possible to change the stored image properties of an instance without
+having to rebuild the instance.
+
+To show the stored image properties of an instance:
+
+.. code-block:: shell
+
+    $ nova-manage image_property show $instance_uuid $property
+
+To update the stored image properties of an instance:
+
+.. code-block:: shell
+
+    $ nova-manage image_property set $instance_uuid --property $property

doc/source/cli/nova-manage.rst

@@ -1668,6 +1668,91 @@ within an environment.
    * - 3
      - Instances found without ``hw_machine_type`` set
 
+Image Property Commands
+=======================
+
+image_property show
+-------------------
+
+.. program:: nova-manage image_property show
+
+.. code-block:: shell
+
+    nova-manage image_property show [INSTANCE_UUID] [IMAGE_PROPERTY]
+
+Fetch and display the recorded image property ``IMAGE_PROPERTY`` of an
+instance identified by ``INSTANCE_UUID``.
+
+.. versionadded:: 25.0.0 (Yoga)
+
+.. rubric:: Return codes
+
+.. list-table::
+   :widths: 20 80
+   :header-rows: 1
+
+   * - Return code
+     - Description
+   * - 0
+     - Successfully completed
+   * - 1
+     - An unexpected error occurred
+   * - 2
+     - Unable to find instance or instance mapping
+   * - 3
+     - No image property found for instance
+
+image_property set
+------------------
+
+.. program:: nova-manage image_property set
+
+.. code-block:: shell
+
+    nova-manage image_property set \
+        [INSTANCE_UUID] [--property] [IMAGE_PROPERTY]=[VALUE]
+
+Set or update the recorded image property ``IMAGE_PROPERTY`` of instance
+``INSTANCE_UUID`` to value ``VALUE``.
+
+The following criteria must be met when using this command:
+
+* The instance must have a ``vm_state`` of ``STOPPED``, ``SHELVED`` or
+  ``SHELVED_OFFLOADED``.
+
+This command is useful for operators who need to update stored instance image
+properties that have become invalidated by a change of instance machine type,
+for example.
+
+.. versionadded:: 25.0.0 (Yoga)
+
+.. rubric:: Options
+
+.. option:: --property
+
+    Image property to set using the format name=value. For example:
+    ``--property hw_disk_bus=virtio --property hw_cdrom_bus=sata``.
+
+.. rubric:: Return codes
+
+.. list-table::
+   :widths: 20 80
+   :header-rows: 1
+
+   * - Return code
+     - Description
+   * - 0
+     - Update completed successfully
+   * - 1
+     - An unexpected error occurred
+   * - 2
+     - Unable to find instance or instance mapping
+   * - 3
+     - The instance has an invalid ``vm_state``
+   * - 4
+     - The provided image property name is invalid
+   * - 5
+     - The provided image property value is invalid
 
 See Also
 ========

nova/cmd/manage.py

@@ -3192,13 +3192,176 @@ def refresh(self, instance_uuid=None, volume_id=None, connector_path=None):
             return 1
 
 
+class ImagePropertyCommands():
+
+    @action_description(_("Show the value of an instance image property."))
+    @args(
+        'instance_uuid', metavar='<instance_uuid>',
+        help='UUID of the instance')
+    @args(
+        'property', metavar='<image_property>',
+        help='Image property to show')
+    def show(self, instance_uuid=None, image_property=None):
+        """Show value of a given instance image property.
+
+        Return codes:
+        * 0: Command completed successfully.
+        * 1: An unexpected error happened.
+        * 2: Instance not found.
+        * 3: Image property not found.
+        """
+        try:
+            ctxt = context.get_admin_context()
+            im = objects.InstanceMapping.get_by_instance_uuid(
+                ctxt, instance_uuid)
+            with context.target_cell(ctxt, im.cell_mapping) as cctxt:
+                instance = objects.Instance.get_by_uuid(
+                    cctxt, instance_uuid, expected_attrs=['system_metadata'])
+                image_property = instance.system_metadata.get(
+                    f'image_{image_property}')
+                if image_property:
+                    print(image_property)
+                    return 0
+                else:
+                    print(f'Image property {image_property} not found '
+                          f'for instance {instance_uuid}.')
+                    return 3
+        except (
+            exception.InstanceNotFound,
+            exception.InstanceMappingNotFound,
+        ) as e:
+            print(str(e))
+            return 2
+        except Exception as e:
+            print(f'Unexpected error, see nova-manage.log for the full '
+                  f'trace: {str(e)}')
+            LOG.exception('Unexpected error')
+            return 1
+
+    def _validate_image_properties(self, image_properties):
+        """Validate the provided image property names and values
+
+        :param image_properties: List of image property names and values
+        """
+        # Sanity check the format of the provided properties, this should be
+        # in the format of name=value.
+        if any(x for x in image_properties if '=' not in x):
+            raise exception.InvalidInput(
+                "--property should use the format key=value")
+
+        # Transform the list of delimited properties to a dict
+        image_properties = dict(prop.split('=') for prop in image_properties)
+
+        # Validate the names of each property by checking against the o.vo
+        # fields currently listed by ImageProps. We can't use from_dict to
+        # do this as it silently ignores invalid property keys.
+        for image_property_name in image_properties.keys():
+            if image_property_name not in objects.ImageMetaProps.fields:
+                raise exception.InvalidImagePropertyName(
+                    image_property_name=image_property_name)
+
+        # Validate the values by creating an object from the provided dict.
+        objects.ImageMetaProps.from_dict(image_properties)
+
+        # Return the dict so we can update the instance system_metadata
+        return image_properties
+
+    def _update_image_properties(self, instance, image_properties):
+        """Update instance image properties
+
+        :param instance: The instance to update
+        :param image_properties: List of image properties and values to update
+        """
+        # Check the state of the instance
+        allowed_states = [
+            obj_fields.InstanceState.STOPPED,
+            obj_fields.InstanceState.SHELVED,
+            obj_fields.InstanceState.SHELVED_OFFLOADED,
+        ]
+        if instance.vm_state not in allowed_states:
+            raise exception.InstanceInvalidState(
+                instance_uuid=instance.uuid, attr='vm_state',
+                state=instance.vm_state,
+                method='image_property set (must be STOPPED, SHELVED, OR '
+                       'SHELVED_OFFLOADED).')
+
+        # Validate the property names and values
+        image_properties = self._validate_image_properties(image_properties)
+
+        # Update the image properties and save the instance record
+        for image_property, value in image_properties.items():
+            instance.system_metadata[f'image_{image_property}'] = value
+
+        # Save and return 0
+        instance.save()
+        return 0
+
+    @action_description(_(
+        "Set the values of instance image properties stored in the database. "
+        "This is only allowed for " "instances with a STOPPED, SHELVED or "
+        "SHELVED_OFFLOADED vm_state."))
+    @args(
+        'instance_uuid', metavar='<instance_uuid>',
+        help='UUID of the instance')
+    @args(
+        '--property', metavar='<image_property>', action='append',
+        dest='image_properties',
+        help='Image property to set using the format name=value. For example: '
+             '--property hw_disk_bus=virtio --property hw_cdrom_bus=sata')
+    def set(self, instance_uuid=None, image_properties=None):
+        """Set instance image property values
+
+        Return codes:
+        * 0: Command completed successfully.
+        * 1: An unexpected error happened.
+        * 2: Unable to find instance.
+        * 3: Instance is in an invalid state.
+        * 4: Invalid input format.
+        * 5: Invalid image property name.
+        * 6: Invalid image property value.
+        """
+        try:
+            ctxt = context.get_admin_context()
+            im = objects.InstanceMapping.get_by_instance_uuid(
+                ctxt, instance_uuid)
+            with context.target_cell(ctxt, im.cell_mapping) as cctxt:
+                instance = objects.Instance.get_by_uuid(
+                    cctxt, instance_uuid, expected_attrs=['system_metadata'])
+                return self._update_image_properties(
+                    instance, image_properties)
+        except ValueError as e:
+            print(str(e))
+            return 6
+        except exception.InvalidImagePropertyName as e:
+            print(str(e))
+            return 5
+        except exception.InvalidInput as e:
+            print(str(e))
+            return 4
+        except exception.InstanceInvalidState as e:
+            print(str(e))
+            return 3
+        except (
+            exception.InstanceNotFound,
+            exception.InstanceMappingNotFound,
+        ) as e:
+            print(str(e))
+            return 2
+        except Exception as e:
+            print('Unexpected error, see nova-manage.log for the full '
+                  'trace: %s ' % str(e))
+            LOG.exception('Unexpected error')
+            return 1
+
+
 CATEGORIES = {
     'api_db': ApiDbCommands,
     'cell_v2': CellV2Commands,
     'db': DbCommands,
     'placement': PlacementCommands,
     'libvirt': LibvirtCommands,
     'volume_attachment': VolumeAttachmentCommands,
+    'image_property': ImagePropertyCommands,
 }
 
 

nova/exception.py

@@ -736,6 +736,10 @@ class InvalidImageRef(Invalid):
     msg_fmt = _("Invalid image href %(image_href)s.")
 
 
+class InvalidImagePropertyName(Invalid):
+    msg_fmt = _("Invalid image property name %(image_property_name)s.")
+
+
 class AutoDiskConfigDisabledByImage(Invalid):
     msg_fmt = _("Requested image %(image)s "
                 "has automatic disk resize disabled.")