doc/rados/operations/crush-map: describe crush locations, hook

Signed-off-by: Sage Weil <sage@inktank.com>

diff --git a/doc/rados/operations/crush-map.rst b/doc/rados/operations/crush-map.rst
index 91f8dfbc02918fc66908d22250df246c047cfd51..51dcdf824868ee2b5e271676b453a835d35e9f57 100644 (file)
--- a/doc/rados/operations/crush-map.rst
+++ b/doc/rados/operations/crush-map.rst
@@ -54,6 +54,61 @@ with a failed host are in a degraded state.
 .. note:: Lines of code in example boxes may extend past the edge of the box. 
    Please scroll when reading or copying longer examples.
 
+CRUSH Location
+==============
+
+The location of an OSD in terms of the CRUSH map's hierarchy is referred to
+as a 'crush location'.  This location specifier takes the form of a list of
+key and value pairs describing a position.  For example, if an OSD is in a
+particular row, rack, and host, and is part of the 'default' CRUSH tree, it's
+crush location could be described as::
+
+  root=default row=a rack=a12 host=foohost
+
+Note:
+
+*. Note that the order of the keys does not matter.
+*. The key name (left of ``='') must be a valid CRUSH ``type``.  By default
+   these include root, datacenter, row, rack, and host, but those types can be
+   customized to be anything appropriate by modifying the CRUSH map.
+*. Not all keys need to be specified.  For example, by default, Ceph
+   automatically sets a ceph-osd daemon's location to be
+   ``root=default host=HOSTNAME'' (based on the output from ``hostname
+   -s'').
+
+ceph-crush-location hook
+------------------------
+
+The ``ceph-crush-location'' utility will generate a default CRUSH location
+string for a given daemon.  The location is based on, in order of preference:
+
+#. A ``TYPE crush location'' option in ceph.conf.  For example, this
+ is ``osd crush location'' for OSD daemons.
+#. A ``crush location'' option in ceph.conf.
+#. A default of ``root=default host=HOSTNAME'' where the hostname is
+ generated with the ``hostname -s'' command.
+
+In a typical deployment scenario, provisioning software (or the system
+adminstrator) can simply set the 'crush location' field in a host's
+ceph.conf to describe that machine's location within the datacenter or
+cluster.  This will be provide location awareness to both Ceph daemons
+and clients alike.
+
+Custom location hooks
+---------------------
+
+A customize location hook can be used in place of the generic hook for OSD daemon placement in the hierarchy.  (On startup, each OSD ensure its position is correct.)::
+
+  osd crush location hook = /path/to/script
+
+This hook is is passed several arguments (below) and should output a single line to stdout with the CRUSH location description.::
+
+  $ ceph-crush-location --cluster CLUSTER --id ID --type TYPE
+
+where the cluster name is typically 'ceph', the id is the daemon
+identifier (the OSD number), and the daemon type is typically ``osd''.
+
+
 Editing a CRUSH Map
 ===================
 
@@ -789,6 +844,7 @@ Where:
 :Example: ``datacenter=dc1 room=room1 row=foo rack=bar host=foo-bar-1``
 
 
+
 Tunables
 ========