Hi Steven,
(Sorry for fat fingers sending an unfinished draft of the mail earlier)
On Sun, 2011-08-21 at 14:38 -0700, Steven Dake wrote:
As has been previously discussed on this mailing list and irc, there
are
gaps between what deltacloud provides and what higher level management
systems (such as Aeolus) have interest. Deltacloud provides a great
low-level interface to various cloud providers objects, but doesn't
enforce any particular policy or organization on these low level objects.
In the Aeolus project we are interested in enforcing organization and
policy. The question becomes do we want to create a coherent set of
APIs that model the Aeolus system. My answer to this is yes, we do, and
to kick that process off, I'll propose a few APIs that we need exposed
from aeolus to support the pacemaker-cloud[1] project.
What pacemaker cloud needs today:
1 notifications that third parties modify a deployable state
1.1 A deployable was detected faulty by a third party
1.2 An assembly was detected faulty by a third party
1.3 A deployable was started by a third party
1.4 A deployable was stopped by a third party
2 third party notification involving deployable state monitoring
2.1 Active monitoring has determined that an assembly has failed
2.2 Active monitoring has determined that a deployable has failed
I think you're missing a lot of background here. The basic idea is that
conductor knows the state of deployments/instances and pacemaker wants
to be notified of state changes? Pacemaker will have policy around how
to react to state changes, e.g. it may restart an instance if it goes
down?
A proposed API model follows:
It looks like you're aiming for this to be a RESTful API, so I'll make
some suggestions based on that assumption
Also, this looks very much like an API for managing web hooks
(
webhooks.org) so I'd stick with the "hook" terminology and try to learn
lessons from other web hook management APIs
Exported from the management system
-----------------------------------
POST api/monitors/add
Add a third party monitor to a list of monitors maintained by the
management system
In RESTful API design terms, monitors are resources and you're modelling
the creation of a new monitor resource in the monitors collection
You don't need to encode "add" in the URI, that's implicit in the HTTP
POST method
inputs: internet protocol address, port, and version of a third
party
software component implementing the monitoring API
RESTful APIs are all about the representation of resources, so you
should be POSTing a (XML/JSON/whatever) representation of the resource
to the collection
outputs: monitor identifier and success or failure
Identifiers for resources in RESTful APIs are URIs. You'd return the URI
of the newly created resource using the Location: header
And failure/success of any HTTP method should be indicated using HTTP
status codes
Also, the POST response should contain a representation of the newly
created resource
Bringing all that together, I'd suggest:
POST /api/hooks HTTP/1.1
Content-type: application/xml
Accept: application/xml
<hook>
<
uri>http://thirdpartymonitor.org/api/event</uri>
</hook>
HTTP/1.1 201 Created
Location:
http://myconductor.org/api/hooks/f1e349df
Content-type: application/xml
<hook id="f1e349df" href="/api/hooks/f1e349df">
<
uri>http://thirdpartymonitor.org/api/events</uri>
</hook>
> POST api/monitors/remove
>
> Remove a third party monitor from the list of monitors maintained by the
> management system
>
> inputs: internet protocol address, port, version, and identifier of a
> third party software component implementing the monitoring API
>
outputs: monitor identifier and success or failure
This should simply be:
DELETE /api/hooks/f1e349df HTTP/1.1
HTTP/1.1 204 No Content
GET api/monitors/list
Retrieve a list of third party monitors from the management system
inputs: version
outputs: list of monitors including internet protocol address, port, and
version
This would be:
GET /api/hooks HTTP/1.1
Accept: application/xml
<hooks>
<hook id="f1e349df" href="/api/hooks/f1e349df">
<
uri>http://thirdpartymonitor.org/api/events</uri>
</hook>
<hook id="290ceba7" href="/api/hooks/290ceba7">
<
uri>http://thirdpartymonitor.org/api/events</uri>
</hook>
...
</hooks>
POST api/monitors/deployable/id
inputs: version and START DETECTED or FAIL DETECTED
outputs: success or fail
POST api/monitors/deployable/assembly/id
inputs: version and START DETECTED or FAIL DETECTED
outputs: success or fail
I'm not sure what you're modelling here - informing conductor that the
state of deployment or instance has changed?
That would be e.g.
PUT /api/instances/1bde3254 HTTP/1.1
Content-Type: application/xml
Accept: application/xml
<instance>
<state>FAILED</state>
</instance>
HTTP/1.1 200 OK
Content-Type: application/xml
<instance id="1bde3254" href="/api/instances/1bde3254">
<name>foo</name>
<state>FAILED</state>
....
</instance>
Or perhaps you meant this as an API for triggering hooks for test
purposes? In that case, I'd model it as creating a new event under a
hook:
POST /api/hooks/f1e349df/events HTTP/1.1
Content-type: application/xml
Accept: application/xml
<event>
<instance id="1bde3254"/>
<state>FAILED</state>
</hook>
HTTP/1.1 201 Created
Location:
http://myconductor.org/api/hooks/50634f21
Content-type: application/xml
<event id="50634f21"
href="/api/hooks/f1e349df/events/50634f21">
<instance id="1bde3254" href="/api/instances/1bde3254"/>
<state>FAILED</state>
</event>
Exported by the third party monitor API
---------------------------------------
POST api/deployable/id
inputs: version, deployment ID, and state (START DETECTED, FAIL
DETECTED, STOP DETECTED), deployable metadata
outputs: success or fail
POST api/deployable/assembly/id
inputs: version, assebmly ID, deployable metadata, and state (START
DETECTED, STOP DETECTED, FAIL DETECTED)
outputs: success or fail
I think we only need one entry-point here - a single URI where conductor
will POST a representation of an event to a third part app, so e.g.
POST /api/events HTTP/1.1
Content-Type: application/xml
<event>
<instance id="1bde3254"
href="http://myconductor.org/api/hooks/f1e349df/events/50634f21"...
<state>FAILED</state>
</hook>
HTTP/1.1 204 No Content
Cheers,
Mark.