From 26a7236ab5b577d8b052800543bf892cd608998f Mon Sep 17 00:00:00 2001 From: Sebastian Wagner Date: Thu, 15 Nov 2018 16:29:03 +0100 Subject: [PATCH] doc/orchestrator: Integrate CLI specification into the documentation Also: Make it clear that the orchestrator is WIP Signed-off-by: Sebastian Wagner --- doc/mgr/orchestrator_cli.rst | 195 +++++++++++++++++++--- src/pybind/mgr/orchestrator_cli/module.py | 24 +++ 2 files changed, 199 insertions(+), 20 deletions(-) diff --git a/doc/mgr/orchestrator_cli.rst b/doc/mgr/orchestrator_cli.rst index 55a76d7fa37c..145c1173eeae 100644 --- a/doc/mgr/orchestrator_cli.rst +++ b/doc/mgr/orchestrator_cli.rst @@ -8,27 +8,44 @@ 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: - -:: +You can select the orchestrator module to use with the ``set backend`` command:: ceph orchestrator set backend -For example, to enable the Rook orchestrator module and use it with the CLI: - -:: +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: - -:: +You can then check backend is properly configured:: ceph orchestrator status @@ -36,12 +53,121 @@ You can then check backend is properly configured: 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 + ceph orchestrator host rm + + . . 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: :: - orchestrator device ls [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 + +See :ref:`ceph-volume-invocation… ` for details. E.g. +``ceph orchestrator osd create host1 lvm create …`` + +.. + Decommission an OSD + ^^^^^^^^^^^^^^^^^^^ + :: + + ceph orchestrator osd rm  + + Removes an OSD from the cluster and the host, if the OSD is marked as + ``destroyed``. + +.. + Blink Device Lights + ^^^^^^^^^^^^^^^^^^^ + :: + + ceph orchestrator device ident-on + ceph orchestrator device ident-off + ceph orchestrator device fault-on + ceph orchestrator device fault-off + + ceph orchestrator osd ident-on {primary,journal,db,all} + ceph orchestrator osd ident-off {primary,journal,db,all} + ceph orchestrator osd fault-on {primary,journal,db,all} + ceph orchestrator osd fault-off {primary,journal,db,all} + +.. + Monitor and manager management + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + :: + + ceph orchestrator mon update [host...] + ceph orchestrator mgr update [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 @@ -50,21 +176,50 @@ services of a particular type via optional --type parameter :: - orchestrator service ls [--host=host] [--type=type] + ceph orchestrator service ls [--host host] [--type type] [--refresh\|--no-cache] -Query the status of a particular service (mon, osd, mgr, mds, rgw). For OSDs -the id is the numeric OSD ID, for MDS services it is the filesystem name: +Discover the status of a particular service:: -:: + ceph orchestrator service status  [--refresh] - orchestrator service status -Create a service. For an OSD, the "what" is :, where the -device naming should match what was reported in ``device ls``. For an MDS -service, the "what" is the filesystem name: +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  [--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   [host…] + ceph orchestrator service add + +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} + + ceph orchestrator service-instance {start,stop,reload} -:: - orchestrator service add +Removing services:: + ceph orchestrator service rm diff --git a/src/pybind/mgr/orchestrator_cli/module.py b/src/pybind/mgr/orchestrator_cli/module.py index d4bfcb3d499e..b0f1bd80b4fd 100644 --- a/src/pybind/mgr/orchestrator_cli/module.py +++ b/src/pybind/mgr/orchestrator_cli/module.py @@ -101,6 +101,30 @@ class OrchestratorCli(MgrModule): raise Exception([getattr(c, 'error') for c in completions]) def _list_devices(self, cmd): + """ + + This (all lines starting with ">") is how it is supposed to work. As of + now, it's not yet implemented: + > :returns: Either JSON: + > [ + >   { + >     "name": "sda", + >     "host": "foo", + >     ... lots of stuff from ceph-volume ... + >     "stamp": when this state was refreshed + >   }, + > ] + > + > or human readable: + > + > HOST  DEV  SIZE  DEVID(vendor\_model\_serial)   IN-USE  TIMESTAMP + > + > Note: needs ceph-volume on the host. + + Note: this does not have to be completely synchronous. Slightly out of + date hardware inventory is fine as long as hardware ultimately appears + in the output of this command. + """ node = cmd.get('node', None) if node: -- 2.47.3