View source for Keystone V3 Migration for OpenStack Service Clients

= What's The Problem? =
Keystone deprecated the V2 APIs as of IceHouse. Per policy, Keystone will support them for 2 more releases. However, there's no certainty that the V2 APIs will continue to be supported beyond the K release, which is about a year from now. The problem is none of the OpenStack services are using the Keystone V3 APIs as of IceHouse. Furthermore, most of the ecosystem (i.e. integration tests, acceptance tests, etc) are still using Keystone V2 APIs.

One major limitation is with Keystone V2 is that it is not domain-aware. This limitation will be problematic when Horizon starting to support Keystone V3 as the default and customer have the need for domains. Consider the following use-case.

# Using Horizon, customer creates new domain Y, user X and project Z in domain Y, and assign roles to user X for project Z.
# Customer then uses an OpenStack service client (i.e. python-novaclient) to get a token for user X in domain Y by specifying the username for user X and project name for project Z. In this case, the action will result in unauthorized (401) as user X and project Z does not exist in the default domain.

= Migration Options =
OpenStack services (i.e. nova, swift, glance, etc) does NOT need to be domain-aware. However, they must be able to authenticate all users, including users in a non-default domain. Our initial investigate revealed all service clients (i.e. python-novaclient, python-swiftclient, etc) are impacted. However, there might be corner cases where the service server-side code are authenticating with Keystone using V2 APIs.

When upgrading Keystone from V2 (Folsom or older) to V3 (Havana or later), Keystone will create an immutable system default domain and migrate all the existing V2 users and projects (formerly tenants) to that domain. Keystone will continue to accept V2 API requests after the migration. However, V2 API can only lookup users and projects in the system default domain, when performing lookup by name. V3 API have access to all users and projects in all domains.

All Keystone IDs are globally unique, regardless of domain containment.

There are two migration options:

# Continue to use Keystone V2 but must also allow user IDs and project IDs for authentication as all IDs are globally unique.
# Integration with python-keystoneclient, and use it to handle authentication and session management.