Documentation about Openstack Keystone v2/v3 usage #214

axel3rd · 2018-05-07T11:35:55Z

See JCLOUDS-1414, documentation about Openstack keystone v2/v3 usage

jclouds-commentator · 2018-05-07T11:37:59Z

Go to http://44ce6b87f08c84c4a336-587a4214cfc62e403204a0b0eced474e.r98.cf5.rackcdn.com/ to review your changes.

jclouds-commentator · 2018-05-07T11:45:11Z

Go to http://e8a2320cb8ee7328bc9a-98112aaa434232edc359e0c94cafc2fa.r90.cf5.rackcdn.com/ to review your changes.

jclouds-commentator · 2018-05-07T11:48:51Z

Go to http://4c17ddefb1e1845a6081-9bb6552a57750bbb30de030b38a1ebcc.r36.cf5.rackcdn.com/ to review your changes.

jclouds-commentator · 2018-05-07T11:51:43Z

Go to http://d6762342ecf65bd47950-3e336ecb7f68d8dda5e5d435de17b0ef.r3.cf5.rackcdn.com/ to review your changes.

axel3rd · 2018-05-07T11:53:53Z

Some tries about code & list typo, the last looks fine: Openstack Keystone v2-v3 authentication

andreaturli

thanks @axel3rd it is super useful!

I've left some comments mainly on the snippets: please address them and edit the document accordingly, i.e. if you replace Some.class with NovaApi.class make sure you do it all over the places.

Thanks

andreaturli · 2018-05-07T11:51:19Z

guides/openstack.md

