Merge "Update the resource classes documentation based on recent progress"

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.