View source for Quick Start Instructions to Get Rolling with OpenStack

__TOC__

==Request an OpenStack Account==

Once you have [http://giwiki.gi.ucsc.edu/index.php/Requirement_for_users_to_get_GI_VPN_access PRISM/GI VPN access], you can request an OpenStack account.  You will need to send an email to cluster-admin@soe.ucsc.edu asking for access, and let us know which lab you are in, or who your PI is, so we can place you in the right OpenStack group.

==Create a SSH Public/Private Keypair==

To log into an OpenStack VM instance, you will need a SSH public key.  The key is "injected" into the instance upon creation, and only someone with that key (i.e. you) will be able to log in via SSH initially.  If you already have a SSH public and private key that you use elsewhere, you can use that one, and can skip to the next step.  If you don't have a SSH keypair set up yet, then you will need to log into the UNIX compatible machine you will be '''logging in from''' (a Mac/Apple computer will also work), and then run the 'ssh-keygen' command.  If you are behind the VPN, you can first log into mustard, crimson or razzmatazz, which are linux servers.  The command will look something like this:

 $ ssh-keygen -t rsa
 
 Generating public/private rsa key pair.
 Enter file in which to save the key (/public/home/frank/.ssh/id_rsa):
 Created directory '/public/home/frank/.ssh'.
 Enter passphrase (empty for no passphrase): [JUST HIT ENTER]
 Enter same passphrase again: [JUST HIT ENTER]
 Your identification has been saved in /public/home/frank/.ssh/id_rsa.
 Your public key has been saved in /public/home/frank/.ssh/id_rsa.pub.
 The key fingerprint is:
 SHA256:dhJG1A3gcwj7Mz17ommt3NIczMVVgrzp8Tf6F1X4jpI
 The key's randomart image is:
 +---[RSA 2048]----+
 |      ..+o.+ ..o.|
 |       = .. + o..|
 |      . * .. + ..|
 |       o =  *   o|
 |        So+o + o.|
 |       . =+oE ooo|
 |         +o.....o|
 |       .o++o .  .|
 |       .=o.   ...|
 +----[SHA256]-----+

You will then have a new directory, "~/.ssh", and inside that directory you will have a file called "id_rsa.pub".  That is your SSH public key.  You will need this in the next step in order to set up your key in OpenStack.

==Log In To giCloud==

Once you have been notified that your account has been set up and have been given login credentials, connect to the VPN and then go to this link in your favorite web browser, which is the login page:

 http://gicloud.prism

To login, enter your username and password.  Also you will see a "Domain" field, just enter the word "default" for the domain.  Click "Log In".  You will be logged into your group's summary page.

==Upload your SSH Public Key==

After creating your new key in the above "Create a SSH Public/Private Keypair" step, you will need to upload that key into OpenStack.  Once you are logged in, on the left hand navigation menu, click "Project", then in the submenu, select "Compute", and finally select "Key Pairs".  It should take you to the "Key Pairs" window as shown here.

[[File:Keypairs.png|900px]]

Next click the "Import Public Key" button on the top right of the window.  In the resulting window, name your key in the "Key Pair Name" field.  Name it something descriptive like "laptop-key" if the key is on your laptop, or "mustard-key" if you are logged into mustard, etc.

To get your key, open a terminal window and type "cat ~/.ssh/id_rsa.pub" to get your full key, as so:

 $ cat ~/.ssh/id_rsa.pub
 
 ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAyVKNfdBbDIk7Iq8JmL+u3vxAn4M1iaQgMU5tHJhMSAYBZEZRLZAFc+Qovxe5zzs1ixte9lCipLep39q2I4U8XND17nYliZ4HVM4MW4GsMUfKsgX2FI3mB2vAQ9pZSLkAhTg2D+92uALUSSv1cDZhTqo7DuPRX2Upxyd5QbRL6TRFswBjHz2vY/JpaPQm1S1d10mokPpmxehLfwp0mVgmz1Uv/6FflqiZ68DhDN67cs1yQgWYXQ01IHPjzTKRwCuZVkgT99rkoqy6TkAyrvsfzYPZbIA2y+ovOBzq6WCUT9gp5Jx/UE6CxLSmAuGPAJkV5D/twKIe75xc+5jdi3I1cgKw== user@laptop

Copy that whole line, starting with "ssh-rsa" all the way through the very last character, including the "user@laptop" bit (which may be different for you, just be sure to include it in the line copy).

Then back in the OpenStack Key Pair dialogue window, paste in the keypair in the "Public Key" window, then click "Import Key".  The key should then appear in the key list.

==Launch a New Instance==

We are now ready to launch our new VM instance.  On the left navigation menu, select "Project", then in the submenu, select "Compute", and finally select "Instances".  You will see any currently running instances in your group in the resulting screen.

Next you need to click the "Launch Instance" button on the top right.  You will be put into the "Details" tab in the instance creation dialogue.  You need to choose an instance name and enter it into the "Instance Name" field.  It should include your username as a prefix so that others know who owns each instance.  Something like "frank-newtest1" would work well.  You can ignore the "Description" field, "Availability Zone" should be "nova: and "Count" should be "1".

Next click the "Source" tab on the left.  In the "Source" menu, in the "Select Boot Source" field, select "Image" and next to it select "No" for "Create New Volume".  Then in the below list of images, choose your image and click the little "Up Arrow" icon to the right of the image you want to add it.

Next click the "Flavor" tab on the left.  In that menu, choose how much CPU, RAM and disk space you want for your new VM.  Some images have minimum requirements, and as such some of the smaller flavors may not be available.  Select your flavor by clicking the little "Up Arrow" icon on the right of your flavor.

Next click the "Key Pair" tab on the left.  Click the little "Up Arrow" to the right of the Kep Pair you created in the previous step where you create a Key Pair.

Ignore the rest of the options on the left, you have configured all you need to launch the instance.  Click the blue "Launch Instance" button on the bottom right of your window, as seen below:

[[File:Launch.png|850px]]

You will be taken back to the Instances Summary page and you should see your new instance launching.  After a bit your instance will change from the "Spawning" to "Running".  This means the instance is now booting, and should finish booting in a minute or two.  In the meantime we will need to attach a "Floating IP" address to your instance such that you can SSH into the instance.  On the right side of your running instance, you should see a drop-down menu, usually the "Create Snapshot" option is pre-selected.  Click the drop down menu arrow to open that menu, and select "Associate Floating IP".

In the "Associate Floating IP" dialogue, click the drop down menu to see if any IP addresses are already available, and if so, go ahead and select one.  If there are none available, click the little "+" button to the right to allocate a floating IP address.  It will ask you what Pool to use, select "ext-net".  You can put in a description if you want but most folks leave that field blank.  Then click "Allocate IP".  It will take you back one menu level.  It will have a field "Port to be Associated", just leave that alone with the default that is already there.  Click the blue "Associate" button on the bottom right of the window.

You will be returned to the "Instances Summary" page again.  You will see your instance running, and it should now list a "Floating IP" that it is running under.  That is the IP that you will use to SSH to the instance.

==Connect to Your New Instance==

Now that your instance is up and running, let's SSH to it and get going!  '''From the computer you created your SSH keys on,''' SSH to your instance using the username as the OS type you chose (ubuntu, centos, etc), and the Floating IP address your instance has.  '''You must be connected to the VPN for this to work!'''  Example:

 $ ssh ubuntu@10.50.100.67

If you launched a CentOS instance, it would instead be "ssh centos@10.50.100.67", as appropriate.  Assuming everything went as planned, you will be logged into your new Linux instance as the "ubuntu" or "centos" user, which is an unprivileged user.  If you get a "Connection Refused" error when trying to SSH in, it means your instance isn't quite through launching yet, try again in about 30 seconds.  You have full sudo rights however to do whatever administration you need to do.  At this point it is assumed you have a little systems administration skills in your belt, or at least have some time to query Google as to how to perform various Linux tasks as necessary.  Your instance has full Internet access to the Greater Internet, so you can download thing fro the Internet, run "apt-get install" or "yum update" or whatever is appropriate.  You can also then install any needed software you need to get your work done.

'''NOTE:''' Your are the Systems Administrator of your instance - we cannot support questions on how to administer Linux for you.  If OpenStack itself is having issues then please let us know, but please defer questions like "How do I install software on Ubuntu" to Google searches.

==Storage on Your New Instance==

Most of your storage on your new instance will be located in the /mnt directory, as seen by a "df -h" command on your instance:

 ubuntu@erich1:~$ df -h
 
 Filesystem      Size  Used Avail Use% Mounted on
 udev             16G     0   16G   0% /dev
 tmpfs           3.2G  676K  3.2G   1% /run
 /dev/vda1        20G  975M   19G   5% /
 tmpfs            16G     0   16G   0% /dev/shm
 tmpfs           5.0M     0  5.0M   0% /run/lock
 tmpfs            16G     0   16G   0% /sys/fs/cgroup
 /dev/vda15      105M  3.4M  102M   4% /boot/efi
 /dev/vdb1       1.0T  1.1G 1023G   1% /mnt
 tmpfs           3.2G     0  3.2G   0% /run/user/1000

Notice that "/mnt" has 1TB of disk space, so store all your big important data in /mnt.  Avoid storing data on "/" whenever possible to prevent issues with the root filesystem filling up.  The exact amount of storage available will depend on what flavor you chose when creating the instance.

==Instance Control Options==

Just a few notes on controlling your instances.  They are fully functioning Linux machines, so a "sudo reboot" will reboot the machine, "sudo poweroff" will shut it down, etc.  In cloud parlance, "Shut Down" means the instance is still there but the power is off.  "Terminated" means it's fully deleted and is unrecoverable, so be sure you want to delete your instance before you do so.  We do not back instances up.  We also have no access to your instance so we cannot log in and see what's going on.

You can control your instance in several ways from the OpenStack web interface, in the Instance Summary page.  On the right side of your instance in the list will be that little drop down menu.  Options of interest are:

'''1: Create Snapshot'''

Never use this option as we have not implemented snapshotting in this environment.

'''2: View Log'''

This will show you the boot/console log of the instance, so you can see if anything is causing issues.

'''3: Hard Reboot Instance'''

This will hard reboot your instance, kind of like hitting the power button to power the instance off, then it will power back on moments later.  Useful if your instance is hosed because of a software crash or other things that may have crashed the instance.

'''4: Delete Instance'''

This will permanently destroy your instance.  It will be deleted and is unrecoverable.  It will also free up the resources it was using such that others can use them however.  This is useful if the group quotas have been reached and some old instances need to be cleaned out to make room for new ones.

'''5: Start Instance'''

This option will be available if the instance is in the "Shut Down" state.  It will boot up the instance when this option is invoked.

Do not use the other options you may see there, most have not been implemented in our deployment of OpenStack.

==Changing Your OpenStack Web Interface Password==

Once you have logged in to the Web Interface, you can change your password by doing the following.

On the top right of the OpenStack web interface, you should see a little icon with your username on it.  Click that icon to expand the drop down menu there, and select "Settings".  Then in the next window, on the left navigation bar, you should see the "Change Password" button.  Complete the Change Password dialogue to change your password.  You may have to log in again after changing your password.

==Networking==

Your instances are connected at 10Gb/s between each other and the internet.  Of course, actual transfer speeds will likely vary based on disk speed, speed of the location to are transferring data to or from, and other factors.

Your instance will be located in a private network that can only be seen by other instances in your group.  Other OpenStack groups are logically separated into their own networks and your instance cannot route to them.  Also, no one can access your instance unless they have a VPN account with us, so your instances are completely fenced off from the Greater Internet inbound, which means you are largely secure against script kiddies and hackers.  You are able to connect outbound from your instances.

==Etiquette==

There is one main thing to remember when using instances in OpenStack.  When you create an instance, it uses CPU, RAM and most importantly, it pins disk space for that instance.  If you use up all the disk, CPU and RAM quota for your group, then others have no resources left to create their own instances.  It is important to know that the best plan of action is to fire up your VM and keep it up when you need it, and then copy your data off it and delete the instance.  Document steps taken to create your instance such that you could do it again if you needed to.  If the physical node that your instance resides on blows up, then your instance is lost forever and we have no backups, so it is up to you to back up important data.  It's also not good form to spin up an instance and store data there, but not log in for months at a time.  Then, you are pinning resources that other may need for urgent work.  Try to be a good neighbor!