Add identity user guide

Add an identity user guide to replace the current placeholder.  Also,
add identity examples and related tests to go along with the guide.
Much of the content for the guide was pulled from [1].

[1] http://docs.openstack.org/admin-guide-cloud/identity_management.html

Change-Id: Iec3caf601732c5c6f63331eac770d1325051aa82
Closes-Bug: #1466182

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)