From cb2971ba27bca79536ad257e991a6d05759108a3 Mon Sep 17 00:00:00 2001 From: Mario Villaplana Date: Thu, 20 Oct 2016 20:34:25 +0000 Subject: [PATCH] Add notification documentation to administrator's guide 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 --- doc/source/deploy/notifications.rst | 191 ++++++++++++++++++++++++++++ doc/source/dev/notifications.rst | 188 ++------------------------- doc/source/index.rst | 5 +- 3 files changed, 206 insertions(+), 178 deletions(-) create mode 100644 doc/source/deploy/notifications.rst diff --git a/doc/source/deploy/notifications.rst b/doc/source/deploy/notifications.rst new file mode 100644 index 0000000000..4faad24f53 --- /dev/null +++ b/doc/source/deploy/notifications.rst @@ -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": , + "event_type": , + "timestamp": , + "publisher_id": , + "message_id": , + "payload": + } + +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 diff --git a/doc/source/dev/notifications.rst b/doc/source/dev/notifications.rst index 2afadf4866..7a4c6ad89e 100644 --- a/doc/source/dev/notifications.rst +++ b/doc/source/dev/notifications.rst @@ -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": , - "event_type": , - "timestamp": , - "publisher_id": , - "message_id": , - "payload": - } - -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 diff --git a/doc/source/index.rst b/doc/source/index.rst index 74e5cfdb81..dec744df10 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -76,7 +76,7 @@ primarily for developers. Ironic System Architecture Provisioning State Machine - Notifications + Developing New 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 Security considerations for your Bare Metal installation Adopting Nodes in an ACTIVE state - Auditing API Traffic Configuring for Multi-tenant Networking Configuring node web or serial console Emitting software metrics + Auditing API Traffic + Notifications Configuration Reference Sample configuration file