From: John Mulligan Date: Wed, 24 May 2023 17:42:26 +0000 (-0400) Subject: doc: make instructions to get an updated cephadm common X-Git-Tag: v18.2.1~323^2 X-Git-Url: http://git.apps.os.sepia.ceph.com/?a=commitdiff_plain;h=399275b6f0b3c5a52aaa0a3796546dddf8be0c26;p=ceph-ci.git 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 (cherry picked from commit d7921e88d69b4bc355da9c0327cc33e59e7d7abb) (cherry picked from commit d11cf0e82aab8d4cef9d423e5d463a373eaf383a) (cherry picked from commit 9ad38033cc5c7f177cb8fe3bae696682687e0346) 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 (cherry picked from commit d11cf0e82aab8d4cef9d423e5d463a373eaf383a) doc: add instructions for compiling cephadm Now that cephadm is based on zipapp, add a short section to the developer docs explaining how to build cephadm yourself. Signed-off-by: John Mulligan (cherry picked from commit 9ad38033cc5c7f177cb8fe3bae696682687e0346) --- diff --git a/doc/cephadm/install.rst b/doc/cephadm/install.rst index 26d752e0d29..b1aa736e225 100644 --- a/doc/cephadm/install.rst +++ b/doc/cephadm/install.rst @@ -50,8 +50,8 @@ There are two ways to install ``cephadm``: distribution-specific installations ----------------------------------- -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: @@ -121,28 +121,41 @@ curl-based installation python3.8 ./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: +.. _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 Bootstrap a new cluster =======================