---
features:
  - |
    The libvirt driver now allows specifying individual CPU feature
    flags for guests, via a new configuration attribute
    ``cpu_model_extra_flags`` -- only when used in combination with a
    custom CPU model.

    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' ("Processor-Context ID") to the _guest_ CPU.
    (Assuming that 'PCID' is available in the physical hardware itself.)

    The ``cpu_model_extra_flags`` makes sense only in combination with
    the ``custom`` CPU mode and a named ``cpu_model`` (e.g. "Westmere",
    "Ivybridge", etc).  For example, the following is the way to specify
    the 'PCID' CPU flag for the Intel "IvyBridge" virtual CPU model in
    ``nova.conf``, under the ``[libvirt]`` section::

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

    Note that Nova supports three distinct CPU modes:

    1. ``cpu_mode = "host-model"``: Nova defaults to using this, when
       ``virt_type=kvm|qemu`` is set in ``nova/conf``.  Using this CPU
       mode will make Nova do the right thing w.r.t 'PCID' -- the
       prerequisite for this is that you must have updated packages of
       libvirt, QEMU, Linux kernel and "microcode" to get relevant
       "Meltdown" fixes.

    2. ``cpu_mode = "host-passthrough"``: When using this CPU mode, if
       the 'PCID' feature flag is available in the hardware, it will be
       passed through to the Nova guests.  You need updated "microcode",
       Linux kernel and QEMU updates; libvirt update is not mandatory
       when using this CPU mode to expose 'PCID' for the guest.

    3. ``cpu_mode = "custom"``: As the name implies, this is used to
       configure an explicit, named CPU model.  It is important to note
       that when using the ``custom`` CPU mode:

       - The only virtual (i.e libvirt / QEMU) 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.

upgrade:
  - |
    To make correct use of the newly introduced Nova configuration
    attribute ``cpu_model_extra_flags``, Operators first have to apply
    all the relevant "Meltdown" CVE fixes for various low-level
    components on all relevant Compute nodes.  This includes updating
    "microcode", Linux kernel on the host & guest, libvirt, and QEMU
    packages; followed by a cold reboot (i.e. explicit stop & start) of
    all Nova instances.

    .. note::
        The ``cpu_model_extra_flags`` config option in OpenStack
        "Queens" and "Pike" releases will restrict the choice of CPU
        feature flags to just 'PCID' -- to address the earlier mentioned
        performance degradation.  However, the "Rocky" release will
        remove this restriction, and allow adding (or removing) multiple
        CPU feature flags.