Jump to: navigation, search

Difference between revisions of "UnifiedCLI"

Line 6: Line 6:
 
== Summary ==
 
== Summary ==
  
A unified [[OpenStack]] CLI will provide users with an improved experience in dealing with the variety of commands and arguments required to operate [[OpenStack]].
+
A unified [[OpenStack]] CLI will provide users with an improved experience in dealing with the variety of commands and arguments required to interact with [[OpenStack]]. The unified CLI is intended to be a complete substitute for the bundled CLI binaries supplied with the [[OpenStack]] project clientsWhere possible it will utilize the existing client modules to minimize duplication of effort.
 
 
== Release Note ==
 
 
 
The Unified CLI is intended to be a complete substitute for the bundles CLI binaries supplied with the [[OpenStack]] project lcient librariesIts use is not mandatory, however it is intended to have a significantly better user experience.
 
  
 
== Rationale ==
 
== Rationale ==
  
The user experience with [[OpenStack]] CLI tools is a frustrating one right now due to a number of inconsistencies between the varios tools, not to mention making a user know that keystone is the user/tenant tool and nova is the instance/flavor/image tools and glance is the image tools (but nova does that too!), etc.
+
The user experience with [[OpenStack]] CLI tools is a frustrating one right now due to a number of inconsistencies between the varios tools, not to mention making a user know that <code><nowiki>keystone</nowiki></code> is the user/tenant tool and <code><nowiki>nova</nowiki></code> is the instance/flavor/image tools and <code><nowiki>glance</nowiki></code> is the image tool that replaces the image functions in <code><nowiki>nova</nowiki></code>.
  
At this point it seems fair to consider those tools to be the 'free sample cli' that comes bundled with the client libraries and ignore them in favor of a new unified in spirit, if not in implementation, [[OpenStack]] CLI interface.
+
At this point it seems fair to consider those tools to be the 'free sample cli' that comes bundled with the client libraries and ignore them in favor of a new unified (in spirit, if not in implementation) [[OpenStack]] CLI interface.
  
It may not be possible (or reasonable) to gather the functionality of the various [[OpenStack]] clients into a single binary; in any case the existing binaries will be replaced with one or more binaries that have a uniform command structure and option usage.  The intended model is similar to that used by git (multiple binaries front-ended by a single interface) or libvirt's virsh (a single monolithic binary that does everything) where they follow the form "cli-tool command arguments".  In addition, the virsh-like mode of an embedded command line can be supported that would be able to speed up operations by caching authentication and other data between commands.
+
It may not be possible (or reasonable) to gather the functionality of the various [[OpenStack]] clients into a single binary; in any case the existing binaries will be replaced with one or more binaries that have a uniform command structure and option usage.  The intended model is similar to that used by <code><nowiki>git</nowiki></code> (multiple binaries front-ended by a single interface) or libvirt's <code><nowiki>virsh</nowiki></code> (a single monolithic binary that does everything) where they follow the form <code><nowiki>cli-tool command arguments</nowiki></code>.  In addition, the virsh-like mode of an embedded command line can be supported that would be able to speed up operations by caching authentication and other data between commands.
  
 
== Goals ==
 
== Goals ==
  
* use consistient naming and strucutre for commands and arguments
 
 
* use the [[OpenStack]] Python client API modules, extending them as required
 
