Merge "Add notification documentation to administrator's guide"
This commit is contained in:
Jenkins
Gerrit Code Review
commit
0d3e2388a2
191
doc/source/deploy/notifications.rst
Normal file
191
doc/source/deploy/notifications.rst
Normal 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
|
||||||
@ -1,50 +1,13 @@
|
|||||||
.. _notifications:
|
.. _develop-notifications:
|
||||||
|
|
||||||
=============
|
============================
|
||||||
Notifications
|
Developing New Notifications
|
||||||
=============
|
============================
|
||||||
|
|
||||||
Ironic notifications are events intended for consumption by external services
|
Ironic notifications are events intended for consumption by external services.
|
||||||
like a billing or usage system, a monitoring data store, or other OpenStack
|
Notifications are sent to these services over a message bus by
|
||||||
services. Notifications are sent to these services over a message bus by
|
oslo.messaging's Notifier class [1]_. For more information about configuring
|
||||||
oslo.messaging's Notifier class [1]_. The consumer sees the notification as a
|
notifications and available notifications, see :ref:`deploy-notifications`.
|
||||||
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 also has a set of base classes that assist in clearly defining the
|
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
|
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)
|
'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
|
SCHEMA defines how to populate the payload fields. It's an optional
|
||||||
attribute that subclasses may use to easily populate notifications with
|
attribute that subclasses may use to easily populate notifications with
|
||||||
data from other objects.
|
data from other objects.
|
||||||
@ -182,136 +149,5 @@ This example will send the following notification over the message bus::
|
|||||||
"publisher_id":"ironic-conductor.hostname01"
|
"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
|
.. [1] http://docs.openstack.org/developer/oslo.messaging/notifier.html
|
||||||
.. [2] http://docs.openstack.org/developer/oslo.versionedobjects
|
.. [2] http://docs.openstack.org/developer/oslo.versionedobjects
|
||||||
.. [3] https://wiki.openstack.org/wiki/LoggingStandards#Log_level_definitions
|
|
||||||
|
|||||||
@ -76,7 +76,7 @@ primarily for developers.
|
|||||||
|
|
||||||
Ironic System Architecture <dev/architecture>
|
Ironic System Architecture <dev/architecture>
|
||||||
Provisioning State Machine <dev/states>
|
Provisioning State Machine <dev/states>
|
||||||
Notifications <dev/notifications>
|
Developing New Notifications <dev/notifications>
|
||||||
|
|
||||||
These pages contain information for PTLs, cross-project liaisons, and core
|
These pages contain information for PTLs, cross-project liaisons, and core
|
||||||
reviewers.
|
reviewers.
|
||||||
@ -160,10 +160,11 @@ of ironic that may or may not be suitable to every situation.
|
|||||||
Configuring RAID during deployment <deploy/raid>
|
Configuring RAID during deployment <deploy/raid>
|
||||||
Security considerations for your Bare Metal installation <deploy/security>
|
Security considerations for your Bare Metal installation <deploy/security>
|
||||||
Adopting Nodes in an ACTIVE state <deploy/adoption>
|
Adopting Nodes in an ACTIVE state <deploy/adoption>
|
||||||
Auditing API Traffic <deploy/api-audit-support>
|
|
||||||
Configuring for Multi-tenant Networking <deploy/multitenancy>
|
Configuring for Multi-tenant Networking <deploy/multitenancy>
|
||||||
Configuring node web or serial console <deploy/console>
|
Configuring node web or serial console <deploy/console>
|
||||||
Emitting software metrics <deploy/metrics>
|
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>
|
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>
|
Sample configuration file <https://git.openstack.org/cgit/openstack/ironic/tree/etc/ironic/ironic.conf.sample>
|
||||||
|
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user