Uing the Tiktalik command line utility

Summary

The Tiktalik Command Line Interface is a command line utility that enables the user to control his private cloud using commands issued in a shell environment.

The purpose of this tutorial is to familiarize you with the basic functions of Tiktalik CLI.

Installation

The CLI is installed using the pip Python package manager, and requires Python 2.7+ to run. Executing:

$ pip install tiktalik-cli

installs the tiktalik command in your system.

Configuring authorization

To use the Tiktalik CLI you need to obtain an API Key. This is easily accomplished using the Tiktalik admin panel. When generating a new key, giving it a descriptive name is a good idea. This allows you to easily localize the key you want to deactivate later, if such need arises.

Having different API Keys for different purposes is good security practice. We recommend using one key for one purpose only, eg. have a different key on your laptop, another one on an admin server etc. This allows you to revoke access for a specific key if such action is necessary.

To initialize authorization information run the tiktalik init-auth command.

The example below assumes that:

• your API Key is vFgUVfGURErNyYvSRVfGuvfWHFgSNaGNfl
• your API Secret key is bm90IGEgcmVhbCBrZXksIGJ1dCB5b3Ugd2luIDUgaW50ZXJuZXQgcG9pbnRzIGZvciBiZWluZyBjdXJpb3VzIQ==

$ tiktalik init-auth vFgUVfGURErNyYvSRVfGuvfWHFgSNaGNfl bm90IGEgcmVhbCBrZXksIGJ1dCB5b3Ugd2luIDUgaW50ZXJuZXQgcG9pbnRzIGZvciBiZWluZyBjdXJpb3VzIQ==
This command saves the credentials to a file ($HOME/.tiktalik/auth). The CLI is ready to use.

Basic usage

The basic usage pattern is:

tiktalik <command> [arguments]

To get a list of available commands run tiktalik without any arguments (short list) or tiktalik --help (long list).

To get help on a specific command run:

tiktalik <command> --help

Creating an instance

To create an instance you need to provide the following information:

• hostname: instance hostname
• instance size: "cpuhog", or size in units: 0.25, 0.5, 1 to 15
• Image UUID: UUID of the image to use. This can be a system-provided image or one of your backups
• list of networks this instance should have access to

Let's walk through the process of creating the instance. The first step is to list available images in order to obtain an Image UUID.

$ tiktalik list-images
e18aee6c-9548-457e-9c20-7103d454969a "Centos 6.4 64-bit", type=image
90783010-5e1b-4948-9b33-bfb4a4502617 "Debian 6.0.7 64-bit", type=image
4a2b3e72-47f1-4e88-b482-1834478ade28 "Ubuntu 12.04.3 LTS 64-bit", type=image

We decide on an Ubuntu install, so the image UUID is 4a2b3e72-47f1-4e88-b482-1834478ade28

Let's view available networks next:

$ tiktalik list-networks
privnet1 a4682bf4-2430-4a36-90e6-7a978bc07b09 10.80.28.0/24 private, owned by user
pub2 e92e60c2-2993-4a0c-b635-c5e2b2462c7a 37.233.98.0/24 public, owned by system

We want the instance to be available on the Internet, and also have access to our private network. Having that in mind, we decide on privnet1 and pub2

The last things we need to decide on are: the instance size and its hostname. We choose the size of 1, the hostname will be web1

Now that we have all the information we need, let's create the instance.

$ tiktalik create-instance 4a2b3e72-47f1-4e88-b482-1834478ade28 1 web1 -n pub2 -n privnet1
Creating new instance with these parameters:
Image UUID: 4a2b3e72-47f1-4e88-b482-1834478ade28
Size: 1
Hostname: web1
Networks: pub2, privnet1
Is this OK?
Please answer 'yes' or 'no' > yes
Instance web1 is now being installed.

Your new instance will be ready to use once it has been installed (which is pretty quick, we promise!).

Note that it is possible to skip the confirmation prompt by using the -b switch.

Viewing instance information

Let's see a list of our instances:

$ tiktalik list
web1  7f798ac0-dfad-4a8e-bed0-f3073b249862 Running

We can see that the new instance is up and running. You can view more details either by running tiktalik list with additional arguments, or using tiktalik info to get detailed information on a specific instance:

$ tiktalik info -n web1
web1 (7f798ac0-dfad-4a8e-bed0-f3073b249862) - Running
  network interfaces:
      eth0 addr: 37.233.98.49 mac: e6:5e:6e:35:dd:f5 network: pub2      
      eth1 addr: 10.80.28.25 mac: e6:ba:f0:77:fb:a3 network: privnet1
  running image Ubuntu 12.04.3 LTS 64-bit (4a2b3e72-47f1-4e88-b482-1834478ade28)
  recent operations:
      Create_Install: web1 started at 2013-04-08 18:37:03 +0200 (UTC) ended at 2013-04-08 18:38:02 +0200 (UTC)
  cost per hour: 0.08364 PLN/h

Controlling instances

Stopping and starting instances is simple:

$ tiktalik stop -n web1
Instance web1 (7f798ac0-dfad-4a8e-bed0-f3073b249862) is now being stopped

Note that we referred to the instance by its name. In case there is more than one instance with the specified hostname an error will be reported. You need to resolve this ambiguity by specifing the instance by UUID.

$ tiktalik start -u 7f798ac0-dfad-4a8e-bed0-f3073b249862
Instance web1 (7f798ac0-dfad-4a8e-bed0-f3073b249862) is now being started

That's it!

If you have any suggestions concerning the Tiktalik CLI, don't hesitate to [contact us]({{ url_for('contact')}}.

For source code and more information, see the project page.

---