Add docs for node.resource_class and flavor creation

This change also outlines the expected changes in Nova wrt bare metal.

Closes-Bug: #1604916
Co-Authored-By: Dmitry Tantsur <dtantsur@redhat.com>
Change-Id: I4f7259c8c13c9080d649731311f9bb8f4bdf1d99

doc/source/deploy/upgrade-guide.rst

@@ -39,6 +39,19 @@ Plan your Upgrade
   #. Restart ironic-conductor and ironic-api services.
 
 
+Upgrading from Ocata to Pike
+============================
+
+#. It is recommended 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>`_
+   for details.
+
+Other upgrade instructions are in the `Pike release notes
+<https://docs.openstack.org/releasenotes/ironic/pike.html>`_.
+
+
 Upgrading from Newton to Ocata
 ==============================
 

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

@@ -3,6 +3,9 @@
 Create flavors for use with the Bare Metal service
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+Scheduling based on properties
+==============================
+
 You'll need to create a special bare metal flavor in the Compute service.
 The flavor is mapped to the bare metal node through the hardware specifications.
 
@@ -30,10 +33,51 @@ The flavor is mapped to the bare metal node through the hardware specifications.
 
       $ nova flavor-key my-baremetal-flavor set cpu_arch=$ARCH
 
-#. Associate the deploy ramdisk and kernel images with the ironic node:
+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.
+
+In the future (Pike or Queens release), a Compute service flavor will use this
+field 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
+resource class.
+
+This work is still in progress (see `blueprint
+custom-resource-classes-in-flavors`), and the syntax for the ``flavor-create``
+call to associate flavors with resource classes is yet to be implemented.
+According to the `custom resource classes specification`_, it will look
+as follows:
 
 .. code-block:: console
 
-      $ ironic node-update $NODE_UUID add \
+      $ nova flavor-key my-baremetal-flavor set resources:CUSTOM_<RESOURCE_CLASS>=1
-          driver_info/deploy_kernel=$DEPLOY_VMLINUZ_UUID \
+
-          driver_info/deploy_ramdisk=$DEPLOY_INITRD_UUID
+where ``<RESOURCE_CLASS>`` is the resource class name in upper case with all
+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
+
+      $ 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::
+   The last step will be required, as the Compute 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
+.. _custom resource classes specification: https://specs.openstack.org/openstack/nova-specs/specs/pike/approved/custom-resource-classes-in-flavors.html

install-guide/source/enrollment.rst

@@ -236,6 +236,29 @@ and may be combined if desired.
 
    See `Choosing a driver`_ above for details on driver properties.
 
+#. Specify a deploy kernel and ramdisk compatible with the node's driver,
+   for example:
+
+   .. code-block:: console
+
+    $ ironic node-update $NODE_UUID add \
+        driver_info/deploy_kernel=$DEPLOY_VMLINUZ_UUID \
+        driver_info/deploy_ramdisk=$DEPLOY_INITRD_UUID
+
+   See :doc:`configure-glance-images` for details.
+
+#. You must also inform the Bare Metal service of the network interface cards
+   which are part of the node by creating a port with each NIC's MAC address.
+   These MAC addresses are passed to the Networking service during instance
+   provisioning and used to configure the network appropriately:
+
+   .. code-block:: console
+
+    $ ironic port-create -n $NODE_UUID -a $MAC_ADDRESS
+
+Adding scheduling information
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 #. Update the node's properties to match the bare metal flavor you created
    when :doc:`configure-nova-flavors`:
 
@@ -273,25 +296,36 @@ and may be combined if desired.
       :ref:`root-device-hints`), the ``local_gb`` value should match the size
       of picked target disk.
 
-   .. TODO(dtantsur): cover resource classes
+   .. note::
+      Properties-based approach to scheduling will eventually be replaced by
+      scheduling based on custom resource classes, as explained below and in
+      :doc:`configure-nova-flavors`.
 
-#. As mentioned in the :ref:`flavor-creation` section, you should specify
+#. Assign a *resource class* to the node. Resource classes will be used for
-   a deploy kernel and ramdisk compatible with the node's driver, for example:
+   scheduling bare metal instances in the future. A *resource class* should
+   represent a class of hardware in your data center, that roughly corresponds
+   to a Compute flavor.
+
+   For example, you may split hardware into three classes:
+
+   #. nodes with a lot of RAM and powerful CPU for computational tasks,
+   #. nodes with powerful GPU for OpenCL computing,
+   #. smaller nodes for development and testing.
+
+   These would correspond to three resource classes, which you can name
+   arbitrary, e.g. ``large-cpu``, ``large-gpu`` and ``small``.
 
    .. code-block:: console
 
-    $ ironic node-update $NODE_UUID add \
+    $ ironic --ironic-api-version=1.21 node-update $NODE_UUID \
-        driver_info/deploy_kernel=$DEPLOY_VMLINUZ_UUID \
+        replace resource_class=$CLASS_NAME
-        driver_info/deploy_ramdisk=$DEPLOY_INITRD_UUID
 
-#. You must also inform the Bare Metal service of the network interface cards
+   To use resource classes for scheduling you need to update your flavors as
-   which are part of the node by creating a port with each NIC's MAC address.
+   described in :doc:`configure-nova-flavors`.
-   These MAC addresses are passed to the Networking service during instance
-   provisioning and used to configure the network appropriately:
 
-   .. code-block:: console
+   .. note::
-
+      Scheduling based on resource classes will replace scheduling based on
-    $ ironic port-create -n $NODE_UUID -a $MAC_ADDRESS
+      properties in the future.
 
 #. If you wish to perform more advanced scheduling of the instances based on
    hardware capabilities, you may add metadata to each node that will be