From eb70a26a60dd81e3639b3fadd8251f8cfc337539 Mon Sep 17 00:00:00 2001 From: Brant Knudson Date: Sun, 28 Feb 2016 10:44:44 -0600 Subject: Update developer docs for keystoneauth session The developer docs should tell developers to use keystoneauth1 sessions rather than keystoneclient sessions or passing arguments to the Client constructors. keystoneclient sessions and constructing Clients using non-sessions is deprecated. Change-Id: Ica19b8d6fb2f5d1a9d0d22d4fe08abb266fd6a86 --- doc/source/using-api-v2.rst | 18 +++++++++++++----- doc/source/using-api-v3.rst | 8 ++++---- doc/source/using-sessions.rst | 17 +++++++++-------- 3 files changed, 26 insertions(+), 17 deletions(-) (limited to 'doc') diff --git a/doc/source/using-api-v2.rst b/doc/source/using-api-v2.rst index 6285d21..1b7c5de 100644 --- a/doc/source/using-api-v2.rst +++ b/doc/source/using-api-v2.rst @@ -26,8 +26,8 @@ attribute of the ``Client`` class is a tenant manager:: >>> keystone.tenants.list() # List tenants You create a valid ``keystoneclient.v2_0.client.Client`` object by passing -authentication data to the constructor. Authentication and examples of common -tasks are provided below. +a :class:`~keystoneauth1.session.Session` 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 @@ -45,22 +45,30 @@ 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 keystoneauth1.identity import v2 + >>> from keystoneauth1 import session >>> from keystoneclient.v2_0 import client >>> token = '012345SECRET99TOKEN012345' >>> endpoint = 'http://192.168.206.130:35357/v2.0' - >>> keystone = client.Client(token=token, endpoint=endpoint) + >>> auth = v2.Token(auth_url=endpoint, token=token) + >>> sess = session.Session(auth=auth) + >>> keystone = client.Client(session=sess) 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 keystoneauth1.identity import v2 + >>> from keystoneauth1 import session >>> from keystoneclient.v2_0 import client >>> username='adminUser' >>> password='secretword' >>> 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) + >>> auth = v2.Password(username=username, password=password, + ... tenant_name=tenant_name, auth_url=auth_url) + >>> sess = session.Session(auth=auth) + >>> keystone = client.Client(session=sess) Creating tenants ================ diff --git a/doc/source/using-api-v3.rst b/doc/source/using-api-v3.rst index 61b2b9d..5885f7c 100644 --- a/doc/source/using-api-v3.rst +++ b/doc/source/using-api-v3.rst @@ -85,11 +85,11 @@ Authenticating Using Sessions ============================= Instantiate a :py:class:`keystoneclient.v3.client.Client` using a -:py:class:`~keystoneclient.session.Session` to provide the authentication +:py:class:`~keystoneauth1.session.Session` to provide the authentication plugin, SSL/TLS certificates, and other data:: - >>> from keystoneclient.auth.identity import v3 - >>> from keystoneclient import session + >>> from keystoneauth1.identity import v3 + >>> from keystoneauth1 import session >>> from keystoneclient.v3 import client >>> auth = v3.Password(auth_url='https://my.keystone.com:5000/v3', ... user_id='myuserid', @@ -118,7 +118,7 @@ password:: ... username=username, password=password, ... user_domain_name=user_domain_name) -A :py:class:`~keystoneclient.session.Session` should be passed to the Client +A :py:class:`~keystoneauth1.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. diff --git a/doc/source/using-sessions.rst b/doc/source/using-sessions.rst index cd8fbb4..a5a5a58 100644 --- a/doc/source/using-sessions.rst +++ b/doc/source/using-sessions.rst @@ -5,7 +5,7 @@ Using Sessions Introduction ============ -The :py:class:`keystoneclient.session.Session` class was introduced into +The :py:class:`keystoneauth1.session.Session` class was introduced into keystoneclient as an attempt to bring a unified interface to the various OpenStack clients that share common authentication and request parameters between a variety of services. @@ -55,8 +55,8 @@ service and fetch a new one. An example from keystoneclient:: - >>> from keystoneclient.auth.identity import v3 - >>> from keystoneclient import session + >>> from keystoneauth1.identity import v3 + >>> from keystoneauth1 import session >>> from keystoneclient.v3 import client >>> auth = v3.Password(auth_url='https://my.keystone.com:5000/v3', @@ -189,11 +189,12 @@ While authentication plugins will endeavour to maintain a consistent set of arguments for an ``endpoint_filter`` the concept of an authentication plugin is purposefully generic and a specific mechanism may not know how to interpret certain arguments and ignore them. For example the -:py:class:`keystoneclient.auth.token_endpoint.Token` plugin (which is used when -you want to always use a specific endpoint and token combination) will always -return the same endpoint regardless of the parameters to ``endpoint_filter`` or -a custom OpenStack authentication mechanism may not have the concept of -multiple ``interface`` options and choose to ignore that parameter. +:py:class:`keystoneauth1.identity.generic.token.Token` plugin (which is used +when you want to always use a specific endpoint and token combination) will +always return the same endpoint regardless of the parameters to +``endpoint_filter`` or a custom OpenStack authentication mechanism may not have +the concept of multiple ``interface`` options and choose to ignore that +parameter. There is some expectation on the user that they understand the limitations of the authentication system they are using. -- cgit v1.2.1