Jump to: navigation, search

OpenStackClient/HumanInterfaceGuidelines

Note: This page covers the OpenStackClient CLI only but looks familiar because it was derived from the Horizon HIG.

Overview

What is a HIG? The Human Interface Guidelines document was created for OpenStack designers in order to direct the creation of new OpenStackClient command interfaces.

Personas

Personas are archetypal users of the system. Keep these types of users in mind when designing the interface.

Alice the admin

Alice is an administrator who is responsible for maintaining the OpenStack cloud installation. She has many years of experience with Linux systems administration.

Darren the deployer

Darren is responsible for doing the initial OpenStack deployment on the host machines.

Emile the end-user

Emile uses the cloud to do software development inside of the virtual machines. She uses the command-line tools because she finds it quicker than using the dashboard.

Principles

The principles established in this section define the high-level priorities to be used when designing and evaluating interactions for the OpenStack command line interface. Principles are broad in scope and can be considered the philosophical foundation for the OpenStack experience; while they may not describe the tactical implementation of design, they should be used when deciding between multiple courses of design.

A significant theme for designing for the OpenStack experience concerns focusing on common uses of the system rather than adding complexity to support functionality that is rarely used.

Consistency

Consistency between OpenStack experiences will ensure that the command line interface feels like a single experience instead of a jumble of disparate products. Fractured experiences only serve to undermine user expectations about how they should interact with the system, creating an unreliable user experience. To avoid this, each interaction and visual representation within the system must be used uniformly and predictably. The architecture and elements detailed in this document will provide a strong foundation for establishing a consistent experience.

Example Review Criteria

  • Do the command actions adhere to a consistent application of actions?
  • Has a new type of command subject or output been introduced?
  • Does the design use command elements (options and arguments) as defined? (See Core Elements.)
  • Can any newly proposed command elements (actions or subjects) be accomplished with existing elemetns?
  • Does the design adhere to the structural model of the core experience? (See Core Architecture.)
  • Are any data objects displayed or manipulated in a way contradictory to how they are handled elsewhere in the core experience?

Simplicity

To best support new users and create straight forward interactions, designs should be as simple as possible. When crafting new commands, designs should minimize the amount of noise present in output: large amounts of nonessential data, overabundance of possible actions, etc. Designs should focus on the intent of the command, requiring only the necessary components and either removing superfluous elements or making them accessible through optional arguments. An example of this principle occurs in OpenStack’s use of tables: only the most often used columns are shown by default. Further data may be accessed through the output control options, allowing users to specify the types of data that they find useful in their day-to-day work.

Example Review Criteria

  • Can options be used to combine otherwise similar commands?
  • How many of the displayed elements are relevant to the majority of users?
  • If multiple actions are required for the user to complete a task, is each step required or can the process be more efficient?

User-Centered Design

Commands should be design based on how a user will interact with the system and not how the system’s backend is organized. While database structures and APIs may define what is possible, they often do not define good user experience; consider user goals and the way in which users will want to interact with their data, then design for these work flows and mold the interface to the user, not the user to the interface.

Commands should be discoverable via the interface itself.

To determine a list of available commands, use the ``-h`` or ``--help`` options:

 $ stack -h

For help with an individual command, use the ``help`` command:

 $ stack help list server

Example Review Criteria

  • How quickly can a user figure out how to accomplish a given task?
  • Has content been grouped and ordered according to usage relationships?
  • Do work flows support user goals or add complexity?

Transparency

Make sure users understand the current state of their infrastructure and interactions. For example, users should be able to access information about the state of each machine/virtual machine easily, without having to actively seek out this information. Whenever the user initiates an action, make sure a confirmation is displayed[1] to show that an input has been received. Upon completion of a process, make sure the user is informed. Ensure that the user never questions the state of their environment.

[1] This goes against the common UNIX philosophy of only reporting error conditions and output that is specifically requested.

Example Review Criteria

  • Does the user receive feedback when initiating a process?
  • When a process is completed?
  • Does the user have quick access to the state of their infrastructure?


Architecture

Command Structure

OpenStackClient has a consistent and predictable format for all of its commands.

  • The top level command name is openstack
  • Sub-commands take the form:
openstack [<global-options>] <object> <action> [<second-object>] [<command-arguments>]


Subcommands have three distinct parts to its commands (in order that they appear):

  • global options
  • command object(s) and action
  • command options and arguments


Output formats:

  • user-friendly tables with headers, etc
  • machine-parsable delimited


Notes:

  • All long options names shall begin with two dashes ('--') and use a single dash ('-') internally between words (--like-this)
  • Authentication options conform to the common CLI authentication guidelines.

Global Options

Global options are global in the sense that the apply to every command invocation regardless of action to be performed. This includes authentication credentials and API version selection. Most global options have a corresponding environment variable that may also be used to set the value. If both are present, the command-line option takes priority. The environment variable names are derived from the option name by dropping the leading dashes ('--'), converting each embedded dash ('-') to an underscore ('_'), and converting to upper case.

--help

The standard `--help` global option displays the documentation for invoking the program and a list of the availably commands on standard output. All other options and commands are ignored when this is present. The traditional short form help option (-h) is also available.

FIXME(aspiers): plagiarised from the "GNU standards for --help". Do we want to plagiarise the rest of it and recommend the output format to be something like this?

Near the end of the `--help` option's output, please place lines giving the email address for bug reports, the package's home page, and the general page for help. The format should be like this:
    Home page: <http://openstack.org/>
    Documentation: <http://docs.openstack.org/>
    Report bugs via: <http://openstack.org/community/>

--version

