From fd09deddcc5f8735e50656ff3606cf3dd97fd10d Mon Sep 17 00:00:00 2001 From: Alfredo Deza Date: Thu, 17 Aug 2017 09:05:39 -0400 Subject: [PATCH] doc/ceph-volume create the lvm activate reference Signed-off-by: Alfredo Deza --- doc/ceph-volume/lvm/activate.rst | 74 ++++++++++++++++++++++++++++++++ doc/ceph-volume/lvm/index.rst | 24 +++++++++++ 2 files changed, 98 insertions(+) create mode 100644 doc/ceph-volume/lvm/activate.rst create mode 100644 doc/ceph-volume/lvm/index.rst diff --git a/doc/ceph-volume/lvm/activate.rst b/doc/ceph-volume/lvm/activate.rst new file mode 100644 index 00000000000..b9f30d69f3d --- /dev/null +++ b/doc/ceph-volume/lvm/activate.rst @@ -0,0 +1,74 @@ +.. _ceph-volume-lvm-activate: + +``activate`` +============ +Once :ref:`ceph-volume-lvm-prepare` is completed, and all the various steps +that entails are done, the volume is ready to get "activated". + +This activation process enables a systemd unit that persists the OSD ID and its +UUID (also called ``fsid`` in Ceph CLI tools), so that at boot time it can +understand what OSD is enabled and needs to be mounted. + +.. note:: The execution of this call is fully idempotent, and there is no + side-effects when running multiple times + +New OSDs +-------- +To activate newly prepared OSDs both the :term:`OSD id` and :term:`OSD uuid` +need to be supplied. For example:: + + ceph-volume activate --filestore 0 0263644D-0BF1-4D6D-BC34-28BD98AE3BC8 + +.. note:: The UUID is stored in the ``osd_fsid`` file in the OSD path, which is + generated when :ref:`ceph-volume-lvm-prepare` is used. + +requiring uuids +^^^^^^^^^^^^^^^ +The :term:`OSD uuid` is being required as an extra step to ensure that the +right OSD is being activated. It is entirely possible that a previous OSD with +the same id exists and would end up activating the incorrect one. + + +Discovery +--------- +With either existing OSDs or new ones being activated, a *discovery* process is +performed using :term:`LVM tags` to enable the systemd units. + +The systemd unit will capture the :term:`OSD id` and :term:`OSD uuid` and +persist it. Internally, the activation will enable it like:: + + systemctl enable ceph-volume@$id-$uuid-lvm + +For example:: + + systemctl enable ceph-volume@0-8715BEB4-15C5-49DE-BA6F-401086EC7B41-lvm + +Would start the discovery process for the OSD with an id of ``0`` and a UUID of +``8715BEB4-15C5-49DE-BA6F-401086EC7B41``. + +.. note:: for more details on the systemd workflow see :ref:`ceph-volume-systemd` + +The systemd unit will look for the matching OSD device, and by looking at its +:term:`LVM tags` will proceed to: + +# mount the device in the corresponding location (by convention this is + ``/var/lib/ceph/osd/-/``) + +# ensure that all required devices are ready for that OSD + +# start the ``ceph-osd@0`` systemd unit + +Existing OSDs +------------- +For exsiting OSDs that have been deployed with different tooling, the only way +to port them over to the new mechanism is to prepare them again (losing data). +See :ref:`ceph-volume-lvm-existing-osds` for details on how to proceed. + +Summary +------- +To recap the ``activate`` process: + +#. require both :term:`OSD id` and :term:`OSD uuid` +#. enable the system unit with matching id and uuid +#. the systemd unit will ensure all devices are ready and mounted (if needed) +#. the matching ``ceph-osd`` systemd unit will get started diff --git a/doc/ceph-volume/lvm/index.rst b/doc/ceph-volume/lvm/index.rst new file mode 100644 index 00000000000..a40274802f0 --- /dev/null +++ b/doc/ceph-volume/lvm/index.rst @@ -0,0 +1,24 @@ +.. _ceph-volume-lvm: + +``lvm`` +======= +Implements the functionality needed to deploy OSDs from the ``lvm`` subcommand: +``ceph-volume lvm`` + +**Command Line Subcommands** + +* :ref:`ceph-volume-lvm-prepare` + +* :ref:`ceph-volume-lvm-activate` + +.. not yet implemented +.. * :ref:`ceph-volume-lvm-scan` + +**Internal functionality** + +There are other aspects of the ``lvm`` subcommand that are internal and not +exposed to the user, these sections explain how these pieces work together, +clarifying the workflows of the tool. + +:ref:`Systemd Units ` | +:ref:`lvm ` -- 2.39.5