diff --git a/doc/source/users/guides/cluster.rst b/doc/source/users/guides/cluster.rst new file mode 100644 index 000000000..d0a0474b8 --- /dev/null +++ b/doc/source/users/guides/cluster.rst @@ -0,0 +1,36 @@ +.. + 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. + + +======================= +Using OpenStack Cluster +======================= + +Before working with the Cluster service, you'll need to create a connection +to your OpenStack cloud by following the :doc:`connect` user guide. This will +provide you with the ``conn`` variable used by all examples in this guide. + +The primary abstractions/resources of the Cluster service are: + +.. toctree:: + :maxdepth: 1 + + Profile Type + Profile + Cluster + Node + Policy Type + Policy + Receiver + Action + Event diff --git a/doc/source/users/guides/cluster/action.rst b/doc/source/users/guides/cluster/action.rst new file mode 100644 index 000000000..1a07479eb --- /dev/null +++ b/doc/source/users/guides/cluster/action.rst @@ -0,0 +1,18 @@ +.. + 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. + +==================== +Working with Actions +==================== + +.. TODO(Qiming): Implement this guide diff --git a/doc/source/users/guides/cluster/cluster.rst b/doc/source/users/guides/cluster/cluster.rst new file mode 100644 index 000000000..b4772ef33 --- /dev/null +++ b/doc/source/users/guides/cluster/cluster.rst @@ -0,0 +1,18 @@ +.. + 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 Clusters +================= + +.. TODO(Qiming): Implement this guide diff --git a/doc/source/users/guides/cluster/event.rst b/doc/source/users/guides/cluster/event.rst new file mode 100644 index 000000000..185f454c5 --- /dev/null +++ b/doc/source/users/guides/cluster/event.rst @@ -0,0 +1,18 @@ +.. + 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. + +=================== +Working with Events +=================== + +.. TODO(Qiming): Implement this guide diff --git a/doc/source/users/guides/cluster/node.rst b/doc/source/users/guides/cluster/node.rst new file mode 100644 index 000000000..d4e2f54f1 --- /dev/null +++ b/doc/source/users/guides/cluster/node.rst @@ -0,0 +1,18 @@ +.. + 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 Nodes +============== + +.. TODO(Qiming): Implement this guide diff --git a/doc/source/users/guides/cluster/policy.rst b/doc/source/users/guides/cluster/policy.rst new file mode 100644 index 000000000..b9e0a0ff3 --- /dev/null +++ b/doc/source/users/guides/cluster/policy.rst @@ -0,0 +1,18 @@ +.. + 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 +================= + +.. TODO(Qiming): Implement this guide diff --git a/doc/source/users/guides/cluster/policy_type.rst b/doc/source/users/guides/cluster/policy_type.rst new file mode 100644 index 000000000..51ca0bca7 --- /dev/null +++ b/doc/source/users/guides/cluster/policy_type.rst @@ -0,0 +1,18 @@ +.. + 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. + +========================= +Working with Policy Types +========================= + +.. TODO(Qiming): Implement this guide diff --git a/doc/source/users/guides/cluster/profile.rst b/doc/source/users/guides/cluster/profile.rst new file mode 100644 index 000000000..ad3f5e5be --- /dev/null +++ b/doc/source/users/guides/cluster/profile.rst @@ -0,0 +1,105 @@ +.. + 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 Profiles +================= + +A **profile type** can be treated as the meta-type of a `Profile` object. A +registry of profile types is built when the Cluster service starts. When +creating a `Profile` object, you will indicate the profile type used in its +`spec` property. + + +List Profiles +~~~~~~~~~~~~~ + +To examine the list of profiles: + +.. literalinclude:: ../../examples/cluster/profile.py + :pyobject: list_profiles + +When listing profiles, you can specify the sorting option using the ``sort`` +parameter and you can do pagination using the ``limit`` and ``marker`` +parameters. + +Full example: `manage profile`_ + + +Create Profile +~~~~~~~~~~~~~~ + +When creating a profile, you will provide a dictionary with keys and values +specified according to the profile type referenced. + +.. literalinclude:: ../../examples/cluster/profile.py + :pyobject: create_profile + +Optionally, you can specify a ``metadata`` keyword argument that contains some +key-value pairs to be associated with the profile. + +Full example: `manage profile`_ + + +Find Profile +~~~~~~~~~~~~ + +To find a profile based on its name or ID: + +.. literalinclude:: ../../examples/cluster/profile.py + :pyobject: find_profile + +The Cluster service doesn't allow updating the ``spec`` of a profile. The only +way to achieve that is to create a new profile. + +Full example: `manage profile`_ + + +Get Profile +~~~~~~~~~~~~ + +To get a profile based on its name or ID: + +.. literalinclude:: ../../examples/cluster/profile.py + :pyobject: get_profile + +Full example: `manage profile`_ + + +Update Profile +~~~~~~~~~~~~~~ + +After a profile is created, most of its properties are immutable. Still, you +can update a profile's ``name`` and/or ``metadata``. + +.. literalinclude:: ../../examples/cluster/profile.py + :pyobject: update_profile + +The Cluster service doesn't allow updating the ``spec`` of a profile. The only +way to achieve that is to create a new profile. + +Full example: `manage profile`_ + + +Delete Profile +~~~~~~~~~~~~~~ + +A profile can be deleted after creation, provided that it is not referenced +by any active clusters or nodes. If you attempt to delete a profile that is +still in use, you will get an error message. + +.. literalinclude:: ../../examples/cluster/profile.py + :pyobject: delete_profile + + +.. _manage profile: http://git.openstack.org/cgit/openstack/python-openstacksdk/tree/examples/cluster/profile.py diff --git a/doc/source/users/guides/cluster/profile_type.rst b/doc/source/users/guides/cluster/profile_type.rst new file mode 100644 index 000000000..45183bf0a --- /dev/null +++ b/doc/source/users/guides/cluster/profile_type.rst @@ -0,0 +1,44 @@ +.. + 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. + +========================== +Working with Profile Types +========================== + +A **profile** is a template used to create and manage nodes, i.e. objects +exposed by other OpenStack services. A profile encodes the information needed +for node creation in a property named ``spec``. + + +List Profile Types +~~~~~~~~~~~~~~~~~~ + +To examine the known profile types: + +.. literalinclude:: ../../examples/cluster/profile_type.py + :pyobject: list_profile_types + +Full example: `manage profile type`_ + + +Get Profile Type +~~~~~~~~~~~~~~~~ + +To get the details about a profile type, you need to provide the name of it. + +.. literalinclude:: ../../examples/cluster/profile_type.py + :pyobject: get_profile_type + +Full example: `manage profile type`_ + +.. _manage profile type: http://git.openstack.org/cgit/openstack/python-openstacksdk/tree/examples/cluster/profile_type.py diff --git a/doc/source/users/guides/cluster/receiver.rst b/doc/source/users/guides/cluster/receiver.rst new file mode 100644 index 000000000..a34f67b7e --- /dev/null +++ b/doc/source/users/guides/cluster/receiver.rst @@ -0,0 +1,18 @@ +.. + 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 Receivers +================== + +.. TODO(Qiming): Implement this guide diff --git a/doc/source/users/index.rst b/doc/source/users/index.rst index a7b4a30ea..5063549f0 100644 --- a/doc/source/users/index.rst +++ b/doc/source/users/index.rst @@ -29,6 +29,7 @@ approach, this is where you'll want to begin. Connect to an OpenStack Cloud Using a Config File Logging Block Store + Cluster Compute Database Identity diff --git a/examples/cluster/__init__.py b/examples/cluster/__init__.py new file mode 100644 index 000000000..e69de29bb diff --git a/examples/cluster/profile.py b/examples/cluster/profile.py new file mode 100644 index 000000000..6f1709fbb --- /dev/null +++ b/examples/cluster/profile.py @@ -0,0 +1,82 @@ +# 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. + +from examples.connect import FLAVOR_NAME +from examples.connect import IMAGE_NAME +from examples.connect import NETWORK_NAME +from examples.connect import SERVER_NAME + +""" +Managing profiles in the Cluster service. + +For a full guide see +http://developer.openstack.org/sdks/python/openstacksdk/users/guides/cluster.html +""" + + +def list_profiles(conn): + print("List Profiles:") + + for profile in conn.cluster.profiles(): + print(profile.to_dict()) + + for profile in conn.cluster.profiles(sort='name:asc'): + print(profile.to_dict()) + + +def create_profile(conn): + print("Create Profile:") + + spec = { + 'profile': 'os.nova.server', + 'version': 1.0, + 'properties': { + 'name': SERVER_NAME, + 'flavor': FLAVOR_NAME, + 'image': IMAGE_NAME, + 'networks': { + 'network': NETWORK_NAME + } + } + } + + profile = conn.cluster.create_profile('os_server', spec) + print(profile.to_dict()) + + +def get_profile(conn): + print("Get Profile:") + + profile = conn.cluster.get_profile('os_server') + print(profile.to_dict()) + + +def find_profile(conn): + print("Find Profile:") + + profile = conn.cluster.find_profile('os_server') + print(profile.to_dict()) + + +def update_profile(conn): + print("Update Profile:") + + profile = conn.cluster.update_profile('os_server', name='old_server') + print(profile.to_dict()) + + +def delete_profile(conn): + print("Delete Profile:") + + conn.cluster.delete_profile('os_server') + + print("Profile deleted.") diff --git a/examples/cluster/profile_type.py b/examples/cluster/profile_type.py new file mode 100644 index 000000000..e1d8ff7f7 --- /dev/null +++ b/examples/cluster/profile_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 profile types in the Cluster service. + +For a full guide see +http://developer.openstack.org/sdks/python/openstacksdk/users/guides/cluster.html +""" + + +def list_profile_types(conn): + print("List Profile Types:") + + for pt in conn.cluster.profile_types(): + print(pt.to_dict()) + + +def get_profile_type(conn): + print("Get Profile Type:") + + pt = conn.cluster.get_profile_type('os.nova.server-1.0') + + print(pt.to_dict())