JSON Schema for versioned notifications

Registered by Balazs Gibizer on 2016-09-02

Versioned notifications in nova have a well defined schema implemented with
versioned objects. This schema prevents from changing the structure of the
notification without communicating the change to the notification consumers.
This communication is done via the version number embedded into the
notification payload. However this communication is limited and does not
contain information about what is changed in the schema or what is the
structure of a new notification.

Notification consumers can understand the structure of the notification payload
based on notification samples or based on the object model only.
If a notification payload is changed then the object model is updated. However
this information is hard to consume from software and the consumer shall not
depend on the object model of the service directly.

Also the consumer does not have an independent and automatic way to ensure that
the received notification has the expected structure without trying to consume
it.

The versioned notification transformation work [1] is progressing well in nova
and the JSONSchema work progressing well in o.vo [2]. We think that
nova can start providing JSONSchemas for the versioned notifications
to the notification consumers.

The following steps are planned for Ocata as part of this bp:
* Implement the get_schema() method for the nova specific o.vo fields similarly
  to how it was implemented to to the o.vo generic fields during [2].
* Implement a script under ./tools directory in nova that generates the JSONSchema
  of the exising versioned notification payload classes.
* Update the notification devref to contain the schemas as well.

[1] https://blueprints.launchpad.net/nova/+spec/versioned-notification-transformation-ocata
[2] https://review.openstack.org/#/q/branch:master+topic:bp/json-schema-for-versioned-object

Blueprint information

Status:
Started
Approver:
Matt Riedemann
Priority:
Low
Drafter:
Balazs Gibizer
Direction:
Needs approval
Assignee:
Balazs Gibizer
Definition:
Pending Approval
Series goal:
None
Implementation:
Blocked
Milestone target:
None
Started by
Matt Riedemann on 2016-12-27

Related branches

Sprints

Whiteboard

We agreed in the 2016/09/22 nova meeting that this could be approved without a spec since it's just a change to add the CLI tool for generating the schemas and the devref updates. There is nothing about this that's sending the schemas with the notifications. -- mriedem 20160922

What version of oslo.versionedobjects is needed for these changes on the nova side? I see several o.vo changes merged and released, but global-requirements for master only requires o.vo>=1.17.0 but some of the changes weren't released until 1.19.0, so doesn't the minimum required version in global-requirements need to be updated? Note that the final release for non-client (oslo) libraries is January 19th. -- mriedem 20161227

Gerrit topic: https://review.openstack.org/#q,topic:bp/json-schema-for-versioned-notifications,n,z

Addressed by: https://review.openstack.org/408737
    Create schema generation for NetworkModel

Addressed by: https://review.openstack.org/411836
    Create script that prints JSON Schema of Notification Payload Classes

Addressed by: https://review.openstack.org/418366
    Validate payload jsonschema in notification test

Addressed by: https://review.openstack.org/418479
    Removed duplicated _UNUSED enum in InstancePowerState Validation of the JSON schema fails when the enum has a duplicate

Marking as blocked on some oslo.versionedobjects changes. -- mriedem 20170112

We're now past the feature freeze for Ocata so I've deferred this to Pike. -- mriedem 20170128

I'm going to defer this to Queens when we can re-assess the state of the dependencies and priority for this work. -- mriedem 20170717

(?)

Work Items

Dependency tree

* Blueprints in grey have been implemented.

This blueprint contains Public information 
Everyone can see this information.

Subscribers

No subscribers.