Human Interface Guide¶

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.

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.

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 and so on. 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.

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:

$ openstack --help

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

$ openstack help server create

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.

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-1> <action> [<object-2>] [<command-arguments>]

Subcommands shall 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

Command Output¶

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

Machine-parsable output format may be specified with the --format option to list and show commands. list commands have an option (--format csv) for CSV output and show commands have an option (--format shell) for the shell variable assignment syntax of var="value". In both cases, all data fields are quoted with “

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 appears in front of the first object in the command.

The options --help and -h display the global options and a list of the supported commands. Note that the commands shown depend on the API versions that are in effect; i.e. if --os-identity-api-version=3 is present Identity API v3 commands are shown.

Authentication¶

Using global options:

$ openstack --os-tenant-name ExampleCo --os-username demo --os-password secret --os-auth-url http://localhost:5000:/v2.0 server show appweb01
+------------------------+-----------------------------------------------------+
|        Property        |                Value                                |
+------------------------+-----------------------------------------------------+
| OS-DCF:diskConfig      | MANUAL                                              |
| OS-EXT-STS:power_state | 1                                                   |
| flavor                 | m1.small                                            |
| id                     | dcbc2185-ba17-4f81-95a9-c3fae9b2b042                |
| image                  | Ubuntu 12.04 (754c231e-ade2-458c-9f91-c8df107ff7ef) |
| keyname                | demo-key                                            |
| 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=secret
$ export OS_AUTH_URL=http://localhost:5000:/v2.0
$ openstack server show appweb01
+------------------------+-----------------------------------------------------+
|        Property        |                Value                                |
+------------------------+-----------------------------------------------------+
| OS-DCF:diskConfig      | MANUAL                                              |
| OS-EXT-STS:power_state | 1                                                   |
| flavor                 | m1.small                                            |
| id                     | dcbc2185-ba17-4f81-95a9-c3fae9b2b042                |
| image                  | Ubuntu 12.04 (754c231e-ade2-458c-9f91-c8df107ff7ef) |
| keyname                | demo-key                                            |
| name                   | appweb01                                            |
| private_address        | 10.4.128.13                                         |
| status                 | ACTIVE                                              |
| user                   | demo                                                |
+------------------------+-----------------------------------------------------+

Machine Output Format¶

Using the csv output format with a list command:

$ openstack server list --format csv
"ID","Name","Status","Private_Address"
"ead97d84-6988-47fc-9637-3564fc36bc4b","appweb01","ACTIVE","10.4.128.13"

Using the show command options of shell output format and adding a prefix of my_ to avoid collisions with existing environment variables:

$ openstack server show --format shell --prefix my_ appweb01
my_OS-DCF:diskConfig="MANUAL"
my_OS-EXT-STS:power_state="1"
my_flavor="m1.small"
my_id="dcbc2185-ba17-4f81-95a9-c3fae9b2b042"
my_image="Ubuntu 12.04 (754c231e-ade2-458c-9f91-c8df107ff7ef)"
my_keyname="demo-key"
my_name="appweb01"
my_private_address="10.4.128.13"
my_status="ACTIVE"
my_user="demo"