[ceph.git] / ceph / doc / ceph-volume / lvm / activate.rst

.. _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/<cluster name>-<osd id>/``)

# 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
Commit	Line	Data
b5b8bbf5 FG	1	.. _ceph-volume-lvm-activate:
	2
	3	``activate``
	4	============
	5	Once :ref:`ceph-volume-lvm-prepare` is completed, and all the various steps
	6	that entails are done, the volume is ready to get "activated".
	7
	8	This activation process enables a systemd unit that persists the OSD ID and its
	9	UUID (also called ``fsid`` in Ceph CLI tools), so that at boot time it can
	10	understand what OSD is enabled and needs to be mounted.
	11
	12	.. note:: The execution of this call is fully idempotent, and there is no
	13	side-effects when running multiple times
	14
	15	New OSDs
	16	--------
	17	To activate newly prepared OSDs both the :term:`OSD id` and :term:`OSD uuid`
	18	need to be supplied. For example::
	19
	20	ceph-volume activate --filestore 0 0263644D-0BF1-4D6D-BC34-28BD98AE3BC8
	21
	22	.. note:: The UUID is stored in the ``osd_fsid`` file in the OSD path, which is
	23	generated when :ref:`ceph-volume-lvm-prepare` is used.
	24
	25	requiring uuids
	26	^^^^^^^^^^^^^^^
	27	The :term:`OSD uuid` is being required as an extra step to ensure that the
	28	right OSD is being activated. It is entirely possible that a previous OSD with
	29	the same id exists and would end up activating the incorrect one.
	30
	31
	32	Discovery
	33	---------
	34	With either existing OSDs or new ones being activated, a discovery process is
	35	performed using :term:`LVM tags` to enable the systemd units.
	36
	37	The systemd unit will capture the :term:`OSD id` and :term:`OSD uuid` and
	38	persist it. Internally, the activation will enable it like::
	39
	40	systemctl enable ceph-volume@$id-$uuid-lvm
	41
	42	For example::
	43
	44	systemctl enable ceph-volume@0-8715BEB4-15C5-49DE-BA6F-401086EC7B41-lvm
	45
	46	Would start the discovery process for the OSD with an id of ``0`` and a UUID of
	47	``8715BEB4-15C5-49DE-BA6F-401086EC7B41``.
	48
	49	.. note:: for more details on the systemd workflow see :ref:`ceph-volume-systemd`
	50
	51	The systemd unit will look for the matching OSD device, and by looking at its
	52	:term:`LVM tags` will proceed to:
	53
	54	# mount the device in the corresponding location (by convention this is
	55	``/var/lib/ceph/osd/<cluster name>-<osd id>/``)
	56
	57	# ensure that all required devices are ready for that OSD
	58
	59	# start the ``ceph-osd@0`` systemd unit
	60
	61	Existing OSDs
	62	-------------
	63	For exsiting OSDs that have been deployed with different tooling, the only way
	64	to port them over to the new mechanism is to prepare them again (losing data).
65	See :ref:`ceph-volume-lvm-existing-osds` for details on how to proceed.
66
67	Summary
68	-------
69	To recap the ``activate`` process:
70
71	#. require both :term:`OSD id` and :term:`OSD uuid`
72	#. enable the system unit with matching id and uuid
73	#. the systemd unit will ensure all devices are ready and mounted (if needed)
74	#. the matching ``ceph-osd`` systemd unit will get started