openstack/ironic
Code Issues Proposed changes

Add notification documentation to administrator's guide

Browse Source 
This moves the description of available notifications in ironic to the
administrator's guide and briefly describes how to configure
notifications. It also documents the message bus topic ironic
notifications are emitted on, since previously that required looking at
code to find out.

Related-Bug: #1526408
Change-Id: I4d5dfe92d2c2646a7cc803fa6ea7ade723aba310
This commit is contained in:
Mario Villaplana 2016-10-20 20:34:25 +00:00
parent 9eb148ad37
commit cb2971ba27
3 changed files with 206 additions and 178 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

191
doc/source/deploy/notifications.rst Normal file
View File

@ -0,0 +1,191 @@
.. _deploy-notifications:
=============
Notifications
=============
Ironic, when configured to do so, will emit notifications over a message bus
that indicate different events that occur within the service. These can be
consumed by any external service. Examples may include a billing or usage
system, a monitoring data store, or other OpenStack services. This page
describes how to enable notifications and the different kinds of notifications
that ironic may emit. The external consumer will see notifications emitted by
ironic as JSON objects structured in the following manner::
{
"priority": <string, defined 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>
}
Configuration
=============
To enable notifications with ironic, there are two configuration options in
ironic.conf that must be adjusted.
The first option is the ``notification_level`` option in the ``[DEFAULT]``
section of the configuration file. This can be set to "debug", "info",
"warning", "error", or "critical", and determines the minimum priority level
for which notifications are emitted. For example, if the option is set to
"warning", all notifications with priority level "warning", "error", or
"critical" are emitted, but not notifications with priority level "debug" or
"info". For information about the semantics of each log level, see the
OpenStack logging standards [1]_. If this option is unset, no notifications
will be emitted. The priority level of each available notification is
documented below.
The second option is the ``transport_url`` option in the
``[oslo_messaging_notifications]`` section of the configuration. This
determines the message bus used when sending notifications. If this is unset,
the default transport used for RPC is used.
All notifications are emitted on the "ironic_versioned_notifications" topic in
the message bus. Generally, each type of message that traverses the message bus
is associated with a topic describing what the message is about. For more
information, see the documentation of your chosen message bus, such as the
RabbitMQ documentation [2]_.
Note that notifications may be lossy, and there's no guarantee that a
notification will make it across the message bus to a consumer.
Versioning
==========
Each notification has an associated version in the "ironic_object.version"
field of the payload. Consumers are guaranteed that microversion bumps will add
new fields, while macroversion bumps are backwards-incompatible and may have
fields removed.
Available notifications
=======================
.. TODO(mariojv) Add some form of tabular formatting below
The notifications that ironic emits are described here. They are listed
(alphabetically) by service first, then by event_type. All examples below
show payloads before serialization to JSON.
------------------------------
ironic-conductor notifications
------------------------------
baremetal.node.power_set
------------------------
* ``baremetal.node.power_set.start`` is emitted by the ironic-conductor service
when it begins a power state change. It has notification level "info".
* ``baremetal.node.power_set.end`` is emitted when ironic-conductor
successfully completes a power state change task. It has notification level
"info".
* ``baremetal.node.power_set.error`` is emitted by ironic-conductor when it
fails to set a node's power state. It has notification level "error". This
can occur when ironic fails to retrieve the old power state prior to setting
the new one on the node, or when it fails to set the power state if a change
is requested.
Here is an example payload for a notification with this event type. The
"to_power" payload field indicates the power state to which the
ironic-conductor is attempting to change the node::
{
"priority": "info",
"payload":{
"ironic_object.namespace":"ironic",
"ironic_object.name":"NodeSetPowerStatePayload",
"ironic_object.version":"1.0",
"ironic_object.data":{
"clean_step": None,
"console_enabled": False,
"created_at": "2016-01-26T20:41:03+00:00",
"driver": "fake",
"extra": {},
"inspection_finished_at": None,
"inspection_started_at": None,
"instance_uuid": "d6ea00c1-1f94-4e95-90b3-3462d7031678",
"last_error": None,
"maintenance": False,
"maintenance_reason": None,
"network_interface": "flat",
"name": None,
"power_state": "power off",
"properties": {
"memory_mb": 4096,
"cpu_arch": "x86_64",
"local_gb": 10,
"cpus": 8},
"provision_state": "available",
"provision_updated_at": "2016-01-27T20:41:03+00:00",
"resource_class": None,
"target_power_state": None,
"target_provision_state": None,
"updated_at": "2016-01-27T20:41:03+00:00",
"uuid": "1be26c0b-03f2-4d2e-ae87-c02d7f33c123",
"to_power": "power on"
}
},
"event_type":"baremetal.node.power_set.start",
"publisher_id":"ironic-conductor.hostname01"
}
baremetal.node.power_state_corrected
------------------------------------
* ``baremetal.node.power_state_corrected.success`` is emitted by
ironic-conductor when the power state on the baremetal hardware is different
from the previous known power state of the node and the database is corrected
to reflect this new power state. It has notification level "info".
Here is an example payload for a notification with this event_type. The
"from_power" payload field indicates the previous power state on the node,
prior to the correction::
{
"priority": "info",
"payload":{
"ironic_object.namespace":"ironic",
"ironic_object.name":"NodeCorrectedPowerStatePayload",
"ironic_object.version":"1.0",
"ironic_object.data":{
"clean_step": None,
"console_enabled": False,
"created_at": "2016-01-26T20:41:03+00:00",
"driver": "fake",
"extra": {},
"inspection_finished_at": None,
"inspection_started_at": None,
"instance_uuid": "d6ea00c1-1f94-4e95-90b3-3462d7031678",
"last_error": None,
"maintenance": False,
"maintenance_reason": None,
"network_interface": "flat",
"name": None,
"power_state": "power off",
"properties": {
"memory_mb": 4096,
"cpu_arch": "x86_64",
"local_gb": 10,
"cpus": 8},
"provision_state": "available",
"provision_updated_at": "2016-01-27T20:41:03+00:00",
"resource_class": None,
"target_power_state": None,
"target_provision_state": None,
"updated_at": "2016-01-27T20:41:03+00:00",
"uuid": "1be26c0b-03f2-4d2e-ae87-c02d7f33c123",
"from_power": "power on"
}
},
"event_type":"baremetal.node.power_state_corrected.success",
"publisher_id":"ironic-conductor.cond-hostname02"
}
.. [1] https://wiki.openstack.org/wiki/LoggingStandards#Log_level_definitions
.. [2] https://www.rabbitmq.com/documentation.html

