Merge "manage: Add image_property commands"

Author: Zuul

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.")