Cluster user guide - first step

This is a first step to add user guide for cluster service. Will propose
more contents in patches that follow.

Change-Id: I1f9a8f45f00872c5d2f375b123260d32adaa6d66

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 <cluster/profile_type>
+   Profile <cluster/profile>
+   Cluster <cluster/cluster>
+   Node <cluster/node>
+   Policy Type <cluster/policy_type>
+   Policy <cluster/policy>
+   Receiver <cluster/receiver>
+   Action <cluster/action>
+   Event <cluster/event>

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

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

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

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

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

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

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

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

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

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 <guides/connect_from_config>
    Logging <guides/logging>
    Block Store <guides/block_store>
+   Cluster <guides/cluster>
    Compute <guides/compute>
    Database <guides/database>
    Identity <guides/identity>

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.")

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())