Open Stack

I would like to add some context for a bigger picture so we might arrive at
a more general solution.
Typically CLI options are fairly static so the help messages are usually
coded directly in the client.
This provides a good user experience by making the info readily available
to the users.
The case for label is a little different, because label provides a general
mechanism to pass arbitrary key/value pairs.
The meaning for these key/value is interpreted based on a particular option
in a particular COE type, so they are not generally applicable.
For instance,  Kubernetes baymodel that uses flannel as network-driver
supports the label "flannel_backend", with the allowed values of "udp,
vxlan, host-gw".
This particular label would be meaningless in another COE like Mesos.

So to provide this kind of info to the users, we have to address 2 issues:
   How the user can discover the available labels specific to the COE,
   along with the valid values to specify.
   How to maintain the help messages specific to each label since they are
   likely to change frequently.

I think just displaying the info for all labels together would not be too
helpful.
Putting the info in the API would make it available to tools built on
Magnum, but Madhuri has a good point that the info would not be available
when the server is not running.
We need to accommodate new bay drivers that may add new labels.
Validation for the label value is another requirement.

Here is a thought on how to meet these requirements:  we can install a yaml
file in /etc/magnum/labels.yaml that would describe all the supported
labels, something like:

flannel_backend:
   valid_values:
      -udp
      -vxlan
      -host-gw
   default_value:  udp
   COE:
      -kubernetes
      -swarm
   help_message: "This label is used with the flannel network driver to
specify the type of back end to use. The option host-gw gives the best
bandwidth performance."
   doc_url: "http://xxx"

Then the client can read this yaml file and list the labels for a COE, say
Kubernetes.  For help on a specific label, the client would print the help
message along with the url for further info (if available)
The validation code can also load this file for a more general way to
validate the baymodel, avoiding hardcoding in api/attr_validator.py
New bay drivers can just append new labels to this file to have them
handled in the same way as Magnum supported labels.
Optionally, the API server can provide access to this info.
In the source, we can keep this file in etc/magnum/labels.yaml.
Maintaining the help messages would be simpler since we just need to edit
the file.

Thought?

Ton,




From:	Jamie Hannaford <jamie.hannaford at rackspace.com>
To:	"OpenStack Development Mailing List (not for usage questions)"
            <openstack-dev at lists.openstack.org>
Cc:	Qun XK Wang <bjwqun at cn.ibm.com>
Date:	05/12/2016 07:08 AM
Subject:	Re: [openstack-dev] [magnum] How to document 'labels'



+1 for 1 and 3.

I'm not sure maintainability should discourage us from exposing information
to the user through the client - we'll face the same maintenance burden as
we currently do, and IMO it's our job as a team to ensure our docs are
up-to-date. Any kind of input which touches the API should also live in the
API docs, because that's in line with every other OpenStack service.

I don't think I've seen documentation exposed via the API before (#2). I
think it's a lot of work too, and I don't see what benefit it provides.

Jamie




From: Hongbin Lu <hongbin.lu at huawei.com>
Sent: 11 May 2016 21:52
To: OpenStack Development Mailing List (not for usage questions)
Cc: Qun XK Wang
Subject: [openstack-dev] [magnum] How to document 'labels'

Hi all,

This is a continued discussion from the last team meeting. For recap,
‘labels’ is a property in baymodel and is used by users to input additional
key-pair pairs to configure the bay. In the last team meeting, we discussed
what is the best way to document ‘labels’. In general, I heard three
options:
      1.       Place the documentation in Magnum CLI as help text (as
      Wangqun proposed [1][2]).
      2.       Place the documentation in Magnum server and expose them via
      the REST API. Then, have the CLI to load help text of individual
      properties from Magnum server.
      3.       Place the documentation in a documentation server (like
      developer.openstack.org/…), and add the doc link to the CLI help
      text.
For option #1, I think an advantage is that it is close to end-users, thus
providing a better user experience. In contrast, Tom Cammann pointed out a
disadvantage that the CLI help text might be easier to become out of date.
For option #2, it should work but incurs a lot of extra work. For option
#3, the disadvantage is the user experience (since user need to click the
link to see the documents) but it makes us easier to maintain. I am
thinking if it is possible to have a combination of #1 and #3. Thoughts?

[1] https://review.openstack.org/#/c/307631/
[2] https://review.openstack.org/#/c/307642/

Best regards,
Hongbin


    Rackspace International GmbH a company registered in the Canton of
Zurich, Switzerland (company identification number CH-020.4.047.077-1)
whose registered office is at Pfingstweidstrasse 60, 8005 Zurich,
Switzerland. Rackspace International GmbH privacy policy can be viewed at
www.rackspace.co.uk/legal/swiss-privacy-policy - This e-mail message may
contain confidential or privileged information intended for the recipient.
Any dissemination, distribution or copying of the enclosed material is
prohibited. If you receive this transmission in error, please notify us
immediately by e-mail at abuse at rackspace.com and delete the original
message. Your cooperation is appreciated.
__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev






-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20160512/a7a33d6b/attachment.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: graycol.gif
Type: image/gif
Size: 105 bytes
Desc: not available
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20160512/a7a33d6b/attachment.gif>