Tutorials/CloudSim/setup

CloudSim setup and installation ==

This tutorial describes how to:


 * Install CloudSim
 * Start/stop CloudSim on the cloud

Introduction ==

CloudSim is a web app that runs in a virtual machine on the Amazon Web Services (AWS) cloud. It allows 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 needed, simulation and robotics software requirements, and available machines on the cloud. Each CloudSim configuration maps to a constellation, which are collections of multiple virtual machines running together.

Prerequisites == 1. You will need a valid AWS account, and its associated key (and secret key). See  AWS account and keys: How to get an Amazon AWS account and set it up for CloudSim. The key and secret key pair are tokens that allow CloudSim to access AWS on behalf of the AWS user.

CloudSim does not use the email address and passwords associated with the AWS account.

2. For the purpose of authentication and loging in CloudSim, every CloudSim user must have a valid gmail (or Google Apps) accounts. So all users (including users with administrative privileges) must have a valid Google account to use CloudSim. You can get Google accounts for free.

Installation ==

This section will show you how to install CloudSim on your Ubuntu machine and run a script that creates a CloudSim instance on AWS. This instance is deployed on a web server 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 for Apache, the Redis no-sequel key/value store and the python bindings). Please refer to the CloudSim development tutorial for more information.

1. Install CloudSim dependencies. This install is sufficient to complete all tutorials except the Development tutorial.

sudo apt-get install -y redis-server python-pip python-redis python-novaclient # CloudSim is compatible with boto 2.8.0 and up, so you can't use the default package in Ubuntu 12.04 sudo pip install --upgrade boto sudo apt-get install -y expect sudo pip install softlayer

1. Download the latest version of CloudSim, called `cloudsim-2.0.x.tar.bz2`, from http://gazebosim.org/assets/distributions/.

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

1. Unpack the files to your local drive

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

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

CloudSim authentication (Google OpenID or Basic authentication?) == CloudSim is available in 2 modes: Basic Authentication and Google OpenID. Google OpenID requires users to use their Google mail accounts. Users don't need to provide password, because CloudSim redirects new users to a Google service. This is the recommended way.

With Basic authentication, users need to provide usernames (not necessarily email addresses) and passwords. Unfortunately the passwords are sent in plain text, so this method is not secure. However it is useful for test purposes.

How to start CloudSim (Google OpenID authentication) ==

We are now ready to create a new AWS machine that runs CloudSim. Simply provide AWS credentials and a Google email account (it is not tied to your AWS email address; you will use this account to log in the system').

For this section, please have your AWS key and secret key at hand. See  AWS account and keys: How to get an Amazon AWS account and set it up for CloudSim.

You will also need an ec2 region. Regions are physical locations in the world (they are further broken into Availability zones). For now, use: us-east-1 (N Virginia), eu-west-1 (Ireland) or us-west-2 (Oregon).

Once the files are unpacked, run the script `create_cloudsim.py`, which has has the following usage: # replace these values with your own username, keys and region (see below) ./cloudsim-X.Y.Z/bin/create_cloudsim.py YOUR_EMAIL_ACCOUNT_TO_LOG_IN_TO_CLOUDSIM key secret_key ec2_availability_zone


 * Once CloudSim is started, you will be able to log in with the username you provided. It must be a Google email (but it does not have to be the email associated with the AWS account). This CloudSim user will have admin privileges.
 * The key and secret key are the credentials for the AWS account under which the CloudSim machine as well as any machine CloudSim provisions will be run.
 * When running constellation using cg1.4xlarge machines, you may have to specify an Availability Zone. Availability Zones are mapped independently for each account. Therefore, they can vary between accounts. For example, the Availability Zone us-east-1a for account A is not necessarily the same as us-east-1a for account B. There are actually four availability zones for us-east region. You must select your actual region to run a constellation of more than one machine. You can do this once you have signed in to CloudSim. If you are unable to run a multi-machine constellation once logged in, try going into Settings and changing the region under Amazon Web Services. Unfortunately, you must determine your region by trial and error.  See   CloudSim administration.  The list of errors (and how to fix them) is covered here:  Troubleshooting CloudSim.

Here's an example:

./cloudsim-2.0.0/bin/create_cloudsim.py somebody@gmail.com FAKE_AWS_KEY FAKE_SECRET_KEY us-east-1

As the script runs, you'll see a lot of console output, including this message:


 * 1) Your CloudSim instance has been launched.  #
 * 2) It will take around 5-10 mins to be ready. #
 * 3) Your CloudSim's URL will appear here soon. #
 * 4)                Stay tuned!                 #
 * 1)                Stay tuned!                 #

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

CloudSim ready. Visit http://54.234.106.123

Stop your CloudSim using the AWS console http://aws.amazon.com/console/

In this example, the URL is http://54.234.106.123. Use your browser (preferably Chromium) 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:



CloudSim is installed successfully.

How to start CloudSim (Basic Authentication) ==

To use the Basic Authentication, you can use any username / password combination you want. Simply supply -b to create_cloudsim.py. E.g.:

./cloudsim-2.0.0/bin/create_cloudsim.py -b mypassword myuser FAKE_AWS_KEY FAKE_SECRET_KEY us-east-1

Then you would login to your CloudSim console with `myuser` and `mypassword`.

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 or if you want to continue with the next CloudSim tutorials.

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.

Next ====

Next: Cloudsim administration: How to manage users, and set new AWS credentials