Completed blog post
diff --git a/_posts/2018-01-11-keystone-v3.md b/_posts/2018-01-11-keystone-v3.md
index 6474ba4..50dd23f 100644
--- a/_posts/2018-01-11-keystone-v3.md
+++ b/_posts/2018-01-11-keystone-v3.md
@@ -9,14 +9,12 @@
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.
-We are happy to announce that starting from jclouds `2.1.0` we support the version 3 of the OpenStack Keystone API too.
+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.
<!--more-->
-## Using the OpenStack Keystone V3 API
-
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.
-### Configuring OpenStack services to use Keystone V3
+# 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:
@@ -25,19 +23,6 @@
overrides.put(KeystoneProperties.KEYSTONE_VERSION, "3");
{% endhighlight %}
-### Connecting to Keystone V3
-
-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:
-
-{% 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()))
- .buildApi(KeystoneApi.class);
-{% endhighlight %}
-
### 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.
@@ -48,15 +33,48 @@
{% highlight java %}
Properties overrides = new Properties();
-// Project scoped authorization (must use the proejct ID)
-overrides.put(KeystoneProperties.SCOPE, "project:2f9b30f706bc45d7923e055567be2e98");
+// Project scoped authorization (can use the proejct 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");
{% endhighlight %}
-## Upgrade notes and breaking changes
+# Using the Keystone V3 APIs
+
+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.
+
+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:
+
+{% 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()))
+ .buildApi(KeystoneApi.class);
+{% endhighlight %}
+
+### 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:
+
+{% 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()))
+ .buildApi(KeystoneApi.class);
+{% endhighlight %}
+
+# Upgrade 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.
-TODO: Details breaking changes
+* 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`.
+* 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.
