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