openstack
/
nova-specs
Code Issues Proposed changes

libvirt: Update instance machine type stash spec 

* Replaces references to a new ``hw_machine_type`` Instance object
  attribute with the existing ``system_metadata`` dict. This was
  actually agreed to during the PTG but lost and replaced with the new
  attribute sometime later.

* Drops the move of the hardcoded default machine types into the
  ``[libvirt]/hw_machine_type`` configurable as on review this is not
  actually required to achieve the goals of this spec and would if
  anything make things more complicated when upgrading.

* Lists the new ``nova-manage`` commands and adds ``SHELVED``
  as an allowed vm_state for the ``update_machine_type`` command.

* Lists the default restrictions around updating the machine type via
  the ``update_machine_type`` outside of a full rebuild. These include
  between underlying machine types and from newer to older versions of the
  same machine type.

* Adds a ``--force`` flag to the ``update_machine_type`` command to
  allow operators to workaround these restrictions.

* Drops the reference to the versioned machine types from the data model
  impact section as we are now using ``system_metadata`` that forces us
  to use strings.

* Replaces the incorrect ``SHUTOFF`` vm_state with the correct ``STOPPED``
  state.

* Replaces some incorrect uses of the term deployer and operator/admin
  with operator.

Change-Id: I36d3b544afb33cdeb70dc3f2a9e067904ebfac05
This commit is contained in:
Lee Yarwood 2020-12-21 11:06:53 +00:00 committed by Dan Smith
parent 8d78679dcc
commit 0d58760cdf
1 changed files with 56 additions and 88 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

144
specs/wallaby/approved/libvirt-stash-instance-machine-type.rst
View File

@ -67,33 +67,33 @@ Use Cases
default machine type for a given host architecture to make use of newer default machine type for a given host architecture to make use of newer
models of emulated hardware and features of QEMU. models of emulated hardware and features of QEMU.
* As a deployer of an existing OpenStack environment I want to default a new * As an operator of an existing OpenStack environment I want to default to a
machine type while not breaking the ABI of existing instances. 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 * 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 the lifetime of the instance, regardless of default configurable changes made
by deployers or developers. by an operator or virt driver developers.
Proposed change Proposed change
=============== ===============
* Copy the hardcoded machine type defaults from the libvirt driver into the * Store the used machine type in the instance system metadata table during the
``[libvirt]/hw_machine_type`` configurable. 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.
* 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.
* Ensure the stored machine type is used during a hard reboot, move or any * 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 other action that results in the domain being redefined aside from a full
rebuild of the instance. rebuild of the instance.
* Allow the stored machine_type of a ``SHUTOFF`` instance to be updated by * Unset the stored machine type during a rebuild allowing a new image defined
an admin/operator via a ``nova-manage`` command. Allowing operators to machine type or host configured default to be used.
migrate instances between versioned machine types if an alias is not 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 Alternatives
------------ ------------
@ -103,49 +103,9 @@ N/A
Data model impact Data model impact
----------------- -----------------
The ``Instance`` object will be extended to include a nullable The machine type will be stored within the ``Instance`` object under the
``hw_machine_type`` attribute that maps to a simple ``StringField`` stored in ``system_metadata`` field that is a ``DictOfNullableStringsField`` using the
the instance extras table. key ``hw_machine_type``.
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)
REST API impact REST API impact
@ -191,19 +151,19 @@ Upgrade impact
When upgrading to Wallaby from Victoria (or earlier) on startup the libvirt 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 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 ``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 underlying guest domain but if one is not found it will instead come from
the instance image metadata property ``hw_machine_type``, the instance image metadata property ``hw_machine_type``,
``[libvirt]/hw_machine_type`` configurable or legacy hardcoded defaults. ``[libvirt]/hw_machine_type`` configurable or legacy hardcoded defaults.
For non-deleted instances that are marked as ``SHELVED_OFFLOADED`` and thus 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 don't reside on a compute host a ``update_machine_type`` ``nova-manage``
that will allow operators/admins to record a machine type. As above this will command will be introduced that will allow operators to set a machine
rely first on any stored image properties but if non is found will require a type. As above this will rely first on any stored image properties but if none
specific machine type to be provided by the caller. 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 determine when all non-deleted instances have had a machine type recorded
across an environment. 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 recommended choice admins and operators will be allowed to configure a
versioned machine either per image or per architecture on a given compute host. 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 As a result the same ``update_machine_type`` ``nova-manage`` command used to
machine type of a given ``SHUTOFF`` instance in the DB, allowing operators and set the machine type of ``SHELVED_OFFLOADED`` instances will also be able to
admins to migrate instances between these versioned machine types overtime update the machine type of instances with a vm_state of ``STOPPED``,
without a full rebuild of the instance. It should be noted that this ``SHELVED`` or ``SHELVED_OFFLOADED``.
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 This will allow operators to migrate instances between these versioned machine
full rebuild of the instance using a new image with associated types overtime without a full rebuild of the instance.
``hw_machine_type`` image property set.
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 Implementation
============== ==============
@ -240,9 +212,6 @@ Feature liaison:
Work Items 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 * 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 spawn of the instance *or* init_host of the compute service for all running
instances. instances.
@ -251,19 +220,22 @@ Work Items
other action that results in the domain being redefined aside from a full other action that results in the domain being redefined aside from a full
rebuild of the instance. rebuild of the instance.
* Introduce a ``nova-manage`` command to allow operators and admin to set * Unset the stored machine type during a rebuild allowing a new image defined
the recorded machine_type for non-deleted ``SHELVE_OFFLOADED`` machine type or host configured default to be used.
instances.
* 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 * 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 been updated for all instances residing on a given host in the env or across
all hosts. all hosts.
* Introduce a ``nova-manage`` command to allow operators and admin to update * Write extensive operator documentation for the above.
the recorded machine_type for a given instance, allowing upgrades between
versioned machine types over time.
* Write extensive operator/admin documentation for the above.
Dependencies Dependencies
============ ============
@ -276,14 +248,10 @@ Testing
The ``grenade`` job will be extended to ensure the machine_type field is The ``grenade`` job will be extended to ensure the machine_type field is
being populated during compute service startup when using the libvirt driver. 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 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. configurable will be written.
References References