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 0ff0d08c84aab12f5e41a0900a4c892bb11d7223..887a682c5f8fb50c1fcc76a004536d28134856cc 100644 (file)
--- 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 43160708a3cbcd5f974cb53dfaadc6f0a637a8ee..198df53b816587e809d187fca9ff9fae89b3538d 100644 (file)
--- 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 6a521744d8fba37e1c6396118f7c957e1a886c1e..a8bd1b21c4b2775e66220de0207815844ffbd501 100644 (file)
--- 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):