5.1 KiB
Cyborg Internal API spec
This document loosely specifies the API calls between the components of Cyborg. Driver, Agent, Conductor, and API endpoint.
These API's are internal and therefore may change from version to version without warning or backwards compatibility. This document is kept as a developer reference to be edited before any internally braking changes are made.
Problem description
Developers writing one component of Cyborg need to know how to talk to another component of Cyborg, hopefully without having to go spelunking in the code of that component.
Use Cases
Happier Cyborg developers
Proposed change
Versioning internal API's
Alternatives
A mess
Data model impact
A fixed internal API should help keep data models consistent.
REST API impact
The API changes add resource endpoints to:
Driver:
- POST start accelerator discovery FROM: Agent
- GET get a list of discovered accelerators and their properties FROM: Agent
Agent:
- POST register driver FROM: Driver
- POST start accelerator discovery across all drivers FROM: Conductor
- GET get a list of all accelerators across all drivers FROM: Conductor
Conductor: * POST register agent FROM: Agent
The following new REST API call will be created:
Driver 'POST /discovery'
Trigger the discovery and setup process for a specific driver
Content-Type: application/json
{
"status":"IN-PROGRESS"
}
Driver 'GET /hardware'
Gets a list of hardware, not accelerators, accelerators are ready to use entires available by the public API. Hardware are physical devices on nodes that may or may not be ready to use or even fully supported.
200 OK
Content-Type: application/json
{
"hardware":[
{
"uuid":"8e45a2ea-5364-4b0d-a252-bf8becaa606e",
"acc_specs":
{
"remote":0,
"num":1,
"device_type":"CRYPTO"
"acc_capability":
{
"num":2
"ipsec":
{
"aes":
{
"3des":50,
"num":1,
}
}
}
}
"acc_status":
{
"setup_required":true,
"reboot_equired":false
}
}]
}
Driver 'POST /hello'
Registers that a driver has been installed on the machine and is ready to use. As well as it's endpoint and hardware support.
Content-Type: application/json
{
"status":"READY",
"endpoint":"localhost:1337",
"type":"CRYPTO"
}
Agent 'POST /discovery'
Trigger the discovery and setup process for all registered drivers
See driver example
Agent 'GET /hardware'
Get list of hardware across all drivers on the node
see driver example
Conductor 'POST /hello'
Registers that an Agent has been installed on the machine and is ready to use.
Content-Type: application/json
{
"status":"READY",
"endpoint":"compute-whatever:1337",
}
Security impact
Care must be taken to secure the internal endpoints from malicious calls
Notifications impact
N/A
Other end user impact
This change might have an impact on python-cyborgclient
Performance Impact
In this model the Agent takes care of wrangling however many drivers are on a compute and the Conductor takes care of wrangling all the agents to present a coherent answer to the API quickly and easily. I don't include API <-> Conductor calls yet because I assume the API will be for the most part working from the database while the Conductor tries to keep that database up to date and takes the occasional setup call.
Other deployer impact
In this model we won't really know when we're missing an agent. If one has reported in previously and then goes away we can have an alarm for that. But if an agent never reports in we just have to assume no instance exists by that name. This means making sure the Cyborg Drivers/Agent's are installed and running is the responsibility of the deployment tool.
Developer impact
More internal communication in Cyborg
Implementation
Assignee(s)
- Primary assignee:
-
jkilpatr
- Other contributors:
-
zhuli
Work Items
N/A
Dependencies
N/A
Testing
N/A
Documentation Impact
N/A
References
N/A
History
Release Name | Description |
---|---|
Queens | Introduced |