Open Stack

There seems to be a want for one tool to be used for each language's
guide, at least as far as I'm aware in the Python world, but I think
it applies everywhere else as well. However, in reality none of the
tools being discussed for any language are what you'd want to use to
both build an application and then to make that application available.

Looking at the current Apache Libcloud guide at
http://developer.openstack.org/firstapp-libcloud/, nearly all of that
guide is about creating and configuring the infrastructure upon which
to run an application (some of which isn't supported in libcloud, but
it fills in the gaps in other ways). Instead of using a tool suited
for that purpose — such as Salt, which uses Libcloud — the reader
builds tooling that serves a similar purpose from scratch. While it
explains how to use Libcloud and some other command line tools to do
those tasks quite well, it ultimately amounts to having the reader
write a large amount of unnecessary code in order to get the app
going.

While the steps serve as pretty good documentation for Libcloud, that
doesn't seem to be the point of the exercise. It would seem to me that
a lot of the infrastructure setup would be better explained in terms
of any number of the configuration management tools out there, and the
application code itself would be where the reader would get into
leveraging the various language libraries — in this case, Libcloud. At
the end of the exercise, I don't really feel successful after having
reinvented a wheel and deployed a pre-written application that wasn't
really discussed.


My first question is: What audience are these guides truly aimed at?
The Getting Started section offers the following:

"""
This guide is for experienced software developers who want to deploy
applications to OpenStack clouds.

If you are familiar with OpenStack but have not created a cloud
application in general or an OpenStack application in particular, this
section teaches you how to program with OpenStack components.
"""

Someone who is experienced is more than likely coming into this with
knowledge of a configuration management or deployment tool, and they
leave without a better handle on that situation as it pertains to
OpenStack. Someone who hasn't created a cloud application learns more
how they could build a deployment tool. Those two personas —
experienced application devs but new to OpenStack, and familiar with
OpenStack but not with building applications — are a fairly broad set
of skills to cover. Are those accurate audiences? Are there more?

My second question follows that: Given one or more of those audiences,
what is the end goal of these guides for them? The Getting Started
section offers the following:

"""
Deploying applications in a cloud environment can be very different
from deploying them in a traditional IT environment. This guide
teaches you how to deploy applications on OpenStack and some best
practices for cloud application development.
"""

As an application developer, I don't leave that guide knowing any more
about how to build my next great application to leverage what
OpenStack offers. A quick glance at the sample application showed no
use of OpenStack [0], and the guide showed me some lower-level stuff
on how OpenStack's APIs can hook me up with the infrastructure needed
to run the app. There are a few high-level general tips offered for
building cloud applications, but nothing that really draws me into how
applications are built to make use of OpenStack.

I don't do operations stuff, but having worked on SDKs for a while
now, the ops people I've talked to over the years are interested to
see something like python-openstacksdk but via Ansible. Telling them
'here's a bunch of methods you can call to get servers' is going to be
responded to with 'now show me a Playbook that uses openstacksdk'.

The documented goals — deploy apps, provide app dev best practices —
are approached in a way that shows OpenStack at a lower and shallower
level than is likely productive for a first timer coming from either
side. Since the language of an application is not necessarily tied to
its deployment tooling, does it make sense for these guides to be
one-language per guide? Does it make sense for deployment and
application development to be tied together in the same guide?


Overall, I would like to know more about who the guides are aimed at
and what should be learned from them before you get people coming in
from the various language SDK teams and start churning out the same
document but for other languages.


[0] except for two Oslo things that could just as easily use the
configparser and logging modules.