This is the fourteenth in a series of short tutorials showing how to perform common cloud operations tasks in Mirantis OpenStack Express — Mirantis’ “Private Cloud as a Service”
In our last tutorial, we introduced OpenStack Orchestration (Heat), and showed some simple ways to automate procedures with HOT templates. Now we’ll come at automation from another perspective, and show how to install the OpenStack CLI clients on any convenient machine, letting you control your cloud remotely.
This tutorial should work for any user of Mirantis OpenStack Express, or for anyone who’s built a private cloud with Mirantis OpenStack. But it’s especially aimed at new users of Mirantis OpenStack Express Developer Edition. Developer Edition users are running inside an OpenStack Tenant (Project) on a shared cloud, rather than managing their own private cluster. That means they can’t access the CLI clients pre-installed on the OpenStack Controller Node, as we described in an earlier tutorial (Mirantis OpenStack Express – Running OpenStack from the Command Line).
That’s not a bad thing, either! While access to the Controller’s CLI can be convenient (in some cases, critical), it’s not a good idea to use that CLI for regular work. Your Controller node is critical infrastructure, so it’s inconvenient and potentially dangerous to build a development environment there (not to mention that — if you redeploy your cloud — that server goes away).
Putting the CLI elsewhere is easy to do, and gives you much more freedom. You can use a comfy desktop, install your preferred developer tools, and provide secure storage for the repos, image files and other data you’ll accumulate. You can also administer multiple clouds from the same machine.
Intro to OpenStack CLI
OpenStack’s CLI — often referred to in the singular — is actually provided by a set of Python client modules, one for each OpenStack component. The clients have names like novaclient and glanceclient (the associated package names are of the form python-novaclient, python-glanceclient, etc.). They work by accepting input arguments, calling the public (internet) or private (internal network) entrypoints of OpenStack REST functions, and parsing results into Python data structures. Most clients implement all the functionality of the corresponding REST interface.
Each client has a corresponding shell script to call it — named after the component, and called as (component) (command) (optional arguments). So, when using the CLI, you can type something like ‘nova list’ (component – command) into your terminal, and the nova script will hand off to the novaclient module which calls parts of the REST interface (in this case, Keystone to authenticate and Nova-Compute) to hand you back a nice table listing all your active servers.
CLI inputs and outputs are much easier to read and manage than the web headers, JSON or XML objects the REST interface likes to communicate with, directly. The client shell scripts can be called by other shell scripts (e.g, bash), and the client modules can be included in your own Python scripts, letting you create sophisticated tooling.
Installing the CLI Clients: Step by Step
It’s easy to install the OpenStack command-line clients on popular flavors of Linux, as well as on Mac or Windows. Details can be found in OpenStack’s official documentation, here. The basic formula is:
- Make sure you have Python 2.6 or later (not Python 3!) installed.
- Install Python setuptools, which is a distribution/package manager used by pip.
- Install pip, the most commonly-used Python package manager.
- Use pip to install the clients from PyPI, the Python Package Index.
- Obtain and source your Project/Tenant’s OpenStack RC file, putting values into your shell environment enabling authentication to your cloud.
- Use your clients to achieve great things.
If you’re using Mac OS X or any relatively recent desktop or server iteration of a popular Linux, congratulations – you already have an appropriate version of Python installed. To be absolutely sure, open a terminal and enter python -V (any version 2 python with 6+ as a sub-version number will do you). Windows users can install from the version 2.7.8 downloadable available at python.org.
Windows users are the outliers in installing setuptools. Luckily, they have a quick solution to steps 1 and 2 above, provided by Christoph Gohlke, who created and maintains unofficial binary installers for setuptools and pip (see http://www.lfd.uci.edu/~gohlke/pythonlibs/#setuptools and http://www.lfd.uci.edu/~gohlke/pythonlibs/#pip). Just download and run in sequence.
Mac OS X users can also sit out installing setuptools, because setuptools and easy_install (a script used to install pip) are installed by default on their system.
Ubuntu and Debian users can open a terminal and type:
# sudo apt-get install python-setuptools
And Fedora, Red Hat, CentOS and other yum users can type:
# sudo yum install python-setuptools
Mac users are an outlier here. They can just open a terminal and type:
# easy_install pip
Us Linux types will enter:
# sudo apt-get install python-pip
… or …
# sudo yum install python-pip
Note that the ‘universe’ software source will need to be enabled on Ubuntu/Debian clients for this command to work as expected.
Installing the CLI Clients
Now that pip is installed, this is simple. Here’s the full list of clients:
- ceilometer – Telemetry API
- cinder – Block Storage API and extensions
- glance – Image Service API
- heat – Orchestration API
- keystone – Identity service API and extensions
- neutron – Networking API
- nova – Compute API and extensions
- sahara – Database Processing API
- swift – Object Storage API
- trove – Database Service API
Your job is to install them in sequence by typing commands of the form:
# sudo pip install python-(project)client
… again and again and again. Here’s a concrete example:
# sudo pip install python-ceilometerclient
Order doesn’t matter. The clients will install and (in some cases) install other clients (e.g., Keystone) to resolve their own dependencies.
Getting your OpenStack RC File
The CLI clients look for environment variables to point themselves towards your cloud’s REST API entry points, and to derive other info (like your username) needed to authenticate transactions. You could create the needed environment variables manually, but it’s much easier to download a complete OpenStack RC script containing all the necessary info (except your password).
You can obtain your RC file through your Mirantis OpenStack Developer (or other edition) Horizon console. Just go to Project -> Compute -> Access & Security, click the API Access tab, and click the button labeled Download OpenStack RC File. Save your RC file in your home directory, or wherever you consider ‘toplevel’ for your CLI work, and run it by entering:
# source openrc.sh
… which opens and runs the file in the context of the current environment. Enter your password when requested — this is the same password you use to log into Horizon, and can be found (in Developer Edition) in your Dashboard’s Credentials popup (Mirantis OpenStack Express Team Edition users will find it on the main Dashboard page in the area describing your cluster.
You should now be able to issue OpenStack CLI commands. A good first test is to try:
# nova image-list
… which returns a list of boot images available to you. Note the ID of the Ubuntu 14.04 LTS dev image. Now let’s try:
# neutron net-list
… which shows available networks. Note the ID of your private network. And finally, let’s use the nova boot command to start a VM, swapping in the IDs for the image and private network you derived from the values returned by the two prior commands:
# nova boot [vm-name] --flavor m1.small --image (image ID) --security-groups default --nic net-id=(private net ID)
In a couple of seconds, your new VM should spawn. Check to see if it’s active, using:
# nova list
… which shows all your active VMs.
In upcoming tutorials, we’ll start building on OpenStack’s CLIs, REST interfaces, orchestration tools and Application Catalog and start assembling more powerful automation.
- Mirantis OpenStack Express Documentation
- Mirantis OpenStack Express Operations Guide
- OpenStack Command-Line Reference
- Install the OpenStack Command-Line Clients
Check out Express for yourself at https://express.mirantis.com.