[openstack-dev] [docs] Our Install Guides Only Cover Defcore - What about big tent?

Matt Kassawara mkassawara at gmail.com
Fri Apr 1 18:38:02 UTC 2016


I didn't see this e-mail until now because I'm busy trying to update and
test the installation guide in time for the Mitaka release. As a primary
contributor to the installation guide for about six releases including
restructuring it a couple of times, I think I can explain why we do what we

First, a little history about the guide...

The installation guide often provides the first experience for people
trying OpenStack. Thus, the guide should provide not just a good
experience, but a great experience. We can all agree on wanting more
adoption of OpenStack. For many people, launching an instance and being
able to access it feels like summiting a mountain. My first experience with
OpenStack involved nearly a month of trying to install Grizzly with neutron
for evaluation purposes using the installation guide. It didn't work.
Looking at various support channels such as IRC and ask.openstack.org, most
people were stuck at the same place without any answers. I finally
determined that nova lacked the configuration telling it to use neutron for
networking, so it kept attempting to build nova networks when those
components didn't exist. I opened a bug and someone fixed it. Shortly
thereafter, I began addressing the seemingly infinite number of
installation guide bugs. However, the cycle of frustration was beginning to
repeat itself with Havana. The reactive method of finding a problem,
opening a bug, and waiting for a patch simply wasn't working for our
audience of potential operators, not developers, that just expect it to

So, I proposed changing the guide from reactive to proactive. In other
words, we update and test the guide prior to release for every distribution
it supports. We began this approach with Icehouse and saw a decrease in
bugs and frustration. Furthermore, when assisting people through various
support channels, we could more easily determine whether the problem was a
just a typo or a problem with the guide. However, proactively maintaining
the guide put a significant burden on the contributors. Gone were the days
of "fire-and-forget" patches. Almost all patches require actual testing,
sometimes across several distributions. Updating the guide for the next
release requires performing full installations, often several times per
distribution, until we can successfully install and test all services
without deviating from the instructions. A considerable amount of work,
especially about a month before release when contributors who involve
themselves in other projects are also busy trying to release those
projects. Thus, the installation guide has seen a decrease in contributions
making it increasingly difficult to update and test for each release.
Furthermore, the installation guide receives little, if any, support from
most projects including "core" projects. Even if those projects know about
the installation guide, most assume that the documentation team magically
updates it for every release to deploy each service in a basic fashion
accounting for configuration changes and recommendations. From the
perspective of a project developer, those updates probably seem simple.
Just read the code, track patches, and maybe attend some meetings, right?
>From the perspective of installation guide contributors, we can't involve
ourselves that deeply in one project let alone nearly ten projects. Imagine
us trying to consider big tent projects? We have begged projects for years
to provide resources for maintaining the installation guide. If nothing
else, provide some notes on an etherpad indicating what we should change.
At this point in the game, we shouldn't have to resort to deprecation
messages or gate job configurations to determine how to deploy a service.

Regarding use of distribution packages instead of source...

The guide uses distribution packages instead of source because our audience
is usually familiar with them and they eliminate a significant number of
steps in an already complex and often overwhelming process. For example,
packages manage dependencies and provide init scripts. The installation
guide teaches our audience how to deploy the most common OpenStack services
for evaluation purposes. For example, our audience quickly learns that each
service typically depends on keystone, a database, and a message queue.
After getting comfortable with the installation process, we recommend
implementing redundancy/security on top of a basic installation and
eventually tooling for a production deployment.

Distribution packages aren't perfect by any means. First, they usually lag
the upstream release cycle by several weeks which forces us to update and
test changes using milestones, sometimes not even the last "feature-freeze"
milestone, after the first release candidate appears upstream. Next, they
sometimes contain bugs and packagers seldom contribute resources to triage
and address them which forces us to implement workarounds that can confuse
or distract our audience. Finally, and most importantly, we can only
include a project in the installation guide if all distributions provide
packages for it which prevents us from adding many newer projects and just
about anything in the big tent.

We would love to add all sufficiently mature projects to the installation
guide because it increases visibility and adoption by operators, but we
lack resources to develop a source installation mechanism that retains as
much simplicity as possible for our audience.

Regarding use of installation content from the developer reference guides...

We can't maintain the proactive nature, consistent structure, and quality
of the installation guide by referencing content in a bunch of disparate
repositories. We also can't easily manage bugs in those repositories.

Regarding Debian, and I'll be brief...

The Debian instructions haven't worked nor received sufficient attention to
resolve significant issues since I began using OpenStack. In fact, I chose
Debian for my first installation and quickly changed to Ubuntu after
getting stuck prior to the nova-neutron interaction problem. We try to
reuse as much content as possible. For example, the configuration for each
service shouldn't depend on distribution. Debian uses a unique GUI-style
mechanism rather than editing files to configure OpenStack services. This
mechanism not only prevents content reuse but also often lacks
configuration changes and recommendations for each release. Furthermore, it
forces us to rely on package maintainers to implement these changes and
recommendations. We could easily disable this mechanism and more or less
follow the instructions for Ubuntu with a different source of packages, but
the primary maintainer of those packages won't let us do it. The Debian
content consumes a considerable amount of space in the source and we can't
reuse it, so we're removing it to ease content contributions for the
distributions we publish.

Long story short...

We get plenty of empty commitments from developers and operators. If you
want to change the installation guide, convert your energy from complaining
about it to actually doing something about it.


On Wed, Mar 30, 2016 at 7:46 AM, Doug Hellmann <doug at doughellmann.com>

> On Wed, Mar 30, 2016, at 03:37 AM, Thomas Goirand wrote:
> > On 03/29/2016 08:33 PM, Doug Hellmann wrote:
> > > If the core doc team isn't able to help you maintain it, maybe it's a
> > > candidate for a separate guide, just like we're discussing for projects
> > > that aren't part of the DefCore set included in the main guide.
> > >
> > > Doug
> >
> > This is exactly what I don't want. Only installing the packages
> > themselves is different. Like for example, "apt-get install foo" and
> > answering a few debconf prompts is often enough to get packages to work,
> > without the need for manual setup of dbs, or rabbitMQ credentials. But
> > that's maybe 20% of the install-guide, and the rest of is left
> > untouched, with no conditionals. For example the description of the
> > services, testing them after install, etc. Having a separated guide
> > would mean that someone would be left to write a full install-guide from
> > scratch, alone. That isn't desirable.
> >
> > It is also my hope that the packaging on upstream infra will get going.
> > If it does, it will make more sense to get the Debian guide up to speed,
> > and probably there will be more contributors.
> Perhaps that common content should be a separate guide? I don't know the
> best solution, but I don't think requiring any one team to keep up with
> *everything* needed to install all projects on all platforms using all
> available tools is the right approach. See Conway's Law.
> Doug
> >
> > Cheers,
> >
> > Thomas Goirand (zigo)
> >
> >
> >
> __________________________________________________________________________
> > 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
> __________________________________________________________________________
> 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20160401/cb33d9fb/attachment.html>

More information about the OpenStack-dev mailing list