User Guide

This guide describes how users log into XOS, acquire VMs, and access XOS services. It assumes the reader is familiar with the general concepts presented in the Architecture Guide.

Because this guide is focused on users, we use OpenCloud as an example of an operational cloud that users might access. This implies a particular portal, a particular set of nodes and sites, and a particular collection of services. Substitute local specifics for an alternative XOS installation.

Getting Started

Users access OpenCloud by logging into the portal at New users register through the same portal, with the request approved by the PI (Principle Investigator) at their home site.

Once the user has an account, the following steps are a quick guide to utilizing OpenCloud resources:

  1. Upload a public key. Select the Users tab in the left-hand navigation bar, click on your email address, and then paste your public key in the box. Click the Save button at right.

  2. Ask your Site PI to create a slice. Instructions for PIs (see Administering a Site for more information):
    • Select the Slices tab in the left-hand navigation bar, and then the Add Slice button on the right. In the Slice Details form, choose a name for the slice and select your own site from the drop-down menu. Slice names must be unique. Click the Save and continue editing button on the right before proceeding.
    • Select the Privileges tab from the top, and then click the Add another slice privilege link. Add the users that will administer the slice with the Admin privilege. (These users will be able to extend slice privileges to other users.)
    • Click the Save button when done.
  3. Create instances. Use either the Tenant or the Developer View (see next section) to instantiate instances (VMs) for your slice.

  4. Log into instances. Once an instance comes up, you will be able to learn its instance ID. You can then ssh into the instance using this ID and the physical node it is running on. See Accessing a Instance for more information.

User Views

Users interact with OpenCloud through a configurable set of Views, each tailored for a different usage scenario or workflow. By default, a user’s home dashboard includes the Tenant view; a Customize tab allows the user to add and remove views from their home dashboard, including the more “advanced” Developer view. Both the Tenant and Developer views are used to administer a user’s slices. From any page, selecting the Home tab in the left-hand navigation bar brings the user back to his or her home dashboard.

Users are also able to directly navigate the underlying data model using the left-hand navigation bar. Each tabs (Deployments, Sites, Slices, Users, and Services) correspond to the core XOS objects, as described in the Data Model. The following sections of this guide describe how to use these tabs to manage users, sites, and deployments, respectively. (The views described in this section are typically use to manage slices.)

There are also views designed to support operators, as described in the Operator Guide.

Tenant View

The Tenant view provides a simple means to acquire Instances, with minimal control over the low-level details of where those Instances are placed and what networks interconnect them. It is loosely patterned after the Amazon EC2 interface.

The Tenant view allows users to specify the number of instances that are to be instantiated on the available sites, select an Image and Flavor for each instance, mount select Data Set(s) into each instance, and specify the TCP Ports the slice is going to use. Users can also set the ServiceClass for the slice, although Best Effort is currently the only supported class.

In the Tenant View, click on the SSH Commands button to see SSH commands that can be cut-and-pasted into the terminal for logging into your instances; click the Download button to save them as a local text file. Accessing an Instance explains other ways to configure SSH access for a slice’s instances.

Note that slices intially created through the Tenant view may also be managed through the Developer view.

Developer View

The Developer view gives users full control over how their slices are instantiated, including instance placement, network configuration, and the privileges granted to other users:

xsh View

The xsh view provides an interactive shell through which users can access XOS objects. It is a Javascript-based environment that includes xoslib, a library projection of the XOS data model. A builtin tutorial illustrates how to use xsh.

Accessing an Instance

Instances connect to the network via NAT; logging into the instance relies on SSH proxying to forward incoming SSH connections. In the Tenant View, click on the SSH Commands button to see SSH commands that can be cut-and-pasted into the terminal for logging into your instances. In the Developer View, the instance Id and node name are displayed in the Instance frame. You can use this information to add lines to your ~/.ssh/config file similar to the following:

Host foobar
  User ubuntu
  IdentityFile ~/.ssh/id_rsa
  ProxyCommand ssh -q

