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

[Wouter Verhelst]

On Thu, Dec 07, 2017 at 06:12:35PM +0100, Thomas Goirand wrote:
> 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/

Missed that. A simple pointer to that documentation from the script (or
even the wiki) would have gone a *long* way towards helping me out on
things here :-)

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

Right.

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

Heh. Will do, thanks :-)

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

For clarity, I'm not saying that you need to have full documentation in
openstack-deploy itself. It makes perfect sense for it to point to the
relevant upstream documentation. However, it doesn't even do that
today. It just runs, magic happens, and I can see that things are
running; but it doesn't tell me what or where, and it doesn't tell me
what the next steps are. After openstack-deploy ran, there are somewhere
between 10 and 20 listening ports on localhost, with no indication of
where to go next.

It doesn't need to be much, but it could be more than there is today :-)

> >> 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! :)

Right :)

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

No, it is not :-)

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

Actually, it turns out that if DEBUG is enabled in the django
configuration, which appears to be the default, then only localhost
connections are allowed. So, no, not me ;)

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

I'll answer this bit later (haven't yet had the time to look at this in
detail)

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

IMHO, that's fine. Just document the choices which the user has to make,
how to make them, and, crucially, what choices have already been made
for the user by the openstack-deploy script.

Honestly, I think openstack-deploy would be massively more usable if it
just had some output at the end saying something along the lines of...

---
Success! The following services have been installed and fully
configured:

- U
- V

The following services have been installed, but require more
configuration before they can be properly used:

- W
- X

You may be interested in the following additional services, which are
also packaged for Debian but have not been installed:

- Y
- Z

For more information on how to configure these services, please see the
upstream documentation at <url>.

The configuration that was generated by this script (including generated
passwords) can be found in the file '/root/openrc.sh'.
---

...because it gives the user immediate feedback of the changes that were
made, and where to look for further information.

(I'm not that sure about the "additional services" bit of the above,
since that might end up being a slippery slope -- but the first two,
surely, should be doable).

As everyone knows, documentation is only read if all else fails, so you
need to force people to look at it by throwing it in their face even
when they didn't ask for it ;-)

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

Oh dear. That's about the amount of memory on that particular bare metal
machine :-)

> Thanks again for your feedback,

Sure.

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

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