15 KiB
Command Structure
OpenStackClient has a consistent and predictable format for all of its commands.
Commands take the form:
openstack [<global-options>] <object-1> <action> [<object-2>] [<command-arguments>]
Note
All long options names begin with two dashes (--
) and
use a single dash (-
) internally between words
(--like-this
). Underscores (_
) are not used in
option names.
Global Options
Global options are global in the sense that they apply to every
command invocation regardless of action to be performed. They include
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.
For example, the default value of --os-username
can be
set by defining the environment variable OS_USERNAME
.
Command Object(s) and Action
Commands consist of an object described by one or more words followed by an action. Commands that require two objects have the primary object ahead of the action and the secondary object after the action. Any positional arguments identifying the objects shall appear in the same order as the objects. 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>
$ volume type list # 'volume type' is a two-word single object
Command Arguments and Options
Each command may have its own set of options distinct from the global options. They follow the same style as the global options and always appear between the command and any positional arguments the command requires.
Objects
The objects consist of one or more words to compose a unique name.
Occasionally when multiple APIs have a common name with common
overlapping purposes there will be options to select which object to
use, or the API resources will be merged, as in the quota
object that has options referring to both Compute and Volume quotas.
access token
: (Identity) long-lived OAuth-based tokenaddress scope
: (Network) a scope of IPv4 or IPv6 addressesaggregate
: (Compute) a grouping of compute hostsavailability zone
: (Compute, Network, Volume) a logical partition of hosts or block storage or network servicescatalog
: (Identity) service catalogcommand
: (Internal) installed commands in the OSC processcompute agent
: (Compute) a cloud Compute agent available to a hypervisorcompute service
: (Compute) a cloud Compute process running on a hostconfiguration
: (Internal) OpenStack client configurationconsistency group
: (Volume) a consistency group of volumesconsistency group snapshot
: (Volume) a point-in-time copy of a consistency groupconsole log
: (Compute) server console text dumpconsole url
: (Compute) server remote console URLconsumer
: (Identity) OAuth-based delegateecontainer
: (Object Storage) a grouping of objectscredential
: (Identity) specific to identity providersdomain
: (Identity) a grouping of projectsec2 credentials
: (Identity) AWS EC2-compatible credentialsendpoint
: (Identity) the base URL used to contact a specific serviceextension
: (Compute, Identity, Network, Volume) OpenStack server API extensionsfederation protocol
: (Identity) the underlying protocol used while federating identitiesflavor
: (Compute) predefined server configurations: ram, root disk and so onfixed ip
: (Compute, Network) - an internal IP address assigned to a serverfloating ip
: (Compute, Network) - a public IP address that can be mapped to a serverfloating ip pool
: (Compute, Network) - a pool of public IP addressesgroup
: (Identity) a grouping of usershost
: (Compute) - the physical computer running compute serviceshypervisor
: (Compute) the virtual machine managerhypervisor stats
: (Compute) hypervisor statistics over all compute nodesidentity provider
: (Identity) a source of users and authenticationimage
: (Image) a disk imageip availability
: (Network) - details of IP usage of a networkip fixed
: (Compute, Network) - an internal IP address assigned to a serverip floating
: (Compute, Network) - a public IP address that can be mapped to a serverip floating pool
: (Compute, Network) - a pool of public IP addresseskeypair
: (Compute) an SSH public keylimits
: (Compute, Volume) resource usage limitsmapping
: (Identity) a definition to translate identity provider attributes to Identity conceptsmodule
: (Internal) - installed Python modules in the OSC processnetwork
: (Compute, Network) - a virtual network for connecting servers and other resourcesnetwork agent
: (Network) - A network agent is an agent that handles various tasks used to implement virtual networksnetwork meter
: (Network) - allow traffic metering in a networknetwork meter rule
: (Network) - rules for network traffic meteringnetwork rbac
: (Network) - an RBAC policy for network resourcesnetwork qos rule
: (Network) - a QoS rule for network resourcesnetwork qos policy
: (Network) - a QoS policy for network resourcesnetwork qos rule type
: (Network) - list of QoS available rule typesnetwork segment
: (Network) - a segment of a virtual networknetwork service provider
: (Network) - a driver providing a network serviceobject
: (Object Storage) a single file in the Object Storageobject store account
: (Object Storage) owns a group of Object Storage resourcespolicy
: (Identity) determines authorizationport
: (Network) - a virtual port for connecting servers and other resources to a networkproject
: (Identity) owns a group of resourcesquota
: (Compute, Volume) resource usage restrictionsregion
: (Identity) a subset of an OpenStack deploymentrequest token
: (Identity) temporary OAuth-based tokenrole
: (Identity) a policy object used to determine authorizationrole assignment
: (Identity) a relationship between roles, users or groups, and domains or projectsrouter
: (Network) - a virtual routersecurity group
: (Compute, Network) - groups of network access rulessecurity group rule
: (Compute, Network) - the individual rules that define protocol/IP/port accessserver
: (Compute) virtual machine instanceserver backup
: (Compute) backup server disk image by using snapshot methodserver dump
: (Compute) a dump file of a server created by features like kdumpserver group
: (Compute) a grouping of serversserver image
: (Compute) saved server disk imageservice
: (Identity) a cloud serviceservice provider
: (Identity) a resource that consumes assertions from anidentity provider
subnet
: (Network) - a contiguous range of IP addresses assigned to a networksubnet pool
: (Network) - a pool of subnetstoken
: (Identity) a bearer token managed by Identity servicetrust
: (Identity) project-specific role delegation between users, with optional impersonationusage
: (Compute) display host resources being consumeduser
: (Identity) individual cloud resources usersuser role
: (Identity) roles assigned to a uservolume
: (Volume) block volumesvolume backup
: (Volume) backup for volumesvolume host
: (Volume) the physical computer for volumesvolume qos
: (Volume) quality-of-service (QoS) specification for volumesvolume snapshot
: (Volume) a point-in-time copy of a volumevolume type
: (Volume) deployment-specific types of volumes availablevolume service
: (Volume) services to manage block storage operationsvolume transfer request
: (Volume) volume owner transfer request
Plugin Objects
The following are known Objects used
by OpenStack plugins
.
These are listed here to avoid name conflicts when creating new plugins.
For a complete list check out plugin-commands
.
action definition
: (Workflow Engine (Mistral))action execution
: (Workflow Engine (Mistral))baremetal
: (Baremetal (Ironic))claim
: (Messaging (Zaqar))cluster
: (Clustering (Senlin))cluster action
: (Clustering (Senlin))cluster event
: (Clustering (Senlin))cluster members
: (Clustering (Senlin))cluster node
: (Clustering (Senlin))cluster policy
: (Clustering (Senlin))cluster policy binding
: (Clustering (Senlin))cluster policy type
: (Clustering (Senlin))cluster profile
: (Clustering (Senlin))cluster profile type
: (Clustering (Senlin))cluster receiver
: (Clustering (Senlin))congress datasource
: (Policy (Congress))congress driver
: (Policy (Congress))congress policy
: (Policy (Congress))congress policy rule
: (Policy (Congress))cron trigger
: (Workflow Engine (Mistral))database flavor
: (Database (Trove))dataprocessing data source
: (Data Processing (Sahara))dataprocessing image
: (Data Processing (Sahara))dataprocessing image tags
: (Data Processing (Sahara))dataprocessing plugin
: (Data Processing (Sahara))message-broker cluster
: (Message Broker (Cue))messaging
: (Messaging (Zaqar))messaging flavor
: (Messaging (Zaqar))network subport
: (Networking (Neutron))network trunk
: (Networking (Neutron))orchestration resource
: (Orchestration (Heat))orchestration template
: (Orchestration (Heat))pool
: (Messaging (Zaqar))ptr record
: (DNS (Designate))queue
: (Messaging (Zaqar))recordset
: (DNS (Designate))search
(Search (Searchlight))search facet
(Search (Searchlight))search resource type
(Search (Searchlight))secret
: (Key Manager (Barbican))secret container
: (Key Manager (Barbican))secret order
: (Key Manager (Barbican))software config
: (Orchestration (Heat))software deployment
: (Orchestration (Heat))stack event
: (Orchestration (Heat))stack hook
: (Orchestration (Heat))stack output
: (Orchestration (Heat))stack resource
: (Orchestration (Heat))stack snapshot
: (Orchestration (Heat))stack template
: (Orchestration (Heat))subscription
: (Messaging (Zaqar))task execution
: (Workflow Engine (Mistral))tld
: (DNS (Designate))workbook
: (Workflow Engine (Mistral))workflow
: (Workflow Engine (Mistral))workflow execution
: (Workflow Engine (Mistral))zone
: (DNS (Designate))zone blacklist
: (DNS (Designate))zone export
: (DNS (Designate))zone import
: (DNS (Designate))zone transfer
: (DNS (Designate))
Actions
The actions used by OpenStackClient are defined below to provide a consistent meaning to each action. Many of them have logical opposite actions. Those actions with an opposite action are noted in parens if applicable.
authorize
- authorize a token (used in OAuth)add
(remove
) - add some object to a container object; the command is built in the order ofcontainer add object <container> <object>
, the positional arguments appear in the same ordercreate
(delete
) - create a new occurrence of the specified objectdelete
(create
) - delete specific occurrences of the specified objectsexpand
(shrink
) - increase the capacity of a clusterfailover
- failover volume host to different backendissue
(revoke
) - issue a tokenlist
- display summary information about multiple objectslock
(unlock
) - lock one or more servers so that non-admin user won't be able to execute actionsmigrate
- move a server or a volume to a different host;--live
performs a live server migration if possiblepause
(unpause
) - stop one or more servers and leave them in memoryquery
- Query resources by Elasticsearch query string or json format DSL.reboot
- forcibly reboot a serverrebuild
- rebuild a server using (most of) the same arguments as in the original createremove
(add
) - remove an object from a group of objectsrescue
(unrescue
) - reboot a server in a special rescue mode allowing access to the original disksresize
- change a server's flavor or a cluster's capacityrestore
- restore a heat stack snapshot or restore a server in soft-deleted stateresume
(suspend
) - return one or more suspended servers to running staterevoke
(issue
) - revoke a tokensave
- download an object locallyset
(unset
) - set a property on the object, formerly called metadatashelve
(unshelve
) - shelve one or more serversshow
- display detailed information about the specific objectshrink
(expand
) - reduce the capacity of a clusterstart
(stop
) - start one or more serversstop
(start
) - stop one or more serverssuspend
(resume
) - stop one or more servers and save to disk freeing memoryunlock
(lock
) - unlock one or more serversunpause
(pause
) - return one or more paused servers to running stateunrescue
(rescue
) - return a server to normal boot modeunset
(set
) - remove an attribute of the objectunshelve
(shelve
) - unshelve one or more servers
Implementation
The command structure is designed to support seamless addition of
plugin command modules via setuptools
entry points. The
plugin commands must be subclasses of Cliff's
command.Command
object. See plugins
for more information.
Command Entry Points
Commands are added to the client using setuptools
entry
points in setup.cfg
. There is a single common group
openstack.cli
for commands that are not versioned, and a
group for each combination of OpenStack API and version that is
supported. For example, to support Identity API v3 there is a group
called openstack.identity.v3
that contains the individual
commands. The command entry points have the form:
action_object = fully.qualified.module.vXX.object:ActionObject
For example, the list user
command for the Identity API
is identified in setup.cfg
with:
openstack.identity.v3 =
# ...
list_user = openstackclient.identity.v3.user:ListUser
# ...