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