Minor text changes and small corrections
diff --git a/_posts/2018-01-11-keystone-v3.md b/_posts/2018-01-11-keystone-v3.md
index 50dd23f..f9b21be 100644
--- a/_posts/2018-01-11-keystone-v3.md
+++ b/_posts/2018-01-11-keystone-v3.md
@@ -7,16 +7,16 @@
title: OpenStack Keystone V3 Support
---
-The last months we have been working on adding support for **OpenStack Keystone V3**. It has not been an easy thing, as all of the existing OpenStack apis depend on it, and we try hard to keep our APIs backwards-compatible. We wanted to implement a clean solution that allowed users to upgrade to the new version with the minimum changes required to the existing code.
+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.
-We are happy to announce that starting from [jclouds 2.1.0](/releasenotes/2.1.0) we support the version 3 of the OpenStack Keystone API too.
+After lots of work, we're finally there and are very happy to announce that, starting from [2.1.0](/releasenotes/2.1.0), jclouds will also support version 3 of the OpenStack Keystone API!
<!--more-->
-To use the OpenStack Keystone V3 API you don't need to invlude any additional dependency. The `openstack-keystone` API contains the code for V2 and V3, so all providers and APIs have access to both versions.
+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
-Using Keystone V3 in OpenStack services is pretty straightforward. Just create the context and make sure to include the following configuration property:
+Configuring OpenStack services to use Keystone V3 is pretty straightforward. Just create your jclouds [context](/start/concepts/) with the following configuration property:
{% highlight java %}
Properties overrides = new Properties();
@@ -25,15 +25,13 @@
### Configuring authentication
-Keystone V3 supports several authentication mechanisms that provide authentication tokens with different permissions. It is important to configure the right authentication method, otherwise some operations offered by the Keystone API might not be available.
+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.
-The credentials in Keystone 3 must include the `domain` name and the `username`, as shown in the example above.
-
-By default, jclouds uses **password authentication with unscoped authorization**, although this can be changed by configuring the `KeystoneProperties.SCOPE` property when creating the context, to configure a project or domain authorization scope. For example
+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:
{% highlight java %}
Properties overrides = new Properties();
-// Project scoped authorization (can use the proejct name or the ID)
+// 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)
@@ -41,11 +39,13 @@
overrides.put(KeystoneProperties.SCOPE, "domainId:2f9b30f706bc45d7923e055567be2e98");
{% endhighlight %}
-# Using the Keystone V3 APIs
+Credentials in Keystone V3 must include the `domain` name and the `username`, as shown above.
-If you are using `openstack-nova` or other OpenStack API, configuring the properties above will suffice. This section details the changes related to the direct use of the Keystone API.
+# Using Keystone V3 APIs
-In order to use directly the `openstack-keystone` API to connect to Keystone V3, you'll have to use the `openstack-keystone-3` API ID when creating the context. Something like:
+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:
{% highlight java %}
KeystoneApi keystone = ContextBuilder.newBuilder("openstack-keystone-3")
@@ -58,23 +58,27 @@
### Invoking Keystone API methods that use PATCH operations
-In Keystone V3 most of the update operations are done by sending `PATCH` HTTP requests. However, the PATCH verb is not supported by the default Java HTTP driver. If you plan to use such API methods, you will need to include an HTTP driver that supports it, such as the [OkHttp](https://github.com/jclouds/jclouds/tree/master/drivers/okhttp) or the [ApacheHC](https://github.com/jclouds/jclouds/tree/master/drivers/apachehc) one. To configure the driver you just need to add the corresponding module to the list of modules passed to the `ContextBuilder` when creating the context. For example:
+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](https://github.com/jclouds/jclouds/tree/master/drivers/okhttp) or [ApacheHC](https://github.com/jclouds/jclouds/tree/master/drivers/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:
{% highlight java %}
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()))
+ .modules(ImmutableSet.of(new SLF4JLoggingModule(), new OkHttpCommandExecutorServiceModule())) // use OkHttp driver
.buildApi(KeystoneApi.class);
{% endhighlight %}
-# Upgrade notes and breaking changes
+# Notes and breaking changes
-In order to support V2 and V3, a major refactor has been done to the `openstack-keystone` API and many packages and classes have been renamed, moved and deleted. If your code is relying on constants or other global classes, you may need to update the package references.
+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 package `org.jclouds.openstack.keystone.config`.
-* Class `CredentialTypes` has been moved to package `org.jclouds.openstack.keystone.auth.config`.
+* 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.
+
+Replace uses of `KeystoneAuthenticationModule` with `AuthenticationModule`, and uses of `AuthenticationApiModule` with `ServiceCatalogModule`.
