This chapter provides the bare-bones instructions for getting up and running with the StratusLab command line client. The client provides a set of commands for interacting with all of the StratusLab services. Getting started involves just four steps:
- Verifying the prerequisites,
- Installation of the client,
- Configuring the client, and
- Testing the installation.
Each is covered in a section below. More detailed information on installing and configuring the client are in subsequent chapters; similarly later chapters also cover the utilization of the StratusLab services more throughly.
Verifying the Prerequisities¶
Before starting, you must verify that the prerequisites for the StratusLab command line are satisfied:
- Python 2 (2.6+), virtualenv and pip are installed.
- Java 1.6 or later is installed.
- An SSH client is installed with an SSH key pair.
- You have an active StratusLab account and connection parameters.
For the first three points, more information can be found in the following chapter and in the appendix.
For the StratusLab account, you must contact the administrator of your cloud infrastructure. The following parts of this chapter presume that you have a username/password pair for credentials and are using the StratusLab reference infrastructure at LAL.
First create a virtual environment to hold the StratusLab client and its dependencies.
$ virtualenv $HOME/env/SL New python executable in /home/sluser/env/SL/bin/python Installing setuptools............done. Installing pip...............done.
You may want to choose a different name or location for your virtual environment. Now you will need to activate that environment.
$ source $HOME/env/SL/bin/activate (SL)$
The prompt should change to include the name of the virtual environment.
Now use pip to install the StratusLab client:
(SL)$ pip install stratuslab-client Downloading/unpacking stratuslab-client Downloading stratuslab-client-13.05.0.RC1.tar.gz (1.2MB): 1.2MB downloaded ... Successfully installed stratuslab-client dirq ... Cleaning up...
You can verify that the client is installed and accessible with by searching for one of the StratusLab commands:
(SL)$ which stratus-copy-config ~/env/SL/bin/stratus-copy-config
All of the StratusLab commands begin with “`stratus-”. On systems that support it, you can use tab completion to see all of the available commands.
Now that the StratusLab client is installed, it needs to be configured. You will need to have your credentials and the cloud service endpoints available.
Copy the reference configuration file into place and verify it is present:
(SL)$ stratus-copy-config (SL)$ ls $HOME/.stratuslab/ stratuslab-user.cfg
This configuration file contains descriptions of all of the parameters that can be set. There are only three or four that must be set.
Set the service endpoints for the cloud entry point and the storage (pdisk):
endpoint = cloud.lal.stratuslab.eu pdisk_endpoint = pdisk.lal.stratuslab.eu
substituting the values for your cloud infrastructure. (These are the values for the StratusLab reference cloud infrastructure at LAL.) Also set the values for your username and password:
username = your.username password = your.password
again substituting your values for these parameters.
You can now see if you have any running machines on the cloud to test if the client is correctly installed:
(SL)$ stratus-describe-instance id state vcpu memory cpu% host/ip name (SL)$
This should return an empty list of machines. If it returns any errors, then you’ll need to correct whatever went wrong in the installation. See the more detailed documentation.
Testing the Installation¶
To test the installation more throughly and to give you an idea how to use the cloud, we will start a virtual machine and create a persistent disk.
Normally, you would browse the StratusLab Marketplace to find an image that is useful for you. You then use the image identifier to start a copy of that image.
We use the image identifier
BN1EEkPiBx87_uLj2-sdybSI-Xb for a
ttylinux image. This is a very minimal linux distribution usually
intended as an embedded operating system. It is extremely small and
boots quickly, making it ideal for tests.
Launch a virtual machine instance using this image:
(SL)$ stratus-run-instance BN1EEkPiBx87_uLj2-sdybSI-Xb ::::::::::::::::::::::::: :: Starting machine(s) :: ::::::::::::::::::::::::: :: Starting 1 machine :: Machine 1 (vm ID: 4710) Public ip: 22.214.171.124 :: Done!
This gives you the VM identifier (4710) and the IP address from where the machine can be accessed. Afterwards, check the status of the machine.
(SL)$ stratus-describe-instance id state vcpu memory cpu% host/ip name 4710 Running 1 1572864 8 vm-152.lal.stratuslab.eu one-4710
You may have to wait a little while until it is in a running state. Then
verify that the machine is accessible with
ping. Once it is visible
try to log into the machine:
(SL)$ stratus-connect-instance 4710 ... Enter passphrase for key '/home/sluser/.ssh/id_rsa': # hostname ttylinux_host # exit
Note that the password is the password for your SSH key. You can also log in directly using ssh:
(SL)$ ssh email@example.com ... Enter passphrase for key '/home/sluser/.ssh/id_rsa': #
Note that your must use the username defined by the person that created the image. This is almost always “root”. In both these cases, information about the SSH host key have been suppressed for clarity.
The machine can then be killed (stopped) with the command:
(SL)$ stratus-kill-instance 4710 (SL)$ (SL)$ stratus-describe-instance 4710 id state vcpu memory cpu% host/ip name 4710 Done 1 1572864 1 vm-152.lal.stratuslab.eu one-4710
The resources allocated to the machine are only released when the
machine is killed. If you shutdown the machine while inside the
operating system with
shutdown, you must still use the
StratusLab command to kill the machine to release the resources.
The lifecycle for a persistent disk (or volume) is also rather simple.
To create a disk:
(SL)$ stratus-create-volume --size 1 --tag=mydisk DISK 08f59022-463a-4662-8136-c0cee5517f17
This creates a new disk with the given tag and a size of 1 GiB. The UUID is the identifier for the disk.
The disks can be listed with the command:
(SL)$ stratus-describe-volumes :: DISK 08f59022-463a-4662-8136-c0cee5517f17 count: 0 owner: cal tag: mydisk size: 1
Normally at this point, it would be attached to a virtual machine instance, formatted, and then used to store data. We will leave that for the detailed chapters below.
When the disk is no longer needed, it can be deleted with the command:
(SL)$ stratus-delete-volume 08f59022-463a-4662-8136-c0cee5517f17 DELETED 08f59022-463a-4662-8136-c0cee5517f17
That is the complete lifecycle for a persistent disk.
This chapter has shown you the procedure for installing the client and then, the basic lifecycles for starting machines and for creating persistent disks. Hopefully, you are intrigued enough to read following chapters that provide more detail on the StratusLab services and their functionality.