Monday, January 4, 2016

Controlling DevStack with OpenStackClient (CLI), enabling Zaqar plugin


In the previous post I described how to install and run DevStack and also how to access OpenStack Dashboard to control it.

In this post I will tell you how to use OpenStackClient which is actually command-line interface (CLI) to all OpenStack services and can be considered as an alternative to the OpenStack Dashboard (GUI). Also I will provide few important details on how it works.

CLI can do everything OpenStack Dashboard can and even more!
For example, CLI commands can be used in automation scripts. You are already familiar with one of them: script uses OpenStack CLI commands to tune all OpenStack services it installs.

Also many of OpenStack services can be controlled by CLI only - they still don't have their respective panels in OpenStack Dashboard now.
One of these services is Zaqar aka Messaging and Notification service.
Let's enable this non-default service in DevStack and perform some actions on it by using CLI.


Step 1. Running DevStack with Zaqar service enabled

Add this line to the end of local.conf file in the DevStack local repository, so Zaqar service will be enabled:

enable_plugin zaqar

Now, if you execute script to run DevStack as usual, the script will additionally clone Zaqar project from Github repository to /opt/stack/zaqar/, globally install it via pip, create configuration files in /etc/zaqar/, install MongoDB linux service, create new service user for Zaqar in OpenStack Identity service (Keystone), etc.

Inside the DevStack local repository execute:

stack@devstack:~/Sync/Repos/devstack$ ./

Step 2. Basic usage of OpenStackClient

When DevStack is running, you can use OpenStackClient which is command-line interface to all OpenStack services. This program comes as part of DevStack. When OpenStackClient is installed on linux system, it's available via openstack command in terminal.

The basic usage is:

stack@devstack:~$ openstack <subcommand>

To list all available subcommands, execute:

stack@devstack:~$ openstack help

Most of subcommands are usually related to corresponding OpenStack services.
For example, subcommands like volume list or volume create are related to OpenStack Block Storage service.
Just like in OpenStack Dashboard, you need to use valid credentials of one of the users of your DevStack cloud (project name, user name and password) to control services and the endpoint URL of Keystone service (it is usually
Without provided credentials service-related openstack subcommands will tell you that credentials parameters are missing.

Let's try to list all Keystone users of our cloud using OpenStackClient.
To do this, execute the following command, it will ask you to enter your admin password you have set in local.conf in the previous guide:

stack@devstack:~$ openstack user list --os-project-name=admin --os-auth-url= --os-username=admin

If the command was successful, the output will be something like this:

stack@devstack:~$ openstack user list --os-project-name=admin --os-auth-url= --os-username=admin
| ID                               | Name     |
| 1be69b6b7c234f92aea7a09875ef2bf8 | glance   |
| 2bcbed87f5a240ccafd1f2ba72f05435 | nova     |
| 6d27a42b39d84ed2886d9b03b5349247 | zaqar    |
| 704a485a6a0a4e32a7c903c328ef5c1e | alt_demo |
| 76343d9c6f0d4a48947704cd44629d3a | cinder   |
| 922757433d71497c84ea0e98aa29e0f3 | demo     |
| e18ca2ecdd3a408b84b8d606f5a60113 | admin    |

user list is a subcommand related to Keystone service. It lists all users of DevStack cloud. The same user list can be also observed via OpenStack Dashboard in Identity panel.

Step 3. Understanding OpenStackClient

When you execute any service-related subcommand, this happens:
  1. OpenStackClient authenticates to Keystone Service via HTTP using provided credentials (project name, user name and password) and Keystone endpoint URL(--os-auth-url parameter) to get the all endpoint URLs of available services for the provided user and authentication token.
  2. OpenStackClient executes functionality of special client program related to the subcommand and uses gathered information from Keystone. For example, in case of queue create subcommand, which is related to Zaqar service, the python-zaqarclient program is executed. Note that Compute, Identity, Image, Storage, Volume and Network services have it's clients embedded directly in OpenStackClient. More about this here.
  3. The client program connects via HTTP to the related service endpoint URL, provides authentication token and tells the service what to do.
  4. The service checks authentication token by asking the same Keystone Service. If token is valid, it performs actions which the client program asked for.
You can manually list all available services and their endpoints for the selected user by using catalog list subcommand which is related to Keystone service. Example for demo user:

stack@devstack:~$ openstack catalog list --os-project-name=demo --os-auth-url= --os-username=demo

By default OpenStackClient doesn't have any queue subcommands like queue createqueue list which are related to Zaqar.
When you enabled Zaqar service in local.conf and executed, the client program for Zaqar called python-zaqarclient was installed in the system by pip install with the special entry points specified in client's setup.cfg.
After installation the entry points can be found by OpenStackClient and accessible via subcommands. More about this here.

Step 4. A lazy way to provide credentials for OpenStackClient

Providing credentials as parameters each time you want to execute one of the openstack subcommands is surely inconvenient.
Instead you can set the special environment variables for your linux user and OpenStackClient command will use them as credentials.
To do this simply modify the hidden .bashrc file inside your home directory and add the following lines to the end of it:

export OS_AUTH_URL=
export OS_USERNAME=admin
export OS_PASSWORD=<password you have set in local.conf in the previous guide>
export OS_PROJECT_NAME=admin

And then in the terminal execute this command to export all environment variables from this file:

stack@devstack:~$ source ~/.bashrc

You have set the environment variables and from now on you'll be able to list catalog like this:

stack@devstack:~$ openstack catalog list

As you see, no need to provide credentials as parameters.
This will work even after you will restart the machine, because environment variables are exported automatically from .bashrc on each login of the linux user to which .bashrc belongs.

Step 5. Managing Zaqar service via OpenStackClient

The queue * and messaging * openstack subcommands are related to Zaqar service. This might change in the future, so don't worry if the following commands will not work.

Let's try to create some message queues in Zaqar service:

stack@devstack:~$ openstack queue create Lovely
stack@devstack:~$ openstack queue create Ohmy

After this, let's try to list all our queues using this command:

stack@devstack:~$ openstack queue list

You'll see this output:

stack@devstack:~$ openstack queue list
| Name   |
| Lovely |
| Ohmy   |

Note: if you will try to list queues using credentials with different project name, you will not see these queues. You can think of projects as separate namespaces where resources exist.

Step 6. Turn off DevStack cloud

After playing with services, you might want to turn off your DevStack cloud with all of it's services.

Inside the DevStack local repository execute:

stack@devstack:~/Sync/Repos/devstack$ ./

In the next guide...

I will tell you how to conveniently work with the code of OpenStack services while your python IDE is on development machine and the code need to be executed on another machine, real or virtual. For this purpose we'll use free and open source decentralized file syncronization service called Syncthing. This service is not part of OpenStack.

No comments:

Post a Comment