diff --git a/specs/wallaby/approved/libvirt-stash-instance-machine-type.rst b/specs/wallaby/approved/libvirt-stash-instance-machine-type.rst index ec2ca5415..aca45f30f 100644 --- a/specs/wallaby/approved/libvirt-stash-instance-machine-type.rst +++ b/specs/wallaby/approved/libvirt-stash-instance-machine-type.rst @@ -67,33 +67,33 @@ Use Cases default machine type for a given host architecture to make use of newer models of emulated hardware and features of QEMU. -* As a deployer of an existing OpenStack environment I want to default a new - machine type while not breaking the ABI of existing instances. +* As an operator of an existing OpenStack environment I want to default to a + new machine type while not breaking the ABI of existing instances. * As a user I want to ensure the ABI of my instance remains the same throughout the lifetime of the instance, regardless of default configurable changes made - by deployers or developers. + by an operator or virt driver developers. Proposed change =============== -* Copy the hardcoded machine type defaults from the libvirt driver into the - ``[libvirt]/hw_machine_type`` configurable. - -* Store the used machine type in the instance extras table during the initial - spawn of the instance *or* init_host of the compute service for all running - instances that don't have a ``machine_type`` listed at present. - -* Allow operators to set the machine_type of ``SHELVE_OFFLOADED`` instances via - a ``nova-manage`` command. +* Store the used machine type in the instance system metadata table during the + initial spawn of the instance *or* init_host of the compute service for all + running instances that don't have a ``hw_machine_type`` already stored. * Ensure the stored machine type is used during a hard reboot, move or any other action that results in the domain being redefined aside from a full rebuild of the instance. -* Allow the stored machine_type of a ``SHUTOFF`` instance to be updated by - an admin/operator via a ``nova-manage`` command. Allowing operators to - migrate instances between versioned machine types if an alias is not used. +* Unset the stored machine type during a rebuild allowing a new image defined + machine type or host configured default to be used. + +* Allow operators to get the machine type of instances via a new + ``get_machine_type`` ``nova-manage`` command. + +* Allow operators to set or update the machine type of instances with a + vm_state of ``STOPPED``, ``SHELVED`` or ``SHELVED_OFFLOADED`` via a new + ``update_machine_type`` ``nova-manage`` command. Alternatives ------------ @@ -103,49 +103,9 @@ N/A Data model impact ----------------- -The ``Instance`` object will be extended to include a nullable -``hw_machine_type`` attribute that maps to a simple ``StringField`` stored in -the instance extras table. - -A ``StringField`` is used here as we cannot enumerate all of the possible -values of machine_type as different distributions provide different -versioned machine_types. For example Fedora provides machine types versioned by -the underlying QEMU version, while RHEL provides machine types versioned by the -underlying RHEL version:: - - $ cat /etc/fedora-release - Fedora release 33 (Thirty Three) - $ qemu-system-x86_64 -machine help | grep q35 - q35 Standard PC (Q35 + ICH9, 2009) (alias of pc-q35-5.1) - pc-q35-5.1 Standard PC (Q35 + ICH9, 2009) - pc-q35-5.0 Standard PC (Q35 + ICH9, 2009) - pc-q35-4.2 Standard PC (Q35 + ICH9, 2009) - pc-q35-4.1 Standard PC (Q35 + ICH9, 2009) - pc-q35-4.0.1 Standard PC (Q35 + ICH9, 2009) - pc-q35-4.0 Standard PC (Q35 + ICH9, 2009) - pc-q35-3.1 Standard PC (Q35 + ICH9, 2009) - pc-q35-3.0 Standard PC (Q35 + ICH9, 2009) - pc-q35-2.9 Standard PC (Q35 + ICH9, 2009) - pc-q35-2.8 Standard PC (Q35 + ICH9, 2009) - pc-q35-2.7 Standard PC (Q35 + ICH9, 2009) - pc-q35-2.6 Standard PC (Q35 + ICH9, 2009) - pc-q35-2.5 Standard PC (Q35 + ICH9, 2009) - pc-q35-2.4 Standard PC (Q35 + ICH9, 2009) - pc-q35-2.12 Standard PC (Q35 + ICH9, 2009) - pc-q35-2.11 Standard PC (Q35 + ICH9, 2009) - pc-q35-2.10 Standard PC (Q35 + ICH9, 2009) - - $ cat /etc/redhat-release - Red Hat Enterprise Linux release 8.2 (Ootpa) - $ /usr/libexec/qemu-kvm -machine help | grep q35 - q35 RHEL-8.2.0 PC (Q35 + ICH9, 2009) (alias of pc-q35-rhel8.2.0) - pc-q35-rhel8.2.0 RHEL-8.2.0 PC (Q35 + ICH9, 2009) - pc-q35-rhel8.1.0 RHEL-8.1.0 PC (Q35 + ICH9, 2009) - pc-q35-rhel8.0.0 RHEL-8.0.0 PC (Q35 + ICH9, 2009) - pc-q35-rhel7.6.0 RHEL-7.6.0 PC (Q35 + ICH9, 2009) - pc-q35-rhel7.5.0 RHEL-7.5.0 PC (Q35 + ICH9, 2009) - pc-q35-rhel7.4.0 RHEL-7.4.0 PC (Q35 + ICH9, 2009) - pc-q35-rhel7.3.0 RHEL-7.3.0 PC (Q35 + ICH9, 2009) +The machine type will be stored within the ``Instance`` object under the +``system_metadata`` field that is a ``DictOfNullableStringsField`` using the +key ``hw_machine_type``. REST API impact @@ -191,19 +151,19 @@ Upgrade impact When upgrading to Wallaby from Victoria (or earlier) on startup the libvirt driver will attempt to record the current machine type of each non-deleted -instance residing on the host. This includes ``SHUTOFF``, ``PAUSED`` and +instance residing on the host. This includes ``STOPPED``, ``PAUSED`` and ``SHELVED`` instances. Where possible this will come from a direct query of the underlying guest domain but if one is not found it will instead come from the instance image metadata property ``hw_machine_type``, ``[libvirt]/hw_machine_type`` configurable or legacy hardcoded defaults. For non-deleted instances that are marked as ``SHELVED_OFFLOADED`` and thus -don't reside on a compute host a ``nova-manage`` command will be introduced -that will allow operators/admins to record a machine type. As above this will -rely first on any stored image properties but if non is found will require a -specific machine type to be provided by the caller. +don't reside on a compute host a ``update_machine_type`` ``nova-manage`` +command will be introduced that will allow operators to set a machine +type. As above this will rely first on any stored image properties but if none +is found will require a specific machine type to be provided by the caller. -A ``nova-status`` command will be introduced to allow operators/admins to +A ``nova-status`` command will be introduced to allow operators to determine when all non-deleted instances have had a machine type recorded across an environment. @@ -211,14 +171,26 @@ While the aliased machine types (``q35`` for example) will be documented as the recommended choice admins and operators will be allowed to configure a versioned machine either per image or per architecture on a given compute host. -As a result another ``nova-manage`` command will be introduced to update the -machine type of a given ``SHUTOFF`` instance in the DB, allowing operators and -admins to migrate instances between these versioned machine types overtime -without a full rebuild of the instance. It should be noted that this -command will not allow the machine_type to be changed between actual types of -machine_type, for example ``pc`` to ``q35``. This will continue to require a -full rebuild of the instance using a new image with associated -``hw_machine_type`` image property set. +As a result the same ``update_machine_type`` ``nova-manage`` command used to +set the machine type of ``SHELVED_OFFLOADED`` instances will also be able to +update the machine type of instances with a vm_state of ``STOPPED``, +``SHELVED`` or ``SHELVED_OFFLOADED``. + +This will allow operators to migrate instances between these versioned machine +types overtime without a full rebuild of the instance. + +It should be noted that by default this command will not allow the machine_type +to be changed between actual types of machine_type, for example ``pc`` to +``q35`` or between a newer and older version of a machine type. + +By default both will continue to require a full rebuild of the instance using a +new image with associated ``hw_machine_type`` image property set or once the +``[libvirt]/hw_machine_type`` defaults have been updated on the launching +compute host. + +A ``--force`` flag will be inlcuded to allow operators to force through +changes in both cases with a warning that the operation will likely break the +ABI within the instance once restarted. Implementation ============== @@ -240,9 +212,6 @@ Feature liaison: Work Items ---------- -* Copy the hardcoded machine type defaults into the - ``[libvirt]/hw_machine_type`` configurable. - * Store the used machine type in the instance extras table during the initial spawn of the instance *or* init_host of the compute service for all running instances. @@ -251,19 +220,22 @@ Work Items other action that results in the domain being redefined aside from a full rebuild of the instance. -* Introduce a ``nova-manage`` command to allow operators and admin to set - the recorded machine_type for non-deleted ``SHELVE_OFFLOADED`` - instances. +* Unset the stored machine type during a rebuild allowing a new image defined + machine type or host configured default to be used. + +* Introduce a ``get_machine_type`` ``nova-manage`` command to allow operators + to get the recorded machine_type of an instance. + +* Introduce a ``update_machine_type`` ``nova-manage`` command to allow + operators to set or update the recorded machine_type for a given instance + with a vm_state of ``STOPPED``, ``SHELVED`` or ``SHELVED_OFFLOADED`` allowing + upgrades between versioned machine types over time. * Introduce a ``nova-status`` upgrade check to ensure the machine_type has been updated for all instances residing on a given host in the env or across all hosts. -* Introduce a ``nova-manage`` command to allow operators and admin to update - the recorded machine_type for a given instance, allowing upgrades between - versioned machine types over time. - -* Write extensive operator/admin documentation for the above. +* Write extensive operator documentation for the above. Dependencies ============ @@ -276,14 +248,10 @@ Testing The ``grenade`` job will be extended to ensure the machine_type field is being populated during compute service startup when using the libvirt driver. -Functional tests should also be written to assert the above and failure -behaviour when attempting to change the default before a machine_type has -been registered for all instances on a given compute. - Documentation Impact ==================== -Operator/admin documentation covering the upgrade impact and use of the +Extensive operator documentation covering the upgrade impact and use of the configurable will be written. References