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

Author: mriedem

doc/source/reference/notifications.rst

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