diff --git a/specs/backlog/event-subscription.rst b/specs/backlog/event-subscription.rst new file mode 100644 index 00000000..67270cb7 --- /dev/null +++ b/specs/backlog/event-subscription.rst @@ -0,0 +1,371 @@ +.. + This work is licensed under a Creative Commons Attribution 3.0 Unported + License. + + http://creativecommons.org/licenses/by/3.0/legalcode + + +=================== +BMC event framework +=================== + +https://storyboard.openstack.org/#!/story/2008366 + +The goal of this spec is to provide an API to manage subscriptions for BMC +events. The user will be able to provide a URL where the BMC will post the +events. + +Non-goals: +* Unify event formats or payloads across drivers. + +* Provide a way to poll for events. + +* Proxy notifications (see [RFE 2008555](https://storyboard.openstack.org/#!/story/2008555)). + +* Store events in ironic at all. + +* Update an existing subscription in the BMC, at this time, as some vendors + support partial updates where as other vendors essentially require a + delete/re-creation to perform an update. This may be something that can + be added later, but it seems not feasible at this time. + +* Choosing EventTypes when creating a subscription won't be supported, + since option is deprecated since [EventDestination v1_5_0](https://redfish.dmtf.org/schemas/v1/EventDestination.v1_5_0.json). + +* Support for creating subscriptions with HTTP Headers. + +Problem description +=================== + +Some BMC's have support to subscribe to specific event notifications about the +hardware (e.g., overheating, removal of the device). + +* As an ironic user, I want to configure the BMC to send event notifications + about potential failures to a specific URI. + +Proposed change +=============== + +Overview +-------- + +This RFE proposes a new top level ReST API `subscriptions` that will allow +listing, creating and deleting subscriptions for nodes. + +Subscriptions workflow +---------------------- + +#. Create a subscription ``POST /v1/nodes//management/`` + ``subscriptions`` + +#. Delete a subscription ``DELETE /v1/nodes//management/`` + ``subscriptions/`` + +#. List subscriptions ``GET /v1/nodes//management/subscriptions`` + +#. Show subscription ``GET /v1/nodes//management/subscriptions/`` + ```` + + +Alternatives +------------ + +The user can directly access the BMC and configure the subscriptions. + + +Data model impact +----------------- + +None. + +State Machine Impact +-------------------- + +None. + +REST API impact +--------------- + +Update the REST API for the node object to allow create/delete/list +event subscriptions. + +* ``GET /v1/nodes//management/subscriptions`` + + Retrieves a list of all subscriptions available. + Returns a JSON object listing all available subscriptions or + empty list. + + Error codes: + + * 404 - Node Not Found / microversion not high enough for API consumer. + + Example response object: + + .. code-block:: json + + { + "subscriptions": [ + { + "id": "", + "links": [ + { + "href": "http://127.0.0.1:6486/v1/nodes//management/ + subscriptions/", + "rel": "self" + }, + { + "href": "http://127.0.0.1:6486/nodes//management/ + subscriptions/", + "rel": "bookmark" + } + ] + }, + { + "id": "", + "links": [ + { + "href": "http://127.0.0.1:6486/v1/nodes//management/ + subscriptions/", + "rel": "self" + }, + { + "href": "http://127.0.0.1:6486/nodes//management/ + subscriptions/", + "rel": "bookmark" + } + ] + }, + ] + } + + +* ``GET /v1/nodes//management/subscriptions/subscription_bmc_id`` + + Retrieves a sbuscription. Returns a JSON object representing the choosen + subscription (``subscription_bmc_id``). + + Error codes: + + * 404 Not Found if node or subscription is not found. + + .. code-block:: json + + { + "id": "", + "destination": "", + "protocol": "", + "context": "", + "event_types": ["Alert"] + } + +* ``POST /v1/nodes//management/subscriptions`` + + Requests the creation of a subscription. + + * Required: `destination`. + + + HTTP codes: + + * 201 Created + * 400 Bad Request + + .. code-block:: json + + { + "destination": "http(s)://host/path", + } + +* ``DELETE /v1/nodes//management/subscriptions/ + `` + + Requests the deletion of a subscription + + HTPP codes: + + * 204 No Content + * 404 Not Found + +.. note:: + The PATCH verb is not being supported at this time in this feature. + +Client (CLI) impact +------------------- + +The following commands will be created: + +.. code-block:: bash + + baremetal node create subscription [node_uuid] [destination] + baremetal node subscription delete [subscription_uuid] + baremetal node subscription list [node] + baremetal node subscription show [node] [subscription_uuid] + +"openstacksdk" +~~~~~~~~~~~~~~ + +Add support for the event subscriptions in openstacksdk. + +RPC API impact +-------------- + +The following new RPC calls will be added: + +* Create subscription + + .. code-block:: python + + def create_subscription(self, context, node_id, destination, topic=None): + +* Delete subscription + + .. code-block:: python + + def delete_subscription(self, context, node_id, subscription_bmc_id, topic=None): + +* List subscriptions + + .. code-block:: python + + def get_all_subscriptions(self, context, node_id, topic=None): + +* Get a subscription + + .. code-block:: python + + def get_subscription(self, context, node_id, subscription_bmc_id, topic=None): + +Driver API impact +----------------- + +The `ManagementInterface` will be updated with the following functions: + +.. code-block:: python + + def create_subscription(self, task, destination): + """Add the new subscription object to the BMC.""" + + def delete_subscription(self, task, subscription_bmc_id): + """Remove the subscription from the BMC.""" + + def get_all_subscriptions(self, task): + """List all subscriptions from the BMC""" + + def get_subscriptions(self, task, subscription_bmc_id): + """Get a subscriptions from the BMC""" + + +The above methods are implemented for Redfish hardware types. +We will disallow changing the management interface of a node if there are +any subscriptions. + +Nova driver impact +------------------ + +None. + +Ramdisk impact +-------------- + +None. + +Security impact +--------------- + +It is recomended to use https. + +Other end user impact +--------------------- + +The user won't be able to choose the ``EventTypes`` for the subscription, +since the option is deprecated in Redfish EventDestination v1_5_0. +We will be using `Alert` by default for the ``EventTypes``. + +The user won't be able to choose the ``Protocol`` for the subscription, +by default it will be `Redfish` following the schema for EventDestination. + +Scalability impact +------------------ + +None. + +Performance Impact +------------------ + +None. + +Other deployer impact +--------------------- + +None. + +Developer impact +---------------- + +Other drivers may implement this feature if the BMC has support for +event subscription. + +Implementation +============== + +Assignee(s) +----------- + +Primary assignee: + + +Redfish Implementation Details +------------------------------ + +The actual support for EventDestination in sushy is based on schema [2]_, +since HW vendors are still working on adding support for newer versions where +the propertie ``EventTypes`` is deprecated. Based on this the Ironic API +will only accept the following redfish properties to create a subscription: + +* Destination - Required + +By default we are considering ``Protocol`` as `Redfish`, ``EventTypes`` as +`["Alert"]` and ``Context`` as `""`. + +When vendors have the support for newer EventDestination new fields will be +added to the Ironic API. + +Work Items +---------- + +* Add support for Events Subscriptions in sushy [1]_ [2]_. +* Add event subscription support to ManagementInterface +* Add event subscription support to redfish hardware type +* Add RPC for event subscriptions +* Add REST API for event subscriptions + + +Dependencies +============ + +None. + +Testing +======= + +* Unit Tests +* Tempest tests + + +Upgrades and Backwards Compatibility +==================================== + +No upgrade impact. + + +Documentation Impact +==================== + +* API reference will be added +* Client documentation will be added. + +References +========== + +.. [1] https://redfish.dmtf.org/schemas/v1/EventService.v1_0_8.json +.. [2] https://redfish.dmtf.org/schemas/v1/EventDestination.v1_0_0.json