doc/cephadm: improve host-management.rst

Signed-off-by: Anthony D'Atri <anthonyeleven@users.noreply.github.com>
(cherry picked from commit 9fb51bb537e8bd9ea60633091acfc48a58262c3b)

diff --git a/doc/cephadm/host-management.rst b/doc/cephadm/host-management.rst
index 59d0f6d1767135718af8ff75fb510d5009d81c93..396ceb22d8900636d2271a020ee2c35ac44e08f5 100644 (file)
--- a/doc/cephadm/host-management.rst
+++ b/doc/cephadm/host-management.rst
@@ -71,9 +71,9 @@ To add each new host to the cluster, perform two steps:
      ceph orch host add host2 10.10.0.102
      ceph orch host add host3 10.10.0.103
 
-   It is best to explicitly provide the host IP address.  If an IP is
+   It is best to explicitly provide the host IP address.  If an address is
    not provided, then the host name will be immediately resolved via
-   DNS and that IP will be used.
+   DNS and the result will be used.
 
    One or more labels can also be included to immediately label the
    new host.  For example, by default the ``_admin`` label will make
@@ -98,10 +98,22 @@ To drain all daemons from a host, run a command of the following form:
 
    ceph orch host drain *<host>*
 
-The ``_no_schedule`` label will be applied to the host. See
-:ref:`cephadm-special-host-labels`.
+The ``_no_schedule`` and ``_no_conf_keyring`` labels will be applied to the
+host. See :ref:`cephadm-special-host-labels`.
 
-All OSDs on the host will be scheduled to be removed. You can check the progress of the OSD removal operation with the following command:
+If you want to drain daemons but leave managed `ceph.conf` and keyring
+files on the host, you may pass the ``--keep-conf-keyring`` flag to the
+drain command.
+
+.. prompt:: bash #
+
+   ceph orch host drain *<host>* --keep-conf-keyring
+
+This will apply the ``_no_schedule`` label to the host but not the
+``_no_conf_keyring`` label.
+
+All OSDs on the host will be scheduled to be removed. You can check
+progress of the OSD removal operation with the following command:
 
 .. prompt:: bash #
 
@@ -126,7 +138,7 @@ cluster by running the following command:
 Offline host removal
 --------------------
 
-Even if a host is offline and can not be recovered, it can be removed from the
+If a host is offline and can not be recovered, it can be removed from the
 cluster by running a command of the following form:
 
 .. prompt:: bash #
@@ -222,8 +234,8 @@ Rescanning Host Devices
 =======================
 
 Some servers and external enclosures may not register device removal or insertion with the
-kernel. In these scenarios, you'll need to perform a host rescan. A rescan is typically
-non-disruptive, and can be performed with the following CLI command:
+kernel. In these scenarios, you'll need to perform a device rescan on the appropriate host.
+A rescan is typically non-disruptive, and can be performed with the following CLI command:
 
 .. prompt:: bash #
 
@@ -286,19 +298,43 @@ create a new CRUSH host located in the specified hierarchy.
 
 .. note:: 
 
-  The ``location`` attribute will be only affect the initial CRUSH location. Subsequent
-  changes of the ``location`` property will be ignored. Also, removing a host will not remove
-  any CRUSH buckets.
+  The ``location`` attribute will be only affect the initial CRUSH location.
+  Subsequent changes of the ``location`` property will be ignored. Also,
+  removing a host will not remove an associated CRUSH bucket unless the
+  ``--rm-crush-entry`` flag is provided to the ``orch host rm`` command
 
 See also :ref:`crush_map_default_types`.
 
+Removing a host from the CRUSH map
+==================================
+
+The ``ceph orch host rm`` command has support for removing the associated host bucket
+from the CRUSH map. This is done by providing the ``--rm-crush-entry`` flag.
+
+.. prompt:: bash [ceph:root@host1/]#
+
+   ceph orch host rm host1 --rm-crush-entry
+
+When this flag is specified, cephadm will attempt to remove the host bucket
+from the CRUSH map as part of the host removal process. Note that if
+it fails to do so, cephadm will report the failure and the host will remain under
+cephadm control.
+
+.. note:: 
+
+  Removal from the CRUSH map will fail if there are OSDs deployed on the
+  host. If you would like to remove all the host's OSDs as well, please start
+  by using  the ``ceph orch host drain`` command to do so. Once the OSDs
+  have been removed, then you may direct cephadm remove the CRUSH bucket
+  along with the host using the ``--rm-crush-entry`` flag.
+
 OS Tuning Profiles
 ==================
 
-Cephadm can be used to manage operating-system-tuning profiles that apply sets
-of sysctl settings to sets of hosts. 
+Cephadm can be used to manage operating system tuning profiles that apply
+``sysctl`` settings to sets of hosts. 
 
-Create a YAML spec file in the following format:
+To do so, create a YAML spec file in the following format:
 
 .. code-block:: yaml
 
@@ -317,18 +353,21 @@ Apply the tuning profile with the following command:
 
    ceph orch tuned-profile apply -i <tuned-profile-file-name>
 
-This profile is written to ``/etc/sysctl.d/`` on each host that matches the
-hosts specified in the placement block of the yaml, and ``sysctl --system`` is
+This profile is written to a file under ``/etc/sysctl.d/`` on each host
+specified in the ``placement`` block, then ``sysctl --system`` is
 run on the host.
 
 .. note::
 
   The exact filename that the profile is written to within ``/etc/sysctl.d/``
   is ``<profile-name>-cephadm-tuned-profile.conf``, where ``<profile-name>`` is
-  the ``profile_name`` setting that you specify in the YAML spec. Because
+  the ``profile_name`` setting that you specify in the YAML spec. We suggest
+  naming these profiles following the usual ``sysctl.d`` `NN-xxxxx` convention. Because
   sysctl settings are applied in lexicographical order (sorted by the filename
-  in which the setting is specified), you may want to set the ``profile_name``
-  in your spec so that it is applied before or after other conf files.
+  in which the setting is specified), you may want to carefully choose
+  the ``profile_name`` in your spec so that it is applied before or after other
+  conf files.  Careful selection ensures that values supplied here override or
+  do not override those in other ``sysctl.d`` files as desired.
 
 .. note::
 
@@ -337,7 +376,7 @@ run on the host.
 
 .. note::
 
-  Applying tuned profiles is idempotent when the ``--no-overwrite`` option is
+  Applying tuning profiles is idempotent when the ``--no-overwrite`` option is
   passed. Moreover, if the ``--no-overwrite`` option is passed, existing
   profiles with the same name are not overwritten.
 
@@ -497,7 +536,7 @@ There are two ways to customize this configuration for your environment:
 
    We do *not recommend* this approach.  The path name must be
    visible to *any* mgr daemon, and cephadm runs all daemons as
-   containers. That means that the file either need to be placed
+   containers. That means that the file must either be placed
    inside a customized container image for your deployment, or
    manually distributed to the mgr data directory
    (``/var/lib/ceph/<cluster-fsid>/mgr.<id>`` on the host, visible at
@@ -550,8 +589,8 @@ Note that ``man hostname`` recommends ``hostname`` to return the bare
 host name:
 
     The FQDN (Fully Qualified Domain Name) of the system is the
-    name that the resolver(3) returns for the host name, such as,
-    ursula.example.com. It is usually the hostname followed by the DNS
+    name that the resolver(3) returns for the host name, for example
+    ``ursula.example.com``. It is usually the short hostname followed by the DNS
     domain name (the part after the first dot). You can check the FQDN
     using ``hostname --fqdn`` or the domain name using ``dnsdomainname``.