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