From: Sebastian Wagner <sebastian.wagner@suse.com>
Date: Thu, 27 Feb 2020 09:57:58 +0000 (+0100)
Subject: doc/mgr/orchestrator: Add documentation for plcement specs
X-Git-Tag: v15.1.1~225^2~1
X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=4e15f03a636ccec76e24ad0736c125085deed34c;p=ceph.git

doc/mgr/orchestrator: Add documentation for plcement specs

Signed-off-by: Sebastian Wagner <sebastian.wagner@suse.com>
---

diff --git a/doc/mgr/orchestrator.rst b/doc/mgr/orchestrator.rst
index 0ff0d08c84aa..887a682c5f8f 100644
--- a/doc/mgr/orchestrator.rst
+++ b/doc/mgr/orchestrator.rst
@@ -250,6 +250,20 @@ Start/stop/reload::
     ceph orch service {stop,start,reload} <type> <name>
 
     ceph orch daemon {start,stop,reload} <type> <daemon-id>
+    
+
+.. _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 43160708a3cb..198df53b8165 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 6a521744d8fb..a8bd1b21c4b2 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):