Skip to content

Latest commit

 

History

History
133 lines (95 loc) · 5.05 KB

apidesc.md

File metadata and controls

133 lines (95 loc) · 5.05 KB
Raw

HaaS API

First describe the main objects, the users and security model, then then the actual API.

Objects in the HaaS

  • project - a grouping of resources (e.g., headnodes, nodes, networks).
  • node - a physical node. Either unallocated or belongs to a project. Has one or more NICs attached to it.
  • headnode - a controlling machine for a project, today a VM, assigned to one project
  • NIC - network card, identified by a user-specified label (e.g., PXE, ipmi, user1, silly) will have a visible ethernet mac address (or equivalent unique number for other network types), and is always part of one node and connected to at most one port.
  • HNIC - headnode network card, identified by a user-specified label (e.g., PXE, ipmi, user1, silly), and is always part of one headnode.
  • port - a port to which NICs can be connected. Only visible to admins.
  • network - a network, today implemented as a VLAN, that NICs and HNICs can be connected to. See networks.md for more details.

Additionally, we provide one built-in authorization model, that adds another kind of object:

  • user - a user, with password and login. Users can have access to any number of projects.

API design philosophy

We provide the most basic API that we can, and attempt to impose no structure that is not required for authorization purposes.

  • A 'project' is merely an authorization domain. It is reasonable to have logically independent groupings of resources within one project, but the HaaS will not help you create such a structure. Policies like this belong in higher-level tools built on top of the haas.

  • We considered having a mechanism for staging a large number of networking changes and performing them all-together, and even potentially allowing roll-back. Instead, we simply have API calls to connect a NIC to a network, and to disconnect it. All other functionalities can be built on top of this.

There is no garbage-collection of objects. If an object is being used somehow, it cannot be deleted. For example, if a node is on a network, the user can neither de-allocate the node nor delete the network. They must first detach the node from the network. (The one exception to this is that, when deleting a headnode, all of its HNICs are deleted with it. This is due to a technical limitation---we cannot currently dynamically add and remove HNICs.)

Most objects are identified by "labels" that are globally unique, e.g., nodes, networks, groups, users, headnodes. While we may eventually change this, it seems a reasonable limitation for now that simplifies the implementation and will allow potential sharing of resources. The system will return an error if a second user tries to create an object with an already existing label. The one exception is NICs, where the label is unique only on a per-node basis.

User operations:

# Basic node allocation and network isolation

network_create              <network_label> <proj_creator> <proj_access> <id>
network_delete              <network_label>

project_connect_node        <project_label> <node_label>
project_detach_node         <project_label> <node_label>

node_connect_network        <node_label> <nic_label> <network_label>
node_detach_network         <node_label> <nic_label>

# Headnode operations

headnode_create             <hn_label> <project_label> <base_img>
headnode_delete             <hn_label>

headnode_start              <hn_label>
headnode_stop               <hn_label>

headnode_create_hnic        <hn_label> <hnic_label>
headnode_delete_hnic        <hn_label> <hnic_label>

headnode_connect_network    <hn_label> <hnic_label> <network>
headnode_detach_network     <hn_label> <hnic_label>

# IPMI-based operations on nodes

node_power_cycle           <node_label>

start_console              <node_label>
show_console               <node_label>
stop_console               <node_label>

# Query interface

list_nodes                 <is_free>
list_project_nodes         <project>
list_project_networks      <project>
list_project_headnodes     <project>
list_switches
show_node                  <node>
show_headnode              <headnode>
show_network               <network>

Authorization-related operations:

# Always useful

project_create              <project_label>
project_delete              <project_label>

# Only meaningful with the built-in auth backend

user_create                 <user_label> <password>
user_delete                 <user_label>

project_add_user            <project_label> <user_label>
project_remove_user         <project_label> <user_label>

Administrative operations to describe physical configuration

list_projects

node_register      <node_label>
node_delete        <node_label>
node_register_nic  <node_label> <nic_label> <mac_addr>
node_delete_nic    <node_label> <nic_label>

port_register      <port_no>
port_delete        <port_no>
port_connect_nic   <port_no> <node_label> <nic_label>
port_detach_nic    <port_no>