Overview

This file describes the HIL API. We first describe the main objects, then users and security model, and finally provide a full reference for the API.

By default, HIL is using the unstable "v0" version for all its API.

Objects in the HIL

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.

The authentication system is pluggable. Authentication mechanisms are provided by extensions (see extensions.md), but the rules about who is allowed to access what are dictated by HIL core. Operations etiher require administratie priilieges, or access to a particular project.

Of note, "users" are not a concept that HIL core understands, though some of the individual auth extensions do.

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 HIL will not help you create such a structure. Policies like this belong in higher-level tools built on top of the hil.
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.

API Reference

How to read

Each possible API call has an entry below containing:

an HTTP method and URL path, including possible <parameters> in the path to be treated as arguments.
Optionally, a summary of the request body (which will always be a JSON object).
A human readable description of the semantics of the call
A summary of the response body for a successful request. Many calls do not return any data, in which case this is omitted.
Any authorization requirements, which could include:
- Administrative access
- Access to a particular project or
- No special access In general, administrative access is sufficient to perform any action.
A list of possible errors.

In addition to the error codes listed for each API call, HIL may return:

400 if something is wrong with the request (e.g. malformed request body)
401 if the user does not have permission to execute the supplied request.
404 if the api call references an object that does not exist (obviously, this is acceptable for calls that create the resource).

Below is an example.

my_api_call

POST /url/path/to/<thing>

Request Body:

{
    "some_field": "a value",
    "this-is-an-example": true,
    "some-optional-field": { (Optional)
        "more-fields": 12352356,
        ...
    }
}

Attempt to do something mysterious to <thing> which must be a coffee pot, and must not be in use by other users. If successful, the response will include some cryptic information.

Response Body (on success):

{
    "some-info": "Hello, World!",
    "numbers": [1,2,3]
}

Authorization requirements:

No special access.

Possible errors:

418, if <thing> is a teapot.
409, if:
- <thing> does not exist
- <thing> is busy
{"foo": <bar>, "baz": <quux>} denotes a JSON object (in the body of the request).

Core API Specification

API calls provided by the HIL core. These are present in all installations.

Networks

network_create

PUT /network/<network>

Request Body:

{
    "owner": <owner>,
    "access": <access>,
    "net_id": <net_id>
}

Create a network. For the semantics of each of the fields, see Networks.

Authorization requirements:

If net_id is '' and owner and access are the same project, then access to that project is required.
Otherwise, administrative access is required.

Possible errors:

409, if a network by that name already exists.
See also bug #461

network_delete

DELETE /network/<network>

Delete a network. The user's project must be the owner of the network, and the network must not be connected to any nodes or headnodes. Finally, there may not be any pending actions involving the network.

Authorization requirements:

If the owner is a project, access to that project is required.
Otherwise, administrative access is required.

Possible Errors:

409 if:
- The network is connected to a node or headnode.
- There are pending actions involving the network.

show_network

GET /network/<network>

View detailed information about <network>.

The result must contain the following fields:

"name", the name of the network
"channels", description of legal channel identifiers for this network. This is a list of channel identifiers, with possible wildcards. The format of these is driver specific, see below.
"owner", the name of the project which created the network, or "admin", if it was created by an administrator.
"access", a list of projects that have access to the network or null if the network is public
"connected-nodes": nodes and list of nics connected to network

Response body (on success):

{
    "name": <network>,
    "channels": <chanel-id-list>,
    "owner": <project or "admin">,
    "access": <project(s) with access to the network/null>
    "connected-nodes": {"<node>": [<list of nics connected to network]}
}

Authorization requirements:

If the network is public, no special access is required.
Otherwise, access to a project in the "access" list or administrative access is required.
Admins and network owners can see all nodes connected to network; other users only see connected nodes that they have access to.

Channel Formats

802.1q VLAN based drivers

Channel identifiers for the VLAN based drivers are one of:

vlan/native, to attach the network as the native (untagged) VLAN
vlan/<vlan_id> where <vlan_id> is a VLAN id number. This attaches the network in tagged, mode, with the given VLAN id.

Additionally, the show_networks api call may return the channel identifier vlan/*, which indicates that any VLAN-based channel id may be used.

Where documentation specifies that the network driver should choose a default channel, the VLAN drivers choose vlan/native.

list_networks

GET /networks

List all networks.

Returns a JSON dictionary of dictionaries, where the exterior dictionary is indexed by the network name and the value of each key is another dictionary with keys corresponding to that network's id and projects

Response contains all networks if the user is an admin. Otherwise, response only contains all public networks.

The response must contain the following fields:

"network", the name of a network
"network_id", the id of the network
"projects", a list of projects with access to the network or 'None' if network is public

Example Response for an admin user:

{
    "netA": {
        "network_id": "101",
        "projects": ["qproj-01", qproj-02"]
    },
    "netB": {
        "network_id": "102",
        "projects": None
    }
}

Example Response for a regular user:

{
    "netA": {
        "network_id": "102",
        "projects": None
    },
    "netB": {
        "network_id": "103",
        "projects": None
    }
}

Authorization requirements:

Administrative access is required to list all networks
No special access is required to list all public networks

list_network_attachments

GET /network/<network>/attachments

List all nodes that are attached to network .

If optional argument 'project' is supplied, only attached nodes belonging to the specified project will be listed.

Returns a JSON dictionary of dictionaries with first level key being the name of the attached node and second level keys being:

"nic", the name of the nic on which the node is attached
"channel", the channel on which the attachment exists
"project", the name of the project which owns the attached node

Example Response:

{
    "node1": {
         "nic": "nic1",
         "channel" "vlan/native",
         "project": "projectA"
    },
    "node2": {
         "nic": "nic2",
         "channel": "vlan/235",
         "project": "projectB"
    }
}

Authorization requirements:

Admins or the project that is the owner can list all attached nodes.
Other projects can only list their own nodes.

network_grant_project_access

PUT /network/<network>/access/<project>

Add to access list for .

Authorization requirements:

Only admins or the network owner can grant a project access to the network.

Possible Errors:

404 - If the network or project does not exist
409 - If the project already has access to the network

network_revoke_project_access

DELETE /network/<network>/access/<project>

Remove from access list for .

Authorization requirements:

Only admins, the network owner, or the project itself can revoke a project's access to the network.

Possible Errors:

404 - If the network or project does not exist.
409 - If the project is the owner of the network.

node_connect_network

POST /node/<node>/nic/<nic>/connect_network

Request body:

{
    "network": <network>,
    "channel": <channel> (Optional)
}

Connect the network named <network> to <nic> on <channel>.

<channel> should be a legal channel identifier specified by the output of show_network, above. If <channel> is omitted, the driver will choose a default, which should be some form of "untagged."

Networks are connected and detached asynchronously. If successful, this API call returns a status code of 202 Accepted, and queues the network operation to be performed. Each nic may have no more than one pending network operation; an attempt to queue a second action will result in an error.

It is important that users of this API check the status of their request using the show_networking_action API to ensure that their previous calls were successful before queuing any new actions on the same nic.

Response body:

{
    "status_id": <unique_id>,
}

Authorization requirements:

Access to the project to which <node> is assigned.
Either <network> must be public, or its "access" field must name the project to which <node> is assigned.

Possible errors:

409, if:
- The current project does not control <node>.
- The current project does not have access to <network>.
- There is already a pending network operation on <nic>.
- <network> is already attached to <nic> (possibly on a different channel).
- The channel identifier is not legal for this network.

node_detach_network

POST /node/<node>/nic/<nic>/detach_network

Request body:

{
    "network": <network>
}

Detach <network> from <nic>.

Networks are connected and detached asynchronously. If successful, this API call returns a status code of 202 Accepted, and queues the network operation to be preformed. Each nic may have no more than one pending network operation; an attempt to queue a second action will result in an error.

Just like the node_attach_network API, please check the status using the show_networking_action API to check the status of previous calls before queuing any new actions.

Response body:

{
    "status_id": <unique_id>,
}

Authorization requirements:

Access to the project to which <node> is assigned.

Possible Errors:

409, if:
- The current project does not control <node>.
- There is already a pending network operation on <nic>.
- <network> is not attached to <nic>.

Nodes

node_register

PUT /node/<node>

Register a node with optional metadata

The "obmd" field has two subfields. The first is "uri", which is the uri for the given node under obmd's API; if obmd's API is available at https://obmd.example.com, then node4 will have a uri of https://obmd.example.com/node/node4. The second is "admin_token", which is the admin token for obmd.

Note that different nodes may be managed by different instances of obmd; HIL does not care.

Request Body:

{
    "obmd": {
        "uri": "https://obmd.example.com/node/node4",
        "admin_token": "208eb61c77c3468558ccd9eec9ca0598"
    },
    "metadata": { (Optional)
        "label_1": "value_1",
        "label_2": "value_2"
    }
}

Authorization requirements:

Administrative access.

Possible errors:

409, if a node with the name <node> already exists

node_delete

DELETE /node/<node>

Delete the node named <node> from the database.

Authorization requirements:

Administrative access.

node_register_nic

PUT /node/<node>/nic/<nic>

Request Body:

{
    "macaddr": <mac_addr>
}

Register a nic named <nic> belonging to <node>. <mac_addr> should be the nic's mac address. This isn't used by HIL itself, but is useful for users trying to configure their nodes.

Authorization requirements:

Administrative access.

Possible errors:

409 if <node> already has a nic named <nic>

node_delete_nic

DELETE /node/<node>/nic/<nic>

Delete the nic named <nic> and belonging to <node>.

Authorization requirements:

Administrative access.

node_enable/disable_obm

PUT /node/<node>/obm

Request body:

{
    "enabled": <boolean>
}

Enable or disable management of the node's OBM. The OBM must be disabled to detach the node from a project, and must be enabled to do things like power cycle the node, view the console etc.

Accepts a boolean argument indicating whether to enable or disable the obm.

Enabling an obm which is already enabled, or disabling one that is already disabled will silently no-op.

Authorization requirements:

Access to the project to which <node> is assigned (if any) or administrative access.

node_power_cycle

POST /node/<node>/power_cycle

Request Body:

{
    "force": <boolean> (Optional, defaults to False)
}

Power cycle the node named <node>, and set it's next boot device to PXE. If the node is powered off, this turns it on.

Accepts one optional boolean argument that determines whether to soft (default) or hard reboot the system.

Authorization requirements:

Access to the project to which <node> is assigned (if any) or administrative access.

Possible Errors:

409, if the node's OBM is not enabled (see node_enable_obm).

node_set_bootdev

PUT /node/<node>/boot_device

Request body:

{
    "bootdev": <boot device>
}

The request body consists of JSON with a bootdev argument:

Sets the node's next boot device persistently

Authorization requirements:

Access to the project to which <node> is assigned (if any) or administrative access.

Possible Errors:

409, if the node's OBM is not enabled (see node_enable_obm).

For IPMI devices

The valid/allowed boot devices are:

pxe : do a pxe boot (network boot)
disk: boot from local hard disk
none: to reset boot order to default.

node_power_off

POST /node/<node>/power_off

Power off the node named <node>. If the node is already powered off, this will have no effect.

Authorization requirements:

Access to the project to which <node> is assigned (if any) or administrative access.

Possible Errors:

409, if the node's OBM is not enabled (see node_enable_obm).

node_power_on

POST /node/<node>/power_on

Power on the node named <node>. If the node is already powered on, this will have no effect.

Authorization requirements:

Access to the project to which <node> is assigned (if any) or administrative access.

Possible Errors:

409, if the node's OBM is not enabled (see node_enable_obm).

node_power_status

GET /node/<node>/power_status

Returns the node's power status.

Response body:

[
    "power_status": "<IPMI chassis power status response>"
]

Response examples: "on" or "off" for IPMI, or "Mock Status" for mock OBM.

Authorization requirements:

Access to the project to which <node> is assigned (if any) or administrative access.

Possible Errors:

409, if the node's OBM is not enabled (see node_enable_obm).

show_console

GET /node/<node>/<console

Stream output from the node's serial console.

The response body will be a byte stream from the node's serial console; streaming will continue until the connection is broken.

Only one client may be connected to a node's console in this fashion at a time; if a second client connects, the first will be disconnected.

The node's obm must be enabled; a BlockedError will be raised otherwise.

Authorization requirements:

Access to the project to which <node> is assigned (if any) or administrative access.

Possible Errors:

409, if the node's OBM is not enabled (see node_enable_obm).

list_nodes

GET /nodes/<is_free>

Return a list of all nodes or free/available nodes. The value of is_free can be all to return all nodes or free to return free/available nodes.

Response body:

[
    "node-1",
    "node-2",
    ...
]

Authorization requirements:

No special access

list_project_nodes

GET /project/<project>/nodes

List all nodes belonging to the given project

Response body:

[
    "node-1",
    "node-2",
    ...
]

Authorization requirements:

Access to <project> or administrative access

list_project_networks

GET /project/<project>/networks

List all networks belonging to the given project

Response body:

[
    "network-1",
    "network-2",
    ...
]

Authorization requirements:

Access to <project> or administrative access

show_node

GET /node/<node>

Show details of a node.

Returns a JSON object representing a node. The object will have at least the following fields:

"name", the name/label of the node (string).
"project", the name of the project a node belongs to or null if the node does not belong to a project
"nics", a list of nics, each represented by a JSON object having at least the following fields:
- "label", the nic's label.
- "macaddr", the nic's mac address.
- "networks", a JSON object describing what networks are attached to the nic. The keys are channels and the values are the names of networks attached to those channels.
- "port", the port to which the nic is connected to or null if the nic is not connected to any port. This field is only visibile if the caller is an admin.
- "switch", the switch that has the port to which the nic is connected to or null if the nic is not connected to any port. Just like port, this is only visible if the caller is an admin.
"metadata", a dictionary of metadata objects

Response body when run by a non-admin user:

{
    "metadata": {
        "EK": "pk"
    },
    "name": "node1",
    "nics": [
        {
            "label": "nic1",
            "macaddr": "01:23:45:67:89",
            "networks": {
                "vlan/235": "storage",
                "vlan/native": "pxe"
            }
        },
        {
            "label": "nic2",
            "macaddr": "12:34:56:78:90",
            "networks": {}
        }
    ],
    "project": "project1"
}

Response body when run by an admin:

{
    "metadata": {
        "EK": "pk"
    },
    "name": "node1",
    "nics": [
        {
            "label": "nic1",
            "macaddr": "01:23:45:67:89",
            "networks": {
                "vlan/235": "storage",
                "vlan/native": "pxe"
            },
            "port": "gi1/0/1",
            "switch": "dell-01"
        },
        {
            "label": "nic2",
            "macaddr": "12:34:56:78:90",
            "networks": {},
            "port": null,
            "switch": null
        }
    ],
    "project": "project1"
}

Authorization requirements:

If the node is free, no special access is required.
Otherwise, access to the project to which <node> is assigned is required.
Admin acces to view port and switch information.

Projects

project_create

PUT /project/<project>

Create a project named <project>

Authorization requirements:

Administrative access.

Possible Errors:

409, if the project already exists

project_delete

DELETE /project/<project>

Delete the project named <project>

Authorization requirements:

Administrative access.

Possible Errors:

409, if:
- The project does not exist
- The project still has resources allocated to it:
  - nodes
  - networks
  - headnodes

project_connect_node

POST /project/<project>/connect_node

Request body:

{
    "node": <node>
}

Reserve the node named <node> for use by <project>. The node must be free.

Authorization requirements:

Access to <project> or administrative access.

Possible errors:

404, if the node or project does not exist.
409, if the node is not free.

project_detach_node

POST /project/<project>/detach_node

{
    "node": <node>
}

Return <node> to the free pool. <node> must belong to the project <project>. It must not be attached to any networks, or have any pending network actions.

If a maintenance pool is configured, the maintenance service will be notified and the node will be moved into the maintenance project. Otherwise, the node will go directly to the free pool. Read docs/maintenance-pool.md for more information.

Authorization requirements:

Access to <project> or administrative access.

Possible errors

409, if the node is attached to any networks, or has pending network actions, or if the node's obm is enabled.

list_projects

GET /projects

Return a list of all projects in HIL

Response body:

[
    "manhattan",
    "runway",
    ...
]

Authorization requirements:

Administrative access.

node_set_metadata

PUT /node/<node>/metadata/<label>

Request Body:

{
    "value": <value>
}

Set metadata with <label> and <value> on <node>.

Authorization requirements:

Administrative access.

node_delete_metadata

DELETE /node/<node>/metadata/<label>

Delete metadata with <label> on <node>.

Authorization requirements:

Administrative access.

Headnodes

headnode_create

PUT /headnode/<headnode>

Request body:

{
    "project": <project>,
    "base_img": <base_img>
}

Create a headnode owned by project <project>, cloned from base image <base_img>. <base_img> must be one of the installed base images.

Authorization requirements:

Access to <project> or administrative access

Possible errors:

409, if a headnode named <headnode> already exists

headnode_delete

DELETE /headnode/<headnode>

Delete the headnode named <headnode>.

Authorization requirements:

Access to the project which owns <headnode> or administrative access.

headnode_start

POST /headnode/<headnode>/start

Start (power on) the headnode. Note that once a headnode has been started, it cannot be modified (adding/removing hnics, changing networks), only deleted --- even if it is stopped.

Authorization requirements:

Access to the project which owns <headnode> or administrative access.

headnode_stop

POST /headnode/<headnode>/stop

Stop (power off) the headnode. This does a force power off; the VM is not given the opportunity to shut down cleanly.

Authorization requirements:

Access to the project which owns <headnode> or administrative access.

headnode_create_hnic

PUT /headnode/<headnode>/hnic/<hnic>

Create an hnic named <hnic> belonging to <headnode>. The headnode must not have previously been started.

Authorization requirements:

Access to the project which owns <headnode> or administrative access.

Possible errors:

409, if:
- The headnode already has an hnic by the given name.
- The headnode has already been started.

headnode_delete_hnic

DELETE /headnode/<headnode>/hnic/<hnic>

Delete the hnic named <hnic> and belonging to <headnode>. The headnode must not have previously been started.

Authorization requirements:

Access to the project which owns <headnode> or administrative access.

Possible errors:

409, if the headnode has already been started.

headnode_connect_network

POST /headnode/<headnode>/hnic/<hnic>/connect_network

Request body:

{
    "network": <network>
}

Connect the network named <network> to <hnic>.

<network> must be the name of a network which:

the headnode's project has the right to attach to, and
was not assigned a specific network id by an administrator (i.e. the network id was allocated dynamically by HIL). This constraint is due to an implementation limitation, but will likely be lifted in the future; see issue #333.

Additionally, the headnode must not have previously been started.

Note that, unlike nodes, headnodes may only be attached via the native/default channel (which is implicit, and may not be specified).

Rationale: separating headnodes from hil core is planned, and it has been deemed not worth the development effort to adjust this prior to the separation. Additionally, headnodes may have an arbitrary number of nics, and so being able to attach two networks to the same nic is not as important.

Authorization requirements:

Access to the project which owns <headnode> or administrative access.
Either <network> must be public, or its "access" field must name the project which owns <headnode>.

Possible errors:

409, if the headnode has already been started.

headnode_detach_network

POST /headnode/<headnode>/hnic/<hnic>/detach_network

Detach the network attached to <hnic>. The headnode must not have previously been started.

Authorization requirements:

Access to the project which owns <headnode> or administrative access.

Possible errors:

409, if the headnode has already been started.

list_project_headnodes

GET /project/<project>/headnodes

Get a list of names of headnodes belonging to <project>.

Response body:

[
    "<headnode1_name>",
    "<headnode2_name>",
    ...
]

Authorization requirements:

Access to <project> or administrative access.

show_headnode

GET /headnode/<headnode>

Get information about a headnode. Includes the following fields:

"name", the name/label of the headnode (string).
"project", the project to which the headnode belongs.
"hnics", a JSON array of hnic names that are attached to this headnode.
"vncport", the vnc port that the headnode VM is listening on; this value can be null if the VM is powered off or has not been created yet.
"uuid", UUID for the headnode.
"base_img", the os image that the headnode is running.

Response body:

{
    "name": <headnode>,
    "project": <projectname>,
    "nics": [<nic1>, <nic2>, ...],
    "vncport": <port number>,
    "uuid": <headnode uuid>,
    "base_img": <headnode base_img>
}

Authorization requirements:

Access to the project which owns <headnode> or administrative access.

Switches

show_switch

GET /switch/<switch>

View detailed information about <switch>.

The result must contain the following fields:

"name", the name of the switch
"ports", a list of the name of the ports which exist on the switch

Response body (on success):

{
    "name": <switch>,
    "ports": <ports-list>
}

Authorization requirements:

Administrative access.

switch_register

Register a network switch of type <type>

<type> (a string) is the type of network switch. The possible values depend on what drivers HIL is configured to use. The remainder of the fields are driver-specific; see the documentation for the driver in question (in docs/network-drivers.md.

PUT /switch/<switch>

Request body:

{
    "type": <type>,
    (extra args; depends on <type>)
}

Authorization requirements:

Administrative access.

Possible Errors:

409, if a switch named <switch> already exists.

switch_delete

DELETE /switch/<switch>

Delete the switch named <switch>.

Prior to deleting a switch, all of the switch's ports must first be deleted.

Authorization requirements:

Administrative access.

Possible Errors:

409, if not all of the switch's ports have been deleted.

list_switches

GET /switches

Return a list of all switches registered in HIL

Response body:

[
    "switch1",
    "hickory",
    ...
]

Authorization requirements:

Administrative access.

switch_register_port

PUT /switch/<switch>/port/<port>

Register a port <port> on <switch>.

The permissible values of <port>, and their meanings, are switch specific; see the documentation for the appropriate driver for more information.

Authorization requirements:

Administrative access.

Possible Errors:

409, if the port already exists

switch_delete_port

DELETE /switch/<switch>/port/<port>

Delete the named <port> on <switch>.

Prior to deleting a port, any nic attached to it must be removed.

Authorization requirements:

Administrative access.

Possible Errors:

409, if there is a nic attached to the port.

port_connect_nic

POST /switch/<switch>/port/<port>/connect_nic

Request body:

{
    "node": <node>,
    "nic": <nic>
}

Connect a port a node's nic.

Authorization requirements:

Administrative access.

Possible errors:

404, if no port is connected to the given nic.
409, if the nic or port is already attached to something.

port_detach_nic

POST /switch/<switch>/port/<port>/detach_nic

Detach the nic attached to <port>.

Authorization requirements:

Administrative access.

Possible errors:

404, if the port is not attached to a nic
409, if the port is attached to a node which is not free.

port_revert

POST /switch/<switch>/port/<port>/revert

Detach the port from all networks. This is an asynchronous call. It's a good idea to check the status using the show_networking_action API before queuing any new actions on the same port.

Response body:

{
    "status_id": <unique_id>,
}

Authorization requirements:

Administrative access.

Possible errors:

404, if there is no nic attached to port
409, if there is already a networking action pending on port

show_port

GET /switch/<switch>/port/<port>

Show the node and nic to which the port is connected.

Response body:

{
    "node": "mynode",
    "nic": "mynic",
    "networks": {"vlan/1511": "mynetwork"}
}

If there is no nic attached to a port, the response body is just an empty json object:

{}

Authorization requirements:

Administrative access.

Possible errors:

404, if the switch and/or port do not exist.

list_active_extensions

GET /active_extensions

Response Body:

[ "hil.ext.switches.mock", "hil.ext.network_allocators.null", ... ]

List all active extensions.

Authorization requirements:

Administrative access.

API Extensions

API calls provided by specific extensions. They may not exist in all configurations.

The `hil.ext.auth.database` auth backend

list_users

GET /auth/basic/users

List all users

Response body:

{
    'hil_user': {'is_admin': True, 'projects': ["runway"]}
    'mock_user': {'is_admin': False, 'projects': ["manhattan"]}
}

Authorization requirements:

Administrative access.

user_create

PUT /auth/basic/user/<username>

Request body:

{
    "password": <plaintext-password>
    "is-admin": <boolean> (Optional, defaults to False)
}

Create a new user whose password is <plaintext-password>.

Authorization requirements:

Administrative access.

Possible errors:

409, if the user already exists

user_delete

DELETE /auth/basic/user/<username>

Delete the user whose username is <username>

Authorization requirements:

Administrative access.

user_set_admin

'PATCH /auth/basic/user/'

Request Body:

{ 'is_admin': }

Set admin status of user '' to true (admin user) or false (regular user)

Authorization requirements:

Administrative access.

Possible errors:

404, if the user does not exist.
409, if the user tries to set own admin privilege

user_add_project

POST /auth/basic/user/<user>/add_project

Request Body:

{ "project": <project_name> }

Add a user to a project.

Authorization requirements:

Administrative access.

user_remove_project

POST /auth/basic/user/<user>/remove_project

Request Body:

{ "project": <project_name> }

Remove a user from a project.

Authorization requirements:

Administrative access.

show_networking_action

GET /networking_action/<status_id>

Get the status of the networking call queued by node_connect_network, node_detach_network, or port_revert, where <status_id> is returned by any of the network calls.

Response Body:

{ "status": , "node": , "nic": , "new_network": "type": "channel": }

where:

status can either be "DONE", "PENDING", or "ERROR".
new_network can be null in case of node_detach_network or revert_port.
type can be revert_port or modify_port.
channel could be '' in case of revert_port.

The status of a networking call is kept until a new action on the same nic is added, after which the old entry is deleted.

Authorization requirements:

Access to the project which owns the node that has the nic on which the networking action is active, or administrative access.

Possible errors:

404, if the status_id is not found.

Files

rest_api.md

Latest commit

History

rest_api.md

File metadata and controls

Overview

Objects in the HIL

API design philosophy

API Reference

How to read

my_api_call

Core API Specification

Networks

network_create

network_delete

show_network

Channel Formats

802.1q VLAN based drivers

list_networks

list_network_attachments

network_grant_project_access

network_revoke_project_access

node_connect_network

node_detach_network

Nodes

node_register

node_delete

node_register_nic

node_delete_nic

node_enable/disable_obm

node_power_cycle

node_set_bootdev

For IPMI devices

node_power_off

node_power_on

node_power_status

show_console

list_nodes

list_project_nodes

list_project_networks

show_node

Projects

project_create

project_delete

project_connect_node

project_detach_node

list_projects

node_set_metadata

node_delete_metadata

Headnodes

headnode_create

headnode_delete

headnode_start

headnode_stop

headnode_create_hnic

headnode_delete_hnic

headnode_connect_network

headnode_detach_network

list_project_headnodes

show_headnode

Switches

show_switch

switch_register

switch_delete

list_switches

switch_register_port

switch_delete_port

port_connect_nic

port_detach_nic

port_revert

show_port

list_active_extensions

API Extensions

The hil.ext.auth.database auth backend

list_users

user_create

user_delete

user_set_admin

user_add_project

The `hil.ext.auth.database` auth backend