188
doc/source/dev/notifications.rst
View File

@ -1,50 +1,13 @@
.. _notifications:
.. _develop-notifications:
=============
Notifications
=============
============================
Developing New Notifications
============================
Ironic notifications are events intended for consumption by external services
like a billing or usage system, a monitoring data store, or other OpenStack
services. Notifications are sent to these services over a message bus by
oslo.messaging's Notifier class [1]_. The consumer sees the notification as a
JSON object structured in the following way as defined by oslo.messaging::
{
"priority": <string, defined 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>
}
Versioned notifications in ironic
=================================
To make it easier for consumers of ironic's notifications to use predictably,
ironic defines each notification and its payload as oslo versioned objects
[2]_.
An increase in the minor version of the payload will indicate that only
new fields have been added since the last version, so the consumer can still
use the notification as it did previously. An increase in the major version of
the payload indicates that the consumer can no longer parse the notification as
it did previously, indicating that a field was removed or the type of the
payload field changed.
Ironic exposes a configuration option in the ``DEFAULT`` section called
``notification_level`` that indicates the minimum level for which
notifications will be emitted. This option is not defined by default, which
indicates that no notifications will be sent by ironic. Notification levels
may be "debug", "info", "warning", "error", or "critical", and each
level follows the OpenStack logging guidelines [3]_. If it's desired that
ironic emit all notifications, the config option should be set to "debug", for
example. If only "warning", "error", and "critical" notifications are needed,
the config option should be set to "warning". This level gets exposed in the
notification on the wire as the "priority" field.
All ironic versioned notifications will be sent on the message bus via the
``ironic_versioned_notifications`` topic.
Ironic notifications are events intended for consumption by external services.
Notifications are sent to these services over a message bus by
oslo.messaging's Notifier class [1]_. For more information about configuring
notifications and available notifications, see :ref:`deploy-notifications`.
Ironic also has a set of base classes that assist in clearly defining the
notification itself, the payload, and the other fields not auto-generated by
@ -99,6 +62,10 @@ object. Here's an example::
'an_extra_field': fields.StringField(nullable=True)
}
Note that both the payload and notification classes are oslo versioned
objects [2]_. Modifications to these require a version bump so that consumers
of notifications know when the notifications have changed.
SCHEMA defines how to populate the payload fields. It's an optional
attribute that subclasses may use to easily populate notifications with
data from other objects.
@ -182,136 +149,5 @@ This example will send the following notification over the message bus::
"publisher_id":"ironic-conductor.hostname01"
}
Available notifications
=======================
.. TODO(mariojv) Move the below to deployer documentation.
.. TODO(mariojv) Match Nova's tabular formatting below.
The notifications that ironic emits are described here. They are listed
(alphabetically) by service first, then by event_type. All examples below
show payloads before serialization to JSON.
------------------------------
ironic-conductor notifications
------------------------------
baremetal.node.power_set
------------------------
* ``baremetal.node.power_set.start`` is emitted by the ironic-conductor service
when it begins a power state change. It has notification level INFO.
* ``baremetal.node.power_set.end`` is emitted when ironic-conductor
successfully completes a power state change task. It has notification level
INFO.
* ``baremetal.node.power_set.error`` is emitted by ironic-conductor when it
fails to set a node's power state. It has notification level ERROR. This can
occur when ironic fails to retrieve the old power state prior to setting the
new one on the node, or when it fails to set the power state if a change is
requested.
Here is an example payload for a notification with this event type. The
"to_power" payload field indicates the power state to which the
ironic-conductor is attempting to change the node::
{
"priority": "info",
"payload":{
"ironic_object.namespace":"ironic",
"ironic_object.name":"NodeSetPowerStatePayload",
"ironic_object.version":"1.0",
"ironic_object.data":{
"clean_step": None,
"console_enabled": False,
"created_at": "2016-01-26T20:41:03+00:00",
"driver": "fake",
"extra": {},
"inspection_finished_at": None,
"inspection_started_at": None,
"instance_uuid": "d6ea00c1-1f94-4e95-90b3-3462d7031678",
"last_error": None,
"maintenance": False,
"maintenance_reason": None,
"network_interface": "flat",
"name": None,
"power_state": "power off",
"properties": {
"memory_mb": 4096,
"cpu_arch": "x86_64",
"local_gb": 10,
"cpus": 8},
"provision_state": "available",
"provision_updated_at": "2016-01-27T20:41:03+00:00",
"resource_class": None,
"target_power_state": None,
"target_provision_state": None,
"updated_at": "2016-01-27T20:41:03+00:00",
"uuid": "1be26c0b-03f2-4d2e-ae87-c02d7f33c123",
"to_power": "power on"
}
},
"event_type":"baremetal.node.power_set.start",
"publisher_id":"ironic-conductor.hostname01"
}
baremetal.node.power_state_corrected
------------------------------------
* ``baremetal.node.power_state_corrected.success`` is emitted by
ironic-conductor when the power state on the baremetal hardware is different
from the previous known power state of the node and the database is corrected
to reflect this new power state. It has notification level INFO.
Here is an example payload for a notification with this event_type. The
"from_power" payload field indicates the previous power state on the node,
prior to the correction::
{
"priority": "info",
"payload":{
"ironic_object.namespace":"ironic",
"ironic_object.name":"NodeCorrectedPowerStatePayload",
"ironic_object.version":"1.0",
"ironic_object.data":{
"clean_step": None,
"console_enabled": False,
"created_at": "2016-01-26T20:41:03+00:00",
"driver": "fake",
"extra": {},
"inspection_finished_at": None,
"inspection_started_at": None,
"instance_uuid": "d6ea00c1-1f94-4e95-90b3-3462d7031678",
"last_error": None,
"maintenance": False,
"maintenance_reason": None,
"network_interface": "flat",
"name": None,
"power_state": "power off",
"properties": {
"memory_mb": 4096,
"cpu_arch": "x86_64",
"local_gb": 10,
"cpus": 8},
"provision_state": "available",
"provision_updated_at": "2016-01-27T20:41:03+00:00",
"resource_class": None,
"target_power_state": None,
"target_provision_state": None,
"updated_at": "2016-01-27T20:41:03+00:00",
"uuid": "1be26c0b-03f2-4d2e-ae87-c02d7f33c123",
"from_power": "power on"
}
},
"event_type":"baremetal.node.power_state_corrected.success",
"publisher_id":"ironic-conductor.cond-hostname02"
}
.. [1] http://docs.openstack.org/developer/oslo.messaging/notifier.html
.. [2] http://docs.openstack.org/developer/oslo.versionedobjects
.. [3] https://wiki.openstack.org/wiki/LoggingStandards#Log_level_definitions

5
doc/source/index.rst
View File

@ -76,7 +76,7 @@ primarily for developers.
Ironic System Architecture <dev/architecture>
Provisioning State Machine <dev/states>
Notifications <dev/notifications>
Developing New Notifications <dev/notifications>
These pages contain information for PTLs, cross-project liaisons, and core
reviewers.
@ -158,10 +158,11 @@ of ironic that may or may not be suitable to every situation.
Configuring RAID during deployment <deploy/raid>
Security considerations for your Bare Metal installation <deploy/security>
Adopting Nodes in an ACTIVE state <deploy/adoption>
Auditing API Traffic <deploy/api-audit-support>
Configuring for Multi-tenant Networking <deploy/multitenancy>
Configuring node web or serial console <deploy/console>
Emitting software metrics <deploy/metrics>
Auditing API Traffic <deploy/api-audit-support>
Notifications <deploy/notifications>
Configuration Reference <http://docs.openstack.org/draft/config-reference/bare-metal.html>
Sample configuration file <https://git.openstack.org/cgit/openstack/ironic/tree/etc/ironic/ironic.conf.sample>