Re: [openstack-dev] Proposal: The OpenStack Client Library Guide
As someone who has dealt with this in the past[1], I can appreciate the complexities of trying to write software that can handle all the various auth options in OpenStack. In my case I gave up and passed all of that off to os-client-config (which, to be fair, is probably what I should have done in the first place, but isn't an option for non-Python projects). I'm not sure I can actually help with this since it didn't make any sense to me, but a big +1 to bringing some sanity to this whole thing. 1: http://blog.nemebean.com/content/creating-openstack-client-instances-python On 04/05/2018 10:55 PM, Adrian Turjak wrote: Hello fellow OpenStackers, As some of you have probably heard me rant, I've been thinking about how to better solve the problem with various tools that support OpenStack or are meant to be OpenStack clients/tools which don't always work as expected by those of us directly in the community. Mostly around things like auth and variable name conventions, and things which often there should really be consistency and overlap. The example that most recently triggered this discussion was how OpenStackClient (and os-client-config) supports certain elements of clouds.yaml and ENVVAR config, while Terraform supports it differently. Both you'd often run on the cli and often both in the same terminal, so it is always weird when certain auth and scoping values don't work the same. This is being worked on, but little problems like this an an ongoing problem. The proposal, write an authoritative guide/spec on the basics of implementing a client library or tool for any given language that talks to OpenStack. Elements we ought to cover: - How all the various auth methods in Keystone work, how the whole authn and authz process works with Keystone, and how to actually use it to do what you want. - What common client configuration options exist and how they work (common variable names, ENVVARs, clouds.yaml), with something like common ENVVARs documented and a list maintained so there is one definitive source for what to expect people to be using. - Per project guides on how the API might act that helps facilitate starting to write code against it beyond just the API reference, and examples of what to expect. Not exactly a duplicate of the API ref, but more a 'common pitfalls and confusing elements to be ware of' section that builds on the API ref of each project. There are likely other things we want to include, and we need to work out what those are, but ideally this should be a new documentation focused project which will result in useful guide on what someone needs to take any programming language, and write a library that works as we expect it should against OpenStack. Such a guide would also help any existing libraries ensure they themselves do fully understand and use the OpenStack auth and service APIs as expected. It should also help to ensure programmers working across multiple languages and systems have a much easier time interacting with all the various libraries they might touch. A lot of this knowledge exists, but it's hard to parse and not well documented. We have reference implementations of it all in the likes of OpenStackClient, Keystoneauth1, and the OpenStackSDK itself (which os-client-config is now a part of), but what we need is a language agnostic guide rather than the assumption that people will read the code of our official projects. Even the API ref itself isn't entirely helpful since in a lot of cases it only covers the most basic of examples for each API. There appears to be interest in something like this, so lets start with a mailing list discussion, and potentially turn it into something more official if this leads anywhere useful. :) Cheers, Adrian __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] Proposal: The OpenStack Client Library Guide
Hi Adrian, Thanks for starting this discussion. I'm adding openstack-sigs ML, please keep it in the loop. We in API SIG are interested in providing guidance on not only writing OpenStack APIs, but also consuming them. For example, we have merged a guideline on consuming API versions: http://specs.openstack.org/openstack/api-wg/guidelines/sdk-exposing-microversions.html More inline. On 04/06/2018 05:55 AM, Adrian Turjak wrote: Hello fellow OpenStackers, As some of you have probably heard me rant, I've been thinking about how to better solve the problem with various tools that support OpenStack or are meant to be OpenStack clients/tools which don't always work as expected by those of us directly in the community. Mostly around things like auth and variable name conventions, and things which often there should really be consistency and overlap. The example that most recently triggered this discussion was how OpenStackClient (and os-client-config) supports certain elements of clouds.yaml and ENVVAR config, while Terraform supports it differently. Both you'd often run on the cli and often both in the same terminal, so it is always weird when certain auth and scoping values don't work the same. This is being worked on, but little problems like this an an ongoing problem. The proposal, write an authoritative guide/spec on the basics of implementing a client library or tool for any given language that talks to OpenStack. Elements we ought to cover: - How all the various auth methods in Keystone work, how the whole authn and authz process works with Keystone, and how to actually use it to do what you want. Yes please! - What common client configuration options exist and how they work (common variable names, ENVVARs, clouds.yaml), with something like common ENVVARs documented and a list maintained so there is one definitive source for what to expect people to be using. Even bigger YES - Per project guides on how the API might act that helps facilitate starting to write code against it beyond just the API reference, and examples of what to expect. Not exactly a duplicate of the API ref, but more a 'common pitfalls and confusing elements to be ware of' section that builds on the API ref of each project. Oh yeah, esp. what to be mindful of when writing an SDK in a statically typed language (I had quite some fun with rust-openstack, I guess Terraform had similar issues). There are likely other things we want to include, and we need to work out what those are, but ideally this should be a new documentation focused project which will result in useful guide on what someone needs to take any programming language, and write a library that works as we expect it should against OpenStack. Such a guide would also help any existing libraries ensure they themselves do fully understand and use the OpenStack auth and service APIs as expected. It should also help to ensure programmers working across multiple languages and systems have a much easier time interacting with all the various libraries they might touch. A lot of this knowledge exists, but it's hard to parse and not well documented. We have reference implementations of it all in the likes of OpenStackClient, Keystoneauth1, and the OpenStackSDK itself (which os-client-config is now a part of), but what we need is a language agnostic guide rather than the assumption that people will read the code of our official projects. Even the API ref itself isn't entirely helpful since in a lot of cases it only covers the most basic of examples for each API. There appears to be interest in something like this, so lets start with a mailing list discussion, and potentially turn it into something more official if this leads anywhere useful. :) Count me in :) Cheers, Adrian __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
[openstack-dev] Proposal: The OpenStack Client Library Guide
Hello fellow OpenStackers, As some of you have probably heard me rant, I've been thinking about how to better solve the problem with various tools that support OpenStack or are meant to be OpenStack clients/tools which don't always work as expected by those of us directly in the community. Mostly around things like auth and variable name conventions, and things which often there should really be consistency and overlap. The example that most recently triggered this discussion was how OpenStackClient (and os-client-config) supports certain elements of clouds.yaml and ENVVAR config, while Terraform supports it differently. Both you'd often run on the cli and often both in the same terminal, so it is always weird when certain auth and scoping values don't work the same. This is being worked on, but little problems like this an an ongoing problem. The proposal, write an authoritative guide/spec on the basics of implementing a client library or tool for any given language that talks to OpenStack. Elements we ought to cover: - How all the various auth methods in Keystone work, how the whole authn and authz process works with Keystone, and how to actually use it to do what you want. - What common client configuration options exist and how they work (common variable names, ENVVARs, clouds.yaml), with something like common ENVVARs documented and a list maintained so there is one definitive source for what to expect people to be using. - Per project guides on how the API might act that helps facilitate starting to write code against it beyond just the API reference, and examples of what to expect. Not exactly a duplicate of the API ref, but more a 'common pitfalls and confusing elements to be ware of' section that builds on the API ref of each project. There are likely other things we want to include, and we need to work out what those are, but ideally this should be a new documentation focused project which will result in useful guide on what someone needs to take any programming language, and write a library that works as we expect it should against OpenStack. Such a guide would also help any existing libraries ensure they themselves do fully understand and use the OpenStack auth and service APIs as expected. It should also help to ensure programmers working across multiple languages and systems have a much easier time interacting with all the various libraries they might touch. A lot of this knowledge exists, but it's hard to parse and not well documented. We have reference implementations of it all in the likes of OpenStackClient, Keystoneauth1, and the OpenStackSDK itself (which os-client-config is now a part of), but what we need is a language agnostic guide rather than the assumption that people will read the code of our official projects. Even the API ref itself isn't entirely helpful since in a lot of cases it only covers the most basic of examples for each API. There appears to be interest in something like this, so lets start with a mailing list discussion, and potentially turn it into something more official if this leads anywhere useful. :) Cheers, Adrian __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev