openstack/keystoneauth
Code Issues Proposed changes

Base Documentation changes

Browse Source 
Update the description to something more appropriate to keystoneauth and
remove the api version specific docs that are not relevant.

Change-Id: Ife0243f9ca5d268fee9544835f3a981cd47144c8
This commit is contained in:
Jamie Lennox 2015-05-01 09:50:10 +10:00
parent 581f4cd493
commit 66cc36a68e
3 changed files with 6 additions and 274 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
doc/source/index.rst
View File

@ -1,10 +1,10 @@
Python bindings to the OpenStack Identity API (Keystone)
========================================================
Common Authentication Library for OpenStack Clients
===================================================
This is a client for OpenStack Identity API. There's a Python API for
:doc:`Identity API v3 <using-api-v3>` and :doc:`v2 <using-api-v2>` (the
:mod:`keystoneauth` modules), and a command-line script (installed as
:doc:`keystone <man/keystone>`).
Keystoneauth provides a standard way to do authentication and service requests
within the OpenStack ecosystem. It is designed for use in conjunction with the
existing OpenStack clients and for simplifying the process of writing new
clients.
Contents:
@ -12,21 +12,10 @@ Contents:
:maxdepth: 1
man/keystone
using-api-v3
using-sessions
authentication-plugins
using-api-v2
api/modules
Related Identity Projects
=========================
In addition to creating the Python client library, the Keystone team also
provides `Identity Service`_, as well as `WSGI Middleware`_.
.. _`Identity Service`: http://docs.openstack.org/developer/keystone/
.. _`WSGI Middleware`: http://docs.openstack.org/developer/keystonemiddleware/
Contributing
============

117
doc/source/using-api-v2.rst
View File

@ -1,117 +0,0 @@
=======================
Using the V2 Client API
=======================
Introduction
============
The main concepts in the Identity v2 API are:
* tenants
* users
* roles
* services
* endpoints
The V2 client API lets you query and make changes through
managers. For example, to manipulate tenants, you interact with a
``keystoneauth.v2_0.tenants.TenantManager`` object.
You obtain access to managers via attributes of the
``keystoneauth.v2_0.client.Client`` object. For example, the ``tenants``
attribute of the ``Client`` class is a tenant manager::
>>> from keystoneauth.v2_0 import client
>>> keystone = client.Client(...)
>>> keystone.tenants.list() # List tenants
You create a valid ``keystoneauth.v2_0.client.Client`` object by passing
authentication data to the constructor. Authentication and examples of common
tasks are provided below.
You can generally expect that when the client needs to propagate an exception
it will raise an instance of subclass of
``keystoneauth.exceptions.ClientException``
Authenticating
==============
There are two ways to authenticate against Keystone:
* against the admin endpoint with the admin token
* against the public endpoint with a username and password
If you are an administrator, you can authenticate by connecting to the admin
endpoint and using the admin token (sometimes referred to as the service
token). The token is specified as the ``admin_token`` configuration option in
your keystone.conf config file, which is typically in /etc/keystone::
>>> from keystoneauth.v2_0 import client
>>> token = '012345SECRET99TOKEN012345'
>>> endpoint = 'http://192.168.206.130:35357/v2.0'
>>> keystone = client.Client(token=token, endpoint=endpoint)
If you have a username and password, authentication is done against the
public endpoint. You must also specify a tenant that is associated with the
user::
>>> from keystoneauth.v2_0 import client
>>> username='adminUser'
>>> password='secreetword'
>>> tenant_name='openstackDemo'
>>> auth_url='http://192.168.206.130:5000/v2.0'
>>> keystone = client.Client(username=username, password=password,
... tenant_name=tenant_name, auth_url=auth_url)
Creating tenants
================
This example will create a tenant named *openStackDemo*::
>>> from keystoneauth.v2_0 import client
>>> keystone = client.Client(...)
>>> keystone.tenants.create(tenant_name="openstackDemo",
... description="Default Tenant", enabled=True)
<Tenant {u'id': u'9b7962da6eb04745b477ae920ad55939', u'enabled': True, u'description': u'Default Tenant', u'name': u'openstackDemo'}>
Creating users
==============
This example will create a user named *adminUser* with a password *secretword*
in the opoenstackDemo tenant. We first need to retrieve the tenant::
>>> from keystoneauth.v2_0 import client
>>> keystone = client.Client(...)
>>> tenants = keystone.tenants.list()
>>> my_tenant = [x for x in tenants if x.name=='openstackDemo'][0]
>>> my_user = keystone.users.create(name="adminUser",
... password="secretword",
... tenant_id=my_tenant.id)
Creating roles and adding users
===============================
This example will create an admin role and add the *my_user* user to that
role, but only for the *my_tenant* tenant:
>>> from keystoneauth.v2_0 import client
>>> keystone = client.Client(...)
>>> role = keystone.roles.create('admin')
>>> my_tenant = ...
>>> my_user = ...
>>> keystone.roles.add_user_role(my_user, role, my_tenant)
Creating services and endpoints
===============================
This example will create the service and corresponding endpoint for the
Compute service::
>>> from keystoneauth.v2_0 import client
>>> keystone = client.Client(...)
>>> service = keystone.services.create(name="nova", service_type="compute",
... description="Nova Compute Service")
>>> keystone.endpoints.create(
... region="RegionOne", service_id=service.id,
... publicurl="http://192.168.206.130:8774/v2/%(tenant_id)s",
... adminurl="http://192.168.206.130:8774/v2/%(tenant_id)s",
... internalurl="http://192.168.206.130:8774/v2/%(tenant_id)s")

