Merge pull request ceph#61685 from zdover23/wip-doc-2025-02-07-cephadm-services-osd

doc/cephadm: improve "Activate Existing OSDs"

Reviewed-by: Anthony D'Atri <[email protected]>

Author: zdover23

doc/cephadm/services/osd.rst

@@ -1057,15 +1057,101 @@ using the `paths` keyword with the following syntax:
 Activate existing OSDs
 ======================
 
-In case the OS of a host was reinstalled, existing OSDs need to be activated
-again. For this use case, cephadm provides a wrapper for :ref:`ceph-volume-lvm-activate` that
-activates all existing OSDs on a host.
+If the operating system of a host has been reinstalled, the existing OSDs
+associated with it must be activated again. ``cephadm`` provides a wrapper for
+:ref:`ceph-volume-lvm-activate` that activates all existing OSDs on a host.
 
-.. prompt:: bash #
+The following procedure explains how to use ``cephadm`` to activate OSDs on a
+host that has recently had its operating system reinstalled.
+
+
+This procedure assumes the existence of two hosts: ``ceph01`` and ``ceph04``.
+
+- ``ceph01`` is a host equipped with an admin keyring. 
+- ``ceph04`` is the host with the recently reinstalled operating system.
+
+#. Install ``cephadm`` and ``podman`` on the host. The command for installing
+   these utilties will depend upon the operating system of the host.
+
+#. Retrieve the public key.
+
+   .. prompt:: bash ceph01#
+      
+      ceph cephadm get-pub-key > ceph.pub
+
+#. Copy the key to the freshly reinstalled host:
+
+   .. prompt:: bash ceph04#
+
+      ssh-copy-id -f -i ceph.pub root@<hostname>
+
+#. Retrieve the private key in order to test the connection:
+
+   .. prompt:: bash ceph01#
+
+      ceph config-key get mgr/cephadm/ssh_identity_key > ceph-private.key
+
+#. From ``ceph01``, Modify the permissions of ``ceph-private.key``:
+
+   .. prompt:: bash ceph01#
+
+      chmod 400 ceph-private.key
+
+#. Log in to ``ceph04`` from ``ceph01`` to test the connection and
+   configuration:
+
+   .. prompt:: bash ceph01#
+
+      ssh -i ceph-private.key ceph04
+
+#. While logged into ``ceph01``, remove ``ceph.pub`` and ``ceph-private.key``:
+
+   .. prompt:: bash ceph01#
+
+      rm ceph.pub ceph-private.key
+
+#. If you run your own container registry, instruct the orchestrator to log in
+   to each host in it: 
+
+   .. prompt:: bash #
+
+      ceph cephadm registry-login my-registry.domain <user> <password>
+
+   When the orchestrator performs the registry login, it will attempt to deploy
+   any missing daemons to the host. This includes ``crash``, ``node-exporter``,
+   and any other daemons that the host ran before its operating system was
+   reinstalled.
+
+   To be a bit clearer, ``cephadm`` attempts to deploy missing daemons to all
+   hosts that have been put under management by cephadm when ``cephadm``
+   determines that the hosts are online. In this context, "online" means
+   "present in the output of the ``ceph orch host ls`` command and possessing a
+   status that is not ``offline`` or ``maintenance``. If it is necessary to log
+   in to the registry in order to pull the images for the missing daemons, then
+   the deployment of the missing daemons will fail until the process of logging
+   in to the registry has been completed.
+
+   .. note:: This step is not necessary if you do not run your own container
+             registry. If your host is still in the "host list", which can be
+             retrieved by running the command ``ceph orch host ls``, you do not
+             need to run this command.
+
+#. Activate the OSDs on the host that has recently had its operating system
+   reinstalled:
+
+   .. prompt:: bash #
+
+      ceph cephadm osd activate <ceph04>
+
+   This command causes ``cephadm`` to scan all existing disks for OSDs. This
+   command will make ``cephadm`` deploy any missing daemons to the host
+   specified. 
+  
 
-  ceph cephadm osd activate <host>...
 
-This will scan all existing disks for OSDs and deploy corresponding daemons.
+*This procedure was developed by Eugen Block in Feburary of 2025, and a blog
+post pertinent to its development can be seen here:*
+`Eugen Block's "Cephadm: Activate existing OSDs" blog post <https://heiterbiswolkig.blogs.nde.ag/2025/02/06/cephadm-activate-existing-osds/>`_.
 
 Further Reading
 ===============