From f72662aeb4f6f966906386d00ff77f77225be928 Mon Sep 17 00:00:00 2001 From: tengqm Date: Fri, 26 Feb 2016 04:53:48 -0500 Subject: [PATCH] Cluster user guide - part 2 This patch adds more user guide to the cluster service. Change-Id: I0cdbad1784350529b1ec7d1ed2c06cae95776e08 --- doc/source/users/guides/cluster/policy.rst | 86 ++++++++++++++++++- .../users/guides/cluster/policy_type.rst | 29 ++++++- examples/cluster/policy.py | 73 ++++++++++++++++ examples/cluster/policy_type.py | 33 +++++++ 4 files changed, 219 insertions(+), 2 deletions(-) create mode 100644 examples/cluster/policy.py create mode 100644 examples/cluster/policy_type.py diff --git a/doc/source/users/guides/cluster/policy.rst b/doc/source/users/guides/cluster/policy.rst index b9e0a0ff3..7c708cac1 100644 --- a/doc/source/users/guides/cluster/policy.rst +++ b/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 diff --git a/doc/source/users/guides/cluster/policy_type.rst b/doc/source/users/guides/cluster/policy_type.rst index 51ca0bca7..3211564d4 100644 --- a/doc/source/users/guides/cluster/policy_type.rst +++ b/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 diff --git a/examples/cluster/policy.py b/examples/cluster/policy.py new file mode 100644 index 000000000..051b838db --- /dev/null +++ b/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.") diff --git a/examples/cluster/policy_type.py b/examples/cluster/policy_type.py new file mode 100644 index 000000000..f3bb03692 --- /dev/null +++ b/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())