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

|URI|Operation|Description| |-|-|-| |/switch/|GET|returns a list of all known switches|

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

|Environment Variable|Default|Description| |-|-|-| | HARVESTER_PORT | 4246 | port on which the service will listen for requests | | HARVESTER_LISTEN | 0.0.0.0 | IP on which the service will listen for requests | | HARVESTER_LOG_LEVEL | warning | log output level | | HARVESTER_LOG_FORMAT | text | format of log messages | | HARVESTER_DHCP_LEASE_FILE | /harvester/dhcpd.leases | lease file to parse for lease information | | HARVESTER_OUTPUT_FILE | | name of file to output discovered lease in bind9 format | | HARVESTER_OUTPUT_FORMAT | {{.ClientHostname}}\tIN A {{.IPAddress}}\t; {{.HardwareAddress}} | specifies the single entry format when outputing to a file | | HARVESTER_VERIFY_LEASES | true | verifies leases with a ping | | HARVESTER_VERIFY_TIMEOUT | 1s | max timeout (RTT) to wait for verification pings | | HARVESTER_VERIFY_WITH_UDP | false | use UDP instead of raw sockets for ping verification | | HARVESTER_QUERY_PERIOD | 30s | period at which the DHCP lease file is processed | | HARVESTER_QUIET_PERIOD | 2s | period to wait between accepting parse requests | | HARVESTER_REQUEST_TIMEOUT | 10s | period to wait for processing when requesting a DHCP lease database parsing | | HARVESTER_RNDC_UPDATE | false | determines if the harvester reloads the DNS servers after harvest | | HARVESTER_RNDC_ADDRESS | 127.0.0.1 | IP address of the DNS server to contact via RNDC | | HARVESTER_RNDC_PORT | 954 | port of the DNS server to contact via RNDC | | HARVESTER_RNDC_KEY_FILE | /key/rndc.conf.maas | key file, with default, to contact DNS server | | HARVESTER_RNDC_ZONE | cord.lab | zone to reload |

REST Resources

|URI|Operation|Description| |-|-|-| | /harvest | POST | Requests the processing of the DHCP lease database | | /lease | GET | Returns the list of DHCP leases harvested from the DHCP server | | /lease/{ip} | GET | Returns a single DHCP lease associated with the given IP | | /lease/hostname/{name} | GET | Returns a single DHCP lease associated with the given client hostname | | /lease/hardware/{mac} | GET | Returns a single DHCP lease associated with the given hardware addreaa |

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
}