OpenStack User Manual, step-by-step instructions with issues commented by a new user

Table of Contents

1. Glossary
2. Asking for an account
3. Logging into the dashboard
4. Usage pattern
5. Configuring access
6. Creating a volume
7. Creating security group for SSH connection
8. Creating an instance
9. Setting up the environment
10. Running experiments
11. Downloading results
12. Deleting an instance
13. Deleting a volume

Glossary

• instance – a virtual machine
• volume – a virtual disk, persistent storage
• node – a physical server or computer that runs instances

Asking for an account

If you don’t have an OpenStack account, you can ask for one by visiting room 25a or contacting Robert Nowak at robert.nowak@pw.edu.pl. You can use the following email template if you want.

To: robert.nowak@pw.edu.pl
Subject: OpenStack account

Please create an OpenStack account for me.
Preferred User Name: MY_PREFERRED_USER_NAME

You will get your user name and a new password in response.

Logging into the dashboard

Make sure you are connected to the internal network1 or the AI Division VPN. Browse to os.ai.ii.pw.edu.pl. The dashboard does not use SSL (HTTPS), because your traffic goes through a trusted iternal newtork or is already encrypted by WireGuard VPN.

Provide your User Name and Password and select Domain: OpenStack.

If you successfully logged in using the password that was given to you by an administrator, please change it now.

There is also a possibility to login using Galera credentials with Domain: Galera. Hovever, you still need to contact an administrator to create a project for you.

Usage pattern

The AI Division OpenStack should be used in the following pattern:

1. Configure access
2. Create a volume
3. Create security group for SSH connection
4. Create an instance from a volume
5. Set up the environment
6. Run experiments
7. Download results
8. Delete instance (free GPU, RAM, CPU)
9. Delete volume (free disk)

Do step 8 if you are absolutely sure you are not going to use the corresponding environment in the future.

Step 1 has to be done only once per user system.

If you want to run experiments in a new environemnt, start with step 2.

If you want to run experiments in an environment you already have set up, start with step 3 and skip step 4, use an existing volume.

Configuring access

In order to log into your instances via SSH, you need to generate a key pair and upload the public key to OpenStack. Generate a key by executing the following command on your computer.

ssh-keygen -f "~/.ssh/openstack" -N ""

Explanation

Let’s now tell your SSH client to use this key. Create file ~/.ssh/config and add the following contents or add them to the end of this file if it exists.

Host 10.221.128.*
	User ubuntu
	IdentityFile ~/.ssh/openstack

Explanation

Now upload your public key. Browse here, click Import Public Key, enter any Key Pair Name (e.g. openstack) and select Key Type: SSH Key. Now click Browse and select ~/.ssh/openstack.pub or paste the contents of this file into the Public Key field.

Please remember to enter your public key, which is the one with .pub suffix.

Creating a volume

Volumes are attached to instances to provide persistent storage. E.g. your home directory is saved there and instances can be booted from them. It is recommended that you create one volume per experiment environment.

Volumes exist independently of instances. You can create a volume, set it up, create an instance and attach the volume to it. When you delete the instance, the volume will persist and you will be able to create another instance from it.

You can create a volume by browsing to Volumes and clicking Create Volume above the table, on the right.

Input a Volume Name and select Volume Source: Image. Under Use image as a source you can select a volume template. The template contains an operating systems and other tools. Select one that best fits your use case. ubuntu2204-cuda115 is the recommended image, but it assumes you are comfortable with a terminal. Desktop images are not supported yet. They work fine, but if you select one, you are on your own.

Input a volume size into the Size (GiB) field. 100 is most likely fine.

Please note that volume Type can be chosen. Here you can select SSD or HDD. It is strongly recommended to select SSD for boot volumes (most use cases). But keep in mind that the per-user SSD quota is much lower than HDD quota.

The rest of the options can be left as-is. Click Create Volume.

Creating Security Group for SSH connection

An instance created with a default Security Group may work for you out of the box and allow for SSH connection. However, if that is not the case and you encounter an error like Connection timed out it means that the Network Security Group rules need some checking-up. This can be achieved by one of the two:

1. Update an exisiting security group (e.g default)
2. Create a new security group
   In any case, the final security group should consist of the following rules:

Rules for a given group can always be edited later in Network->Security Group->Manage rules.

Creating an instance

There are two ways to get to the Launch Instance.

On the Volumes page, click the little down arrow next to the volume you want to use and select Launch as Instance.

