[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 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
-------------------
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 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-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 (filestore or bluestore) 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 tooling 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

And for :term:`filestore`:

#. 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
3efd9988	20	ceph-volume lvm activate --bluestore 0 0263644D-0BF1-4D6D-BC34-28BD98AE3BC8
b5b8bbf5	21
b32b8144	22	.. note:: The UUID is stored in the ``fsid`` file in the OSD path, which is
b5b8bbf5 FG	23	generated when :ref:`ceph-volume-lvm-prepare` is used.
b5b8bbf5 FG	24
28e407b8 AA	25	Activating all OSDs
	26	-------------------
	27	It is possible to activate all existing OSDs at once by using the ``--all``
	28	flag. For example::
	29
	30	ceph-volume lvm activate --all
	31
	32	This call will inspect all the OSDs created by ceph-volume that are inactive
	33	and will activate them one by one. If any of the OSDs are already running, it
	34	will report them in the command output and skip them, making it safe to rerun
	35	(idempotent).
	36
b5b8bbf5 FG	37	requiring uuids
	38	^^^^^^^^^^^^^^^
	39	The :term:`OSD uuid` is being required as an extra step to ensure that the
	40	right OSD is being activated. It is entirely possible that a previous OSD with
	41	the same id exists and would end up activating the incorrect one.
	42
	43
28e407b8 AA	44	dmcrypt
	45	^^^^^^^
	46	If the OSD was prepared with dmcrypt by ceph-volume, there is no need to
	47	specify ``--dmcrypt`` on the command line again (that flag is not available for
	48	the ``activate`` subcommand). An encrypted OSD will be automatically detected.
	49
	50
b5b8bbf5 FG	51	Discovery
	52	---------
	53	With either existing OSDs or new ones being activated, a discovery process is
	54	performed using :term:`LVM tags` to enable the systemd units.
	55
	56	The systemd unit will capture the :term:`OSD id` and :term:`OSD uuid` and
	57	persist it. Internally, the activation will enable it like::
	58
	59	systemctl enable ceph-volume@$id-$uuid-lvm
	60
	61	For example::
	62
	63	systemctl enable ceph-volume@0-8715BEB4-15C5-49DE-BA6F-401086EC7B41-lvm
	64
	65	Would start the discovery process for the OSD with an id of ``0`` and a UUID of
	66	``8715BEB4-15C5-49DE-BA6F-401086EC7B41``.
	67
3efd9988	68	.. note:: for more details on the systemd workflow see :ref:`ceph-volume-lvm-systemd`
b5b8bbf5 FG	69
	70	The systemd unit will look for the matching OSD device, and by looking at its
	71	:term:`LVM tags` will proceed to:
	72
	73	# mount the device in the corresponding location (by convention this is
	74	``/var/lib/ceph/osd/<cluster name>-<osd id>/``)
	75
	76	# ensure that all required devices are ready for that OSD
	77
	78	# start the ``ceph-osd@0`` systemd unit
	79
3efd9988 FG	80	.. note:: The system infers the objectstore type (filestore or bluestore) by
	81	inspecting the LVM tags applied to the OSD devices
	82
b5b8bbf5 FG	83	Existing OSDs
b5b8bbf5 FG	84	-------------
28e407b8 AA	85	For existing OSDs that have been deployed with ``ceph-disk``, they need to be
	86	scanned and activated :ref:`using the simple sub-command <ceph-volume-simple>`.
	87	If a different tooling was used then the only way to port them over to the new
	88	mechanism is to prepare them again (losing data). See
	89	:ref:`ceph-volume-lvm-existing-osds` for details on how to proceed.
b5b8bbf5 FG	90
	91	Summary
	92	-------
3efd9988 FG	93	To recap the ``activate`` process for :term:`bluestore`:
	94
	95	#. require both :term:`OSD id` and :term:`OSD uuid`
	96	#. enable the system unit with matching id and uuid
	97	#. Create the ``tmpfs`` mount at the OSD directory in
	98	``/var/lib/ceph/osd/$cluster-$id/``
	99	#. Recreate all the files needed with ``ceph-bluestore-tool prime-osd-dir`` by
	100	pointing it to the OSD ``block`` device.
	101	#. the systemd unit will ensure all devices are ready and linked
	102	#. the matching ``ceph-osd`` systemd unit will get started
	103
	104	And for :term:`filestore`:
b5b8bbf5 FG	105
	106	#. require both :term:`OSD id` and :term:`OSD uuid`
	107	#. enable the system unit with matching id and uuid
	108	#. the systemd unit will ensure all devices are ready and mounted (if needed)
	109	#. the matching ``ceph-osd`` systemd unit will get started