doc: update the cephadm download instructions

Starting with reef, cephadm is a compiled (zipapp) python application.
The cephadm script has been renamed and thus the old curl-based
download instructions will no loner work. While cephadm still has
no dependencies outside the Python stdlib, this will be changed in
future versions so it is no longer appropriate to just download the
source file of cephadm and run it either.

This change updates the `Install cephadm` section of the doc to explain
how to acquire a "compiled" version of cephadm as well as:
* moving and tweaking the note that the two installation methods are
  distinct
* adding a new note linking to instructions on building cephadm
* moving the distribution-specific installations before the curl-based
  installation to subtly hint that we prefer you to get it using
  packages if you can
* Noting cephadm's minimal required python verision and how to run it
  with a particular python version.

Note from Zac Dover, June 1, 2023: Note: This commit is a cherry-pick of
d11cf0e, which was introduced by John Mulligan in #48180. This is one of
three commits introduced in that PR, and this cherry-pick cleans up
omissions I (Zac Dover) inadvertently introduced while attempting to
rectify the merge conflicts in #51843. This should be the final
main-branch-targeting commit that cleans up PR#51483.

Signed-off-by: John Mulligan <jmulligan@redhat.com>
(cherry picked from commit d11cf0e82aab8d4cef9d423e5d463a373eaf383a)
(cherry picked from commit 7c6a2cad96405616719b85c740aabd98558c93ac)

diff --git a/doc/cephadm/install.rst b/doc/cephadm/install.rst
index 17267c643766f4e946726b819fe95cdfe0b6fb8f..58c997fda90aaadfc248fc343de2dcd134a0d4cd 100644 (file)
--- a/doc/cephadm/install.rst
+++ b/doc/cephadm/install.rst
@@ -41,61 +41,17 @@ There are two ways to install ``cephadm``:
 #. a :ref:`curl-based installation<cephadm_install_curl>` method
 #. :ref:`distribution-specific installation methods<cephadm_install_distros>`
 
-curl-based installation
------------------------
-
-* Use ``curl`` to fetch the most recent version of the
-  standalone script.
-
-  .. prompt:: bash #
-     :substitutions:
-
-     curl --silent --remote-name --location https://github.com/ceph/ceph/raw/|stable-release|/src/cephadm/cephadm
-
-  Make the ``cephadm`` script executable:
-
-  .. prompt:: bash #
-
-   chmod +x cephadm
-
-  This script can be run directly from the current directory:
-
-  .. prompt:: bash #
-
-   ./cephadm <arguments...>
-
-* Although the standalone script 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:
-
-  .. prompt:: bash #
-     :substitutions:
-
-     ./cephadm add-repo --release |stable-release|
-     ./cephadm install
-
-  Confirm that ``cephadm`` is now in your PATH by running ``which``:
-
-  .. prompt:: bash #
-
-    which cephadm
-
-  A successful ``which cephadm`` command will return this:
-
-  .. code-block:: bash
-
-    /usr/sbin/cephadm
+.. 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.
 
 .. _cephadm_install_distros:
 
 distribution-specific installations
 -----------------------------------
 
-.. important:: The methods of installing ``cephadm`` in this section are distinct from the curl-based method above. Use either the curl-based method above or one of the methods in this section, but not both the curl-based method and one of these.
-
-Some Linux distributions  may already include up-to-date Ceph packages.  In
-that case, you can install cephadm directly. For example:
+Some Linux distributions may already include up-to-date Ceph packages.  In that
+case, you can install cephadm directly. For example:
 
   In Ubuntu:
 
@@ -165,42 +121,28 @@ curl-based installation
 
      python3.8 ./cephadm <arguments...>
 
-.. _cephadm_update:
-
-update cephadm
---------------
-
-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.
-
-To install the packages provided by the Ceph project that provide the
-``cephadm`` command, run the following commands:
-
-.. prompt:: bash #
-   :substitutions:
+* 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 add-repo --release |stable-release|
-   ./cephadm install
+  .. prompt:: bash #
+     :substitutions:
 
-Confirm that ``cephadm`` is now in your PATH by running ``which`` or
-``command -v``:
+     ./cephadm add-repo --release |stable-release|
+     ./cephadm install
 
-.. prompt:: bash #
+  Confirm that ``cephadm`` is now in your PATH by running ``which``:
 
-   which cephadm
+  .. prompt:: bash #
 
-A successful ``which cephadm`` command will return this:
+    which cephadm
 
-.. code-block:: bash
+  A successful ``which cephadm`` command will return this:
 
-   /usr/sbin/cephadm
+  .. code-block:: bash
 
+    /usr/sbin/cephadm
 
 Bootstrap a new cluster
 =======================