Document setting discover_hosts_in_cells_interval in nova.conf

By default, starting with Ocata, an operator needs to run a nova-manage command
after each node is enrolled to make sure it's correctly mapped to a cell.
This is not something we can ask in all cases (especially if Ironic UI is used),
so let us document running a periodic task for it instead.

Change-Id: I0c7bf29b0e27bef7205880ebc164d3a82e7b0be8
Closes-Bug: #1715646
(cherry picked from commit 2427ffca8bd0e2ab5127020ae6ffea9decfdc915)

2 files changed, 30 insertions, 11 deletions

diff --git a/doc/source/install/configure-compute.rst b/doc/source/install/configure-compute.rst
index 5f0a47653..aa0471edf 100644
--- a/doc/source/install/configure-compute.rst
+++ b/doc/source/install/configure-compute.rst
@@ -48,6 +48,26 @@ service's controller nodes and compute nodes.
        # Not possible for bare metal nodes, so set it to False.
        track_instance_changes=False
 
+       [scheduler]
+
+       # This value controls how often (in seconds) the scheduler should
+       # attempt to discover new hosts that have been added to cells.
+       # If negative (the default), no automatic discovery will occur.
+       # As each bare metal node is represented by a separate host, it has
+       # to be discovered before the Compute service can deploy on it.
+       # The value here has to be carefully chosen based on a compromise
+       # between the enrollment speed and the load on the Compute scheduler.
+       # The recommended value of 2 minutes matches how often the Compute
+       # service polls the Bare Metal service for node information.
+       discover_hosts_in_cells_interval=120
+
+   .. note::
+        The alternative to setting the ``discover_hosts_in_cells_interval``
+        option is to run the following command on any Compute controller node
+        after each node is enrolled::
+
+            nova-manage cell_v2 discover_hosts
+
 #. If you have not switched to make use of :ref:`scheduling-resource-classes`,
    then the following options should be set as well. They must be removed from
    the configuration file after switching to resource classes.
@@ -98,17 +118,6 @@ service's controller nodes and compute nodes.
        # setting it to 0 to disable this behavior completely.
        #consecutive_build_service_disable_threshold = 10
 
-       [scheduler]
-
-       # This value controls how often (in seconds) the scheduler should
-       # attempt to discover new hosts that have been added to cells.
-       # If negative (the default), no automatic discovery will occur.
-       # As each bare metal node is represented by a separate host, it has
-       # to be discovered before the Compute service can deploy on it.
-       # It can be done manually after enrolling every node or batch of nodes,
-       # or this periodic task can be enabled to do it automatically.
-       #discover_hosts_in_cells_interval=-1
-
 #. Change these configuration options in the ``ironic`` section.
    Replace:
 
diff --git a/doc/source/install/enrollment.rst b/doc/source/install/enrollment.rst
index fcf10bb1d..5d473dc10 100644
--- a/doc/source/install/enrollment.rst
+++ b/doc/source/install/enrollment.rst
@@ -466,6 +466,16 @@ For more details on the Bare Metal service's state machine, see the
 
 .. _ComputeCapabilitiesFilter: https://docs.openstack.org/nova/pike/user/filter-scheduler.html
 
+Mapping nodes to Compute cells
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If the Compute service is used for scheduling, and the
+``discover_hosts_in_cells_interval`` was not set as described in
+:doc:`configure-compute`, then log into any controller node and run the
+following command to map the new node(s) to Compute cells::
+
+    nova-manage cell_v2 discover_hosts
+
 Logical names
 -------------