Merge "Add identity user guide"

doc/source/users/guides/identity.rst

@@ -5,4 +5,107 @@ Before working with the Identity 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 in the examples below.
 
-.. TODO(thowe): Implement this guide
+The OpenStack Identity service is the default identity management system for
+OpenStack. The Identity service authentication process confirms the identity
+of a user and an incoming request by validating a set of credentials that the
+user supplies. Initially, these credentials are a user name and password or a
+user name and API key. When the Identity service validates user credentials,
+it issues an authentication token that the user provides in subsequent
+requests. An authentication token is an alpha-numeric text string that enables
+access to OpenStack APIs and resources. A token may be revoked at any time and
+is valid for a finite duration.
+
+List Users
+----------
+A **user** is a digital representation of a person, system, or service that
+uses OpenStack cloud services. The Identity service validates that incoming
+requests are made by the user who claims to be making the call. Users have
+a login and can access resources by using assigned tokens. Users can be
+directly assigned to a particular project and behave as if they are contained
+in that project.
+
+.. literalinclude:: ../examples/identity/list.py
+   :pyobject: list_users
+
+Full example: `identity resource list`_
+
+List Credentials
+----------------
+**Credentials** are data that confirms the identity of the user. For example,
+user name and password, user name and API key, or an authentication token that
+the Identity service provides.
+
+.. literalinclude:: ../examples/identity/list.py
+   :pyobject: list_credentials
+
+Full example: `identity resource list`_
+
+List Projects
+-------------
+A **project** is a container that groups or isolates resources or identity
+objects.
+
+.. literalinclude:: ../examples/identity/list.py
+   :pyobject: list_projects
+
+Full example: `identity resource list`_
+
+List Domains
+------------
+A **domain** is an Identity service API v3 entity and represents a collection
+of projects and users that defines administrative boundaries for the management
+of Identity entities. Users can be granted the administrator role for a domain.
+A domain administrator can create projects, users, and groups in a domain and
+assign roles to users and groups in a domain.
+
+.. literalinclude:: ../examples/identity/list.py
+   :pyobject: list_domains
+
+Full example: `identity resource list`_
+
+List Groups
+-----------
+A **group** is an Identity service API v3 entity and represents a collection of
+users that are owned by a domain. A group role granted to a domain or project
+applies to all users in the group. Adding users to, or removing users from, a
+group respectively grants, or revokes, their role and authentication to the
+associated domain or project.
+
+.. literalinclude:: ../examples/identity/list.py
+   :pyobject: list_groups
+
+Full example: `identity resource list`_
+
+List Services
+-------------
+A **service** is an OpenStack service, such as Compute, Object Storage, or
+Image service, that provides one or more endpoints through which users can
+access resources and perform operations.
+
+.. literalinclude:: ../examples/identity/list.py
+   :pyobject: list_services
+
+Full example: `identity resource list`_
+
+List Endpoints
+--------------
+An **endpoint** is a network-accessible address, usually a URL, through which
+you can access a service.
+
+.. literalinclude:: ../examples/identity/list.py
+   :pyobject: list_endpoints
+
+Full example: `identity resource list`_
+
+List Regions
+------------
+A **region** is an Identity service API v3 entity and represents a general
+division in an OpenStack deployment. You can associate zero or more
+sub-regions with a region to make a tree-like structured hierarchy.
+
+.. literalinclude:: ../examples/identity/list.py
+   :pyobject: list_regions
+
+Full example: `identity resource list`_
+
+.. _identity resource list: http://git.openstack.org/cgit/openstack/python-openstacksdk/tree/examples/identity/list.py

examples/connect.py

@@ -38,6 +38,8 @@ class Opts(object):
     def __init__(self, cloud_name='test_cloud', debug=False):
         self.cloud = cloud_name
         self.debug = debug
+        # Use identity v3 API for examples.
+        self.identity_api_version = '3'
 
 
 def _get_resource_value(resource_key, default):

examples/identity/list.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.
+
+"""
+List resources from the Identity service.
+
+For a full guide see TODO(etoews):link to docs on developer.openstack.org
+"""
+
+
+def list_users(conn):
+    print("List Users:")
+
+    for user in conn.identity.users():
+        print(user)
+
+
+def list_credentials(conn):
+    print("List Credentials:")
+
+    for credential in conn.identity.credentials():
+        print(credential)
+
+
+def list_projects(conn):
+    print("List Projects:")
+
+    for project in conn.identity.projects():
+        print(project)
+
+
+def list_domains(conn):
+    print("List Domains:")
+
+    for domain in conn.identity.domains():
+        print(domain)
+
+
+def list_groups(conn):
+    print("List Groups:")
+
+    for group in conn.identity.groups():
+        print(group)
+
+
+def list_services(conn):
+    print("List Services:")
+
+    for service in conn.identity.services():
+        print(service)
+
+
+def list_endpoints(conn):
+    print("List Endpoints:")
+
+    for endpoint in conn.identity.endpoints():
+        print(endpoint)
+
+
+def list_regions(conn):
+    print("List Regions:")
+
+    for region in conn.identity.regions():
+        print(region)

openstack/tests/examples/test_identity.py

@@ -0,0 +1,38 @@
+# 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.
+
+import unittest
+
+from examples import connect
+from examples.identity import list as identity_list
+
+
+class TestIdentity(unittest.TestCase):
+    """Test the identity examples
+
+    The purpose of these tests is to ensure the examples run without erring
+    out.
+    """
+
+    @classmethod
+    def setUpClass(cls):
+        cls.conn = connect.create_connection_from_config()
+
+    def test_identity(self):
+        identity_list.list_users(self.conn)
+        identity_list.list_credentials(self.conn)
+        identity_list.list_projects(self.conn)
+        identity_list.list_domains(self.conn)
+        identity_list.list_groups(self.conn)
+        identity_list.list_services(self.conn)
+        identity_list.list_endpoints(self.conn)
+        identity_list.list_regions(self.conn)