Installing the CLI

Using pip (recommend)

When installing the CLI using pip, it is recommended to use a python virtual environment to contain the required dependencies.

The following provides the basics of manually installing the OpenStack command line tools on common operating systems.

The examples all make reference to the use of virtual environments. Please refer to the Using python virtual environments tutorial for more information on venv.

Operating system specific steps

Ubuntu Linux 18.04

Ubuntu 18.04 uses Python 3.x by default. We recommended using Python3.x because python2 has been scheduled for retirement soon and therefore migrating over to Python3 is a necessity.

# Install python 3.x and virtualenv
sudo apt-get install python3 python3-venv

# Create a new virtual environment and activate it
python3 -m venv venv

# Activate the virtual environment
source venv/bin/activate

# Install the Python openstack client libraries into your virtual environment
pip install python-{openstackclient,ceilometerclient,heatclient,neutronclient,swiftclient,octaviaclient,magnumclient}

Debian Linux 8

# Make sure you have virtualenv and pip code dependencies installed
sudo apt-get install gcc python-dev python-virtualenv

# Create a new virtual environment for Python 3.x and activate it
virtualenv venv

# Activate the virtual environment
source venv/bin/activate

# Install the Python openstack client libraries and the Python timezone definitions
# into your virtual environment
pip install pytz python-{openstackclient,ceilometerclient,heatclient,neutronclient,swiftclient,octaviaclient,magnumclient}

CentOS Linux 7

# Make sure you have Python development tools and wget installed
sudo yum install python-devel gcc wget

# retrieve the pip installer script and install pip and virtualenv
wget https://bootstrap.pypa.io/get-pip.py
sudo python get-pip.py
sudo pip install virtualenv

# Create a new virtual environment for Python 3.x and activate it
virtualenv venv

# Activate the virtual environment
source venv/bin/activate

# Install the Python openstack client libraries into your virtual environment
pip install python-{openstackclient,ceilometerclient,heatclient,neutronclient,swiftclient,octaviaclient,magnumclient}

MacOS

# from a terminal session install pip and virtualenv
sudo easy_install pip
sudo pip install virtualenv

# Create a new virtual environment and activate it
virtualenv venv
source venv/bin/activate

# Install the Python openstack client libraries into your virtual environment
pip install python-{openstackclient,ceilometerclient,heatclient,neutronclient,swiftclient,octaviaclient,magnumclient}

Windows (Powershell)

A good overview for the setup and configuration of Python and pip on Windows can be found at http://www.tylerbutler.com/2012/05/how-to-install-python-pip-and-virtualenv-on-windows-with-powershell/

Note

The guide above mentions how to download virtualenv for powershell, however this is assuming you are using python2 which has been discontinued. For this reason, we recommend using pip to install the normal virtualenvwrapper. using pip install virtualenvwrapper

Assuming that Python and pip have successfully been installed then

# From a PowerShell session started with administration rights
# create and activate a virtual environment
virtualenv.exe venv
.\venv\scripts\activate

# Install the Python openstack client libraries into your virtual environment
pip install python-openstackclient python-ceilometerclient python-heatclient python-neutronclient python-swiftclient python-octaviaclient python-magnumclient

Now that you have installed the required libraries to work with the Catalyst Cloud onto your virtual environment; You have to make sure that whenever you use powershell to interact with the cloud, you work on your Virtual Environment. It may save time to make a short python script that runs the activation command for you when you start powershell up.

If any errors are encountered while pip is building packages it may be necessary to install the Microsoft Visual C++ Compiler for Python 2.7 and retry.

Windows (Linux Subsystem)

This is a much easier method to using the Command Line Interface on a windows machine. It allows you to create a virtual instance of a linux operating system of your choice, then complete the rest of this tutorial as if you were running said operating system. For this example we will be using Ubuntu 18.04

Note

This method is only available if you currently run a 64bit version of windows.

First, you will need to open PowerShell as an Administrator and run:

# Running as Administrator
Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux

You will then need to download a version of Ubuntu from either the Microsoft store, from a command line script, or to manually unpack it and install it from their release website. For our purposes we will be using the Microsoft Store.

../../_images/windows-store.png

I’ve chosen to use Ubuntu 18.04. Once installed, you open the application and set up an Unix account. An Unix account is only relevant on your machine and once set up you won’t need to use your login details again (but hold on to them for security purposes) Once that is done you will be met with a screen somewhat like this:

../../_images/unix-shell.png

Once you have this up and running, you’ll need to change directory to be able to find files you download onto your windows machine. The following code should get you to your root folder, aka ‘My Computer’

$ cd /mnt/c

Then you simply need to follow the guide on how to install the CLI on ubuntu detailed earlier on this page.

Using Docker (experimental)

The Catalyst Cloud CLI is available as a Docker container that is easy to use, packaging the command line interface and all its dependencies.

This tool requires Docker to be installed to function. You can find instructions on how to install and configure Docker here. You can run the docker ps command to confirm Docker has been successfully installed.

Run the following command to install the Catalyst Cloud CLI:

bash <(wget -qO - https://raw.githubusercontent.com/catalyst-cloud/openstackclient-container/master/fetch-installer.sh) -a ccloud -u https://api.cloud.catalyst.net.nz:5000/v3

Note

Our documentation currently refers to the CLI command as openstack. When using the containerised version of the CLI, this command must be replaced with ccloud in the provided examples.

If you are intending to use the containerised tools you will need to obtain the non MFA enabled openrc file for authentication.To get a copy of the non MFA enabled openrc file, select the dropdown in the upper right corner of the dash board and click on OpenStack RC File v3. Select Save As when prompted to select the location on your machine to save this file to.

../../_images/openrc-no-mfa.png

If you need more information on using the file see Source an OpenStack RC file.