VMMS Docs

This page documents the interface for Tango's Virtual Machine Management Systems' (VMMSs) API and instructions for setting up VMMSs. See the vmms directory in Tango for example implementations.

API

The functions necessary to implement the API are documented here. Note that for certain implementations, some of these methods will be no-ops since the VMMS doesn't require any particular instructions to perform the specified actions. Furthermore, throughout this document, we use the term "VM" liberally to represent any container-like object on which Tango jobs may be run.

initializeVM

initializeVM(self, vm)

Creates a new VM instance for the VMMS based on the fields of vm, which is a TangoMachine object defined in tangoObjects.py.

waitVM

waitVM(self, vm, max_secs)

Waits at most max_secs for a VM to be ready to run jobs. Returns an error if the VM is not ready after max_secs.

copyIn

copyIn(self, vm, inputFiles)

Copies the input files for a job into the VM. inputFiles is a list of InputFile objects defined in tangoObjects.py. For each InputFile object, file.localFile is the name of the file on the Tango host machine and file.destFile is what the name of the file should be on the VM.

runJob

runJob(self, vm, runTimeout, maxOutputFileSize)

Runs the autodriver binary on the VM. The autodriver runs make on the VM (which in turn runs the job via the Makefile that was provided as a part of the input files for the job). The output from the autodriver most likely should be redirected to some feedback file to be used in the next method of the API.

copyOut

copyOut(self, vm, destFile)

Copies the output file for the job out of the VM into destFile on the Tango host machine.

destroyVM

destroyVM(self, vm)

Removes a VM from the Tango system.

safeDestroyVM

safeDestroyVM(self, vm)

Removes a VM from the Tango system and makes sure that it has been removed.

getVMs

getVMs(self)

Returns a complete list of VMs associated with this Tango system.

Docker VMMS Setup

This is a guide to set up Tango to run jobs inside Docker containers.

Install docker on host machine by following instructions on the docker installation page. Ensure docker is running:
```
$ docker ps # CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
```

Build base Docker image from root Tango directory.

cd path/to/Tango
docker build -t autograding_image vmms/
docker images autograding_image    # Check if image built

Update VMMS_NAME in config.py.

# in config.py
VMMS_NAME = "localDocker"

Amazon EC2 VMMS Setup

This is a guide to set up Tango to run jobs on an Amazon EC2 VM.

Create an AWS Account or use an existing one.
Obtain your access_key_id and secret_access_key by following the instructions here.
Add AWS Credentials to a file called ~/.boto using the following format:
```
[Credentials]
    aws_access_key_id = MYAMAZONTESTKEY12345
    aws_secret_access_key = myawssecretaccesskey12345
```
Tango uses the Boto Python package to interface with Amazon Web Services
In the AWS EC2 console, create an Ubuntu 14.04+ EC2 instance and save the .pem file in a safe location.
Copy the directory and contents of autodriver/ in the Tango repo into the EC2 VM. For more help connecting to the EC2 instance follow this guide
```
chmod 400 /path/my-key-pair.pem
scp -i /path/my-key-pair.pem -r autodriver/ ubuntu@<ec2-host-name>.compute-1.amazonaws.com:~/
```
The autodriver is used as a sandbox environment to run the job inside the VM. It limits Disk I/O, Disk Usage, monitors security, and controls other valuable sudo level resources.

In the EC2 VM, compile the autodriver.

$ cd autodriver/
$ make clean; make
$ cp -p autodriver /usr/bin/autodriver

Create the autograde Linux user and directory. All jobs will be run under this user.

$ useradd autograde
$ mkdir autograde
$ chown autograde autograde
$ chown :autograde autograde

In the AWS EC2 console, create an AMI image from your EC2 VM. Use this guide to create a custom AMI.

Exit the EC2 instance and edit the following values in config.py in the Tango directory.

# VMMS to use. Must be set to a VMMS implemented in vmms/ before
# starting Tango.  Options are: "localDocker", "distDocker",
# "tashiSSH", and "ec2SSH"
VMMS_NAME = "ec2SSH"
######
# Part 5: EC2 Constants
#
EC2_REGION = 'us-east-1'             # EC2 Region
EC2_USER_NAME = 'ubuntu'             # EC2 username
DEFAULT_AMI = 'ami-4c99c35b'         # Custom AMI Id
DEFAULT_INST_TYPE = 't2.micro'       # Instance Type
DEFAULT_SECURITY_GROUP = 'autolab-autograde-ec2'  # Security Group with full access to EC2
SECURITY_KEY_PATH = '/path/to/my-key-pair.pem'    # Absolute path to my-key-pair.pem
DYNAMIC_SECURITY_KEY_PATH = ''       # Leave blank
SECURITY_KEY_NAME = 'my-key-pair'    # Name of the key file. Ex: if file name is 'my-key-pair.pem', fill value with 'my-key-pair'
TANGO_RESERVATION_ID = '1'           # Leave as 1
INSTANCE_RUNNING = 16                # Status code of a running instance, leave as 16

You should now be ready to run Tango jobs on EC2! Use the Tango CLI to test your setup.