Tutorials/CloudSim/1.1/setup

CloudSim ==

CloudSim is a web app that runs in a virtual machine on the AWS (Amazon Web Services) cloud. It allows its users to launch, terminate and monitor virtual machines in the (AWS) cloud running ROS, Gazebo and the DRC simulator. Different configurations can be launched, depending on the computing power, simulation and robotics software requirements, and available machines on the cloud. Each CloudSim configuration maps to a constellation that can contain multiple virtual machines running together.

Prerequisites == CloudSim runs on the Amazon cloud infrastructure. You should signup for an account by visiting your amazon console



Once the process is done, log in to the AWS console.

You should have your AWS key pairs credentials ready before going through this tutorial.

You can obtain your AWS keys from the AWS console via the credential menu:



You must press the "show" button to see the secret key from your browser:



Also, CloudSim only accepts users with valid gmail (or Google Apps) accounts. So all users (including users with administrative priviledges) must have a valid google account to use the system. You can get Google accounts for free.

Introduction ==

This tutorial will show you how to install CloudSim on your Ubuntu machine and run a script that creates a CloudSim web app on AWS. This web app is deployed on a webserver running on a micro instance (using your AWS account credentials).

CloudSim is written in python and uses the boto library to access AWS. Follow these instructions to install the minimum packages required to launch a CloudSim instance. For CloudSim development and installation on your local machine, you will need more packages ( like the apache web server, the OpenID authentication plugin, the redis no key/value store and the redis python bindings). Please refer to the user guide for more information.

Installation ==

If you have already installed Gazebo or DRCSim, you may skip to step 4.

1. Configure your Ubuntu repositories to allow "restricted," "universe," and "multiverse." You can follow the Ubuntu guide for instructions on doing this.

1. Setup your computer to accept software from packages.osrfoundation.org.

sudo sh -c 'echo "deb http://packages.ros.org/ros/ubuntu precise main" > /etc/apt/sources.list.d/ros-latest.list' sudo sh -c 'echo "deb http://packages.osrfoundation.org/gazebo/ubuntu precise main" > /etc/apt/sources.list.d/gazebo-latest.list'

1. Retrieve and install the keys for the ROS and DRC repositories.

wget http://packages.ros.org/ros.key -O - | sudo apt-key add - wget http://packages.osrfoundation.org/gazebo.key -O - | sudo apt-key add -

1. Update apt-get and install CloudSim. This install is sufficient to complete all tutorials but the Development tutorial.

sudo apt-get update sudo apt-get install cloud-utils drcsim python zip unzip openvpn openssh-client ros-fuerte-visualization

1. Check your installation. Running the command below should respond with a usage message.

cloud-publish-image

1. Download the latest version of CloudSim, called `cloudsim-X.Y.Z.tar.bz2`, from http://gazebosim.org/assets/distributions/. For this tutorial, we'll assume that you're using version 1.1.1:

# Change the version number as appropriate! wget http://gazebosim.org/assets/distributions/cloudsim-1.1.1.tar.bz2

1. Unpack the files to your local drive

# Change the version number as appropriate! tar xf cloudsim-1.1.1.tar.bz2

This unpacks the CloudSim source code on your local machine. This code allows you to run the web app on your local machine, or create an AWS machine with the app inside. For the purpose of this tutorial, we will launch the CloudSim web app into an AWS instance.

Running the script ==

Once the files are unpacked, run the script `create_cloudsim.py`, which has has the following usage:

usage: create_cloudsim.py username key secret_key

The username is the Google email of the first admin user of the CloudSim instance. The key and secret key are the credentials for the AWS account under which the CloudSim machine as well as the simulation machines will be run.

Here's an example:

./cloudsim-1.1.1/bin/create_cloudsim.py somebody@gmail.com FAKEOFAKEOFAKEOFAKEO FAkexNOItfake6Hxs1fake5JKP+B9fakeUfake7

Once the script starts, you should see a list of events printed to the console, e.g.:

