Open Stack

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-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>