From 4e15f03a636ccec76e24ad0736c125085deed34c Mon Sep 17 00:00:00 2001 From: Sebastian Wagner Date: Thu, 27 Feb 2020 10:57:58 +0100 Subject: [PATCH] doc/mgr/orchestrator: Add documentation for plcement specs Signed-off-by: Sebastian Wagner --- doc/mgr/orchestrator.rst | 14 +++++++++++ doc/mgr/orchestrator_modules.rst | 29 +++++++++++++---------- src/pybind/mgr/orchestrator/_interface.py | 4 ++-- 3 files changed, 32 insertions(+), 15 deletions(-) diff --git a/doc/mgr/orchestrator.rst b/doc/mgr/orchestrator.rst index 0ff0d08c84aab..887a682c5f8fb 100644 --- a/doc/mgr/orchestrator.rst +++ b/doc/mgr/orchestrator.rst @@ -250,6 +250,20 @@ Start/stop/reload:: ceph orch service {stop,start,reload} ceph orch daemon {start,stop,reload} + + +.. _orchestrator-cli-placement-spec: + +Placement Specification +======================= + +In order to allow the orchestrator to deploy a *service*, it needs to +know how many and where it should deploy *daemons*. The orchestrator +defines a placement specification: + +* To deploy three *daemons*, simply specify the count: ``3`` +* To deploy *daemons* on specific hosts, specify the host names: ``host1 host2 host3`` +* To deploy *daemons* on a subset of hosts, also specify the count: ``2 host1 host2 host3`` Configuring the Orchestrator CLI diff --git a/doc/mgr/orchestrator_modules.rst b/doc/mgr/orchestrator_modules.rst index 43160708a3cbc..198df53b81658 100644 --- a/doc/mgr/orchestrator_modules.rst +++ b/doc/mgr/orchestrator_modules.rst @@ -134,19 +134,6 @@ becomes *effective*, meaning that the operation has really happened .. autoclass:: ProgressReference :members: - -Placement ---------- - -In general, stateless services do not require any specific placement -rules, as they can run anywhere that sufficient system resources -are available. However, some orchestrators may not include the -functionality to choose a location in this way, so we can optionally -specify a location when creating a stateless service. - -OSD services generally require a specific placement choice, as this -will determine which storage devices are used. - Error Handling -------------- @@ -237,7 +224,23 @@ Devices .. py:currentmodule:: orchestrator +Placement +--------- + +A :ref:`orchestrator-cli-placement-spec` defines the placement of +daemons of a specifc service. + +In general, stateless services do not require any specific placement +rules as they can run anywhere that sufficient system resources +are available. However, some orchestrators may not include the +functionality to choose a location in this way. Optionally, you can +specify a location when creating a stateless service. + + +.. autoclass:: PlacementSpec + :members: + Services -------- diff --git a/src/pybind/mgr/orchestrator/_interface.py b/src/pybind/mgr/orchestrator/_interface.py index 6a521744d8fba..a8bd1b21c4b27 100644 --- a/src/pybind/mgr/orchestrator/_interface.py +++ b/src/pybind/mgr/orchestrator/_interface.py @@ -1223,9 +1223,9 @@ class PlacementSpec(object): def validate(self): if self.hosts and self.label: # TODO: a less generic Exception - raise Exception('Host and label are mutually exclusive') + raise OrchestratorValidationError('Host and label are mutually exclusive') if self.count is not None and self.count <= 0: - raise Exception("num/count must be > 1") + raise OrchestratorValidationError("num/count must be > 1") @classmethod def from_strings(cls, strings): -- 2.39.5