./cloudsim-1.1.1/inside/cgi-bin ./cloudsim-1.1.1/cloudsimd/launchers ./cloudsim-1.1.1/cloudsimd/launchers/cloudsim.py Warning: redis not installed. cloudsim log> cloudsim launch constellation 'fc3856ee-3ffd-11e2-bf8b-902b343559be' event: cloudsim data:{'state': 'reserve', 'machine_name': 'cloudsim_fc3856ee-3ffd-11e2-bf8b-902b343559be', 'type:': 'launch'}

event: cloudsim data:{'reservation_id': u'r-1eff1e66', 'state': 'reserve', 'machine_name': 'cloudsim_fc3856ee-3ffd-11e2-bf8b-902b343559be', 'type': 'launch'}

...

The whole process lasts approximately 3.5 minutes. Once its finished, the url of the new CloudSim machine web app is written to the terminal, e.g.:

cloudsimd start/running, process 9277 cloudsim_monitord start/running, process 9280

Warning: redis not installed. cloudsim log> setup complete Warning: redis not installed. cloudsim log> ssh -i /tmp/tmpqm4upocloudsim/cloudsim_fc3856ee-3ffd-11e2-bf8b-902b343559be/key-cloudsim_fc3856ee-3ffd-11e2-bf8b-902b343559be.pem ubuntu@ec2-184-73-113-29.compute-1.amazonaws.com

Warning: redis not installed. cloudsim log> http://ec2-184-73-113-29.compute-1.amazonaws.com

In this example, the URL is http://ec2-184-73-113-29.compute-1.amazonaws.com. Use your browser (preferably Chrome) to visit the URL and login with the Google user account that you provided on the command line to the script. You'll see a landing page:



Click on the `Console` link to get to the console. Because this account has administrative privileges, it has an enhanced interface:



CloudSim administrative tasks ==

Add users ===

CloudSim organizes users by their internet domains (i.e osrfoundation.org). Users can therefore start/stop and monitor constellations of every users from the same domain.

Users with administrative privileges can perform the following additional tasks: add / remove users and change the AWS credentials.



To Add a user, type in a valid Google email address in the text box, select the type of user from the drop down menu (user or admin), and press the "Add user" button.

To remove a user, press the "X" button next to the user name.

You may need to reload the page to see the effect of user additions and removals.

Warning: Do not remove the last remaining administrative user, or you'll lose access to this CloudSim instance!

Override the AWS credentials === This feature allows users with administrative privileges to set new AWS credentials. By default, the AWS credentials used to launch CloudSim will be used by CloudSim to launch other machines.

Just type in the new credentials and press the "override" button. The will check the credentials against AWS before accepting new ones.



Note: Overriding credentials affects all constellations operations. Any new constellation launches will be performed using the new credentials, and billed to the corresponding AWS user. Therefore, this operation should only be performed when no constellation is running (because you may not be able to control existing machines with the new credentials). Also, overriding the credentials has no effect on the CloudSim machine itself, and it continue running under its current account.

SSH access to the CloudSim machine ===

Users with administrative privileges can connect to the CloudSim instance via ssh. To do so, they need to download the ssh key by following the "SSH key download" link at the bottom left of the screen. This downloads a zip file that contains the ssh key (key-xxx.pem) and a script to connect to the machine (ssh.sh).



This example unzips a downloaded key file and sources the ssh.sh command to log into the CloudSim instance: unzip ~/Downloads/cloudsim_ssh.zip . cloudsim_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/ssh.sh

Other administrative privileges ===

Users with administrative privileges also have an extending list of constellation types they can launch. For example, it is possible to launch another CloudSim instance (using the current AWS credentials, and the current user as administrator).

How to stop CloudSim ===

When you're done using CloudSim you can terminate it via your AWS Console, as you would terminate any other EC2 machine. Note that CloudSim runs on a `micro` instance, which is free for most AWS users. So it's probably OK to leave your CloudSim instance running even when you're not using it.

Warning: Before terminating a CloudSim instance, be sure to use the CloudSim interface to terminate all machines that were launched via CloudSim. Otherwise, you could lose track of launched machines, leading to unexpected EC2 usage charges.

What to do next ===

Please refer to the constellation turorial and the user guide for more information about using and hacking CloudSim.