Navigation :

Quick Start

Join the Openstack-Users email list. This is where announcements of potentially disruptive changes will go, and a place where you can ask questions and suggest improvements to the system.

Getting an Account

You can register for an OpenStack account at https://cloud-registration.csail.mit.edu (CSAIL Login required). After you have an existing account this same link can be used to reset your password if you forget it.

On registration you will be given a personal ‘usersandbox’ project with a small quota to play around with. If your group has an existing OpenStack project (and it allows self registration which is the default) then you can also elect to join that project during the registaration process.

Users can belong to multiple projects even though our web wrapper only allows one. If you need to be in multiple groups email help@csail.mit.edu, for existing groups have a current member or sponsoring PI make the request for you so we know it’s authorized.

If your group doesn’t have an OpenStack project yet email help@csail.mit.edu with the name you’d like, the name of a CSAIL PI (probably your supervisor) , and ideally some description of how you plan to use OpenStack so we can make a reasonable guess at an initial quota. All work in OpenStack is done in a “project” (or tenant depending on which documents you’re reading but they are the same thing), quotas are assigned by group, operating system images are shared within groups, etc.

When a new user account is created through the web interface all existing members get an email notifying them. This postgating is the only insurance against random people joining your project (within the lab, not the whole internet), so do keep an eye on it.

While most projects are comfortable with this rather loose gating, since it allows self sign up. Upon request we can create projects that do not allow self sign up, this is more secure but does mean all new users will need be manually created by TIG.

Launching a VM

Do not skip this section. The instructions on launching Ephemeral and Persistent instances are a prerequisite for OpenStack use.

By default all VMs are ephemeral and their state is deleted on shutdown please read this documentation to find out how to snapshot your instances and how to create and attach persistent storage if you need to preserve local state.

Walk through launching an Ephemeral VM – last update 14 June 2018
Walk through launching a Persistent VM – in progress 14 June 2018

The above walk throughs are simplistic by design. There is a detailed upstream user guide at https://docs.openstack.org/mitaka/user-guide/ this is much more current and includes advanced use cases like programatically creating and resources with the python API.

Logging into your instance

Once you’ve booted an instance as described above and the appropriate Security Group Rules have been applied, it can be accessed remotely via SSH. With the Ubuntu and CSAIL Ubuntu images we provide, you can log into the instance as the ‘ubuntu’ user, provided that you’ve associated an SSH key with the instance (see OpenStack SSH Keys).

Logging in as the ‘ubuntu’ user is the only way to log into instances newly booted from the standard Ubuntu cloud image. You can access CSAIL Ubuntu images either via your SSH key and the ‘ubuntu’ user, or with your CSAIL Kerberos account. More information on the base images provided by TIG is available at Ubuntu and CSAIL Ubuntu images.

Lastly, If you happen to have launched your instance using the Heat Orchestration service, you may need to log into your instance as the ‘ec2_user’ rather than the ‘ubuntu’ user.

Got Root?

For privileged access to Ubuntu cloud images, and the CSAIL images based on them, you must provide an ssh public key when you boot your instances and connect via ssh as the user “ubuntu”. This user is configured with passwordless sudo access so you can run commands with root privilege by prefixing them with ‘sudo’ for example:

ubuntu@my-vm:~$ sudo apt-get install mit-scheme

Details of how to setup and use public keys with OpenStack are on the OpenStack SSH Keys page.

Basic tools

The easiest way to interact with OpenStack is through the web dashboard at https://horizon.csail.mit.edu this provides most common features, though does not expose all functionality. To get advanced functions it is sometimes necessary to use the command line or write your own code to drive the API.

Command line access

Certain advanced features, such as affinity and anti-affinity groups, to keep instances together for speed or apart for fault tolerance, are only available through the CLI or direct API calls.

The public login server login.csail.mit.edu is running CSAIL/Ubuntu 18.04 is available with all the latest OpenStack related command line tools installed.

If you plan on regularly using the CLI, it is best to install them on a group server or your workstation.

To install the command line tools first install pip
- On Mac: sudo easy_install pip
- On Ubuntu or Debian: sudo apt-get install python-pip
Then: sudo pip install python-openstackclient.

Wherever you run you’ll need to create a configuration file ~/.config/openstack/clouds.yaml with the following content replacing <PROJECT> with your project name and <USER> with your CSAIL username. You can add multiple stanzas for different projects and or users so long as the have unique names see upstream cli configuration docs for full details:

  clouds:
    default:
      auth:
        project_name: <PROJECT>
        username: <USER>@csail.mit.edu
        auth_url: https://keystone.csail.mit.edu:35358/
        user_domain_name: Default
        project_domain_name: Default
      region_name: CSAIL_Stata
      identity_api_version: 3

You can access this configuration either by specifying --os-cloud default on the command line or exporting the environmentvariable OS_CLOUD=default

openstack help [subcommand] is very useful, full CLI docs at https://docs.openstack.org/python-openstackclient/latest/.

It is also possible to use AWS EC2 compatible tools like the euca2ools or awscli package to interact with OpenStack. This covers most common actions but only the intersection of OpenStack and EC2 features. This is convenient if you are using both our OpenStack and EC2, but if you are only using OpenStack the openstack CLI is the the most feature complete tool.

Using templated orchestration

TIG has moved to using Terraform for our cloud orchestration which supports both openstack and all major public cloud providers. Terraform offers more deployment options and than cloud specific tool like OpenStack’s Heat Orchestration or AWS’s “Cloud Formation” tools.

We do however provide Heat both for historic reasons and because some higher level cloud utilites we may provide in the future depend on it.

API access

Complete API reference is available at http://docs.openstack.org/

Your favorite programming language probably has a library or module for talking to OpenStack. GOlang has Gopher Cloud. Python users should look at OpenStack python bindings or Boto which uses the Amazon EC2 compatibility API to to talk to OpenStack (and also of course speaks to AWS). Ruby hackers can look at the Fog gem which supports a variety of cloud APIs.