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

.. _ceph-volume-lvm-activate:

``activate``
============

After :ref:`ceph-volume-lvm-prepare` has completed its run, the volume can be
activated. 

Activating the volume involves enabling a ``systemd`` unit that persists the
``OSD ID`` and its ``UUID`` (which is also called the ``fsid`` in the Ceph CLI
tools). After this information has been persisted, the cluster can determine
which OSD is enabled and must be mounted.

.. note:: The execution of this call is fully idempotent. This means that the
   call can be executed multiple times without changing the result of its first
   successful execution.

For information about OSDs deployed by cephadm, refer to
:ref:`cephadm-osd-activate`.

New OSDs
--------
To activate newly prepared OSDs both the :term:`OSD id` and :term:`OSD uuid`
need to be supplied. For example::

    ceph-volume lvm activate --bluestore 0 0263644D-0BF1-4D6D-BC34-28BD98AE3BC8

.. note:: The UUID is stored in the ``fsid`` file in the OSD path, which is
          generated when :ref:`ceph-volume-lvm-prepare` is used.

Activating all OSDs
-------------------

.. note:: For OSDs deployed by cephadm, please refer to :ref:`cephadm-osd-activate`
          instead.

It is possible to activate all existing OSDs at once by using the ``--all``
flag. For example::

    ceph-volume lvm activate --all

This call will inspect all the OSDs created by ceph-volume that are inactive
and will activate them one by one. If any of the OSDs are already running, it
will report them in the command output and skip them, making it safe to rerun
(idempotent).

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.


dmcrypt
^^^^^^^
If the OSD was prepared with dmcrypt by ceph-volume, there is no need to
specify ``--dmcrypt`` on the command line again (that flag is not available for
the ``activate`` subcommand). An encrypted OSD will be automatically detected.


Discovery
---------
With OSDs previously created by ``ceph-volume``, 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@lvm-$id-$uuid

For example::

    systemctl enable ceph-volume@lvm-0-8715BEB4-15C5-49DE-BA6F-401086EC7B41

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-lvm-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

.. note:: The system infers the objectstore type by
          inspecting the LVM tags applied to the OSD devices

Existing OSDs
-------------
For existing OSDs that have been deployed with ``ceph-disk``, they need to be
scanned and activated :ref:`using the simple sub-command <ceph-volume-simple>`.
If a different tool was used then 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 for :term:`bluestore`:

#. Require both :term:`OSD id` and :term:`OSD uuid`
#. Enable the system unit with matching id and uuid
#. Create the ``tmpfs`` mount at the OSD directory in
   ``/var/lib/ceph/osd/$cluster-$id/``
#. Recreate all the files needed with ``ceph-bluestore-tool prime-osd-dir`` by
   pointing it to the OSD ``block`` device.
#. The systemd unit will ensure all devices are ready and linked
#. The matching ``ceph-osd`` systemd unit will get started
Commit	Line	Data
b5b8bbf5 FG	1	.. _ceph-volume-lvm-activate:
	2
	3	``activate``
	4	============
39ae355f	5
aee94f69 TL	6	After :ref:`ceph-volume-lvm-prepare` has completed its run, the volume can be
aee94f69 TL	7	activated.
b5b8bbf5	8
aee94f69 TL	9	Activating the volume involves enabling a ``systemd`` unit that persists the
	10	``OSD ID`` and its ``UUID`` (which is also called the ``fsid`` in the Ceph CLI
	11	tools). After this information has been persisted, the cluster can determine
	12	which OSD is enabled and must be mounted.
b5b8bbf5	13
aee94f69 TL	14	.. note:: The execution of this call is fully idempotent. This means that the
	15	call can be executed multiple times without changing the result of its first
	16	successful execution.
b5b8bbf5	17
aee94f69 TL	18	For information about OSDs deployed by cephadm, refer to
aee94f69 TL	19	:ref:`cephadm-osd-activate`.
a4b75251	20
b5b8bbf5 FG	21	New OSDs
	22	--------
	23	To activate newly prepared OSDs both the :term:`OSD id` and :term:`OSD uuid`
	24	need to be supplied. For example::
	25
