Update the resource classes documentation based on recent progress

The feature works now, so we can remove uncertaincy from the docs. Also adds
an upgrade release note to populate the resource_class field before the upgrade.

Change-Id: I22234aafdd195dd76c621b93042a67cdb36f3e65

doc/source/admin/upgrade-guide.rst

@@ -42,7 +42,7 @@ Plan your Upgrade
 Upgrading from Ocata to Pike
 ============================
 
-#. It is recommended to set the ``resource_class`` field for nodes registered
+#. It is required to set the ``resource_class`` field for nodes registered
    with the Bare Metal service *before* using the Pike version of the Compute
    service. See `enrollment documentation
    <https://docs.openstack.org/project-install-guide/baremetal/draft/enrollment.html#enrollment-process>`_

doc/source/install/configure-compute.rst

@@ -56,11 +56,6 @@ service's controller nodes and compute nodes.
       #reserved_host_disk_mb=0
       reserved_host_memory_mb=0
 
-      # Flag to decide whether to use baremetal_scheduler_default_filters or not.
-      # (boolean value)
-      #scheduler_use_baremetal_filters=False
-      scheduler_use_baremetal_filters=True
-
       # Determines if the Scheduler tracks changes to instances to help with
       # its filtering decisions (boolean value)
       #scheduler_tracks_instance_changes=True
@@ -74,6 +69,21 @@ service's controller nodes and compute nodes.
       #scheduler_host_subset_size=1
       scheduler_host_subset_size=9999999
 
+    If you have not migrated to using :ref:`scheduling-resource-classes`, then
+    the following should be set as well:
+
+    .. code-block:: ini
+
+      [default]
+
+      # Flag to decide whether to use baremetal_scheduler_default_filters or not.
+      # (boolean value)
+      #scheduler_use_baremetal_filters=False
+      scheduler_use_baremetal_filters=True
+
+    This option is deprecated and has to be unset after migration
+    to resource classes.
+
 #. Change these configuration options in the ``ironic`` section.
    Replace:
 

doc/source/install/configure-nova-flavors.rst

@@ -33,40 +33,32 @@ The flavor is mapped to the bare metal node through the hardware specifications.
 
       $ nova flavor-key my-baremetal-flavor set cpu_arch=$ARCH
 
+.. _scheduling-resource-classes:
+
 Scheduling based on resource classes
 ====================================
 
 The Newton release of the Bare Metal service includes a field on the node
 resource called ``resource_class``. This field is available in version 1.21 of
-the Bare Metal service API.
+the Bare Metal service API. Starting with the Pike release, this field has
+to be populated for all nodes, as explained in :doc:`enrollment`.
 
-In the future (Pike or Queens release), a Compute service flavor will use this
+As of the Pike release, a Compute service flavor is able to use this field
-field for scheduling, instead of the CPU, RAM, and disk properties defined in
+for scheduling, instead of the CPU, RAM, and disk properties defined in
-the flavor above. A flavor will require *exactly one* of some bare metal
+the flavor above. A flavor can request *exactly one* instance of a bare metal
 resource class.
 
-This work is still in progress (see `blueprint
+To achieve that, the flavors, created as described in `Scheduling based on
-custom-resource-classes-in-flavors`), and the syntax for the ``flavor-create``
+properties`_, have to be associated with one custom resource class each.
-call to associate flavors with resource classes is yet to be implemented.
+A name of the custom resource class is the name of node's resource class, but
-According to the `custom resource classes specification`_, it will look
+upper-cased, with ``CUSTOM_`` prefix prepended, and all punctuation replaced
-as follows:
+with an underscore:
 
 .. code-block:: console
 
       $ nova flavor-key my-baremetal-flavor set resources:CUSTOM_<RESOURCE_CLASS>=1
 
-where ``<RESOURCE_CLASS>`` is the resource class name in upper case with all
+Another set of flavor properties should be used to disable scheduling
-punctuation replaces with an underscore.
-
-For example,
-
-.. code-block:: console
-
-      $ ironic --ironic-api-version=1.21 node-update $NODE_UUID \
-        replace resource_class=baremetal.with-GPU
-      $ nova flavor-key my-baremetal-flavor set resources:CUSTOM_BAREMETAL_WITH_CPU=1
-
-Another set of extra_specs properties will be used to disable scheduling
 based on standard properties for a bare metal flavor:
 
 .. code-block:: console
@@ -75,9 +67,34 @@ based on standard properties for a bare metal flavor:
       $ nova flavor-key my-baremetal-flavor set resources:MEMORY_MB=0
       $ nova flavor-key my-baremetal-flavor set resources:DISK_GB=0
 
-.. note::
+.. warning::
-   The last step will be required, as the Compute service will stop providing
+   The last step will be mandatory in the Queens release, as the Compute
-   standard resources for bare metal nodes.
+   service will stop providing standard resources for bare metal nodes.
 
-.. _blueprint custom-resource-classes-in-flavors: https://blueprints.launchpad.net/nova/+spec/custom-resource-classes-in-flavors
+Example
-.. _custom resource classes specification: https://specs.openstack.org/openstack/nova-specs/specs/pike/approved/custom-resource-classes-in-flavors.html
+-------
+
+If you want to define a class of nodes called ``baremetal.with-GPU``, start
+with tagging some nodes with it:
+
+.. code-block:: console
+
+      $ ironic --ironic-api-version=1.21 node-update $NODE_UUID \
+        replace resource_class=baremetal.with-GPU
+
+.. warning::
+    It is possible to **add** a resource class to ``active`` nodes, but it is
+    not possiblre to **replace** an existing resource class on them.
+
+Then you can update your flavor to request the resource class instead of
+the standard properties:
+
+.. code-block:: console
+
+      $ nova flavor-key my-baremetal-flavor set resources:CUSTOM_BAREMETAL_WITH_GPU=1
+      $ nova flavor-key my-baremetal-flavor set resources:VCPU=0
+      $ nova flavor-key my-baremetal-flavor set resources:MEMORY_MB=0
+      $ nova flavor-key my-baremetal-flavor set resources:DISK_GB=0
+
+Note how ``baremetal.with-GPU`` in the node's ``resource_class`` field becomes
+``CUSTOM_BAREMETAL_WITH_GPU`` in the flavor's properties.

releasenotes/notes/resource-classes-1bf903547236a473.yaml

@@ -0,0 +1,15 @@
+---
+upgrade:
+  - |
+    Due to upcoming changes in the way Nova schedules bare metal nodes, all
+    nodes in a deployment using Nova have to get the ``resource_class`` field
+    populated before the upgrade. See `enrollment documentation
+    <https://docs.openstack.org/ironic/latest/install/enrollment.html#enrollment-process>`_
+    and `flavor configuration documentation
+    <https://docs.openstack.org/ironic/latest/install/configure-nova-flavors.html#scheduling-based-on-resource-classes>`_
+    for details.
+
+    Once you've migrated your flavors to resource classes, you should unset
+    the deprecated ``use_baremetal_filters`` option in the Compute service
+    configuration. Otherwise you'll be using the filters incompatible with
+    scheduling based on resource classes.