ceph/doc/mgr/orchestrator_cli.rst
Sebastian Wagner 26a7236ab5 doc/orchestrator: Integrate CLI specification into the documentation
Also: Make it clear that the orchestrator is WIP

Signed-off-by: Sebastian Wagner <sebastian.wagner@suse.com>
2018-11-21 18:23:51 +01:00

226 lines
6.7 KiB
ReStructuredText
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

.. _orchestrator-cli-module:
================
Orchestrator CLI
================
This module provides a command line interface (CLI) to orchestrator
modules (ceph-mgr modules which interface with external orchestation services)
As the orchestrator CLI unifies different external orchestrators, a common nomenclature
for the orchrstrator module is needed.
+--------------------------------------+--------------------------------------+
| host | hostname (not DNS name) on the |
| | physical host. Not the podname, |
| | container name, or hostname inside |
| | the container. |
+--------------------------------------+--------------------------------------+
| service | A logical service, e.g., “MDS for |
| | fs1” or “NFS gateway(s)”. Typically |
| | comprised of multiple service |
| | instances on multiple hosts for HA |
+--------------------------------------+--------------------------------------+
| service instance | A single instance of a service. |
| |  Usually a daemon, but maybe not |
| | (e.g., might be a kernel service |
| | like LIO or knfsd or whatever) |
+--------------------------------------+--------------------------------------+
| daemon | A running process on a host; use |
| | “service instance” instead |
+--------------------------------------+--------------------------------------+
Configuration
=============
You can select the orchestrator module to use with the ``set backend`` command::
ceph orchestrator set backend <module>
For example, to enable the Rook orchestrator module and use it with the CLI::
ceph mgr module enable orchestrator_cli
ceph mgr module enable rook
ceph orchestrator set backend rook
You can then check backend is properly configured::
ceph orchestrator status
Usage
=====
.. warning::
The orchestrator CLI is unfinished and work in progress. Some commands will not
exist, or return a different result.
.. note::
Orchestrator modules may only implement a subset of the commands listed below.
Also, the implementation of the commands are orchestrator module dependent and will
differ between implementations.
Status
~~~~~~
::
ceph orchestrator status
Show current orchestrator mode and high-level status (whether the module able
to talk to it)
Also show any in-progress actions.
..
Host Management
~ ~~~~~~~~~~~~~~
List hosts associated with the cluster: :
ceph orchestrator host ls
Add and remove hosts: :
ceph orchestrator host add <host>
ceph orchestrator host rm <host>
. . note: :
Removing a host only succeeds, if the host is unused.
OSD Management
~~~~~~~~~~~~~~
List Devices
^^^^^^^^^^^^
Print a list of discovered devices, grouped by node and optionally
filtered to a particular node:
::
ceph orchestrator device ls [--host=...] [--devname=...] [--refresh]
Create OSDs
^^^^^^^^^^^
Create OSDs on a group of devices on a single host::
ceph orchestrator osd create <host> <ceph-volume-invocation…>
See :ref:`ceph-volume-invocation… <ceph-volume-overview>` for details. E.g.
``ceph orchestrator osd create host1 lvm create …``
..
Decommission an OSD
^^^^^^^^^^^^^^^^^^^
::
ceph orchestrator osd rm <osd-id>
Removes an OSD from the cluster and the host, if the OSD is marked as
``destroyed``.
..
Blink Device Lights
^^^^^^^^^^^^^^^^^^^
::
ceph orchestrator device ident-on <host> <devname>
ceph orchestrator device ident-off <host> <devname>
ceph orchestrator device fault-on <host> <devname>
ceph orchestrator device fault-off <host> <devname>
ceph orchestrator osd ident-on {primary,journal,db,all} <osd-id>
ceph orchestrator osd ident-off {primary,journal,db,all} <osd-id>
ceph orchestrator osd fault-on {primary,journal,db,all} <osd-id>
ceph orchestrator osd fault-off {primary,journal,db,all} <osd-id>
..
Monitor and manager management
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
ceph orchestrator mon update <num> [host...]
ceph orchestrator mgr update <num> [host...]
Creates or removes MONs or MGRs from the cluster. Orchestrator may return an
error if it doesn't know how to do this transition.
.. note::
The host lists are the new full list of mon/mgr hosts
.. note::
specifying hosts is optional for some orchestrator modules
and mandatory for others (e.g. Ansible).
Service Management
~~~~~~~~~~~~~~~~~~
Service Status
^^^^^^^^^^^^^^
Print a list of services known to the orchestrator. The list can be limited to
services on a particular host with the optional --host parameter and/or
services of a particular type via optional --type parameter
(mon, osd, mgr, mds, rgw):
::
ceph orchestrator service ls [--host host] [--type type] [--refresh\|--no-cache]
Discover the status of a particular service::
ceph orchestrator service status <type> <name> [--refresh]
Query the status of a particular service instance (mon, osd, mds, rgw). For OSDs
the id is the numeric OSD ID, for MDS services it is the filesystem name::
ceph orchestrator service-instance status <type> <instance-name> [--refresh]
Stateless services (MDS/RGW/NFS/rbd-mirror/iSCSI)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The orchestrator is not responsible for configuring the services. Please look into the corresponding
documentation for details.
The ``name`` parameter is an identifier of the group of instances:
* a CephFS filesystem for a group of MDS daemons,
* a zone name for a group of RGWs
Sizing: the ``size`` parameter gives the number of daemons in the cluster
(e.g. the number of MDS daemons for a particular CephFS filesystem).
Creating/growing/shrinking services::
ceph orchestrator service update <type> <name> <size> [host…]
ceph orchestrator service add <type> <what>
e.g., ``ceph orchestrator service update mds myfs 3 host1 host2 host3``
Note: as with mon creation, the host list is optional, depending on the
orchestrator backend in use.
Start/stop/reload::
ceph orchestrator service {stop,start,reload} <type> <name>
ceph orchestrator service-instance {start,stop,reload} <type> <instance-name>
Removing services::
ceph orchestrator service rm <type> <name>