Add spec for allowing name as positional argument

blueprint positional-name

Change-Id: I75d14cc3de16810d57424ac9a0f66c7a66982f05
This commit is contained in:
Drago Rosson 2017-01-31 02:40:56 -06:00 committed by Drago
parent 48ab123a6d
commit 8bf99f093d
1 changed files with 116 additions and 0 deletions

View File

@ -0,0 +1,116 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
=================================
Name as a Positional CLI Argument
=================================
Launchpad blueprint:
https://blueprints.launchpad.net/magnum/+spec/positional-name
Make the magnum CLI more user-friendly by allowing cluster and cluster template
names to be specified positionally.
Problem description
===================
The shortest way to create a cluster using the magnum CLI is::
magnum cluster-create --cluster-template mytemplate
Since magnum is a service to manage clusters, users will issue sub-commands
such as `cluster-show`, `cluster-config` `cluster-update`, and
`cluster-delete`, which all take the form::
magnum cluster-{command} <name or UUID> ...
If the user didn't specify a name when creating their cluster, they will have
to use the autogenerated name or the UUID, which are neither personalized nor
memorable. So, many (or, in my opinion, virtually all) users are going to supply
a name, which is currently a flag::
magnum cluster-create --name mycluster --cluster-template mytemplate
The fact that users must specify the name using a flag on create and then
positionally for all other commands creates a small, but important, amount of
friction when interacting with magnum; it affects every user creating a
cluster, reading documentation, or watching a demo about how easy magnum is to
use.
Names as positional arguments are not unprecedented in OpenStack. In fact,
there are quite a few resources where the name is positional. For example,
nova servers and flavors, heat stacks, keystone users, swift containers, and
neutron networks, security groups, flavors, and routers.
Proposed change
===============
Support `name` as a positional, optional CLI argument for the `cluster-create`
and `cluster-template-create` sub-commands::
magnum cluster-template-create [name] ...
magnum cluster-create [name] ...
For example::
magnum cluster-template-create mytemplate ...
magnum cluster-create mycluster --cluster-template mytemplate ...
Whether `[name]` can appear anywhere in the list of arguments can be
decided at implementation time. This spec proposes to support the argument at
least directly after the sub-command name.
Supplying a name will still be optional, and the `--name` flag version of the
command will still be valid so that all commands are backwards-compatible.
Whether `[name]` and `--name` are mutually exclusive or one should take
precedence if both are specified can be decided at implementation time.
This change will not affect the API.
Alternatives
------------
1. Make name positional and mandatory.
This would make the magnum CLI more like other OpenStack CLIs where the name
is required. However, it would be a breaking CLI change and would probably
only make sense if the API were to change too, which would mean it would be
a bigger breaking change.
Implementation
==============
Assignee(s)
-----------
Primary assignee:
Jason Dunsmore
Milestones
----------
Target Milestone for completion:
pike-1
Work Items
----------
1. Support `[name]` for `cluster-create`.
2. Support `[name]` for `cluster-template-create`.
Dependencies
============
None
Security Impact
===============
None