Browse Source

Add spec for allowing name as positional argument

blueprint positional-name

Change-Id: I75d14cc3de16810d57424ac9a0f66c7a66982f05
Drago Rosson 2 years ago
parent
commit
8bf99f093d
1 changed files with 116 additions and 0 deletions
  1. 116
    0
      specs/pike/positional-name.rst

+ 116
- 0
specs/pike/positional-name.rst View File

@@ -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
+=================================
8
+Name as a Positional CLI Argument
9
+=================================
10
+
11
+Launchpad blueprint:
12
+
13
+https://blueprints.launchpad.net/magnum/+spec/positional-name
14
+
15
+Make the magnum CLI more user-friendly by allowing cluster and cluster template
16
+names to be specified positionally.
17
+
18
+Problem description
19
+===================
20
+
21
+The shortest way to create a cluster using the magnum CLI is::
22
+
23
+  magnum cluster-create --cluster-template mytemplate
24
+
25
+Since magnum is a service to manage clusters, users will issue sub-commands
26
+such 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
+
31
+If the user didn't specify a name when creating their cluster, they will have
32
+to use the autogenerated name or the UUID, which are neither personalized nor
33
+memorable. So, many (or, in my opinion, virtually all) users are going to supply
34
+a name, which is currently a flag::
35
+
36
+  magnum cluster-create --name mycluster --cluster-template mytemplate
37
+
38
+The fact that users must specify the name using a flag on create and then
39
+positionally for all other commands creates a small, but important, amount of
40
+friction when interacting with magnum; it affects every user creating a
41
+cluster, reading documentation, or watching a demo about how easy magnum is to
42
+use.
43
+
44
+Names as positional arguments are not unprecedented in OpenStack. In fact,
45
+there are quite a few resources where the name is positional. For example,
46
+nova servers and flavors, heat stacks, keystone users, swift containers, and
47
+neutron networks, security groups, flavors, and routers.
48
+
49
+Proposed change
50
+===============
51
+
52
+Support `name` as a positional, optional CLI argument for the `cluster-create`
53
+and `cluster-template-create` sub-commands::
54
+
55
+  magnum cluster-template-create [name] ...
56
+
57
+  magnum cluster-create [name] ...
58
+
59
+For example::
60
+
61
+  magnum cluster-template-create mytemplate ...
62
+
63
+  magnum cluster-create mycluster --cluster-template mytemplate ...
64
+
65
+Whether `[name]` can appear anywhere in the list of arguments can be
66
+decided at implementation time. This spec proposes to support the argument at
67
+least directly after the sub-command name.
68
+
69
+Supplying a name will still be optional, and the `--name` flag version of the
70
+command will still be valid so that all commands are backwards-compatible.
71
+Whether `[name]` and `--name` are mutually exclusive or one should take
72
+precedence if both are specified can be decided at implementation time.
73
+
74
+This change will not affect the API.
75
+
76
+Alternatives
77
+------------
78
+
79
+1. 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
+
86
+Implementation
87
+==============
88
+
89
+Assignee(s)
90
+-----------
91
+
92
+Primary assignee:
93
+  Jason Dunsmore
94
+
95
+Milestones
96
+----------
97
+
98
+Target Milestone for completion:
99
+  pike-1
100
+
101
+Work Items
102
+----------
103
+
104
+1. Support `[name]` for `cluster-create`.
105
+
106
+2. Support `[name]` for `cluster-template-create`.
107
+
108
+Dependencies
109
+============
110
+
111
+None
112
+
113
+Security Impact
114
+===============
115
+
116
+None

Loading…
Cancel
Save