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
Matt Riedemann 8 months ago
1 changed files with 17 additions and 0 deletions
  1. +17

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

@@ -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:

Existing versioned notifications