openstack_cli is both an executable binary that can be run, and a library that can be used in Rust programs.

Installing the `osc` executable

Assuming you have Rust/Cargo installed, run this command in a terminal:

cargo install openstack_cli

It will make the osc command available in your PATH if you've allowed the PATH to be modified when installing Rust. cargo uninstall openstack_cli uninstalls.

Adding `openstack_cli` library as a dependency

Run this command in a terminal, in your project's directory:

cargo add openstack_cli

To add it manually, edit your project's Cargo.toml file and add to the [dependencies] section:

openstack_cli = "0.13.5"

The openstack_cli library will be automatically available globally. Read the openstack_cli library documentation.

Back to the crate overview.

Readme

OpenStackClient

osc is a CLI for the OpenStack written in Rust. It is relying on the corresponding openstack_sdk crate (library) and is generated using OpenAPI specifications. That means that the maintenance effort for the tool is much lower compared to the fully human written python-openstackclient. Due to the fact of being auto-generated there are certain differences to the python cli but also an enforced UX consistency.

NOTE: As a new tool it tries to solve some issues with the original python-openstackclient. That means that it can not provide seamless migration from one tool to another.

Commands implementation code is being produced by codegenerator what means only low maintenance is required for that code.

Features

Advanced authentication caching built-in and enabled by default
Status based resource coloring (resource list table rows are colored by the resource state)
Output configuration (using $XDG_CONFIG_DIR/osc/config.yaml it is possible to configure which fields should be returned when listing resources to enable customization).
Strict microversion binding for resource modification requests (instead of openstack server create ... which will not work with all microversions you use osc compute server create290 which will only work if server supports it. It is similar to openstack --os-compute-api-version X.Y). It behaves the same on every cloud independent of which microversion this cloud supports (as long as it supports required microversion).
Can be wonderfully combined with jq for ultimate control of the necessary data (osc server list -o json | jq -r ".[].flavor.original_name")
Output everything what cloud sent (osc compute server list -o json to return fields that we never even knew about, but the cloud sent us).
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)

Microversions

Initially python-openstackclient was using lowest microversion unless additional argument specifying microversion was passed. Later, during switching commands towards using of the OpenStackSDK a highest possible microversion started being used (again unless user explicitly requested microversion with --XXX-api-version Y.Z). One common thing both approaches use is to give user control over the version what is crucial to guarantee stability. The disadvantage of both approaches is that they come with certain opinions that does not necessarily match what user expects and make expectation on what will happen hard. For the end user reading help page of the command is pretty complex and error prone when certain parameters appear, disappear and re-appear with different types between microversion. Implementing (and using) the command is also both complex and error prone in this case.

osc is trying to get the best of 2 approaches and providing dedicated commands for microversions (i.e. create20, create294). Latest microversion command is always having a general alias (create in the above case) to let user explicitly use latest microversion, what, however, does not guarantee it can be invoked with requested parameters. This approach allows user to be very explicit in the requirement and have a guarantee of the expected parameters. When a newer microversion is required user should explicitly to do "migration" step adapting the invocation to a newer set of parameters. Microversion (or functionality) deprecation is also much simpler this way and is handled by marking the whole command deprecated and/or drop it completely.

Request timing

osc supports --timing argument that enables capturing of all HTTP requests and outputs timings grouped by URL (ignoring the query parameters) and method.

Connection configuration

osc tool supports connection configuration using the clouds.yaml files and environment variables. In difference to the python-openstackclient no merging of configuration file data with the environment variables is supported. Reason for that is number of errors and unexpected behavior users are experiencing due to that.

--os-cloud <CLOUD_NAME> command argument points to the connection configured in the clouds.yaml file(s).
$OS_CLOUD environment variable points to the configuration in the clouds.yaml file
--cloud-config-from-env flag directs cli to ignore clouds.yaml configuration file completely and only rely on the environment variables (prefixed as usual with OS_ prefix).
--os-cloud-name <CLOUD_NAME> or $OS_CLOUD_NAME environment variable uses the specified value as the reference connection name i.e when the authentication helper resolves the missing authentication parameters (like password or similar).
With no cloud being specified in any of the above ways a fuzzy select with all cloud connections configured in the clouds.yaml file is used to get the user selection interactively. This will not happen in a non-interactive mode (i.e when stdin is not a terminal).
--os-project-name and --os-project-id cause the connection to be established with the regular credentials, but use the different project for the `scoped token.

Sometimes it may be undisired to keep secrets in clouds.yaml or secure.yaml files. In the interactive mode such data is retrieved from the user via regular prompts. It is possible to specify the path to the external executable command that would be called with 2 parameters: the required attribute key (i.e. password) and the connection name. The executable may be called multiple times with different parameters when required. There is no support for passing all required parameters in one invocation. This executable must not write anything to the stdout except of the actual value. Whatever is written into the stderr would be included in the osc log in the warning level. Please note that there are no security guards possible for what the command actually performs. In future pre-built with better security handling may be added (i.e. fetching secrets from Vault, Bitwarden, etc).

#!/usr/bin/env bash

KEY=$1
CLOUD=$2

echo -e "Requested $KEY for $CLOUD" > &2
echo  "a_super_secret"

Installing the osc executable

Adding openstack_cli library as a dependency

Installing the `osc` executable

Adding `openstack_cli` library as a dependency