Open Stack

On Tue, May 24, 2016 at 8:58 PM, John Garbutt <john at johngarbutt.com> wrote:

> On 24 May 2016 at 19:03, Ian Cordasco <sigmavirus24 at gmail.com> wrote:
> > -----Original Message-----
> > From: Erno Kuvaja <ekuvaja at redhat.com>
> > Reply: OpenStack Development Mailing List (not for usage questions)
> > <openstack-dev at lists.openstack.org>
> > Date: May 24, 2016 at 06:06:14
> > To: OpenStack Development Mailing List (not for usage questions)
> > <openstack-dev at lists.openstack.org>
> > Subject:  [openstack-dev] [all][oslo_config] Improving Config Option
> Help Texts
> >
> >> Hi all,
> >>
> >> Based on the not yet merged spec of categorized config options [0] some
> >> project seems to have started improving the config option help texts.
> This
> >> is great but I noticed scary trend on clutter to be added on these
> >> sections. Now looking individual changes it does not look that bad at
> all
> >> in the code 20 lines well structured templating. Until you start
> comparing
> >> it to the example config files. Lots of this data is redundant to what
> is
> >> generated to the example configs already and then the maths struck me.
> >>
> >> In Glance only we have ~120 config options (this does not include
> >> glance_store nor any other dependencies we pull in for our configs like
> >> Keystone auth. Those +20 lines of templating just became over 2000
> lines of
> >> clutter in the example configs and if all projects does that we can
> >> multiply the issue. I think no-one with good intention can say that it's
> >> beneficial for our deployers and admins who are already struggling with
> the
> >> configs.
> >>
> >> So I beg you when you do these changes to the config option help fields
> >> keep them short and compact. We have the Configuration Docs for extended
> >> descriptions and cutely formatted repetitive fields, but lets keep those
> >> off from the generated (Example) config files. At least I would like to
> be
> >> able to fit more than 3 options on the screen at the time when reading
> >> configs.
> >>
> >> [0] https://review.openstack.org/#/c/295543/
> >
> > Hey Erno,
> >
> > So here's where I have to very strongly disagree with you. That spec
> > was caused by operator feedback, specifically for projects that
> > provide multiple services that may or may not have separated config
> > files which and which already have "short and compact" descriptions
> > that are not very helpful to oeprators.
>
> +1
>
> The feedback at operator sessions in Manchester and Austin seemed to
> back up the need for better descriptions.
>
>
I'm all for _better_ descriptions.


> More precisely, Operators should not need to read the code to
> understand how to use the configuration option.
>
> Now often that means they are longer. But they shouldn't be too long.
>
>
Let me give an example of what I see as a clutter with the newly proposed
help texts:

Glance config files are split per service. So we have files
glance-api.conf, glance-registry.conf, glance-scrubber.conf etc.
We should not need to add 300 lines (once for each option) to
glance-api.conf containing repetitive:
"""

Services which consume this:
    * ``glance-api``
"""
As it's glance-api.conf this _should_ be self-explanatory. This is getting
worse for certain options we have in multiple config files that will have:
"""

Services which consume this:
    * ``glance-api`` (mandatory for v1; optional for v2)
    * ``image scrubber`` (a periodic task)
    * ``cache prefetcher`` (a periodic task)
"""
Which is kind of correct, but as all these three services has their own
configs, changing it in one does not necessarily affect the rest
(glance-api.conf is exception here if it is available and -scrubber and/or
-cache configs are not). So now adding these lines to glance-scrubber.conf
gives impression that glance-api consumes it from there, which is false.

Will all options in [keystone_authtoken] have a list of every single
OpenStack service consuming it? I certainly hope not.

The next part of cluttering is adding again extra ~300 redundant lines:
"""

Possible values:
    * A valid port number
"""
This is specific example for PortOpt, Currently the configgenrator provides
following from single line help text:
"""
# Port the registry server is listening on. (port value)
# Minimum value: 0
# Maximum value: 65535
#registry_port = 9191
"""
Is "Possible values:\n A valid port number" by any means adding value to
that help? I've seen the same with IntOpt where configgenerator adds that
(integer value) and we add "Possible values:\n Valid Integer".

> The *example* config files will have a lot more detail in them. Last I
> > saw (I've stopped driving that specification) there was going to be a
> > way to generate config files without all of the descriptions. That
> > means that for operators who don't care about that can ignore it when
> > they generate configuration files. Maybe the functionality doesn't
> > work right this instant, but I do believe that's a goal and it will be
> > implemented.
>
> Different modes of the config generator should help us cater for
> multiple use cases.
>
>
I'm not asking to strip it all off. I'm asking us not to clutter the
example config files with redundant or confusing data just because of the
sake of it. More is not necessarily better.


> I am leaving that as a discussion in oslo specs for the moment.
>
> > Beyond that, I don't think example/sample configuration files should
> > be treated differently from documentation, nor do I think that our
> > documentation team couldn't make use of the improved documentation
> > we're adding to each option. In short, I think this effort will
> > benefit many different groups of people in and around OpenStack.
> > Simply arguing that this is going to make the sample config files have
> > more lines of code is not a good argument against this. Please do
> > reconsider.
>
>
So sorry if I got misunderstood. Hopefully the above explained what I'm
against of.

Best,
Erno "jokke_" Kuvaja


> Now I have been discussing a change in Nova's approach to reduce the
> size of some of them, but that was really for different reasons:
> http://lists.openstack.org/pipermail/openstack-dev/2016-May/095538.html
>
> Thanks,
> johnthetubaguy
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20160525/dd8e34ac/attachment.html>