API Documentation

There are a number of services that provide automation services for CORD. These services are written in the theme of Docker based micro(µ) services. Each runs independently in its own container and they consume the other µ services via REST API calls as well as provide a REST API through which other services can utilize their functions.

The current list of µ services are:

automation automates bare metal compute hosts through the MAAS deployment life cycle and invokes CORD specific provisioning
provisioner applies CORD specific provisioning to compute nodes and fabric switches
switchq identifies supported fabric switches and invokes CORD specific provisioning
allocator allocates IP addresses from a specified range to be used for interfaces attached to the leaf - spine fabric
harvester augments MAAS's DDNS capability to support all devices that request a DHCP address
config-generator generates a configuration file for the ONOS leaf - spine (segment routing) fabric

Automation

Docker image: cord-maas-automation

Configuration

|Command Line Flag|Default|Description| |-|-|- |-apikey|""|key with which to access MAAS server| |-maas|"http://localhost/MAAS"|url over which to access MAAS| |-apiVersion|"1.0"|version of the API to access| |-queryPeriod|"15s"|frequency the MAAS service is polled for node states| |-preview|false|displays the action that would be taken, but does not do the action, in this mode the nodes are processed only once| |-mappings|"{}"|the mac to name mappings| |-always-rename|true|attempt to rename at every stage of workflow| |-filter|'{"hosts":{"include":[".*"],"exclude":[]},"zones":{"include": ["default"],"exclude":[]}}'|constrain by hostname what will be automated|

REST Resources

None

Provisioner

Docker image: cord-provisioner

Configuration

REST Resources

|URI|Operation|Description| |-|-|-| |/provision/|POST|create a new provisioning request| |/provision/|GET|get a list of all provisioning requests and their state| |/provision/{id}|GET|get a single provisioning request and state| |/provision/{id}|DELETE|delete a provisioning request|

POST /provision/

POSTs to this URL will initiate a new provisioning request. This requests requires that a provisioning request object is sent as data to the request.

This request returns a 201 Accepted response, if the request was successfully queued for provisioning.

The request is a JSON objects with the following members:

Example:

{
    "id": "node-fe30a9c4-4a30-11e6-b7a3-002590fa5f58"
    "name": "lively-road.cord.lab",
    "ip": "10.2.0.16",
    "mac": "00:25:90:fa:5f:4f",
    "role_selector": "",
    "role": "",
    "script": "",
}

GET /provision/

Fetches the list of all provisioning requests and their state information. The result is a JSON array such as the example below:

[
  {
    "timestamp": 1469550527,
    "message": "",
    "status": 2,
    "worker": 2,
    "request": {
      "Role": "compute-node",
      "Script": "/etc/maas/ansible/do-ansible",
      "Info": {
        "script": "",
        "role": "",
        "role_selector": "",
        "mac": "00:25:90:fa:5f:53",
        "ip": "10.2.0.15",
        "name": "bitter-prison.cord.lab",
        "id": "node-fe205272-4a30-11e6-a48d-002590fa5f58"
      }
    }
  },
  {
    "timestamp": 1468544505,
    "message": "",
    "status": 2,
    "worker": 0,
    "request": {
      "Role": "fabric-switch",
      "Script": "/etc/maas/ansible/do-switch",
      "Info": {
        "script": "/etc/maas/ansible/do-switch",
        "role": "fabric-switch",
        "role_selector": "",
        "mac": "cc:37:ab:7c:ba:da",
        "ip": "10.2.0.5",
        "name": "leaf-2",
        "id": "cc:37:ab:7c:ba:da"
      }
    }
  }
]

GET /provision/{id}

Fetches the provisioning request and state for a single specified ID. The result is a single JSON object as described below:

{
  "timestamp": 1469550527,
  "message": "",
  "status": 2,
  "worker": 2,
  "request": {
    "Role": "compute-node",
    "Script": "/etc/maas/ansible/do-ansible",
    "Info": {
      "script": "",
      "role": "",
      "role_selector": "",
      "mac": "00:25:90:fa:5f:53",
      "ip": "10.2.0.15",
      "name": "bitter-prison.cord.lab",
      "id": "node-fe205272-4a30-11e6-a48d-002590fa5f58"
    }
  }
}

DELETE /provision/{id}

Removes a request from the provisioner. If the request is inflight the request will be completed before it is removed.

Switchq

** Docker image:** cord-maas-switchq

Configuration

REST Resources

None

Allocator

Docker image: cord-ip-allocator

Configuration

REST Resources

|URI|Operation|Description| |-|-|-| |/allocations/{mac}|DELETE|delete allocation for a specific MAC| |/allocations/{mac}|GET|return the allocation for a specific MAC| |/allocations/|GET|return the list of all allocations| |/addresses/{ip}|DELETE|delete the allocation associated with a specific IP|

DELETE /allocations/{mac}

If the specified MAC address is associated with an IP address this allocation / association is deleted.

GET /allocations/{mac}

Returns the IP address associated with the specified MAC, if no association exists then an IP address is allocated form the range, associated with the MAC, and returned.

|Name|Type|Description| |-|-|-| |Ip|string|IP address associated with the specified MAC| |MAC|string|MAC address|

Example:

{
  "Ip": "10.6.1.4",
  "Mac": "00:25:90:fa:5f:79"
}

GET /allocations/

Returns a list of all known MAC to IP associations.

|Name|Type|Description| |-|-|-| |Ip|string|IP address associated with the specified MAC| |MAC|string|MAC address|

Example:

[
  {
    "Ip": "10.6.1.4",
    "Mac": "00:25:90:fa:5f:79"
  },
  {
    "Ip": "10.6.1.2",
    "Mac": "00:25:90:fa:5f:53"
  },
  {
    "Ip": "10.6.1.3",
    "Mac": "00:25:90:fa:5f:4f"
  }
]

DELETE /allocations/{ip}

If the specified IP is associated with a MAC address this association is deleted.

Harvester

Docker image: cord-dhcp-harvester

Configuration

REST Resources

|URI|Operation|Description| |-|-|-| |/harvest|POST|Forces the service to perform an IP harvest against the DHCP server and update DNS|

POST /harvest

The service periodically harvests IP information from the specified DHCP server and updates DNS zones accordingly. This request force an harvest to be performed immediately.

config-generator

Docker image: cord-config-generator

Configuration

REST Resources

|URI|Operation|Description| |-|-|-| |/config/|POST|Generates and returns a CORD leaf - spine configuration file|

POST /config/

This request will interrogate the specified ONOS instance and if the expected number of switches and hosts are in ONOS it will then generate a configuration file suitable to use for the CORD leaf - spine fabric and return that to the caller.

example:

{
    "switchcount" : 4,
    "hostcount" : 4
}