[PKG-Openstack-devel] Bug#883723: Bug#883723: openstack-deploy: undocumented

[Thomas Goirand]

On 12/07/2017 11:03 AM, Wouter Verhelst wrote:
> Oh, okay. I did say "resembling", mostly because I hadn't had a chance
> of testing it out yet, in much detail.
> 
> That's possibly also something that should be documented. The script
> already does a great deal and gets you partway there; it's fine if that
> doesn't yet do everything, but then at least a hint in the documentation
> as to what it doesn't do yet in some reasonable detail, with a pointer to
> the upstream bits of documentation that should be followed, would be
> useful.

I have extensively contributed to the upstream documentation. There's
even 2 install guide that you'll find for OpenStack in Newton:

https://docs.openstack.org/newton/install-guide-debconf/
https://docs.openstack.org/newton/install-guide-debian/

What you can do is simply run openstack-deploy, then read the steps of
the install-guide. Most of the steps will be already performed by the
script, like installing the package, registering endpoint in the
keystone catalog, setting the keystone_authtoken and configuring the db.

Unfortunately, because the doc people appeared unstaff after rackspace
laid-off a lot of its personnel, this is the last install-guide for
OpenStack. It's quite fortunate that it is also the best install-guide
for Debian, where I could check everything was working as expected. So I
very much recommend this reading.

>> For example, the networking setup is *not* performed by this operation,
>> neither Cinder is installed or configured. Within my test setup, this is
>> done by the openstack-deploy-proxy-network script. I would strongly
>> advise for reading this script before using it. It also setups Neutron
>> using openvswitch, which is fine for a small deployment, but wont scale
>> past 10 nodes (too many GRE tunnels is very CPU intensive).
> 
> This, too, sounds like something that might need to be documented.

In theory, I would agree. Though I found that contributing to the doc
upstream was a much better way to address the documentation.

>> the only small issue with the default is the name of the MySQL server.
>> It should in fact be mariadb-server. Probably you've found this out by
>> yourself.
> 
> I have. Even so, just accepting the default does work, due to mariadb
> metapackages doing the right thing.

Oh good! :)

>> The default with the Debian OpenStack packages is to *not* use SSL.
> 
> Actually, after running "openstack-deploy all-in-one" on a pristine
> Debian system (installed from d-i, "apt install openstack-deploy",
> running "openstack-deploy all-in-one") and accepting the defaults (apart
> from the keystone endpoint that doesn't have a default, as per above), I
> found that the openstack-dashboard-ssl-redirect.conf and
> openstack-dashboard-ssl.conf apache2 sites were enabled.

Installing horizon without any preseeding just work too, though you end
up having horizon installed under /horizon instead of the root of the
web server, which is Debian policy compliant. You can just
dpkg-reconfigure openstack-dashboard-apache if that's what you prefer.

> (additionally, the default configuration doesn't seem to allow
> connecting to the dashboard from a remote system. I'm not sure yet
> whether that's me or whether the configuration simply needs to be
> updated)

I believe that's just you, but I may be wrong! :)

>> I unfortunately don't think some documentation could be useful until the
>> script can support multi-node setup, and allow a fully working
>> configuration for a running cloud, as per above.
> 
> I have to disagree here.
> 
> For the simple case of "let me install things and see how it works",
> having an all-in-one setup working *is* a useful thing. For people who
> simply want to test and play with things, documentation is very very
> useful.

Now that I gave you a pointer to upstream install-guide for Debian, do
you still have the same view on this?

> However, if the all-in-one case
> works really really well, that would go a long way towards enabling
> people to understand openstack better, and would likely net you some
> more interested contributors.

I'd like to reach that point where just running the openstack-deploy
script would be enough. Though there's one par that can't ever be done
automatically: networking. Indeed, it really depend on your
configuration and topology. I've been thinking about this for a long
time and can't think it out.

> I would love to be able to contribute, but at this point in time I can
> only point out holes in the documentation from a newbie's POV. The
> openstack-deploy run that triggered this bug report was my first attempt
> at learning how Openstack works...

I very much appreciate your feedback already. Thanks !

> The documentation doesn't need to complete, but it should be enough to
> get started.

I see your point. I'll try to write something down. I in fact already
did some of this as a blog entry to explain openstack-tempest-ci, which
may be useful for newbies to just try the Debian OpenStack all-in-one
version within a KVM machine. The only issue is that that machine has to
be quite big (at least 24 GB of RAM).

Thanks again for your feedback,
Cheers,

Thomas Goirand (zigo)