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

[Wouter Verhelst]

Control: severity -1 normal
Control: retitle -1 openstack-deploy: incomplete, undocumented

On Thu, Dec 07, 2017 at 10:03:57AM +0100, Thomas Goirand wrote:
> Hi Wouter,
> 
> On 12/06/2017 09:24 PM, Wouter Verhelst wrote:
> > Package: openstack-deploy
> > Version: 0.15
> > Severity: minor
> > 
> > After running "openstack-deploy all-in-one", I find that I do have
> > something resembling a working openstack installation. Thanks for that!
> 
> Yes, this was the initial goal, but no, after you've run the script, you
> *don't* have a working installation.

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.

> What openstack-deploy does is *only* installing packages using
> preseeding, but that's unfortunately not enough to have something that
> works.

Right.

> 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.

> Another goal of the openstack-deploy script is to provide a working
> preseed library, which can be re-used. That goal, IMO, is fully reached.
> See /usr/share/openstack-deploy/preseed-lib. However, it would need 2
> improvements: 1/ support more OpenStack services, not just the core
> ones. 2/ get improvement for supporting newer debconf preseeding (it
> currently uses pre-jessie way, which still works, but should be updated).

Right.

> > Unfortunately, however, after all that has happened, one sits there with
> > a "now what" feeling:
> > 
> > - The installation asks for a number of things. What do these things
> >   mean? (just hitting "enter" to everything *seems* to work, except for
> >   the "keystone endpoint IP, for which I just entered 127.0.0.1 in this
> >   test environment).
> 
> Most questions should be answered with the default, which is why the
> openstack-deploy script has a --non-interactive optional parameter.

Right, yes, I saw that. But my point is that it should be documented
somehow/somewhere what the meaning of all those questions is. What
happens if I enter something else?

For the generated passwords, this is rather obvious, but not for all of
the asked questions.

> In Stretch (if that's what you're using),

Yes.

> 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.

> > - Something is running, but where? (localhost:80, it turns out, with
> >   non-SSL HTTP redirected to its SSL version)
> 
> 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.

I think this makes sense, but it didn't work for my setup; however, this
is likely to be because reaching my openstack test VM's webinterface
required me to use an ssh jumphost and do a few "interesting" things.

(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)

[...]
> > - After fiddling with apache SSL settings so that those work (this was
> >   on a pristine VM to test with), I need to log on. What with? (the
> >   value of RC_KEYSTONE_ADMINPASS in /root/osinstallrc, it turns out)
> 
> The openstack-deploy script writes an openrc.sh script. This script
> contains all the login credentials. What you should do is either
> copy/past the content of this script in your .bashrc, or simply source
> it manually on the shell. Then you can use the openstack command line tools.
> 
> The initial goal of the /root/osinstallrc file, is to:
> 1/ Cache every answer that have been key-ed in.
> 2/ Be useful to transporting one's answer from one server to another
> over scp, so that we get a full cluster provisioning.
> 
> While 1/ works already very well, 2/ isn't implemented yet, even though
> the mechanism should work quite well.

Right.

I had suspected that it would already, but I can understand that
implementing that is not trivial.

> > I realize that the goal of openstack-deploy is probably to support
> > openstack-tempest-ci rather than to support users
> 
> That is correct.
> 
> > but since it's
> > packaged in Debian, and since it seems to have several modes, all of
> > which should support larger installations too, it seems like a prime
> > candidate for "look at this if you want to build your own cloud"
> 
> I would love to transform this script to support multi-node installation
> and be somehow useful for Debian users directly. But I have to admit it
> didn't reach that point yet.

Fair enough.

> > If only it were a bit better documented.
> 
> 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.

Even in its current state, where openstack-deploy gets you part of the
way there, but not completely, I think it can be useful for such users,
provided it's clear to them what they get and what they don't get, what
they may want to add if they want more, and how they should do so --
even if that's not in full howto-style detail.

People who will be implementing a large setup (say, dozens of nodes or
more) should already be expected read up on openstack and all the
options that exist before they go ahead and install things, so the
openstack-deploy script doesn't necessarily need to cater to them (at
least not in a first implementation). 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.

Having said that, I completely understand that it's work, and somebody
needs to do it.

> I would very much appreciate contribution toward this goal.

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...

As a first and obvious step, it might be useful if the questions that
are asked by openstack-deploy were a bit more self-documenting; e.g.,
rather than just saying "please enter value X [default xyz]", do
something along the lines of "we need value X for purpose foo which will
be used by the neutron, keystone, and rabbitmq services. For more
infomation, see <URL>.\nValue X [default xyz]". This doesn't need to be
very complicated or large; the main point is that it should allow a user
who goes "wtf is this" to understand what the point is to the question,
and where to look for further information.

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

[...]

-- 
Could you people please use IRC like normal people?!?

  -- Amaya Rodrigo Sastre, trying to quiet down the buzz in the DebConf 2008
     Hacklab