From 7c6a2cad96405616719b85c740aabd98558c93ac Mon Sep 17 00:00:00 2001 From: John Mulligan Date: Mon, 19 Sep 2022 13:46:48 -0400 Subject: [PATCH] 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 (cherry picked from commit d11cf0e82aab8d4cef9d423e5d463a373eaf383a) --- doc/cephadm/install.rst | 55 ++++++++++++++--------------------------- 1 file changed, 18 insertions(+), 37 deletions(-) diff --git a/doc/cephadm/install.rst b/doc/cephadm/install.rst index 066c6fd9d2c..412ca14169c 100644 --- a/doc/cephadm/install.rst +++ b/doc/cephadm/install.rst @@ -43,13 +43,9 @@ up-to-date cephadm. There are two ways to get the initial ``cephadm``: #. :ref:`distribution-specific installation methods` #. a :ref:`curl-based installation` method -Once you have an initial copy of cephadm avaiable, follow the steps to -:ref:`update to an active release of cephadm` 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. +.. 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. .. 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,13 +54,12 @@ that you have the latest fixes for the version of Ceph you'll be managing. cephadm. See :ref:`compiling-cephadm` for details on how to create your own standalone cephadm executable. - .. _cephadm_install_distros: distribution-specific installations ----------------------------------- -Some Linux distributions may already include Ceph packages. In +Some Linux distributions may already include up-to-date Ceph packages. In that case, you can install cephadm directly. For example: In Ubuntu: @@ -135,42 +130,28 @@ curl-based installation python3.8 ./cephadm -.. _cephadm_update: - -update cephadm --------------- +* 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: -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: + .. prompt:: bash # + :substitutions: - ./cephadm add-repo --release |stable-release| - ./cephadm install + ./cephadm add-repo --release |stable-release| + ./cephadm install -Confirm that ``cephadm`` is now in your PATH by running ``which`` or -``command -v``: + Confirm that ``cephadm`` is now in your PATH by running ``which``: -.. prompt:: bash # - - 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 ======================= -- 2.39.5