[openstack-dev] [magnum] How to document 'labels'

Hongbin Lu hongbin034 at gmail.com
Fri May 13 19:27:25 UTC 2016


Ton,

It seems the approach you proposed requires the yaml file that describes
all the labels to be copied between repos (openstack/magnum,
openstack/python-magnumclient, openstack/magnum-ui). Unless we setup a CI
job to copy the file, I don't think it can solve the maintenance problem.

Best regards,
Hongbin

On Thu, May 12, 2016 at 4:33 PM, Ton Ngo <ton at us.ibm.com> wrote:

> 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:
>
>    1. How the user can discover the available labels specific to the COE,
>    along with the valid values to specify.
>    2. 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,
>
>
> [image: Inactive hide details for Jamie Hannaford ---05/12/2016 07:08:47
> AM---+1 for 1 and 3. I'm not sure maintainability should disco]Jamie
> Hannaford ---05/12/2016 07:08:47 AM---+1 for 1 and 3. I'm not sure
> maintainability should discourage us from exposing information to the u
>
> 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/*
> <https://review.openstack.org/#/c/307631/>
> [2] *https://review.openstack.org/#/c/307642/*
> <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
>
>
>
> __________________________________________________________________________
> 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/20160513/7701be9e/attachment-0001.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/20160513/7701be9e/attachment-0001.gif>


More information about the OpenStack-dev mailing list