Merge "Cluster user guide - part 2"

doc/source/users/guides/cluster/policy.rst

@@ -15,4 +15,88 @@
 Managing Policies
 =================
 
-.. TODO(Qiming): Implement this guide
+A **policy type**  can be treated as the meta-type of a `Policy` object. A
+registry of policy types is built when the Cluster service starts. When
+creating a `Policy` object, you will indicate the policy type used in its
+`spec` property.
+
+
+List Policies
+~~~~~~~~~~~~~
+
+To examine the list of policies:
+
+.. literalinclude:: ../../examples/cluster/policy.py
+   :pyobject: list_policys
+
+When listing policies, you can specify the sorting option using the ``sort``
+parameter and you can do pagination using the ``limit`` and ``marker``
+parameters.
+
+Full example: `manage policy`_
+
+
+Create Policy
+~~~~~~~~~~~~~
+
+When creating a policy, you will provide a dictionary with keys and values
+according to the policy type referenced.
+
+.. literalinclude:: ../../examples/cluster/policy.py
+   :pyobject: create_policy
+
+Optionally, you can specify a ``metadata`` keyword argument that contains some
+key-value pairs to be associated with the policy.
+
+Full example: `manage policy`_
+
+
+Find Policy
+~~~~~~~~~~~
+
+To find a policy based on its name or ID:
+
+.. literalinclude:: ../../examples/cluster/policy.py
+   :pyobject: find_policy
+
+Full example: `manage policy`_
+
+
+Get Policy
+~~~~~~~~~~
+
+To get a policy based on its name or ID:
+
+.. literalinclude:: ../../examples/cluster/policy.py
+   :pyobject: get_policy
+
+Full example: `manage policy`_
+
+
+Update Policy
+~~~~~~~~~~~~~
+
+After a policy is created, most of its properties are immutable. Still, you
+can update a policy's ``name`` and/or ``metadata``.
+
+.. literalinclude:: ../../examples/cluster/policy.py
+   :pyobject: update_policy
+
+The Cluster service doesn't allow updating the ``spec`` of a policy. The only
+way to achieve that is to create a new policy.
+
+Full example: `manage policy`_
+
+
+Delete Policy
+~~~~~~~~~~~~~
+
+A policy can be deleted after creation, provided that it is not referenced
+by any active clusters or nodes. If you attempt to delete a policy that is
+still in use, you will get an error message.
+
+.. literalinclude:: ../../examples/cluster/policy.py
+   :pyobject: delete_policy
+
+
+.. _manage policy: http://git.openstack.org/cgit/openstack/python-openstacksdk/tree/examples/cluster/policy.py

doc/source/users/guides/cluster/policy_type.rst

@@ -15,4 +15,31 @@
 Working with Policy Types
 =========================
 
-.. TODO(Qiming): Implement this guide
+A **policy** is a template that encodes the information needed for specifying
+the rules that are checked/enforced before/after certain actions are performed
+on a cluster. The rules are encoded in a property named ``spec``.
+
+
+List Policy Types
+~~~~~~~~~~~~~~~~~
+
+To examine the known policy types:
+
+.. literalinclude:: ../../examples/cluster/policy_type.py
+   :pyobject: list_policy_types
+
+Full example: `manage policy type`_
+
+
+Get Policy Type
+~~~~~~~~~~~~~~~
+
+To retrieve the details about a policy type, you need to provide the name of
+it.
+
+.. literalinclude:: ../../examples/cluster/policy_type.py
+   :pyobject: get_policy_type
+
+Full example: `manage policy type`_
+
+.. _manage profile type: http://git.openstack.org/cgit/openstack/python-openstacksdk/tree/examples/cluster/policy_type.py

examples/cluster/policy.py

@@ -0,0 +1,73 @@
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+
+"""
+Managing policies in the Cluster service.
+
+For a full guide see
+http://developer.openstack.org/sdks/python/openstacksdk/users/guides/cluster.html
+"""
+
+
+def list_policies(conn):
+    print("List Policies:")
+
+    for policy in conn.cluster.policies():
+        print(policy.to_dict())
+
+    for policy in conn.cluster.policies(sort='name:asc'):
+        print(policy.to_dict())
+
+
+def create_policy(conn):
+    print("Create Policy:")
+
+    spec = {
+        'policy': 'senlin.policy.deletion',
+        'version': 1.0,
+        'properties': {
+            'criteria': 'oldest_first',
+            'destroy_after_deletion': True,
+        }
+    }
+
+    policy = conn.cluster.create_policy('dp01', spec)
+    print(policy.to_dict())
+
+
+def get_policy(conn):
+    print("Get Policy:")
+
+    policy = conn.cluster.get_policy('dp01')
+    print(policy.to_dict())
+
+
+def find_policy(conn):
+    print("Find Policy:")
+
+    policy = conn.cluster.find_policy('dp01')
+    print(policy.to_dict())
+
+
+def update_policy(conn):
+    print("Update Policy:")
+
+    policy = conn.cluster.update_policy('dp01', name='dp02')
+    print(policy.to_dict())
+
+
+def delete_policy(conn):
+    print("Delete Policy:")
+
+    conn.cluster.delete_policy('dp01')
+
+    print("Policy deleted.")

examples/cluster/policy_type.py

@@ -0,0 +1,33 @@
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+
+"""
+Managing policy types in the Cluster service.
+
+For a full guide see
+http://developer.openstack.org/sdks/python/openstacksdk/users/guides/cluster.html
+"""
+
+
+def list_policy_types(conn):
+    print("List Policy Types:")
+
+    for pt in conn.cluster.policy_types():
+        print(pt.to_dict())
+
+
+def get_policy_type(conn):
+    print("Get Policy Type:")
+
+    pt = conn.cluster.get_policy_type('senlin.policy.deletion-1.0')
+
+    print(pt.to_dict())