Spec for keystone V3 Support changes

This spec will describe necessary changes to the python
neutronclient to integrate with python-keystoneclient
for authentication and session management.

Change-Id: Ia7b3aecba8361db1eabc82c7f93041b4c928ff4f

specs/juno/keystone-v3-api-support.rst

@@ -0,0 +1,229 @@
+..
+ This work is licensed under a Creative Commons Attribution 3.0 Unported
+ License.
+
+ http://creativecommons.org/licenses/by/3.0/legalcode
+
+==============================================================
+Add support for Keystone V3 APIs in the python-neutronclient.
+==============================================================
+
+URL of the launchpad blueprint:
+********************************************************************************
+https://blueprints.launchpad.net/python-neutronclient/+spec/keystone-api-v3-support
+
+This blueprint is meant to capture the changes necessary to the
+python-neutronclient to integrate with python-keystoneclient for authentication
+and session management.  All clients have this requirement.
+
+
+Problem description
+===================
+Python-neutronclient lacks Keystone V3 support. Furthermore, it is duplicating
+python-keystoneclient logic by maintaining its own version of Keystone V2
+authentication API and session management (i.e. endpoint lookup). A major
+drawback with this approach is that it must be constantly updated in response
+to any Keystone API changes. Maintenance is also a burden as authentication
+and session management are not consistent across all OpenStack Python clients.
+
+
+Proposed change
+===============
+Utilizing python-keystoneclient for authentication and session management
+so that they are completely abstracted from python-neutronclient. The changes
+are twofold, CLI (shell) and SDK (Client).
+
+CLI
+---
+For CLI, the global identity arguments, which are common to all the OpenStack
+Python clients, should be provided and facilitated by python-keystoneclient.
+Python-neutronclient does not need to know about them. It simply need a way
+to convey them to the end users. Therefore, the following global identity
+arguments will be isolated and eventually be facilitated by
+python-keystoneclient:
+
+- *--os-auth-url*
+- *--insecure*
+- *--os-cacert*
+- *--os-cert*
+- *--os-key*
+- *--os-token*
+- *--os-username*
+- *--os-user_id*
+- *--os-password*
+- *--os-user-domain-id*
+- *--os-user-domain-name*
+- *--os-tenant-name*
+- *--os-tenant-id*
+- *--os-project-name*
+- *--os-project-id*
+- *--os-project-domain-id*
+- *--os-project-domain-name*
+- *--os-region-name*
+- *--os-service-type* (Default to ``network``)
+- *--os-endpoint-type* (Default to ``publicURL``)
+- *--os-url* (DEPRECATED, should be using *--os-endpoint* instead)
+- *--os-endpoint*
+- *--os-auth-strategy* (DEPRECATED, absence of *--os-auth-url* signify no auth)
+
+
+Client
+------
+Use ``keystoneclient.session.Session`` for session management and
+python-keystoneclient auth plugin for authentication. This is done by
+introducing two optional arguments, ``session`` and ``auth``,  to
+``neutronclient.common.clientmanager.ClientManager`` class::
+
+    class ClientManager(object):
+        """Manages access to API clients, including authentication.
+        """
+        neutron = ClientCache(neutron_client.make_client)
+        # Provide support for old quantum commands (for example
+        # in stable versions)
+        quantum = neutron
+
+        def __init__(self, token=None, url=None,
+                     auth_url=None,
+                     endpoint_type=None,
+                     tenant_name=None,
+                     tenant_id=None,
+                     username=None,
+                     user_id=None,
+                     password=None,
+                     region_name=None,
+                     api_version=None,
+                     auth_strategy=None,
+                     insecure=False,
+                     ca_cert=None,
+                     log_credentials=False,
+                     service_type=None,
+                     session=None,
+                     auth=None
+                     ):
+
+Where caller can optionally pass in an instance of
+``keystoneclient.session.Session`` in ``session`` and an instance of
+``keystoneclient.auth.base.BaseAuthPlugin`` in ``auth``.
+
+If ``session`` is provided, we shall use it for HTTP session management instead
+of ``neutronclient.client.HTTPClient``. This is done by providing shims for the
+the existing ``neutronclient.client.HTTPClient`` to preserve backward
+compatibility.
+
+Changes to ``neutronclient.client``::
+
+    class SessionHTTPClient(HTTPClient):
+        """Shims for HTTPClient.
+
+        Requests are delegated to keystoneclient Session.
+        """
+
+        def __init__(self, session, auth,
+                     region_name=None,
+                     service_type='network',
+                     endpoint_type='publicURL'):
+
+    def _construct_http_client(*args, **kwargs):
+        session = kwargs.pop('session', None)
+        auth = kwargs.pop('auth', None)
+        if session:
+            return SessionHTTPClient(session, auth, **kwargs)
+        else:
+            return HTTPClient(**kwargs)
+
+
+For ``neutronclient.common.clientmanager.ClientManager`` and
+``neutronclient.v2_0.client.Client``, instead of instantiating
+``neutronclient.client.HTTPClient``, it will just call
+``neutronclient.client._construct_http_client`` to get a HTTP client
+object.
+
+At some point in the future if we choose to completely remove the old HTTPClient,
+we should also remove the ServiceCatalog class and all the home-grown parsing
+that goes with it.  It's much cleaner to simply let the keystone client do
+all that parsing.  bklei will add a fixme comment in the code to note that
+for future cleanup.
+
+Alternatives
+------------
+None -- this is a required change.
+
+
+Data model impact
+-----------------
+None.
+
+
+REST API impact
+---------------
+None.
+
+
+Security impact
+---------------
+None.
+
+
+Notifications impact
+--------------------
+None.
+
+
+Other end user impact
+---------------------
+In order to authenticate with V3 in keystone, if a username is provided
+for authentication, the user's domain name or id must also be provided.
+Similarly, if a tenant/project name is provided, the tenant's domain name
+or id must also be specified.
+
+Performance Impact
+------------------
+Shouldn't be any -- the same calls to keystone are being made, just via
+the keystone client instead of the neutron specific HTTPClient.
+
+
+Other deployer impact
+---------------------
+None.
+
+
+Developer impact
+----------------
+Same as the end user impact.
+
+
+Implementation
+==============
+
+Assignee(s)
+-----------
+Bradley Klein (bklei)
+
+
+Work Items
+----------
+Need to import the keystone client session and auth plugin, and construct
+both to authenticate.
+
+
+Dependencies
+============
+None, the keystone client already provides what is needed for this change.
+
+
+Testing
+=======
+Unit testing comprehensively tests the keystone integration, those tests will
+be modified/enhanced to also test the new V3 code.
+
+
+Documentation Impact
+====================
+The new domain specific parameters for the neutron command should be documented.
+It would also probably make sense to mention that the python-keystoneclient
+supports both v2 and v3 auth based on the value provided by auth-url.
+
+
+References
+==========
+None.