Open Stack

On 6/4/20 11:40 AM, Akihiro Motoki wrote:
> - Drop the installation guide (per OS or as a whole)

Please don't do that.

> Most users deploy OpenStack using deployment projects (or their own
> deployment tools).

Then how would the person writing the deployment tool do the work?

> Step-by-step guides might be useful from educational perspective

They are.

> but unmaintained guides are not useful.

What I would very much prefer would be a more general guide on how to
setup a MySQL db for a project, and how to setup an endpoint. Then the
individual project documentation would just point at that doc, and
inform the reader what is the default for:
- service name
- port number
- endpoint URL

Then we need a more general descriptions of what services are for, and
where to deploy then. For example, in Neutron, it'd be enough to explain
that:
- neutron-rpc-server should be deployed on 3 controllers
- neutron-api should go on 3 controllers, with HAproxy in front
- dhcp-agent can be deployed anywhere, but then l3 & l2 agent must be on
the same server as well
- metadata-agent, ovs-agent and l3-agent must be on each compute

This type of explanation is a way more useful than a step-by-step:

apt-get install neutron-l3-agent

where we're giving zero explanation of what the l3 agent does, where it
should be installed, and why.

>From the Debian perspective, I would have like to have a specific place
where we could have explained how the Debconf system works, and how it
has been designed in the package (ie: in a way so that a full cluster
deployment could be done only with preseed, but also in a way so that it
doesn't bother anyone using a deployment tool like Puppet or Ansible).
Currently, there's no place where to write about this. Though it was
documented, and well documented, at the time.

I believe the install-guide for Debian was kind of nearly perfect around
in 2016, with these specific chapters, and lots of debconf screenshots
to explain it all. That is just *GONE*. This is frustrating, and a
disservice for our users.

More generally, I found the move of the install guide to each individual
project was a huge regression, and since then, it has a lot less value.
All the work I did at the time to document things for Debian has been
slowly removed. I have absolutely no idea why contributors have been
doing that, and I don't think that's fair to have done it.

I also found that the conditionals we had at the time (ie: if
osname=Ubuntu or Debian, that kind of things...) was very helpful. These
days, we're duplicating, that's really silly.

Back at the time, the decision was made because some core contributors
to the install guide just left the project. It was at the time said that
moving the maintenance to each individual projects would scale nicer. I
am now convince that this is the exact opposite that has happened: docs
are maintained a lot less now, with lower quality, and less uniformity.
So I am convince that we did a very bad move at the time, one that we
shouldn't have made.

If we were going back to what we would do in 2016, I would contribute
again. But considering what the install guide has become, this really
isn't motivating.

Your thoughts?

Cheers,

Thomas Goirand (zigo)