Open Stack

I remember installing OpenStack for the first time and being overwhelmed by
the amount of moving parts. I can't imagine adding automation with more
moving parts on top of it. Since those days, I spend a considerable amount
of time providing support in #openstack and other channels. I see a large
number of people deploy OpenStack for the first time using automation
because it appears to offer the path of least resistance and inevitably run
into problems with the automation system, OpenStack, or both. Even people
who successfully deploy OpenStack for the first time using automation will
eventually run into problems with OpenStack that the automation system
obscures, can't resolve, or makes worse. Frustration with OpenStack
increases and causes people to look for other solutions.

In reality, no one should deploy OpenStack manually in a production
environment. However, we need to emphasize the importance of walking (or
crawling) before running with OpenStack. The installation guide helps
people understand OpenStack services and the interaction among them.
Consistency, persistence, and some level of repetition reinforce important
tasks and the recommended order in which to perform them. These facets also
help minimize surprises. For example, creating the SQL database, populating
keystone, and configuring keystone access applies to almost every service
and occurs prior to other configuration steps. After installing OpenStack
using one of the minimal example architectures, people can reference other
documentation to improve redundancy and performance of their environment.
Only after people build a stable, scalable, repeatable environment should
they look at automation.

Currently, all distributions in the installation guide except Debian follow
this mantra. Consistency among the other distributions allows the small
number of contributors and testers to reuse code, reduce code complexity,
and release new versions in a timely manner. Furthermore, contributors and
testers can easily implement changes to a particular OpenStack
configuration file for the other distributions. However, similar changes
for Debian require specifically installing and testing the Debian packages.
If a particular package doesn't already implement changes to the OpenStack
configuration file, contributors must open a bug in another repository and
wait for a patch or patch it themselves which requires additional skills
and a completely different build and test environment. Finally, updating
the Debian procedures requires taking screen shots of Debconf that don't
easily translate into other languages. Why perform all of these extra steps
to maintain the installation guide for one distribution?

I think we can resolve many of these issues by disabling Debconf in the
installation guide and pointing people to supplemental documentation if
they prefer to use it.

On Thu Nov 27 2014 at 5:00:52 AM Thomas Goirand <zigo at debian.org> wrote:

> On 11/27/2014 11:16 AM, Tom Fifield wrote:
> > Thomas,
> >
> > As you know, I am in awe of the amount of effort you put in in packaging
> > and feel you are under-appreciated :) I'm sorry to trim your email so
> > much, but I just wanted to address this one point. Hopefully the others
> > will reply more fully (which you deserve, for such a detailed email).
> >
> > On 27/11/14 07:41, Thomas Goirand wrote:
> >> See this:
> >>
> >> http://docs.openstack.org/juno/install-guide/install/apt-
> debian/content/glance-install.html
> >>
> >> Then see this:
> >> http://docs.openstack.org/juno/install-guide/install/apt/
> content/glance-install.html
> >>
> >> Then tell me which of the 2 is the most easy, and which one newbies will
> >> want to read.
> >
> > I think there's an assumption here which is worth commenting on.
> >
> > The purpose of the install guide on docs.openstack.org is actually not
> > to make the 'most easy' way to install OpenStack.
> >
> > The purpose of the install guide on docs.openstack.org is to get a
> > reasonably-good practice deployment up while educating the reader just
> > enough on how the underlying things work that they can then move on to
> > use more advanced tools (think puppet, chef, et al) in conjunction with
> > the other documents.
> >
> > For example's sake, one 'most easy' way to install OpenStack that quite
> > a lot of people use is DevStack.
> >
> > What is needed in the install guide on docs.openstack.org is a
> > mid-point, that takes them from that "hand-holding" way to being able to
> > use automation to do an install.
> >
> > Regards,
> >
> > Tom
>
> Hi Tom,
>
> Thanks for your nice words.
>
> One important thing here. For each and every service we're documenting,
> there's the same exact explanations on how to set the
> keystone_authtoken, the API endpoints, the rabbitMQ credentials and the
> MySQL database. In the Ubuntu doc, this feels like there's a lot of
> redundancy.
>
> We discussed this during the Paris summit, and the issue here, is that
> we want the readers to be able to do cut/past, so it's not really
> possible to have a global chapter that would talk about the above 4
> subjects. But otherwise, we all felt it would have been better with a
> single chapter talking about it.
>
> In Debian, there's such chapter, which is the Debconf chapter. In it, I
> have documented the directives which are edited by the automation. So it
> is still possible for someone who wishes to use puppet/chef/$you-name-it
> to do so by reading the install-guide, as the information is also there
> for Debian, and because Debconf supports manual edition of directives.
>
> So I don't think we have an issue here, and we're still on the mid-point
> that you're talking about.
>
> Your thoughts?
>
> Cheers,
>
> Thomas Goirand (zigo)
>
>
> _______________________________________________
> OpenStack-docs mailing list
> OpenStack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20141201/c2fe944b/attachment.html>