* use the [[OpenStack]] Python client API modules, extending them as required
* use a single-binary approach that also contains an embedded command-line that can execute multiple commands on a single authentication (see libvirt's virsh for an example)
+
* use consistent naming and structure for commands and arguments
 
* consistent output formats with the option of reliably machine parsable formats
 
* consistent output formats with the option of reliably machine parsable formats
 +
* use a single-binary approach that also contains an embedded command-line that can execute multiple commands on a single authentication (see libvirt's <code><nowiki>virsh</nowiki></code> for an example)
 
* independence from the [[OpenStack]] project names
 
* independence from the [[OpenStack]] project names
  
Line 32: Line 28:
 
=== Command Structure ===
 
=== Command Structure ===
  
* the top level command name is represented here with 'oscli'
+
* the top level command name is represented here with <code><nowiki>oscli</nowiki></code>
 
* sub-commands take the form:
 
* sub-commands take the form:
** <code><nowiki>oscli [<global-options>] <verb> <noun> [<object>] [<command-local-options>]</nowiki></code>
+
** <code><nowiki>oscli [<global-options>] <verb> <noun> [<command-local-arguments>]</nowiki></code>
  
 
The existing command sets for Keystone, Nova, Glance and Quantum have been mapped into the [[/Mapping| new command format]].
 
The existing command sets for Keystone, Nova, Glance and Quantum have been mapped into the [[/Mapping| new command format]].
Line 41: Line 37:
  
 
* All long options names shall use '-' as the interpolation character
 
* All long options names shall use '-' as the interpolation character
* [[/Authentication|Authentication options]] conform to the original [[CLIAuth]] with the exception as noted above ('-' chars)
+
* Authentication options conform to [[/Authentication| a revised version of]] the original [[CLIAuth]]
 
* All arguments are <code><nowiki>--argument=value</nowiki></code>
 
* All arguments are <code><nowiki>--argument=value</nowiki></code>
  
Line 55: Line 51:
 
* Positional arguments are allowed where the common use case is obvious, with the <code><nowiki>--argument=value</nowiki></code> also being accepted
 
* Positional arguments are allowed where the common use case is obvious, with the <code><nowiki>--argument=value</nowiki></code> also being accepted
  
== Other Information ==
+
== Additional Information ==
 +
 
 +
=== Supplemental Documents ===
 +
 
 +
* [[/Authentication|Revised OSCLI Authentication]]
 +
* [[/Mapping|Command Mapping]]
 +
 
 +
=== Other Resources ===
  
 
* Previous work in this vein is at [[UnifiedCommandLineClient]]
 
* Previous work in this vein is at [[UnifiedCommandLineClient]]

Revision as of 15:51, 12 April 2012

UnifiedCLI

Status: DRAFT

Summary

A unified OpenStack CLI will provide users with an improved experience in dealing with the variety of commands and arguments required to interact with OpenStack. The unified CLI is intended to be a complete substitute for the bundled CLI binaries supplied with the OpenStack project clients. Where possible it will utilize the existing client modules to minimize duplication of effort.

Rationale

The user experience with OpenStack CLI tools is a frustrating one right now due to a number of inconsistencies between the varios tools, not to mention making a user know that keystone is the user/tenant tool and nova is the instance/flavor/image tools and glance is the image tool that replaces the image functions in nova.

At this point it seems fair to consider those tools to be the 'free sample cli' that comes bundled with the client libraries and ignore them in favor of a new unified (in spirit, if not in implementation) OpenStack CLI interface.

It may not be possible (or reasonable) to gather the functionality of the various OpenStack clients into a single binary; in any case the existing binaries will be replaced with one or more binaries that have a uniform command structure and option usage. The intended model is similar to that used by git (multiple binaries front-ended by a single interface) or libvirt's virsh (a single monolithic binary that does everything) where they follow the form cli-tool command arguments. In addition, the virsh-like mode of an embedded command line can be supported that would be able to speed up operations by caching authentication and other data between commands.

Goals

  • use the OpenStack Python client API modules, extending them as required
  • use consistent naming and structure for commands and arguments
  • consistent output formats with the option of reliably machine parsable formats
  • use a single-binary approach that also contains an embedded command-line that can execute multiple commands on a single authentication (see libvirt's virsh for an example)
  • independence from the OpenStack project names

Design

Command Structure

  • the top level command name is represented here with oscli
  • sub-commands take the form:
    • oscli [<global-options>] <verb> <noun> [<command-local-arguments>]

The existing command sets for Keystone, Nova, Glance and Quantum have been mapped into the new command format.

Command Arguments

  • All long options names shall use '-' as the interpolation character
  • Authentication options conform to a revised version of the original CLIAuth
  • All arguments are --argument=value

Other

  • arguments that normally require an ID in the OS-API may also use the name or other short identifier where reasonable to support
  • output option for character-delimited format, character can be specified, default to '|'

Implementation

Unresolved issues

  • Positional arguments are allowed where the common use case is obvious, with the --argument=value also being accepted

Additional Information

Supplemental Documents

Other Resources