<html><body><p>I would like to add some context for a bigger picture so we might arrive at a more general solution.<br>Typically CLI options are fairly static so the help messages are usually coded directly in the client.<br>This provides a good user experience by making the info readily available to the users.<br>The case for label is a little different, because label provides a general mechanism to pass arbitrary key/value pairs. <br>The meaning for these key/value is interpreted based on a particular option in a particular COE type, so they are not generally applicable.<br>For instance, Kubernetes baymodel that uses flannel as network-driver supports the label "flannel_backend", with the allowed values of "udp, vxlan, host-gw". <br>This particular label would be meaningless in another COE like Mesos.<br><br>So to provide this kind of info to the users, we have to address 2 issues:
<ol type="1"><li>How the user can discover the available labels specific to the COE, along with the valid values to specify.
<li>How to maintain the help messages specific to each label since they are likely to change frequently. </ol><br>I think just displaying the info for all labels together would not be too helpful.<br>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.<br>We need to accommodate new bay drivers that may add new labels.<br>Validation for the label value is another requirement.<br><br>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:<br><br>flannel_backend:<br> valid_values: <br> -udp<br> -vxlan<br> -host-gw<br> default_value: udp<br> COE: <br> -kubernetes<br> -swarm<br> 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."<br> doc_url: "http://xxx"<br> <br>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)<br>The validation code can also load this file for a more general way to validate the baymodel, avoiding hardcoding in api/attr_validator.py<br>New bay drivers can just append new labels to this file to have them handled in the same way as Magnum supported labels.<br>Optionally, the API server can provide access to this info.<br>In the source, we can keep this file in etc/magnum/labels.yaml.<br>Maintaining the help messages would be simpler since we just need to edit the file.<br><br>Thought?<br><br>Ton,<br> <br><br><img width="16" height="16" src="cid:1__=8FBBF522DFC6DCDE8f9e8a93df938690918c8FB@" border="0" alt="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"><font color="#424282">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</font><br><br><font size="2" color="#5F5F5F">From: </font><font size="2">Jamie Hannaford <jamie.hannaford@rackspace.com></font><br><font size="2" color="#5F5F5F">To: </font><font size="2">"OpenStack Development Mailing List (not for usage questions)" <openstack-dev@lists.openstack.org></font><br><font size="2" color="#5F5F5F">Cc: </font><font size="2">Qun XK Wang <bjwqun@cn.ibm.com></font><br><font size="2" color="#5F5F5F">Date: </font><font size="2">05/12/2016 07:08 AM</font><br><font size="2" color="#5F5F5F">Subject: </font><font size="2">Re: [openstack-dev] [magnum] How to document 'labels'</font><br><hr width="100%" size="2" align="left" noshade style="color:#8091A5; "><br><br><br><font size="4" face="Calibri">+1 for 1 and 3. </font><br><br><font size="4" face="Calibri">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.</font><br><br><font size="4" face="Calibri">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.</font><br><br><font size="4" face="Calibri">Jamie</font><br>
<p><hr width="100%" size="2" align="left"><br><b><font face="Calibri">From:</font></b><font face="Calibri"> Hongbin Lu <hongbin.lu@huawei.com></font><b><font face="Calibri"><br>Sent:</font></b><font face="Calibri"> 11 May 2016 21:52</font><b><font face="Calibri"><br>To:</font></b><font face="Calibri"> OpenStack Development Mailing List (not for usage questions)</font><b><font face="Calibri"><br>Cc:</font></b><font face="Calibri"> Qun XK Wang</font><b><font face="Calibri"><br>Subject:</font></b><font face="Calibri"> [openstack-dev] [magnum] How to document 'labels'</font><font size="4" color="#212121" face="Calibri"> </font><br><font size="4" color="#212121" face="Calibri"> </font><br><font color="#1F497D" face="Calibri">Hi all,</font><br><font color="#1F497D" face="Calibri"> </font><br><font color="#1F497D" face="Calibri">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:</font><ul><ul><font color="#1F497D" face="Calibri">1. Place the documentation in Magnum CLI as help text (as Wangqun proposed [1][2]).</font><br><font color="#1F497D" face="Calibri">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.</font><br><font color="#1F497D" face="Calibri">3. Place the documentation in a documentation server (like developer.openstack.org/…), and add the doc link to the CLI help text.</font></ul></ul><font color="#1F497D" face="Calibri">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?</font><br><font color="#1F497D" face="Calibri"> </font><br><font color="#1F497D" face="Calibri">[1] </font><a href="https://review.openstack.org/#/c/307631/"><u><font color="#0000FF" face="Calibri">https://review.openstack.org/#/c/307631/</font></u></a><br><font color="#1F497D" face="Calibri">[2] </font><a href="https://review.openstack.org/#/c/307642/"><u><font color="#0000FF" face="Calibri">https://review.openstack.org/#/c/307642/</font></u></a><br><font color="#1F497D" face="Calibri"> </font><br><font color="#1F497D" face="Calibri">Best regards,</font><br><font color="#1F497D" face="Calibri">Hongbin</font><p><font size="4" face="Calibri"> </font><hr width="100%" size="2" align="left"><font size="4" face="Calibri">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 </font><font size="4" face="Calibri">www.rackspace.co.uk/legal/swiss-privacy-policy</font><font size="4" face="Calibri"> - 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@rackspace.com and delete the original message. Your cooperation is appreciated. </font><tt>__________________________________________________________________________<br>OpenStack Development Mailing List (not for usage questions)<br>Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe<br></tt><tt><a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a></tt><tt><br></tt><p><p><BR>
</body></html>