Reducing Nova Guest Performance Impact from Applying "Meltdown" Fixes
=====================================================================

Release note
------------

The libvirt driver now allows specifying individual CPU feature
flags for guests, via a new configuration attribute
``[libvirt]/cpu_model_extra_flags`` -- only with ``custom`` as the
``[libvirt]/cpu_model``.  Refer to its documentation in
``nova.conf`` for usage details.

One of the motivations for this is to alleviate the performance
degradation (caused as a result of applying the "Meltdown" CVE
fixes) for guests running with certain Intel-based virtual CPU
models.  This guest performance impact is reduced by exposing the
CPU feature flag 'PCID' ("Process-Context ID") to the *guest* CPU,
assuming that it is available in the physical hardware itself.

Note that besides ``custom``, Nova's libvirt driver has two other
CPU modes: ``host-model`` (which is the default), and
``host-passthrough``.  Refer to the
``[libvirt]/cpu_model_extra_flags`` documentation for what to do
when you are using either of those CPU modes in context of 'PCID'.


Documentation of `cpu_model_extra_flags`
----------------------------------------

This allows specifying granular CPU feature flags when specifying CPU
models.  For example, to explicitly specify the ``pcid``
(Process-Context ID, an Intel processor feature) flag to the "IvyBridge"
virtual CPU model::

    [libvirt]
    cpu_mode = custom
    cpu_model = IvyBridge
    cpu_model_extra_flags = pcid

Currently, the choice is restricted to only one option: ``pcid`` (the
option is case-insensitive, so ``PCID`` is also valid).  This flag is
now required to address the guest performance degradation as a result of
applying the "Meltdown" CVE fixes on certain Intel CPU models.

Note that when using this config attribute to set the 'PCID' CPU flag,
not all virtual (i.e. libvirt / QEMU) CPU models need it:

* The only virtual CPU models that include the 'PCID' capability are
  Intel "Haswell", "Broadwell", and "Skylake" variants.

* The libvirt / QEMU CPU models "Nehalem", "Westmere", "SandyBridge",
  and "IvyBridge" will _not_ expose the 'PCID' capability by default,
  even if the host CPUs by the same name include it.  I.e.  'PCID' needs
  to be explicitly specified when using the said virtual CPU models.

For now, the ``cpu_model_extra_flags`` config attribute is valid only in
combination with ``cpu_mode`` + ``cpu_model`` options.

Besides ``custom``, the libvirt driver has two other CPU modes: The
default, ``host-model``, tells it to do the right thing with respect to
handling 'PCID' CPU flag for the guest -- *assuming* you are running
updated processor microcode, host and guest kernel, libvirt, and QEMU.
The other mode, ``host-passthrough``, checks if 'PCID' is available in
the hardware, and if so directly passes it through to the Nova guests.
Thus, in context of 'PCID', with either of these CPU modes
(``host-model`` or ``host-passthrough``), there is no need to use the
``cpu_model_extra_flags``.