Open Stack

Hi peers,

Since Magnum-UI should display selectable values for user, so Magnum-UI wants to get available values from API.
https://blueprints.launchpad.net/magnum/+spec/magnum-api-swagger-support
https://bugs.launchpad.net/magnum-ui/+bug/1568890

And we don't want to write same things in many files, sometimes with nits.
ex.) write help messages and available key/values into API, CLI, UI and docs

My understanding for Swagger (=OpenAPI) and related tools are:
- generate swagger-spec JSON file (like YAML file proposed by Ton) from source code (with decorator), means writing documents as source code of API (#2)
- provide the JSON file via REST API (#2) to CLI (#1) and UI for available values and help messages not inconsistent with the source code.
- generate online documents from the JSON file (#3)
- are promoted by API-WG
- implementations seems starting to be tried in Nova and Zaqar

I'd like to re-propose to use Swagger.
But it needs more investigation, so I'm not sure where is a middle ground for now.


Best regards, 

Shu Muto

> -----Original Message-----
> From: Ton Ngo [mailto:ton at us.ibm.com]
> Sent: Friday, May 13, 2016 5:33 AM
> To: OpenStack Development Mailing List (not for usage questions)
> <openstack-dev at lists.openstack.org>
> Cc: Qun XK Wang <bjwqun at cn.ibm.com>
> Subject: Re: [openstack-dev] [magnum] How to document 'labels'
> 
> 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,
> 
> 
> 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
> 
> 
>