Internal API spec
This is my attempt at whipping up some internal API calls for Crushil, there's some assumptions in here we should talk about. Hopefully this will also be a good place to keep track of the internal API in general. Change-Id: I59f3706190d0abed2997a8302717308ea5974ac5
This commit is contained in:
parent
111630aa07
commit
9d40c88d0e
|
@ -0,0 +1,312 @@
|
||||||
|
..
|
||||||
|
This work is licensed under a Creative Commons Attribution 3.0 Unported
|
||||||
|
License.
|
||||||
|
|
||||||
|
http://creativecommons.org/licenses/by/3.0/legalcode
|
||||||
|
|
||||||
|
==========================================
|
||||||
|
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
|
||||||
|
---------------------
|
||||||
|
|
||||||
|
Aside from the API, are there other ways a user will interact with this
|
||||||
|
feature?
|
||||||
|
|
||||||
|
* Does this change have an impact on python-cyborgclient? What does the user
|
||||||
|
interface there look like?
|
||||||
|
|
||||||
|
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)
|
||||||
|
-----------
|
||||||
|
|
||||||
|
Who is leading the writing of the code? Or is this a blueprint where you're
|
||||||
|
throwing it out there to see who picks it up?
|
||||||
|
|
||||||
|
If more than one person is working on the implementation, please designate the
|
||||||
|
primary author and contact.
|
||||||
|
|
||||||
|
Primary assignee:
|
||||||
|
<launchpad-id or None>
|
||||||
|
|
||||||
|
Other contributors:
|
||||||
|
<launchpad-id or None>
|
||||||
|
|
||||||
|
Work Items
|
||||||
|
----------
|
||||||
|
|
||||||
|
Work items or tasks -- break the feature up into the things that need to be
|
||||||
|
done to implement it. Those parts might end up being done by different people,
|
||||||
|
but we're mostly trying to understand the timeline for implementation.
|
||||||
|
|
||||||
|
|
||||||
|
Dependencies
|
||||||
|
============
|
||||||
|
|
||||||
|
* Include specific references to specs and/or blueprints in cyborg, or in other
|
||||||
|
projects, that this one either depends on or is related to.
|
||||||
|
|
||||||
|
* If this requires functionality of another project that is not currently used
|
||||||
|
by Cyborg, document that fact.
|
||||||
|
|
||||||
|
* Does this feature require any new library dependencies or code otherwise not
|
||||||
|
included in OpenStack? Or does it depend on a specific version of library?
|
||||||
|
|
||||||
|
|
||||||
|
Testing
|
||||||
|
=======
|
||||||
|
|
||||||
|
Please discuss the important scenarios needed to test here, as well as
|
||||||
|
specific edge cases we should be ensuring work correctly. For each
|
||||||
|
scenario please specify if this requires specialized hardware, a full
|
||||||
|
OpenStack environment, or can be simulated inside the Cyborg tree.
|
||||||
|
|
||||||
|
Please discuss how the change will be tested. We especially want to know what
|
||||||
|
tempest tests will be added. It is assumed that unit test coverage will be
|
||||||
|
added so that doesn't need to be mentioned explicitly, but discussion of why
|
||||||
|
you think unit tests are sufficient and we don't need to add more tempest
|
||||||
|
tests would need to be included.
|
||||||
|
|
||||||
|
Is this untestable in gate given current limitations (specific hardware /
|
||||||
|
software configurations available)? If so, are there mitigation plans (3rd
|
||||||
|
party testing, gate enhancements, etc).
|
||||||
|
|
||||||
|
|
||||||
|
Documentation Impact
|
||||||
|
====================
|
||||||
|
|
||||||
|
Which audiences are affected most by this change, and which documentation
|
||||||
|
titles on docs.openstack.org should be updated because of this change? Don't
|
||||||
|
repeat details discussed above, but reference them here in the context of
|
||||||
|
documentation for multiple audiences. For example, the Operations Guide targets
|
||||||
|
cloud operators, and the End User Guide would need to be updated if the change
|
||||||
|
offers a new feature available through the CLI or dashboard. If a config option
|
||||||
|
changes or is deprecated, note here that the documentation needs to be updated
|
||||||
|
to reflect this specification's change.
|
||||||
|
|
||||||
|
References
|
||||||
|
==========
|
||||||
|
|
||||||
|
Please add any useful references here. You are not required to have any
|
||||||
|
reference. Moreover, this specification should still make sense when your
|
||||||
|
references are unavailable. Examples of what you could include are:
|
||||||
|
|
||||||
|
* Links to mailing list or IRC discussions
|
||||||
|
|
||||||
|
* Links to notes from a summit session
|
||||||
|
|
||||||
|
* Links to relevant research, if appropriate
|
||||||
|
|
||||||
|
* Related specifications as appropriate (e.g. if it's an EC2 thing, link the
|
||||||
|
EC2 docs)
|
||||||
|
|
||||||
|
* Anything else you feel it is worthwhile to refer to
|
||||||
|
|
||||||
|
|
||||||
|
History
|
||||||
|
=======
|
||||||
|
|
||||||
|
Optional section intended to be used each time the spec is updated to describe
|
||||||
|
new design, API or any database schema updated. Useful to let reader understand
|
||||||
|
what's happened along the time.
|
||||||
|
|
||||||
|
.. list-table:: Revisions
|
||||||
|
:header-rows: 1
|
||||||
|
|
||||||
|
* - Release Name
|
||||||
|
- Description
|
||||||
|
* - Pike
|
||||||
|
- Introduced
|
Loading…
Reference in New Issue