FIXME(aspiers): plagiarised from the beginning of `GNU standards for --version. but there are many other good ideas which could be copied too.

The standard `--version` option should direct the program to print information about its name, version, origin and legal status, all on standard output, and then exit successfully. Other options and arguments should be ignored once this is seen, and the program should not perform its normal function.
The first line is meant to be easy for a program to parse; the version number proper starts after the last space. In addition, it contains the canonical name for this program, in this format:
    OpenStack Nova (Compute) 2012.1.0.3
The program's name should be a constant string; don't compute it from `sys.argv`. The idea is to state the standard or canonical name for the program, not its file name. There are other ways to find out the precise file name where a command is found in `PATH`.

Other Global Options

The environment variable name for a global option is derived by

  • removing the leading `--`
  • converting the option name to upper case
  • replacing the remaining `-` (dash) chars with `_` (underscore)

All global options begin with `--os-`. The corresponding environment variable begins with `OS_` to reduce the potential for collisions with other existing environment variables. If global options take precedence over the corresponding environment variable when both are present.

Command Object(s) and Action

Commands generally consist of an object described by one or more words followed by an action. When a command requires two objects be acted upon the primary object appears ahead of the action and the secondary object appears after the action. If both objects have positional arguments to identify them the arguments appear in the same order as the objects in the command. In badly formed English it is expressed as "(Take) object1 (and perform) action (using) object2 (to it)." <object-1> <action> <object-2> Examples:

   * group add user <group> <user>
   * access token list   (here, 'access token' is a two-word single object)

The help command is unique as it appears in front of a normal command and displays the help text for that command rather than execute it.

  • Object names are always specified in command in their singular form. This is contrary to natural

language use.

    • FIXME(dtroyer): auto-correct this in the client?**

Command Arguments and Options

  • Positional arguments trail command options.

Most commands have one or more arguments (aka positional arguments) that supply information required to carry out the command. Optional information is supplied with options following the same style as the global options, without the corresponding environment variables.

If a command accepts various verbs/nouns as the early

    • [FIXME(aspiers): or earliest?]** positional argument(s), then it

should treat `--help` when following such an argument as being equivalent to requesting help for that specific action via the `help` action. For example, the following should produce equivalent output:

    • FIXME(aspiers): design still in discussion on openstack list**


Option Forms

  • *boolean*: boolean options shall use a form of `--<true>|--<false>` or `--<option>|--no-<option>`. For example, the `enabled` state of a tenant is set with `--enable|--disable`.


Command Output

The usual command output is pretty-printed using the Python `prettytable` module.

A machine-parsable output format may be specified with the global option `--os-output-format`.

    • [FIXME(dtroyer): insert better option name here]** The machine-parsable

output is a line oriented character delimited format with the delimting character `|` which may be changed with the global option `--os-output-char`.

Note that setting `--os-output-char=,` does not produce true CSV format; there are no headers and string values are not quoted. Certain characters are not good candidates for delimiters as they may appear naturally in the command output data; these include `:` (colon) and `.` (period).

    • [FIXME(ijw): without any form of quoting, then no delimiter is guaranteed to be safe if I want to parse the output on the command line. Would it be possible to write a script that's guaranteed to work with e.g. all instance names?]**

Help Commands

The help system is considered separately due to its special status among the commands. Rather than performing tasks against a system, it provides information about the commands available to perform those tasks. The format of the `help` command therefore varies from the form for other commands in that the `help` command is optionally followed by an action and subject in order to provide more specific information on that command.

Examples

The following examples depict common command and output formats expected to be produces by the OpenStack client.

    • FIXME(dtroyer): the example output below is based on the existing clients, improve them!)**

Authentication

Using global options::

   stack --os-tenant-name ExampleCo --os-username demo --os-password secrete --os-auth-url http://localhost:5000:/v2.0 show server appweb01
   +------------------------+--------------------------------------+
   |        Property        |                Value                 |
   +------------------------+--------------------------------------+
   | OS-DCF:diskConfig      | MANUAL                               |
   | OS-EXT-STS:power_state | 1                                    |
   | flavor                 | m1.small                             |
   | id                     | dcbc2185-ba17-4f81-95a9-c3fae9b2b042 |
   | image                  | 754c231e-ade2-458c-9f91-c8df107ff7ef |
   | name                   | appweb01                             |
   | private_address        | 10.4.128.13                          |
   | status                 | ACTIVE                               |
   | user                   | demo                                 |
   +------------------------+--------------------------------------+

Using environment variables::

   export OS_TENANT_NAME=ExampleCo
   export OS_USERNAME=demo
   export OS_PASSWORD=secrete
   export OS_AUTH_URL=http://localhost:5000:/v2.0
   show server appweb01
   +------------------------+--------------------------------------+
   |        Property        |                Value                 |
   +------------------------+--------------------------------------+
   | OS-DCF:diskConfig      | MANUAL                               |
   | OS-EXT-STS:power_state | 1                                    |
   | flavor                 | m1.small                             |
   | id                     | dcbc2185-ba17-4f81-95a9-c3fae9b2b042 |
   | image                  | 754c231e-ade2-458c-9f91-c8df107ff7ef |
   | name                   | appweb01                             |
   | private_address        | 10.4.128.13                          |
   | status                 | ACTIVE                               |
   | user                   | demo                                 |
   +------------------------+--------------------------------------+


Machine Output Format

Using the default `|` separator::

   stack --os-output-format list server
   ead97d84-6988-47fc-9637-3564fc36bc4b|appweb01

[** FIXME(ijw): Interesting example choice here - you've chosen a vertical table format above and a horizontal, unlabelled table format below. How would I know from the output above that the columns that would appear in the horizontal layout are the ones shown? Perhaps there should be a column list option?**]

Using `,` as a delimiter, mixing global options and environment variables::

   export OS_OUTPUT_CHAR=","
   stack --os-output-format list server
   ead97d84-6988-47fc-9637-3564fc36bc4b,appweb01