1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
|
=============
Notifications
=============
Like many other OpenStack services, nova emits notifications to the message
bus with the ``Notifier`` class provided by :oslo.messaging-doc:`oslo.messaging
<reference/notifier.html>`. From the notification consumer point of view, a
notification consists of two parts: an envelope with a fixed structure defined
by oslo.messaging and a payload defined by the service emitting the
notification. The envelope format is the following::
{
"priority": <string, selected from a predefined list by the sender>,
"event_type": <string, defined by the sender>,
"timestamp": <string, the isotime of when the notification emitted>,
"publisher_id": <string, defined by the sender>,
"message_id": <uuid, generated by oslo>,
"payload": <json serialized dict, defined by the sender>
}
There are two types of notifications in nova: legacy notifications which have
an unversioned payload and newer notifications which have a versioned payload.
Legacy (unversioned) notifications
----------------------------------
The unversioned notifications exist from the early days of nova and have mostly
grown organically. The structure of the payload of the unversioned
notifications is defined in the code that emits the notification and no
documentation or enforced backward compatibility contract exists for that
format.
Nova code uses the ``nova.rpc.get_notifier`` call to get a configured
oslo.messaging ``Notifier`` object and it uses the oslo-provided functions on
the ``Notifier`` object to emit notifications. The configuration of the
returned ``Notifier`` object depends on the parameters of the ``get_notifier``
call and the value of the oslo.messaging configuration options
:oslo.config:option:`oslo_messaging_notifications.driver` and
:oslo.config:option:`oslo_messaging_notifications.topics`.
Versioned notifications
-----------------------
The versioned notification concept was created to fix the shortcomings of the
unversioned notifications. The envelope structure of the emitted notification
is the same as in the unversioned notification case as it is provided by
oslo.messaging. However, the payload is not a free-form dictionary but a
serialized :oslo.versionedobjects-doc:`oslo versionedobjects object <>`.
.. _service.update:
For example the wire format of the ``service.update`` notification looks like
the following::
{
"priority": "INFO",
"payload": {
"nova_object.namespace": "nova",
"nova_object.name": "ServiceStatusPayload",
"nova_object.version": "1.0",
"nova_object.data": {
"host": "host1",
"disabled": false,
"last_seen_up": null,
"binary": "nova-compute",
"topic": "compute",
"disabled_reason": null,
"report_count": 1,
"forced_down": false,
"version": 2
}
},
"event_type": "service.update",
"publisher_id": "nova-compute:host1"
}
The serialized oslo.versionedobject as a payload provides a version number to
the consumer so the consumer can detect if the structure of the payload has
changed. Nova provides the following contract regarding the versioned
notification payload:
* The payload version defined by the ``nova_object.version`` field of the
payload will be increased if and only if the syntax or the semantics of the
``nova_object.data`` field of the payload is changed.
* A minor version bump indicates a backward compatible change which means that
only new fields are added to the payload so a well written consumer can still
consume the new payload without any change.
* A major version bump indicates a backward incompatible change of the payload
which can mean removed fields, type change, etc in the payload.
* There is an additional field, ``nova_object.name``, for every payload
alongside the ``nova_object.data`` and ``nova_object.version`` fields. This
field contains the name of the nova internal representation of the payload
type. Client code should not depend on this name.
A `presentation from the Train summit`__ goes over the background and usage of
versioned notifications, and provides a demo.
.. __: https://www.openstack.org/videos/summits/denver-2019/nova-versioned-notifications-the-result-of-a-3-year-journey
Configuration
-------------
The :oslo.config:option:`notifications.notification_format` config option can
be used to specify which notifications are emitted by nova.
The versioned notifications are emitted to a different topic than the legacy
notifications. By default they are emitted to ``versioned_notifications`` but
this can be configured using the
:oslo.config:option:`notifications.versioned_notifications_topics` config
option.
There are notification configuration options in nova which are specific for
certain notification types like
:oslo.config:option:`notifications.notify_on_state_change`,
:oslo.config:option:`notifications.default_level`, etc.
Notifications can be disabled entirely by setting the
:oslo.config:option:`oslo_messaging_notifications.driver` config option to
``noop``.
Reference
---------
A list of all currently supported versioned notifications can be found in
:doc:`/reference/notifications`.
|