3efd9988	26	ceph-volume lvm activate --bluestore 0 0263644D-0BF1-4D6D-BC34-28BD98AE3BC8
b5b8bbf5	27
b32b8144	28	.. note:: The UUID is stored in the ``fsid`` file in the OSD path, which is
b5b8bbf5 FG	29	generated when :ref:`ceph-volume-lvm-prepare` is used.
b5b8bbf5 FG	30
28e407b8 AA	31	Activating all OSDs
28e407b8 AA	32	-------------------
a4b75251	33
39ae355f	34	.. note:: For OSDs deployed by cephadm, please refer to :ref:`cephadm-osd-activate`
a4b75251 TL	35	instead.
a4b75251 TL	36
28e407b8 AA	37	It is possible to activate all existing OSDs at once by using the ``--all``
	38	flag. For example::
	39
	40	ceph-volume lvm activate --all
	41
	42	This call will inspect all the OSDs created by ceph-volume that are inactive
	43	and will activate them one by one. If any of the OSDs are already running, it
	44	will report them in the command output and skip them, making it safe to rerun
	45	(idempotent).
	46
b5b8bbf5 FG	47	requiring uuids
	48	^^^^^^^^^^^^^^^
	49	The :term:`OSD uuid` is being required as an extra step to ensure that the
	50	right OSD is being activated. It is entirely possible that a previous OSD with
	51	the same id exists and would end up activating the incorrect one.
	52
	53
28e407b8 AA	54	dmcrypt
	55	^^^^^^^
	56	If the OSD was prepared with dmcrypt by ceph-volume, there is no need to
	57	specify ``--dmcrypt`` on the command line again (that flag is not available for
	58	the ``activate`` subcommand). An encrypted OSD will be automatically detected.
	59
	60
b5b8bbf5 FG	61	Discovery
b5b8bbf5 FG	62	---------
11fdf7f2	63	With OSDs previously created by ``ceph-volume``, a discovery process is
b5b8bbf5 FG	64	performed using :term:`LVM tags` to enable the systemd units.
	65
	66	The systemd unit will capture the :term:`OSD id` and :term:`OSD uuid` and
	67	persist it. Internally, the activation will enable it like::
	68
11fdf7f2	69	systemctl enable ceph-volume@lvm-$id-$uuid
b5b8bbf5 FG	70
	71	For example::
	72
11fdf7f2	73	systemctl enable ceph-volume@lvm-0-8715BEB4-15C5-49DE-BA6F-401086EC7B41
b5b8bbf5 FG	74
	75	Would start the discovery process for the OSD with an id of ``0`` and a UUID of
	76	``8715BEB4-15C5-49DE-BA6F-401086EC7B41``.
	77
3efd9988	78	.. note:: for more details on the systemd workflow see :ref:`ceph-volume-lvm-systemd`
b5b8bbf5 FG	79
	80	The systemd unit will look for the matching OSD device, and by looking at its
	81	:term:`LVM tags` will proceed to:
	82
1e59de90 TL	83	#. Mount the device in the corresponding location (by convention this is
1e59de90 TL	84	``/var/lib/ceph/osd/<cluster name>-<osd id>/``)
b5b8bbf5	85
1e59de90	86	#. Ensure that all required devices are ready for that OSD.
b5b8bbf5	87
1e59de90	88	#. Start the ``ceph-osd@0`` systemd unit
b5b8bbf5	89
1e59de90	90	.. note:: The system infers the objectstore type by
3efd9988 FG	91	inspecting the LVM tags applied to the OSD devices
3efd9988 FG	92
b5b8bbf5 FG	93	Existing OSDs
b5b8bbf5 FG	94	-------------
28e407b8 AA	95	For existing OSDs that have been deployed with ``ceph-disk``, they need to be
28e407b8 AA	96	scanned and activated :ref:`using the simple sub-command <ceph-volume-simple>`.
1e59de90	97	If a different tool was used then the only way to port them over to the new
28e407b8 AA	98	mechanism is to prepare them again (losing data). See
28e407b8 AA	99	:ref:`ceph-volume-lvm-existing-osds` for details on how to proceed.
b5b8bbf5 FG	100
	101	Summary
	102	-------
3efd9988 FG	103	To recap the ``activate`` process for :term:`bluestore`:
3efd9988 FG	104
1e59de90 TL	105	#. Require both :term:`OSD id` and :term:`OSD uuid`
1e59de90 TL	106	#. Enable the system unit with matching id and uuid
3efd9988 FG	107	#. Create the ``tmpfs`` mount at the OSD directory in
	108	``/var/lib/ceph/osd/$cluster-$id/``
	109	#. Recreate all the files needed with ``ceph-bluestore-tool prime-osd-dir`` by
	110	pointing it to the OSD ``block`` device.
1e59de90 TL	111	#. The systemd unit will ensure all devices are ready and linked
1e59de90 TL	112	#. The matching ``ceph-osd`` systemd unit will get started