Document how to use NodeDataLookup generation utility

The updated version of the Ceph documentation warns
about the problems of using name-based methods of
refering to block devices and suggests use of the
by_path method to avoid this problem. It then links
to the updated Node Specific Hieradata document which
contains a description of how to use the utility from
the related bug.

Change-Id: I2131d87c51f142166f341d2a9c209162659fca43

deploy-guide/source/features/ceph_config.rst

@@ -291,6 +291,17 @@ following::
       osd_scenario: lvm
       osd_objectstore: bluestore
 
+The example above configures the devices list using the disk
+name, e.g. `/dev/sdb`, based on the `sd` driver. This method of
+referring to block devices is not guaranteed to be consistent on
+reboots so a disk normally identified by `/dev/sdc` may be named
+`/dev/sdb` later. Another way to refer to block devices is `by-path`
+which is persistent accross reboots. The `by-path` names for your
+disks are in the Ironic introspection data. A utility exists to
+generate a Heat environment file from Ironic introspection data
+with a devices list for each of the Ceph nodes in a deployment
+automatically as described in :doc:`node_specific_hieradata`.
+
 .. warning:: `osd_scenario: lvm` is used above to default new
              deployments to bluestore as configured, by `ceph-volume`,
              and is only available with ceph-ansible 3.2, or newer,

deploy-guide/source/features/node_specific_hieradata.rst

@@ -58,6 +58,57 @@ In the above example we're customizing only a single key for a single node, but
 the structure is that of a UUID-mapped hash so it is possible to customize
 multiple and different keys for multiple nodes.
 
-Finally, add such an environment file to the deploy commandline::
+Generating the Heat environment file for Ceph devices
+-----------------------------------------------------
+
+The tools directory of tripleo-heat-templates
+(`/usr/share/openstack-tripleo-heat-templates/tools/`) contains a
+utility called `make_ceph_disk_list.py` which can be used to create
+a valid JSON Heat environment file automatically from Ironic's
+introspection data.
+
+Export the introspection data from Ironic for the Ceph nodes to be
+deployed::
+
+  openstack baremetal introspection data save oc0-ceph-0 > ceph0.json
+  openstack baremetal introspection data save oc0-ceph-1 > ceph1.json
+  ...
+
+Copy the utility to the stack user's home directory on the undercloud
+and then use it to generate a `node_data_lookup.json` file which may
+be passed during openstack overcloud deployment::
+
+  ./make_ceph_disk_list.py -i ceph*.json -o node_data_lookup.json -k by_path
+
+Pass the introspection data file from `openstack baremetal
+introspection data save` for all nodes hosting Ceph OSDs to the
+utility as you may only define `NodeDataLookup` once during a
+deployment. The `-i` option can take an expression like `*.json` or a
+list of files as input.
+
+The `-k` option defines the key of ironic disk data structure to use
+to identify the disk to be used as an OSD. Using `name` is not
+recommended as it will produce a file of devices like `/dev/sdd` which
+may not always point to the same device on reboot. Thus, `by_path` is
+recommended and is the default if `-k` is not specified.
+
+Ironic will have one of the available disks on the system reserved as
+the root disk. The utility will always exlude the root disk from the
+list of devices genereated.
+
+Use `./make_ceph_disk_list.py --help` to see other available options.
+
+Deploying with NodeDataLookup
+-----------------------------
+
+Add the environment file described in the previous section to the
+deploy commandline::
 
   openstack overcloud deploy [other overcloud deploy options] -e ~/my-node-settings.yaml
+
+or::
+
+  openstack overcloud deploy [other overcloud deploy options] -e ~/node_data_lookup.json
+
+JSON is the recommended format (instead of JSON embedded in YAML)
+because you may use `jq` to validate the entire file before deployment.