Command interface

osc

OpenStack command line interface.

Configuration

As all OpenStack tools it fully supports clouds.yaml

Certain aspects of the CLI itself (not the cloud connection) can be configured using $XDG_CONFIG_HOME/osc/config.yaml file. With it it is possible, for example, to configure which resource fields are returned when no other output controlling parameters has be passed.

Example:

yaml views: compute.server: # Listing compute servers will only return ID, NAME and IMAGE columns unless `-o wide` or `-f XXX` parameters are being passed fields: [id, name, image] dns.zone/recordset: # DNS zone recordsets are listed in the wide mode by default. wide: true

Features

  • osc api as an API wrapper allowing user to perform any direct API call specifying service type, url, method and payload. This can be used for example when certain resource is not currently implemented natively.

  • osc auth with subcommands for dealing explicitly with authentication (showing current auth info, renewing auth, MFA/SSO support)

  • Every resource is having a service type in the command solving confusions like user groups vs volume groups

  • Every multi-word resource name is "-" separated (i.e. floating-ip, access-rule)

Output

  • osc ... -o json as an explicit machine readable format output. It allows seeing raw resource json representation as send by the API without any processing on the client side.

Note: the result is not the raw json response, but the raw json resource information found underneath expected resource key. This mode can be used i.e. to see fields that are not expected by the osc and allows further easy machine processing with tools like jq

  • osc ... -o wide for list operations to return all known fields. By default list operation will only return a subset of known generic resource fields to prevent multiline tables. This mode (together with not specifying -o parameter at all) is considered as an output for humans. Field names are not generally renamed and are names as the API returns them.

Shell autocompletion

osc supports generation of the completion file for diverse shells. This can be enabled i.e. by executing

bash echo 'source <(osc completion bash)' >>~/.bashrc

Usage: osc [OPTIONS] <COMMAND>

Available subcommands:

  • osc api — Perform direct REST API requests with authorization
  • osc auth — Cloud Authentication operations
  • osc block-storage — Block Storage (Volume) service (Cinder) commands
  • osc catalog — Catalog commands args
  • osc compute — Compute service (Nova) operations
  • osc container-infrastructure — Container Infra service (Magnum) operations
  • osc dns — DNS service (Designate) operations
  • osc identity — Identity (Keystone) commands
  • osc image — Image service operations
  • osc load-balancer — Load Balancer service operations
  • osc network — Network (Neutron) commands
  • osc object-store — Object Store service (Swift) commands
  • osc placement — The placement API service was introduced in the 14.0.0 Newton release within the nova repository and extracted to the placement repository in the 19.0.0 Stein release. This is a REST API stack and data model used to track resource provider inventories and usages, along with different classes of resources. For example, a resource provider can be a compute node, a shared storage pool, or an IP allocation pool. The placement service tracks the inventory and usage of each provider. For example, an instance created on a compute node may be a consumer of resources such as RAM and CPU from a compute node resource provider, disk from an external shared storage pool resource provider and IP addresses from an external IP pool resource provider
  • osc completion — Output shell completion code for the specified shell (bash, zsh, fish, or powershell). The shell code must be evaluated to provide interactive completion of osc commands. This can be done by sourcing it from the .bash_profile

Options:

  • --os-cloud <OS_CLOUD> — Name reference to the clouds.yaml entry for the cloud configuration

  • --os-project-id <OS_PROJECT_ID> — Project ID to use instead of the one in connection profile

  • --os-project-name <OS_PROJECT_NAME> — Project Name to use instead of the one in the connection profile

  • --os-client-config-file <OS_CLIENT_CONFIG_FILE> — Custom path to the clouds.yaml config file

  • --os-client-secure-file <OS_CLIENT_SECURE_FILE> — Custom path to the secure.yaml config file

  • -o, --output <OUTPUT> — Output format

    Possible values:

    • json: Json output
    • wide: Wide (Human readable table with extra attributes). Note: this has effect only in list operations

  • -f, --fields <FIELDS> — Fields to return in the output (only in normal and wide mode)

  • -p, --pretty — Pretty print the output

  • -v, --verbose — Verbosity level. Repeat to increase level

  • --timing — Record HTTP request timings