Docs for isolated aggregates request filter

Added reference documentation and release note to explain how filtering
of hosts by isolate aggregates works.

Change-Id: I8d8086973039308f9041a36463a834b5275708e3
Implements: blueprint placement-req-filter-forbidden-aggregates

4 files changed, 124 insertions, 0 deletions

diff --git a/doc/source/admin/configuration/schedulers.rst b/doc/source/admin/configuration/schedulers.rst
index 58aacba50b..5c52df8e64 100644
--- a/doc/source/admin/configuration/schedulers.rst
+++ b/doc/source/admin/configuration/schedulers.rst
@@ -99,6 +99,14 @@ periodic task runs - which is controlled by the
 
 .. _os-services: https://docs.openstack.org/api-ref/compute/#compute-services-os-services
 
+Isolate Aggregates
+------------------
+
+Starting in the Train release, there is an optional placement pre-request filter
+:doc:`/reference/isolate-aggregates`
+When enabled, the traits required in the server's flavor and image must be at
+least those required in an aggregate's metadata in order for the server to be
+eligible to boot on hosts in that aggregate.
 
 Filter scheduler
 ~~~~~~~~~~~~~~~~
@@ -198,6 +206,8 @@ use this filter, see :ref:`host-aggregates`.
 Note the ``disk_allocation_ratio`` :ref:`bug 1804125 <bug-1804125>`
 restriction.
 
+.. _`AggregateImagePropertiesIsolation`:
+
 AggregateImagePropertiesIsolation
 ---------------------------------
 
@@ -262,6 +272,13 @@ following options in the ``nova.conf`` file:
    # Separator used between the namespace and keys (string).
    aggregate_image_properties_isolation_separator = .
 
+.. note::
+
+   This filter has limitations as described in `bug 1677217
+   <https://bugs.launchpad.net/nova/+bug/1677217>`_
+   which are addressed in placement :doc:`/reference/isolate-aggregates`
+   request filter.
+
 .. _AggregateInstanceExtraSpecsFilter:
 
 AggregateInstanceExtraSpecsFilter
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 2e6f41c5c4..5755304d67 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -239,6 +239,7 @@ looking parts of our architecture. These are collected below.
    reference/upgrade-checks
    reference/vm-states
    reference/scheduler-hints-vs-flavor-extra-specs
+   reference/isolate-aggregates
    user/index
    user/aggregates
    user/architecture
diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst
index 47cdda6530..b834cc5eda 100644
--- a/doc/source/reference/index.rst
+++ b/doc/source/reference/index.rst
@@ -35,6 +35,9 @@ The following is a dive into some of the internals in nova.
 .. todo:: Need something about versioned objects and how they fit in with
           conductor as an object backporter during upgrades.
 
+* :doc:`/reference/isolate-aggregates`: Describes how the placement filter
+  works in nova to isolate groups of hosts.
+
 Debugging
 =========
 
diff --git a/doc/source/reference/isolate-aggregates.rst b/doc/source/reference/isolate-aggregates.rst
new file mode 100644
index 0000000000..a23a3aa124
--- /dev/null
+++ b/doc/source/reference/isolate-aggregates.rst
@@ -0,0 +1,103 @@
+..
+      Copyright 2019 NTT DATA
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+Filtering hosts by isolating aggregates
+=======================================
+
+Background
+-----------
+
+I want to set up an aggregate ``ABC`` with hosts that allow you to run only
+certain licensed images. I could tag the aggregate with metadata such as
+``<LICENSED=WINDOWS>``. Then if I boot an instance with an image containing the
+property ``<LICENSED=WINDOWS>``, it will land on one of the hosts in aggregate
+``ABC``. But if the user creates a new image which does not include
+``<LICENSED=WINDOWS>`` metadata, an instance booted with that image could still
+land on a host in aggregate ``ABC`` as reported in launchpad bug `1677217`_.
+The :ref:`AggregateImagePropertiesIsolation` scheduler filter passes even
+though the aggregate metadata ``<LICENSED=WINDOWS>`` is not present in the
+image properties.
+
+.. _1677217: https://bugs.launchpad.net/nova/+bug/1677217
+
+Solution
+--------
+
+The above problem is addressed by blueprint
+`placement-req-filter-forbidden-aggregates`_ which was implemented in the
+20.0.0 Train release.
+
+The following example assumes you have configured aggregate ``ABC`` and added
+hosts ``HOST1`` and ``HOST2`` to it in Nova, and that you want to isolate those
+hosts to run only instances requiring Windows licensing.
+
+#. Set the :oslo.config:option:`scheduler.enable_isolated_aggregate_filtering`
+   config option to ``true`` in nova.conf and restart the nova-scheduler
+   service.
+
+#. Add trait ``CUSTOM_LICENSED_WINDOWS`` to the resource providers for
+   ``HOST1`` and ``HOST2`` in the Placement service.
+
+   First create the ``CUSTOM_LICENSED_WINDOWS`` trait
+
+   .. code-block:: console
+
+     # openstack --os-placement-api-version 1.6 trait create CUSTOM_LICENSED_WINDOWS
+
+   Discover the ID of ``HOST1``, which is its resource provider UUID
+
+   .. code-block:: console
+
+     # host_id=$(openstack resource provider show <HOST1_UUID>)
+
+   Start to build the command line by first collecting existing traits for ``HOST1``
+
+   .. code-block:: console
+
+     # traits=$(openstack --os-placement-api-version 1.6 resource provider trait list -f value $server_id | sed 's/^/--trait /')
+
+   Replace ``HOST1``\ 's traits, adding ``CUSTOM_LICENSED_WINDOWS``
+
+   .. code-block:: console
+
+     # openstack --os-placement-api-version 1.6 resource provider trait set $traits --trait CUSTOM_LICENSED_WINDOWS $server_id
+
+   Repeat the above steps for ``HOST2``.
+
+#. Add the ``trait:CUSTOM_LICENSED_WINDOWS=required`` metadata property to
+   aggregate ``ABC``.
+
+   .. code-block:: console
+
+     openstack --os-compute-api-version 2.53 aggregate set --property trait:CUSTOM_LICENSED_WINDOWS=required ABC
+
+As before, any instance spawned with a flavor or image containing
+``trait:CUSTOM_LICENSED_WINDOWS=required`` will land on ``HOST1`` or ``HOST2``
+because those hosts expose that trait.
+
+However, now that the ``isolate_aggregates`` request filter is configured,
+any instance whose flavor or image **does not** contain
+``trait:CUSTOM_LICENSED_WINDOWS=required`` will **not** land on ``HOST1`` or
+``HOST2`` because aggregate ``ABC`` requires that trait.
+
+The above example uses a ``CUSTOM_LICENSED_WINDOWS`` trait, but you can use any
+custom or `standard trait`_ in a similar fashion.
+
+The filter supports the use of multiple traits across multiple aggregates. The
+combination of flavor and image metadata must require **all** of the traits
+configured on the aggregate in order to pass.
+
+.. _placement-req-filter-forbidden-aggregates: https://specs.openstack.org/openstack/nova-specs/specs/train/approved/placement-req-filter-forbidden-aggregates.html
+.. _standard trait: https://docs.openstack.org/os-traits/latest/