Alternatively, go to Instances and click Launch Instance above the table, on the right. You will need to select a volume you want to use in the Source step.

In the Details step, input an Instance Name. It makes sense to be the same, or simmilar to the volume name.

In the flavor step, select a flavor.

Flavors determine which graphic card you get and on which node it will run. To select a flavor, first look at the table on the main OpenStack page. Click the Explanation arrow below the table and read the explanation.

In the Security Groups step the default group will be automatically selected. If the security group rules have been updated for this one you can just leave it as it is. If you created a new group for the job, select it from the available ones now. Both the security group and its rules can be edited later, during the lifetime of an instance by going to Compute->Instances and selecting the desired operation under Actions for the given instance.

If you have more than one SSH key added to your account you have to select one SSH key that you’ll use to log in in the Key Pair step.

Click Launch Instance on the bottom right. Now your instance will go through Build state. When the provisioning is finished it will assume a state of Active.

If your instance assumes Error status, click on the instance name to see the error message. Check the Fault section. If Message says

No valid host was found. There are not enough hosts available.

it means that you selected a flavor of which there are zero instances available. Please see the table mentioned above.

Known issues at this stage include Error: build of instance or the Build step entering an infinte loop.

If you get any of the above or any other error message, please do not hesitate to contact the system administrator: Szymon Śmiech szymon.smiech@pw.edu.pl and/or report it to robert.nowak@pw.edu.pl. Include the entire error message.

Take note of the IP Address of the instance, visible in the table in the Instances page. You can now log into your instance using this address.

ssh 10.221.128.xx

If you see a shell prompt with hostname matching your instance name you succeeded.

Setting up the environment

After logging in, you can set up an environment for your experiments. Install packages and clone repositories you need.

You can also upload files from your local computer to the instance. One way to do that would be to use the scp program like this:

scp -r local-dir/ 10.221.128.xx:remote-dir/

Running experiments

You can now run your experiments by executing commands while connected to your instance. Tip! If you want your experiments to continue running when you disconnect from the instance you can use the screen program. Example:

$ ssh 10.221.128.xx
$ screen
[Enter]
$ ./run-my-experiment
{Ctrl+a} {lift fingers} {d}
[detached from 1337.pts-0.myinstance]
$ exit

Then when you want to log in and check the progress:

# ssh 10.221.128.xx
$ screen -r

Detach and let it run some more:

{Ctrl+a} {lift fingers} {d}
[detached from 1337.pts-0.myinstance]
$ exit

Downloading results

You can download results of your experiments by using the scp program.

scp -r 10.221.128.xx:remote-dir/ local-dir/

Deleting an instance

Why delete instead of shelve?

Freeing resources is a crucial part of using the AI Division OpenStack. There is only a limited number of graphic cards in the cluster. When your instance is Active or even Shut Off, the graphic card assigned to it is reserved. This means, nobody else can use it at that time. Hey! You WILL NOT lose any data by deleting an instance. * Volume will not be deleted. **

• You will not lose any data in persistent storage (disk, volume). You will however lose the contents of the memory (RAM), but it’s most likely fine. ** If you did not select the option Delete Volume on Instance Delete when creating the instance. (not selected by default)

When your experiment is finished, delete the instance by browsing to Instances, clicking the little down arrow near the instance you want to delete and click Delete Instance on the bottom of the action list. You might have to scroll downwards a bit to see it.

Known Issues
It may happen that upon deleting an instance, the volume mounted to it will not detect the fact and keep on showing in use status.
This state makes it impossible for it to be mounted to another instance or simply deleted. If you encounter this issue, you are advised to contact the system administrator: Szymon Śmiech szymon.smiech@pw.edu.pl.

Deleting a volume

You don’t have to delete volumes, but it’s a good idea if you are sure you will not use them any more. You might want to keep the number volumes under control as there is a limit to the total size of volumes you own. When you reach this limit and try to create another volume you will get a message like this:

Error: Unable to create volume. Details VolumeSizeExceedsAvailableQuota: Requested volume or snapshot exceeds allowed gigabytes_SSD quota. Requested 5000G, quota is 500G and 310G has been consumed. (HTTP 413) (Request-ID: req-784700f8-ee83-4343-b7dc-bacd3dd064f5)

To delete a volume, find it on the Volumes page, click the little down arrow next to it and click Delete Volume.

Work in progress, ticket: https://ben.ii.pw.edu.pl/gitlab/ai-net/ai-net-tickets/-/issues/36 ↩︎

AI Division, Institute of Computer Science, Warsaw University of Technology