doc: make instructions to get an updated cephadm common

As discussed in person and over the ceph orch weekly, we want all users
to use a recent supported version of cephadm. Previously, the
instructions only had those downloading cephadm with curl using the
"add-repo" and "install" commands to get a up-to-date cephadm build.
According to ADK we've seen cases of users get "old" distro packages
in the past. Change the instructions so that the "update cephadm" steps
are common after acquiring a "bootstrap copy" of cephadm.

Signed-off-by: John Mulligan <jmulligan@redhat.com>

diff --git a/doc/cephadm/install.rst b/doc/cephadm/install.rst
index 8984a1e0e3836481e8c4f371a27c0be67a7a89bd..cfeee24fe165f986506c151ddaa1268f67d5ee0e 100644 (file)
--- a/doc/cephadm/install.rst
+++ b/doc/cephadm/install.rst
@@ -36,14 +36,20 @@ Ceph.
 Install cephadm
 ===============
 
-There are two ways to install ``cephadm``:
+When installing cephadm there are two key steps: first you need to acquire
+an initial copy of cephadm, then the second step is to ensure you have an
+up-to-date cephadm. There are two ways to get the initial ``cephadm``:
 
 #. :ref:`distribution-specific installation methods<cephadm_install_distros>`
 #. a :ref:`curl-based installation<cephadm_install_curl>` method
 
-.. important:: These methods of installing ``cephadm`` are mutually exclusive.
-   Choose either the distribution-specific method or the curl-based method. Do
-   not attempt to use both these methods on one system.
+Once you have an initial copy of cephadm avaiable, follow the steps to
+:ref:`update to an active release of cephadm<cephadm_update>` to ensure
+that you have the latest fixes for the version of Ceph you'll be managing.
+
+.. important:: The two methods of initially installing ``cephadm`` are mutually
+   exclusive.  Choose either the distribution-specific method or the curl-based
+   method. Do not attempt to use both these methods on one system.
 
 .. note:: Recent versions of cephadm are based on a compilation of source files.
    Unlike for earlier versions of Ceph it is no longer sufficient to copy a
@@ -58,7 +64,7 @@ There are two ways to install ``cephadm``:
 distribution-specific installations
 -----------------------------------
 
-Some Linux distributions  may already include up-to-date Ceph packages.  In
+Some Linux distributions may already include Ceph packages.  In
 that case, you can install cephadm directly. For example:
 
   In Ubuntu:
@@ -129,28 +135,41 @@ curl-based installation
 
      python3.8 ./cephadm <arguments...>
 
-* Although the standalone cephadm is sufficient to get a cluster started, it is
-  convenient to have the ``cephadm`` command installed on the host.  To install
-  the packages that provide the ``cephadm`` command, run the following
-  commands:
+.. _cephadm_update:
 
-  .. prompt:: bash #
-     :substitutions:
+update cephadm
+--------------
 
-     ./cephadm add-repo --release |stable-release|
-     ./cephadm install
+The cephadm binary can be used to bootstrap a cluster and for a variety
+of other management and debugging tasks. The Ceph team strongly recommends
+using an actively supported version of cephadm. Additionally, although
+the standalone cephadm is sufficient to get a cluster started, it is
+convenient to have the ``cephadm`` command installed on the host. Older or LTS
+distros may also have ``cephadm`` packages that are out-of-date and
+running the commands below can help install a more recent version
+from the Ceph project's repositories.
 
-  Confirm that ``cephadm`` is now in your PATH by running ``which``:
+To install the packages provided by the Ceph project that provide the
+``cephadm`` command, run the following commands:
 
-  .. prompt:: bash #
+.. prompt:: bash #
+   :substitutions:
+
+   ./cephadm add-repo --release |stable-release|
+   ./cephadm install
+
+Confirm that ``cephadm`` is now in your PATH by running ``which`` or
+``command -v``:
+
+.. prompt:: bash #
 
-    which cephadm
+   which cephadm
 
-  A successful ``which cephadm`` command will return this:
+A successful ``which cephadm`` command will return this:
 
-  .. code-block:: bash
+.. code-block:: bash
 
-    /usr/sbin/cephadm
+   /usr/sbin/cephadm