Command Line Interface

The OpenStack Command Line Interface (CLI) serves as a powerful tool for users to interact with their OpenStack cloud environment directly from the terminal or command prompt. The CLI allows Users to perform the same operations that can be usually done via OpenStack dashboard, such as creating Instances, Volumes, Networks etc and many more, and it offers a convenient and efficient way to manage resources, automate tasks, and perform various operations within an OpenStack deployment.

Access to the OpenStack CLI is granted thanks to a feature called Application Credentials (in the following AC) that is available on CINECA OpenStack infrastructure.

Important

By default, the OpenStack CLI is not enabled to external users. In order to have access to the OpenStack CLI service, you need to provide to CINECA a static IP address of the machine from which you will launch the OpenStack commands. Please contact to CINECA support team requesting to add the static IP to the ones allowed to use this service.

Installation

The recommended method to install the CLI is using the python package in the PyPI repository.

pip install python-openstackclient

Using a python virtual environment will help you manage dependencies and avoid conflicts with other Python packages.

Alternatively, the CLI is installable via standard package manager on Linux machines. Check your own distribution’s repositories to check if the package is available.

Important

Check that the version is the one compatible with the specific cloud system your project is allocated on in Cloud Specifics. With greater versions some commands might not work.
For some services, you might need to install additional packages, please see the OpenStack CLI Documentation

Configuration

To use the CLI, you need cloud-specific elements:

System SSL certificate chain: visit the Cloud Specifics page of infrastructure where your project is allocated, to download the certificate
Valid OpenStack Application Credentials: see section Application credentials creation
Environmental variables: see section Setting the Environmental Variables

Application credentials creation

Application Credentials (ACs) are used to securely authenticate users with the OpenStack CLI without exposing user passwords. ACs use a unique “Application Credential ID” and corresponding “secret string” for authentication, ensuring privacy. Users can also delegate role assignments to ACs, controlling authorization levels. Each tenant has its own set of ACs, requiring separate generation ACs for each tenant.

Each user has to generate their own application credentials.

To generate an application credential, you need to login into the Horizon Dashboard, select the project for which the Application Credentials are needed, then go to “Identity → Application credentials” page. You then need to select “Create Application Credential” and fill out the mandatory fields:

name: provide a name for your AC
expiration date: set an expiration for your AC
roles: If you want the AC to have all your available roles, please do not select anything. If by accident, you selected an item in the roles list, you have to re-create from scratch the AC.

Warning

In CINECA HPC Cloud infrastructure, it is possible to create AC with duration up to 7 days. Application Credentials with expiration time greater that 1 week will be automatically removed.

After selecting the button “Create Application Credentials”, the interface shows you the ID and secret of the generated Application Credential.

Download the Application Credential file by clicking on the button “Download openrc file” or, in alternative, “Download cloud.yaml file”.

Important

Remember that the secret will not be available after closing the page, so you must capture it or download it. If you have not saved the AC secret, you have to re-create from scratch the AC.

Setting the Environmental Variables

The OpenStack CLI uses environment variables to store authentication details, such as the OpenStack Identity (Keystone) service endpoint, authentication method, and credentials. By setting these environment variables, you can configure the OpenStack CLI to authenticate with your cloud environment and perform various operations.

In particular, you need to define an environment variable called “OS_CACERT” with the the full path to your SSL certificate chain file. You can set this variable in different ways depending if you have downloaded the AC in the previous step as openrc or yaml file.

openrc file

Each time you would like to use the AC, you have to source the openrc file and export the “OS_CACERT” variable:

source app-cred-...-openrc.sh
export OS_CACERT=<path-to>/<chain_file_name>

clouds.yaml

You have to edit the yaml file and add the “cacert” line with the correct indentation as in the following:

clouds:
   <app-credential-name>:

     auth:

       auth_url: <AUTH_URL>

       application_credential_id: "<AC_ID>"
       application_credential_secret: "<AC_secret>"

     region_name: "RegionOne"

     interface: "public"
     identity_api_version: 3
     auth_type: "v3applicationcredential"
     cacert: "<path-to>/<chain_file_name>"

<app-credential-name> is the name that will allow your system to refer to that specific authentication, while <AUTH_URL> is the URL of the CINECA HPC Cloud infrastructure where the AC have been created. These two fields will be automatically compiled when you download the yaml file from OpenStack together with the AC secret and ID. There may be more than one AC in a single file, under the same clouds block.

Using OpenStack CLI

Once you have set up the OpenStack CLI and configured the necessary environment variables, you can start using the CLI to interact with your cloud environment. The OpenStack CLI provides a wide range of commands for managing resources, performing operations, and automating tasks within an OpenStack deployment. Here are two basic OpenStack CLI commands that you can use to test if the CLI is working correctly:

openstack project list # List all the project associated with the user
openstack server list # List all the servers in the project

More OpenStack commands can be found at the following link: OpenStack CLI Commands

For CLI documentation refer to the following link: OpenStack CLI Documentation