+* On v2: *tenant*, *user*, *password*.
+* On v3: a *project* (new name for *tenant*), an authentication *domain* for this *project*, a *user*, an authentication *domain* for this *user* (the two domains can be different).
+
+JClouds provide backward compatibility between keystone v2-v3 ... but you should have following section in mind to fully understand the authentication on your Openstack platform (in addition of blog: [OpenStack Keystone V3 Support](https://jclouds.apache.org/blog/2018/01/16/keystone-v3/)).


please use jclouds or Apache jclouds

provides instead of provide

andreaturli · 2018-05-07T11:52:26Z

guides/openstack.md

+This snippet:
+{% highlight java %}
+final Properties overrides = new Properties();
+overrides.put(KeystoneProperties.KEYSTONE_VERSION, "2");


isn't KEYSTONE_VERSION=2 the default?

According the Javadoc the default is 3 ; but I have not verified or really measured the impact to not provide this property ...

thanks @axel3rd for the quick update

I think from nova code https://github.com/jclouds/jclouds/blob/master/apis/openstack-nova/src/main/java/org/jclouds/openstack/nova/v2_0/NovaApiMetadata.java#L74 the default keystone version is 3 but the extra property would probably not hurt

@demobox @nacx any preference?

I'd leave it here for clarity. Also as we move forward version 2 will be eventually deprecated and removed, so better encourage users to be explicit about the version being used.

andreaturli · 2018-05-07T11:54:56Z

guides/openstack.md

+final Properties overrides = new Properties();
+overrides.put(KeystoneProperties.KEYSTONE_VERSION, "2");
+
+ContextBuilder.newBuilder(new SomeApiMetadata())


why new SomeApiMetadata()? wouldn't be clear with something as generic as openstack-nova

andreaturli · 2018-05-07T11:57:04Z

guides/openstack.md

+   .endpoint("https://host:5000/v2.0")
+   .credentials("myTenant:foo", "bar")
+   .overrides(overrides)
+   .buildApi(Some.class);


why Some.class here? I think NovaApi.class is a bit better, as it is now in http://jclouds.apache.org/guides/openstack/#nova, wdyt?

jclouds-commentator · 2018-05-07T12:47:12Z

Go to http://393f4caa8037a748294f-756fd4e7d22e69a6f0ff4346cb78ae2b.r35.cf5.rackcdn.com/ to review your changes.

axel3rd · 2018-05-07T12:49:16Z

@andreaturli : Thanks for grammar fix & suggestions. Fixed in Keystone v2-v3 authentication. Except about KeystoneProperties.KEYSTONE_VERSION ... not sure about that.

andreaturli · 2018-05-07T12:52:39Z

Actually @axel3rd I think we should somehow edit List Servers and Swift: Use Containers paragraphs as well pointing maybe the reader to the authentication section above instead of using

        novaApi = ContextBuilder.newBuilder(provider)
                .endpoint("http://xxx.xxx.xxx.xxx:5000/v2.0/")
                .credentials(identity, credential)
                .modules(modules)
                .buildApi(NovaApi.class);

wdyt?

axel3rd · 2018-05-07T13:09:58Z

pointing maybe the reader to the authentication section above instead of using

I have hesitate to do that ... but the current snippet explicits how to retrieve an API (nova, swift, ...) even if v2 is deprecated (v3 needs more code).
So keystone considerations was writted before (hoping that user read it before trying sample).

Perhaps a consensus could be to add a comment before ContextBuilder like:

// Please refer to 'Keystone v2-v3 authentication' for complete authentication use case

nacx · 2018-05-07T13:17:54Z

One minor comment, but it would help readability if you format the generated json auth example.

jclouds-commentator · 2018-05-07T13:23:46Z

Go to http://ae4404efef77109c76ca-bf5e3651b7ed971bf54720901bab17d5.r49.cf5.rackcdn.com/ to review your changes.

jclouds-commentator · 2018-05-07T13:31:03Z

Go to http://eb3572d47d95412306ae-9ba5d3580b14e830c75c09652bfd2f59.r53.cf5.rackcdn.com/ to review your changes.

axel3rd · 2018-05-07T13:32:14Z

Perhaps a consensus could be to add a comment before ContextBuilder like [...]:
One minor comment, but it would help readability if you format the generated json auth example.

Done (without new-line-comma for json, to reduce lines number). Last proposal: Keystone v2-v3 authentication (and following)

nacx

Thanks! LGTM.
Since you reference a new keystone property I'd hold this and merge once the changes in Keystone are merged and the new property exists.

axel3rd · 2018-05-07T15:29:33Z

Since you reference a new keystone property I'd hold this and merge once the changes in Keystone are merged and the new property exists.

Yes ... and perhaps some minor change on properties name in progress ...

andreaturli · 2018-05-07T16:14:16Z

thanks @axel3rd

jclouds-commentator · 2018-05-07T16:16:37Z

Go to http://ad99be29f1570e3a80bb-ec8c9f9fa769d9cd6f2ad277a7469fe8.r48.cf5.rackcdn.com/ to review your changes.

axel3rd · 2018-05-07T16:17:20Z

Yes ... and perhaps some minor change on properties name in progress ...

Done, 1 line changed:

overrides.put(KeystoneProperties.PROJECT_DOMAIN_NAME, "default"); // Since jclouds v2.2.0 (see PROJECT_DOMAIN_ID as complement)

Linked with jclouds#1204.

nacx · 2018-05-10T09:01:32Z

Changes merged and published to the website. Thanks @axel3rd!

axel3rd · 2018-05-10T13:15:58Z

@nacx : As a "new feature", I didn't thought it was could be integrated in v2.1.x, I will be attentive to the roadmap because this PR doc is perhaps not true: : Keystone v2-v3 authentication (v3: Project-scoped)

overrides.put(KeystoneProperties.PROJECT_DOMAIN_NAME, "default"); // Since jclouds v2.2.0 (see PROJECT_DOMAIN_ID as complement)

nacx · 2018-05-10T13:36:51Z

We can change that. As long as the feature does not break backward compat, I see no problem in adding it in the next bugfix release. It will help adoption and facilitate early testing.

axel3rd · 2018-05-10T13:55:42Z

So very valuable 2 characters PR ^^ : #215

nacx · 2018-05-10T20:29:39Z

Often these tiny PRs get more review comments and change requests than thousand lines ones! :)

demobox · 2018-05-11T00:05:14Z

guides/openstack.md

@@ -92,6 +93,220 @@ There are some differences in terminology between jclouds and OpenStack that sho
  </div>
 </div>

+## <a id="keystone"></a>Keystone v2-v3 authentication
+
+Openstack Keystone (aka: [OpenStack Identity Service](https://docs.openstack.org/keystone/latest/)) has major changes between v2 and v3 (detail. [Identity API v2.0 and v3 History](https://docs.openstack.org/keystone/latest/contributor/http-api.html)).


[minor] Quite a few instances of "Openstack" (lowercase s) rather than "OpenStack" here - is that worth cleaning up?

In official documentation, "S" is in uppercase. I can do the cleanup in a way or the other, but we should choose :)

demobox · 2018-05-11T00:05:35Z

guides/openstack.md

+
+Openstack Keystone (aka: [OpenStack Identity Service](https://docs.openstack.org/keystone/latest/)) has major changes between v2 and v3 (detail. [Identity API v2.0 and v3 History](https://docs.openstack.org/keystone/latest/contributor/http-api.html)).
+
+Basically to login, you should provide:


[minor] Drop "basically"; just "To login, provide:"?

demobox · 2018-05-11T00:08:40Z

guides/openstack.md

+* On v2: *tenant*, *user*, *password*.
+* On v3: a *project* (new name for *tenant*), an authentication *domain* for this *project*, a *user*, an authentication *domain* for this *user* (the two domains can be different).
+
+jclouds provides backward compatibility between keystone v2-v3 ... but you should have following section in mind to fully understand the authentication on your Openstack platform (in addition of blog: [OpenStack Keystone V3 Support](https://jclouds.apache.org/blog/2018/01/16/keystone-v3/)).


[minor] "...compatibility between Keystone v2 and v3, but you should keep the following in mind to fully understand authentication against your OpenStack platform:

lots of examples

See also the recent "OpenStack Keystone v3 Support" blog post.

demobox · 2018-05-11T00:11:09Z

guides/openstack.md

+Will produce when authentication needed: 
+
+    POST https://host:5000/v2.0/tokens HTTP/1.1
+    {


Is there any particular benefit to trying to list the request so exactly here? In my experience, these are the parts of documentation that go stale very quickly.

Can we instead either give the code samples to the user and explain how they can configure logging to see what exactly is being sent (if that is necessary), or describe this a bit more abstractly, e.g. in form of a table?

Configure logging to see what exactly is sent is simple (jclouds write the property to set to true and SLF4J in debug).

The (little) difficulty in jclouds authentication usage is the option to configure. It depends mainly of OpenStack platform configuration (v2, v3, domains, ...) ... and some manual REST tries on token endpoint could be required to see what is supported by the platform.

So these snippet are to help the user on jclouds usage when it has found its way of auhentication on OpenStack.

demobox · 2018-05-11T00:12:20Z

guides/openstack.md

@@ -146,6 +361,7 @@ public class JCloudsNova implements Closeable {
        String identity = "demo:demo"; // tenantName:userName
        String credential = "devstack";

+        // Please refer to 'Keystone v2-v3 authentication' chapter for complete authentication use case


[minor] "section" rather than "chapter"? Also, should this comment perhaps come before the declaration of String identity?

axel3rd · 2018-05-11T11:44:55Z

@demobox : Thanks for the review. I will do it in a // PR (this one merged) after feedback on my remarks.

demobox · 2018-05-11T13:19:30Z

I will do it in a // PR (this one merged) after feedback on my remarks.

Thanks for taking a look! I should add that I think most of my comments are minor, and it's also fine to leave things as they are unless we feel there's really a good reason for a follow-up PR.

And thanks for helping improve the jclouds documentation, of course!

andreaturli suggested changes May 7, 2018

View reviewed changes

nacx approved these changes May 7, 2018

View reviewed changes

andreaturli approved these changes May 7, 2018

View reviewed changes

#JCLOUDS-1414: Documentation about Openstack Keystone v2/v3 usage

959eea7

axel3rd mentioned this pull request May 7, 2018

OpenStack Keystone V3 - different auth "domains" support (JCLOUDS-1414) jclouds/jclouds#1204

Closed

nacx closed this May 10, 2018

axel3rd deleted the JCLOUDS-1414-OpenstackKeystoneComplements branch May 10, 2018 13:12

demobox reviewed May 11, 2018

View reviewed changes

axel3rd mentioned this pull request May 11, 2018

JCLOUDS-1414: Keystone authentication improvment #216

Closed


		Openstack Keystone (aka: [OpenStack Identity Service](https://docs.openstack.org/keystone/latest/)) has major changes between v2 and v3 (detail. [Identity API v2.0 and v3 History](https://docs.openstack.org/keystone/latest/contributor/http-api.html)).

		Basically to login, you should provide:

Documentation about Openstack Keystone v2/v3 usage #214

Documentation about Openstack Keystone v2/v3 usage #214

Conversation

axel3rd commented May 7, 2018

jclouds-commentator commented May 7, 2018

jclouds-commentator commented May 7, 2018

jclouds-commentator commented May 7, 2018

jclouds-commentator commented May 7, 2018

axel3rd commented May 7, 2018

andreaturli left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jclouds-commentator commented May 7, 2018

axel3rd commented May 7, 2018

andreaturli commented May 7, 2018

axel3rd commented May 7, 2018

nacx commented May 7, 2018

jclouds-commentator commented May 7, 2018

jclouds-commentator commented May 7, 2018

axel3rd commented May 7, 2018

nacx left a comment

Choose a reason for hiding this comment

axel3rd commented May 7, 2018

andreaturli commented May 7, 2018

jclouds-commentator commented May 7, 2018

axel3rd commented May 7, 2018

nacx commented May 10, 2018

axel3rd commented May 10, 2018

nacx commented May 10, 2018

axel3rd commented May 10, 2018

nacx commented May 10, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

axel3rd commented May 11, 2018

demobox commented May 11, 2018