Merge "User reference documentation for zone policy"

doc/source/user/policy_types/zone_placement.rst

@@ -11,9 +11,77 @@
   License for the specific language governing permissions and limitations
   under the License.
 
+.. _ref-zone-policy:
 
 =====================
 Zone Placement Policy
 =====================
 
-<TBD>
+The zone placement policy is designed to enable the deployment and management
+resource pools across multiple availability zones. Note that the current design
+is only concerned with the availability zones configured to Nova compute
+service. Support to Cinder availability zones and Neutron availability zones
+may be added in future when we have volume storage specific or network
+specific profile types.
+
+The current implementation of the zone placement policy works with clusters of
+Nova virtual machines only.
+
+
+Properties
+~~~~~~~~~~
+
+A typical spec for a zone placement policy is exemplified in the following
+sample:
+
+.. code-block:: yaml
+
+  type: senlin.policy.zone_placement
+  version: 1.0
+  properties:
+    regions:
+      - name: az_1
+        weight: 100
+      - name: az_2
+        weight: 200
+
+In this sample spec, two availability zones are provided, namely "``az_1``" and
+"``az_2``". Each availability zone can have an optional "``weight``" attribute
+associated with it.
+
+The "``weight``" value is to be interpreted as a relative number. The value
+assigned to one zone has to be compared to those assigned to other zones for
+an assessment. In the sample shown above, ``az_1`` and ``az_2`` are assigned
+weights of 100 and 200 respectively. This means that among every 3 nodes
+creation, one is expected to be scheduled to ``az_1`` and the other 2 are
+expected to be scheduled to ``az_2``. In other words, the chance for ``az_2``
+receiving a node creation request is twice of that for ``az_1``.
+
+The "``weight``" value has to be a positive integer, if specified. The default
+value is 100 for all zones whose weight is omitted.
+
+
+Validation
+~~~~~~~~~~
+
+When creating a zone placement policy, the Senlin engine validates whether
+the zone names given are all known to be usable availability zones by the Nova
+compute service. Do NOT pass in an invalid availability zone name and hope
+Senlin can create a zone for you.
+
+Later on when the zone placement policy is triggered upon node creation or node
+deletion actions, it always validates if the provided availability zones are
+still valid and usable.
+
+
+Node Distribution
+~~~~~~~~~~~~~~~~~
+
+After a zone placement polic is attached to a cluster and enabled, all future
+node creations (by cluster scaling for example) will trigger an evaluation of
+the policy. Similarly, a node deletion action will also trigger an evaluation
+of it because the policy's goal is to maintain the node distribution based on
+the one computed from the weight distribution of all zones.
+
+The zone placement policy will favor availability zones with highest weight
+values when selecting a zone for nodes to be created.