UnifiedCommandLineClient

OpenStack Unified Client

#!wiki caution
'''This document is potentially superceded'''

A new project has been created along these lines: see [[UnifiedCLI]] for more information. FIXME: Ideally the valuable ideas in this document should be merged into [[UnifiedCLI]], and then this page removed to avoid confusion.

Working with multiple OpenStack projects can be quite tedious as they all have their own command-line tools. Having a single command-line interface (CLI) will help to unify project developers, reduce operational headaches, and provide users with a better overall experience.

Start with Authentication / Authorization

If the first step, when calling our unified CLI, is to authenticate against a provided authentication endpoint (managed by a Keystone-compaible service), then right away feedback can be given to the user regarding which services are available for use.

For example, if incorrect authentication is given, or an invalid/inaccessible URL is given:

$ os
usage: os [--url URL] [--username USERNAME] [--apikey APIKEY] [--project PROJECT]

Command-line interface for connecting to various OpenStack projects.

Correct authentication URL and credentials must be supplied before more detailed options can be given.

Once valid authentication information is given, we can provide the user with a better overview of available services:

$ os
usage: os <project>

Command-line interface for connecting to various OpenStack projects.

Supported projects:
	compute		Manage compute nodes via the "Nova" API.
	image		Manage disk images via the "Glance" API.
	queue		Manage queues via the "Burrow" API.
	volume		Manage remote disk volumes via the "Lunr" API.
	auth		Manage authentication and authorization via the "Keystone" API.
	network		Manage networks via the "Melange" API.

The list of services above is generated by reading the service catalog provided by a Keystone-based service, which currently looks something like this:

{
    "auth":{
        "token":{
            "id":"asdasdasd-adsasdads-asdasdasd-adsadsasd",
            "expires":"2010-11-01T03:32:15-05:00"
        },
        "serviceCatalog":{
            "service1":[
                {
                    "region":"DFW",
                    "publicURL":"https://service1-public/v1/blah-blah",
                    "internalURL":"https://service1-internal/v1/blah-blah"
                },
                {
                    "region":"ORD",
                    "publicURL":"https://service1-public-ord/v1/blah-blah",
                    "internalURL":"https://service1-internal-ord/v1/blah-blah"
                }
            ],
            "service2":[
                {
                    "region":"DFW",
                    "publicURL":"https://service2-public-dfw/v1/blah-blah"
                },
                {
                    "region":"ORD",
                    "publicURL":"https://service2-public-orf/v1/blah-blah"
                }
            ],
            "service3":[
                {
                    "publicURL":"https://service3-public/v1/blah-blah"
                }
            ]
        }
    }
}

When a service is selected on the command line, detailed information will be generated based on the authorization of the currently authenticated user. For example:

$ os compute
usage: os compute <command>

Command-line interface for retrieving information from an OpenStack Compute service.

Supported API versions:
	--version=1.0 
	--version=1.1 [Default]

Supported commands:
	boot			Boot a new server.
	delete			Shut down and delete a server.
	flavor-list		Print a list of available 'flavors'.
	image-list		Print a list of available disk images.
	snapshot		Create a new disk image based on a currently
				running server.
	list			List active servers.
	reboot			Reboot a server.
	rebuild			Shutdown, re-image, and re-boot a server.
	rename			Rename a server.
	resize			Begin the resize process.
	resize-confirm		Confirm a previously started resize.
	resize-revert		Revert a previously started resize.

	admin:diagnostics	Retrieve server diagnostics.
	admin:boot		Boot a new server, with extra options.
	admin:lock		Lock a server, preventing any changes.
	admin:unlock		Remove server lock, allowing future changes.

	zone:list		List zones underneath this endpoint.
	zone:info		Get information on this endpoint's zone.
	zone:add		Add a new child zone underneath this endpoint.

We can see that this user has access to many run-of-the-mill Compute tasks, but they are also authorized to use functions from the "Compute Administrative Extension" and the "Compute Zones Extension". You can tell that these commands are provided by extensions because they are prefixed with a relevant...prefix.

Required Options

I understand the irony (?) of having required options, but they're not technically required because they'll default to environmental variables, so having them as command line arguments is not an option.

Command Line Option	Environmental Variable
--url	OS_AUTH_URL
--project	OS_PROJECT_ID
--username	OS_AUTH_USER
--api_key	OS_AUTH_KEY

Potential Issues

• An implementation of this might be slow before caching is involved because even the error response views above require a round-trip talk with one or more OpenStack services. Caching solves this, but caching shouldn't be considered for the first release of this client.
• Currently Keystone seems to be returning versioned service URLs. For example, the service catalog might return http://openstack.org/compute/v1.1 instead of http://openstack.org/compute/. The client should be able to choose a version just as they are currently able to choose a region.