In the above, replace “foobar” with a label of your choice for this instance. User is the default login user for the image. IdentityFile should point to the key that you’ve uploaded to OpenCloud. ProxyCommand should point to the instance ID and node for the instance. Once an entry is present for the instance in ~/.ssh/config, you can login using the label:

# ssh foobar

Other utilities like scp also work as expected when referencing the instance using the label.

A current limitation is that only one user key is injected into the slice. Because SSH is indirect through the ProxyCommand, it is not sufficient to manually add additional keys for other users to an account inside the instance; for the time being, an administrator will need to add the additional keys to the proxy environment as well.

In addition to SSH connectivity via NAT, there are two other network-related issues of note. First, to run an Internet-accessible service in a slice, it is necessary to reserve a TCP or UDP port. This is done using the Network Ports field in the Tenant View. The service can then be accessed at this port on the hosting server (e.g., in the above example). Second, all the instances at a given site are automatically connected by a private network. Run ifconfig from within an instance to learn the instance’s private address (i.e., the 10.x.x.x address associated with eth0). This private virtual network is per-site. Instances in different sites must use an Internet-accessible address to communicate (i.e., using a reserved port and hosting server name as described above).

Administering a User

All users are able to manage their own accounts and Site Admins are able to manage the accounts of users homed at that site. Select the Users tab in the left-hand navigation bar, and then click on the desired user. The available user details are as follows:

Administering a Site

Site Admins are responsible for managing the users, slices, nodes, and deployments affiliated with the site. Select the Sites tab in the left-hand navigation bar and click on the desired site. The available site details are as follows:

Administering a Deployment

Deployment Admins are responsible for managing the privileges, sites, images, flavors, and visibility for the deployment. Select the Deployments tab in the left-hand navigation bar and click on the desired deployment. The available deployment details are as follows:

The Privileges tab is used to grant other users Admin privileges for the deployment.

The Sites tab is used to bind a Site (and the Nodes they host) to this Deployment. Nodes are imported into a Deployment through a Controller that is responsible for instantiating and managing the Nodes. For example, in the case of an OpenStack cluster, the Controller effectively connects XOS to the Nova, Neutron, and Keystone services running on the OpenStack head node.

To create a new Deployment-to-Site-to-Controller binding, use the Add another Site Deployment link at the bottom of the Sites tab. You will be prompted for the Site and the Controller. If an existing Controller is not suitable, then the “+” button next to the Controller dropdown may be used to create a new Controller.

Creating a Controller involves defining the following fields:

The list of controllers is not a top-level item in the navigation panel, so to edit an existing Controller, first go to another object (e.g., Deployment), and then use the Core link at the top of the page to bring up the list of Core XOS objects. Select the Change link next to Controller. [Workflow to be cleaned up.]

Administering Images

To upload an image to XOS, place the image file in /opt/xos/images. Note that adding a file to this directory must be done atomically, for example by uploading the file elsewhere and then using ‘mv’ to move the file into the directory. If a file is uploaded directly to /opt/xos/images, then it’s possible the Synchronizer may attempt to sync the image to controllers while the upload is in progress, before the file is complete.

Once the image has been placed in /opt/xos/images, the Synchronizer will run and automatically sync that image to all controllers.

Even though an image has been uploaded and synced, it is still not available for use until it has been enabled in a deployment. See the Administering a deployment section above.

Accessing an Administering Services

XOS is designed to support a set of contributed services, but the set of services available on any particular system is as cloud-specific as the underlying hardware infrastructure. In the case of OpenCloud, there are currently two contributed Services, each of which extends the XOS Data Model with its own abstract objects, and hence, is accessible via OpenCloud’s REST API.

Select the Services tab in the left-hand navigation bar to see the available services. Then select a specific service to either (1) access or use that service, or (2) administer that service.

Users typically access a service (e.g., mount a Syndicate volume or publish content in the CDN) through a service-provided view, but it is also possible to access a service using the Access tab. The details of how the user interacts with the service is beyond the scope of this Guide. [Per-service specifications to be added as an appendix.]

Service adminstrators typically use the other tabs to manage the service. In addition to adding a new service, this includes:

Information about how to implement a new service is given in Section Adding Services of the Developer Guide.