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.

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

diff --git a/doc/cephadm/install.rst b/doc/cephadm/install.rst
index ddae5865ac3f5e5735f05afaea44829042ebc91a..8984a1e0e3836481e8c4f371a27c0be67a7a89bd 100644 (file)
--- a/doc/cephadm/install.rst
+++ b/doc/cephadm/install.rst
@@ -38,94 +38,119 @@ Install cephadm
 
 There are two ways to install ``cephadm``:
 
-#. a :ref:`curl-based installation<cephadm_install_curl>` method
 #. :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.
 
-.. _cephadm_install_curl:
+.. 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
+   single source file from Ceph's git tree and run it. If you wish to run
+   cephadm using a development version you should create your own build of
+   cephadm. See :ref:`compiling-cephadm` for details on how to create your own
+   standalone cephadm executable.
 
-curl-based installation
------------------------
 
-* Use ``curl`` to fetch the most recent version of the
-  standalone script.
+.. _cephadm_install_distros:
 
-  .. prompt:: bash #
-     :substitutions:
+distribution-specific installations
+-----------------------------------
 
-     curl --silent --remote-name --location https://github.com/ceph/ceph/raw/|stable-release|/src/cephadm/cephadm
+Some Linux distributions  may already include up-to-date Ceph packages.  In
+that case, you can install cephadm directly. For example:
 
-  Make the ``cephadm`` script executable:
+  In Ubuntu:
 
   .. prompt:: bash #
 
-   chmod +x cephadm
+     apt install -y cephadm
 
-  This script can be run directly from the current directory:
+  In CentOS Stream:
 
   .. prompt:: bash #
+     :substitutions:
 
-   ./cephadm <arguments...>
+     dnf search release-ceph
+     dnf install --assumeyes centos-release-ceph-|stable-release|
+     dnf install --assumeyes cephadm
 
-* 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:
+  In Fedora:
 
   .. prompt:: bash #
-     :substitutions:
 
-     ./cephadm add-repo --release |stable-release|
-     ./cephadm install
+     dnf -y install cephadm
 
-  Confirm that ``cephadm`` is now in your PATH by running ``which``:
+  In SUSE:
 
   .. prompt:: bash #
 
-    which cephadm
+     zypper install -y cephadm
 
-  A successful ``which cephadm`` command will return this:
+.. _cephadm_install_curl:
 
-  .. code-block:: bash
+curl-based installation
+-----------------------
 
-    /usr/sbin/cephadm
+* First, determine what version of Ceph you will need. You can use the releases
+  page to find the `latest active releases <https://docs.ceph.com/en/latest/releases/#active-releases>`_.
+  For example, we might look at that page and find that ``17.2.6`` is the latest
+  active release.
 
-.. _cephadm_install_distros:
+* Use ``curl`` to fetch a build of cephadm for that release.
 
-distribution-specific installations
------------------------------------
+  .. prompt:: bash #
+     :substitutions:
 
-.. 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.
+     CEPH_RELEASE=17.2.6 # replace this with the active release
+     curl --silent --remote-name --location https://download.ceph.com/rpm-${CEPH_RELEASE}/el9/noarch/cephadm
 
-Some Linux distributions  may already include up-to-date Ceph packages.  In
-that case, you can install cephadm directly. For example:
+  Ensure the ``cephadm`` file is executable:
 
-  In Ubuntu:
+  .. prompt:: bash #
+
+   chmod +x cephadm
+
+  This file can be run directly from the current directory:
 
   .. prompt:: bash #
 
-     apt install -y cephadm
+   ./cephadm <arguments...>
 
-  In CentOS Stream:
+* If you encounter any issues with running cephadm due to errors including
+  the message ``bad interpreter``, then you may not have Python or
+  the correct version of Python installed. The cephadm tool requires Python 3.6
+  and above. You can manually run cephadm with a particular version of Python by
+  prefixing the command with your installed Python version. For example:
 
   .. prompt:: bash #
      :substitutions:
 
-     dnf search release-ceph
-     dnf install --assumeyes centos-release-ceph-|stable-release|
-     dnf install --assumeyes cephadm
+     python3.8 ./cephadm <arguments...>
 
-  In Fedora:
+* 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:
 
   .. prompt:: bash #
+     :substitutions:
 
-     dnf -y install cephadm
+     ./cephadm add-repo --release |stable-release|
+     ./cephadm install
 
-  In SUSE:
+  Confirm that ``cephadm`` is now in your PATH by running ``which``:
 
   .. prompt:: bash #
 
-     zypper install -y cephadm
+    which cephadm
+
+  A successful ``which cephadm`` command will return this:
+
+  .. code-block:: bash
+
+    /usr/sbin/cephadm
 
 
 

diff --git a/doc/dev/cephadm/developing-cephadm.rst b/doc/dev/cephadm/developing-cephadm.rst
index d71c87b6a37a1635c36ab1f9e147483ec8139723..e6b8c302aa754470b3819c358137d2932b6ad3d8 100644 (file)
--- a/doc/dev/cephadm/developing-cephadm.rst
+++ b/doc/dev/cephadm/developing-cephadm.rst
@@ -389,6 +389,7 @@ Note regarding different variables used in the code
   (Not the case for e.g. OSDs. OSDs are always called OSD.N)
 * a ``daemon_name`` is ``<daemon_type>.<daemon_id>``
 
+.. _compiling-cephadm:
 
 Compiling cephadm
 =================