In the last few months, the jclouds community has been working hard on adding support for OpenStack Keystone V3. This has not been easy, as all the existing OpenStack APIs depend on it and we try hard to keep our APIs backwards-compatible. We wanted a clean solution that allowed users to upgrade with minimal changes required to existing code.

After lots of work, we're finally there and are very happy to announce that, starting from the upcoming 2.1.0 release, jclouds will also support version 3 of the OpenStack Keystone API!

No new dependencies will be required to use the OpenStack Keystone V3 API: openstack-keystone contains the code for both V2 and V3, so all jclouds providers and APIs can support both versions.

Configuring OpenStack services to use Keystone V3

Configuring OpenStack services to use Keystone V3 is pretty straightforward. Just create your jclouds context with the following configuration property:

Properties overrides = new Properties();
overrides.put(KeystoneProperties.KEYSTONE_VERSION, "3");

Configuring authentication

Keystone V3 supports several authentication mechanisms, which provide authentication tokens with different permissions. It is important to configure the correct authentication method, otherwise some operations offered by the Keystone API might not be available.

By default, jclouds uses password authentication with unscoped authorization. Project or domain authorization scopes can be configured by setting the KeystoneProperties.SCOPE property when creating your jclouds context, for example:

Properties overrides = new Properties();
// Project scoped authorization (can use the project name or the ID)
overrides.put(KeystoneProperties.SCOPE, "project:jclouds");
overrides.put(KeystoneProperties.SCOPE, "projectId:2f9b30f706bc45d7923e055567be2e98");
// Domain scoped authorization (can use the domain name or the ID)
overrides.put(KeystoneProperties.SCOPE, "domain:default");
overrides.put(KeystoneProperties.SCOPE, "domainId:2f9b30f706bc45d7923e055567be2e98");

Credentials in Keystone V3 must include the domain name and the username, as shown above.

Using Keystone V3 APIs

If you are using openstack-nova or other OpenStack APIs, configuring the properties above will suffice. This section describes changes needed only if you are using the Keystone API directly.

In order to use the openstack-keystone API to connect to Keystone V3, use the openstack-keystone-3 API ID when creating the context. For example:

KeystoneApi keystone = ContextBuilder.newBuilder("openstack-keystone-3")
   .endpoint("http://openstack-keystone/identity/v3")
   .credentials("domain:admin", "password")
   .overrides(overrides)
   .modules(ImmutableSet.of(new SLF4JLoggingModule()))
   .buildApi(KeystoneApi.class);

Invoking Keystone API methods that use PATCH operations

In the Keystone V3 API, most of the update operations are carried out by sending PATCH HTTP requests. The PATCH verb, however, is not supported by jclouds' default Java HTTP driver. If you plan to use such API methods, you will use an HTTP driver with support for PATCH, such as the OkHttp or ApacheHC drivers.

To configure an HTTP driver, add the corresponding module to the list of modules passed to the ContextBuilder when creating your jclouds context. For example:

KeystoneApi keystone = ContextBuilder.newBuilder("openstack-keystone-3")
   .endpoint("http://openstack-keystone/identity/v3")
   .credentials("domain:admin", "password")
   .overrides(overrides)
   .modules(ImmutableSet.of(new SLF4JLoggingModule(), new OkHttpCommandExecutorServiceModule())) // use OkHttp driver
   .buildApi(KeystoneApi.class);

Notes and breaking changes

Supporting both the V2 and V3 Keystone APIs required a major refactor of the openstack-keystone API. Many packages and classes have been renamed, moved and deleted as a result. If your code uses constants or other global classes, you may need to update the following package references:

• Class KeystoneProperties has been moved to org.jclouds.openstack.keystone.config.
• Class CredentialTypes has been moved to org.jclouds.openstack.keystone.auth.config.
• The KeystoneAuthenticationModule and the AuthenticationApiModule have been refactored and generalised into:
  • AuthenticationModule - Providing authentication services to all OpenStack APIs and providers.
  • ServiceCatalogModule - Providing endpoint resolution to all OpenStack APIs and providers.

Use AuthenticationModule and ServiceCatalogModule when developing OpenStack APIs.