Browse Source

Add docs on what not to include in notifications

Based on bug 1823104 it's clear we should have some
explicit wording in the notification reference docs
about what not to include in versioned notification
payloads, so this change attempts to start that with
the most obvious thing - don't expose access credentials
to the nova deployment.

This also adds a reminder to think about what is being
added / mirrored from internal objects and determine if
consumers really need it and if they aren't asking, opt
to not including it until requested.

Change-Id: I326aa39d963091282a5d0b70ba222abfe8ccfdac
Related-Bug: #1823104
changes/20/650020/1
Matt Riedemann 4 months ago
parent
commit
8856009445
1 changed files with 17 additions and 0 deletions
  1. 17
    0
      doc/source/reference/notifications.rst

+ 17
- 0
doc/source/reference/notifications.rst View File

@@ -333,11 +333,28 @@ requires the notification.
333 333
   object and use the SCHEMA field to map the internal object to the
334 334
   notification payload. This way the evolution of the internal object model
335 335
   can be decoupled from the evolution of the notification payload.
336
+
337
+  .. important:: This does not mean that every field from internal objects
338
+                 should be mirrored in the notification payload objects.
339
+                 Think about what is actually needed by a consumer before
340
+                 adding it to a payload. When in doubt, if no one is requesting
341
+                 specific information in notifications, then leave it out until
342
+                 someone asks for it.
343
+
336 344
 * The delete notification should contain the same information as the create or
337 345
   update notifications. This makes it possible for the consumer to listen only to
338 346
   the delete notifications but still filter on some fields of the entity
339 347
   (e.g. project_id).
340 348
 
349
+What should **NOT** be in the notification payload
350
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
351
+
352
+* Generally anything that contains sensitive information about the internals
353
+  of the nova deployment, for example fields that contain access credentials
354
+  to a cell database or message queue (see `bug 1823104`_).
355
+
356
+.. _bug 1823104: https://bugs.launchpad.net/nova/+bug/1823104
357
+
341 358
 Existing versioned notifications
342 359
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
343 360
 

Loading…
Cancel
Save