e6f7425444
The POST /os-server-external-events API had the following confusing behavior: With multiple events in the payload, if *some* (but not all) were dropped, the HTTP response was 207, with per-event 4xx error codes in the payload. But if *all* of the events were dropped, the overall HTTP response was 404 with no payload. Thus, especially for consumers sending only one event at a time, it was impossible to distinguish e.g. "you tried to send an event for a nonexistent instance" from "the instance you specified hasn't landed on a host yet". This fix gets rid of that sweeping 404 condition, so if *any* subset of the events are dropped (including *all* of them), the HTTP response will always be 207, and the payload will always contain granular per-event error codes. This effectively means the API can no longer return 404, ever. Closes-Bug: #1855752 Change-Id: Ibad1b51e2cf50d00102295039b6e82bc00bec058
78 lines
2.2 KiB
ReStructuredText
78 lines
2.2 KiB
ReStructuredText
.. -*- rst -*-
|
|
|
|
====================================================
|
|
Create external events (os-server-external-events)
|
|
====================================================
|
|
|
|
.. warning::
|
|
This is an ``admin`` level service API only designed to be used by
|
|
other OpenStack services. The point of this API is to coordinate
|
|
between Nova and Neutron, Nova and Cinder, Nova and Ironic (and potentially
|
|
future services) on activities they both need to be involved in,
|
|
such as network hotplugging.
|
|
|
|
Unless you are writing Neutron, Cinder or Ironic code you **should not**
|
|
be using this API.
|
|
|
|
Creates one or more external events. The API dispatches each event to a
|
|
server instance.
|
|
|
|
Run Events
|
|
==========
|
|
|
|
.. rest_method:: POST /os-server-external-events
|
|
|
|
Creates one or more external events, which the API dispatches to the
|
|
host a server is assigned to. If the server is not currently assigned
|
|
to a host the event will not be delivered.
|
|
|
|
You will receive back the list of events that you submitted, with an
|
|
updated ``code`` and ``status`` indicating their level of success.
|
|
|
|
Normal response codes: 200, 207
|
|
|
|
A 200 will be returned if all events succeeded, 207 will be returned
|
|
if any events could not be processed. The ``code`` attribute for the
|
|
event will explain further what went wrong.
|
|
|
|
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
|
|
|
|
.. note:: Prior to the fix for `bug 1855752`_, error response code 404 may be
|
|
erroneously returned when all events failed.
|
|
|
|
.. _bug 1855752: https://bugs.launchpad.net/nova/+bug/1855752
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
|
|
- events: events
|
|
- name: event_name
|
|
- server_uuid: server_uuid
|
|
- status: event_status
|
|
- tag: event_tag
|
|
|
|
**Example Run Events**
|
|
|
|
.. literalinclude:: ../../doc/api_samples/os-server-external-events/event-create-req.json
|
|
:language: javascript
|
|
|
|
Response
|
|
--------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- events: events
|
|
- code: code
|
|
- name: event_name
|
|
- server_uuid: server_uuid
|
|
- status: event_status
|
|
- tag: event_tag
|
|
|
|
**Example Run Events**
|
|
|
|
.. literalinclude:: ../../doc/api_samples/os-server-external-events/event-create-resp.json
|
|
:language: javascript
|