magnum-specs/specs/pike/positional-name.rst

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