140
doc/source/using-api-v3.rst
View File

@ -1,140 +0,0 @@
=======================
Using the V3 Client API
=======================
Introduction
============
The main concepts in the Identity v3 API are:
* :py:mod:`~keystoneauth.v3.credentials`
* :py:mod:`~keystoneauth.v3.domains`
* :py:mod:`~keystoneauth.v3.endpoints`
* :py:mod:`~keystoneauth.v3.groups`
* :py:mod:`~keystoneauth.v3.policies`
* :py:mod:`~keystoneauth.v3.projects`
* :py:mod:`~keystoneauth.v3.regions`
* :py:mod:`~keystoneauth.v3.role_assignments`
* :py:mod:`~keystoneauth.v3.roles`
* :py:mod:`~keystoneauth.v3.services`
* :py:mod:`~keystoneauth.v3.tokens`
* :py:mod:`~keystoneauth.v3.users`
The :py:mod:`keystoneauth.v3.client` API lets you query and make changes
through ``managers``. For example, to manipulate a project (formerly
called tenant), you interact with a
:py:class:`keystoneauth.v3.projects.ProjectManager` object.
You obtain access to managers through attributes of a
:py:class:`keystoneauth.v3.client.Client` object. For example, the
``projects`` attribute of a ``Client`` object is a projects manager::
>>> from keystoneauth.v3 import client
>>> keystone = client.Client(...)
>>> keystone.projects.list() # List projects
While it is possible to instantiate a
:py:class:`keystoneauth.v3.client.Client` object (as done above for
clarity), the recommended approach is to use the discovery mechanism
provided by the :py:class:`keystoneauth.client.Client` class. The
appropriate class will be instantiated depending on the API versions
available::
>>> from keystoneauth import client
>>> keystone =
... client.Client(auth_url='http://localhost:5000', ...)
>>> type(keystone)
<class 'keystoneauth.v3.client.Client'>
One can force the use of a specific version of the API, either by
using the ``version`` keyword argument::
>>> from keystoneauth import client
>>> keystone = client.Client(auth_url='http://localhost:5000',
version=(2,), ...)
>>> type(keystone)
<class 'keystoneauth.v2_0.client.Client'>
>>> keystone = client.Client(auth_url='http://localhost:5000',
version=(3,), ...)
>>> type(keystone)
<class 'keystoneauth.v3.client.Client'>
Or by specifying directly the specific API version authentication URL
as the auth_url keyword argument::
>>> from keystoneauth import client
>>> keystone =
... client.Client(auth_url='http://localhost:5000/v2.0', ...)
>>> type(keystone)
<class 'keystoneauth.v2_0.client.Client'>
>>> keystone =
... client.Client(auth_url='http://localhost:5000/v3', ...)
>>> type(keystone)
<class 'keystoneauth.v3.client.Client'>
Upon successful authentication, a :py:class:`keystoneauth.v3.client.Client`
object is returned (when using the Identity v3 API). Authentication and
examples of common tasks are provided below.
You can generally expect that when the client needs to propagate an
exception it will raise an instance of subclass of
``keystoneauth.exceptions.ClientException`` (see
:py:class:`keystoneauth.openstack.common.apiclient.exceptions.ClientException`)
Authenticating Using Sessions
=============================
Instantiate a :py:class:`keystoneauth.v3.client.Client` using a
:py:class:`~keystoneauth.session.Session` to provide the authentication
plugin, SSL/TLS certificates, and other data::
>>> from keystoneauth.auth.identity import v3
>>> from keystoneauth import session
>>> from keystoneauth.v3 import client
>>> auth = v3.Password(auth_url='https://my.keystone.com:5000/v3',
... user_id='myuserid',
... password='mypassword',
... project_id='myprojectid')
>>> sess = session.Session(auth=auth)
>>> keystone = client.Client(session=sess)
For more information on Sessions refer to: `Using Sessions`_.
.. _`Using Sessions`: using-sessions.html
Non-Session Authentication (deprecated)
=======================================
The *deprecated* way to authenticate is to pass the username, the user's domain
name (which will default to 'Default' if it is not specified), and a
password::
>>> from keystoneauth import client
>>> auth_url = 'http://localhost:5000'
>>> username = 'adminUser'
>>> user_domain_name = 'Default'
>>> password = 'secreetword'
>>> keystone = client.Client(auth_url=auth_url, version=(3,),
... username=username, password=password,
... user_domain_name=user_domain_name)
A :py:class:`~keystoneauth.session.Session` should be passed to the Client
instead. Using a Session you're not limited to authentication using a username
and password but can take advantage of other more secure authentication
methods.
You may optionally specify a domain or project (along with its project
domain name), to obtain a scoped token::
>>> from keystoneauth import client
>>> auth_url = 'http://localhost:5000'
>>> username = 'adminUser'
>>> user_domain_name = 'Default'
>>> project_name = 'demo'
>>> project_domain_name = 'Default'
>>> password = 'secreetword'
>>> keystone = client.Client(auth_url=auth_url, version=(3,),
... username=username, password=password,
... user_domain_name=user_domain_name,
... project_name=project_name,
... project_domain_name=project_domain_name)