Open Stack

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