summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorDrago Rosson <drago@rosson.me>2017-01-31 02:40:56 -0600
committerDrago <drago.rosson@rackspace.com>2017-02-09 16:49:04 +0000
commit8bf99f093ded5aff8ee68eca01e85948ee9717a2 (patch)
tree79476071ce669e9fa8fd9bd8b0567b75750f706b
parent48ab123a6ded665b7142454519979c078c4d4624 (diff)
Add spec for allowing name as positional argument
Notes
Notes (review): Code-Review+2: Adrian Otto <adrian.otto@rackspace.com> Code-Review+1: Jaycen Grant <jaycen.v.grant@intel.com> Code-Review+1: Vijendar Komalla <vijendar.komalla@rackspace.com> Code-Review+1: Jason Dunsmore <jason.dunsmore@rackspace.com> Code-Review+2: Spyros Trigazis <strigazi@gmail.com> Code-Review+2: Ton Ngo <ton@us.ibm.com> Workflow+1: Ton Ngo <ton@us.ibm.com> Verified+2: Jenkins Submitted-by: Jenkins Submitted-at: Mon, 13 Feb 2017 21:09:31 +0000 Reviewed-on: https://review.openstack.org/427060 Project: openstack/magnum-specs Branch: refs/heads/master
-rw-r--r--specs/pike/positional-name.rst116
1 files changed, 116 insertions, 0 deletions
diff --git a/specs/pike/positional-name.rst b/specs/pike/positional-name.rst
new file mode 100644
index 0000000..25a119c
--- /dev/null
+++ b/specs/pike/positional-name.rst
@@ -0,0 +1,116 @@
1..
2 This work is licensed under a Creative Commons Attribution 3.0 Unported
3 License.
4
5 http://creativecommons.org/licenses/by/3.0/legalcode
6
7=================================
8Name as a Positional CLI Argument
9=================================
10
11Launchpad blueprint:
12
13https://blueprints.launchpad.net/magnum/+spec/positional-name
14
15Make the magnum CLI more user-friendly by allowing cluster and cluster template
16names to be specified positionally.
17
18Problem description
19===================
20
21The shortest way to create a cluster using the magnum CLI is::
22
23 magnum cluster-create --cluster-template mytemplate
24
25Since magnum is a service to manage clusters, users will issue sub-commands
26such as `cluster-show`, `cluster-config` `cluster-update`, and
27`cluster-delete`, which all take the form::
28
29 magnum cluster-{command} <name or UUID> ...
30
31If the user didn't specify a name when creating their cluster, they will have
32to use the autogenerated name or the UUID, which are neither personalized nor
33memorable. So, many (or, in my opinion, virtually all) users are going to supply
34a name, which is currently a flag::
35
36 magnum cluster-create --name mycluster --cluster-template mytemplate
37
38The fact that users must specify the name using a flag on create and then
39positionally for all other commands creates a small, but important, amount of
40friction when interacting with magnum; it affects every user creating a
41cluster, reading documentation, or watching a demo about how easy magnum is to
42use.
43
44Names as positional arguments are not unprecedented in OpenStack. In fact,
45there are quite a few resources where the name is positional. For example,
46nova servers and flavors, heat stacks, keystone users, swift containers, and
47neutron networks, security groups, flavors, and routers.
48
49Proposed change
50===============
51
52Support `name` as a positional, optional CLI argument for the `cluster-create`
53and `cluster-template-create` sub-commands::
54
55 magnum cluster-template-create [name] ...
56
57 magnum cluster-create [name] ...
58
59For example::
60
61 magnum cluster-template-create mytemplate ...
62
63 magnum cluster-create mycluster --cluster-template mytemplate ...
64
65Whether `[name]` can appear anywhere in the list of arguments can be
66decided at implementation time. This spec proposes to support the argument at
67least directly after the sub-command name.
68
69Supplying a name will still be optional, and the `--name` flag version of the
70command will still be valid so that all commands are backwards-compatible.
71Whether `[name]` and `--name` are mutually exclusive or one should take
72precedence if both are specified can be decided at implementation time.
73
74This change will not affect the API.
75
76Alternatives
77------------
78
791. Make name positional and mandatory.
80
81 This would make the magnum CLI more like other OpenStack CLIs where the name
82 is required. However, it would be a breaking CLI change and would probably
83 only make sense if the API were to change too, which would mean it would be
84 a bigger breaking change.
85
86Implementation
87==============
88
89Assignee(s)
90-----------
91
92Primary assignee:
93 Jason Dunsmore
94
95Milestones
96----------
97
98Target Milestone for completion:
99 pike-1
100
101Work Items
102----------
103
1041. Support `[name]` for `cluster-create`.
105
1062. Support `[name]` for `cluster-template-create`.
107
108Dependencies
109============
110
111None
112
113Security Impact
114===============
115
116None