.. _notifications: ============= Notifications ============= Similarly to other OpenStack services Fenix emits notifications to the message bus with the Notifier class provided by oslo.messaging [1]_. From the notification consumer point of view a notification consists of two parts: an envelope with a fixed structure defined by oslo.messaging and a payload defined by the service emitting the notification. The envelope format is the following: .. code-block:: json { "priority": "string, selected from a predefined list by the sender. Fenix currently uses 'info'.", "event_type": "string, defined by the sender. Event types are defined later in this docuemnt.", "timestamp": "string, the isotime of when the notification emitted", "publisher_id": "string, defined by the sender. Fenix uses 'fenix'", "message_id": "uuid, generated by oslo.", "payload": "json serialized dict, defined by the sender. This is defined for each event type later in this document." } Admin ===== These notifications are meant for admin level user. Infrastructure admin who is in charge of triggering the rolling maintenance and upgrade workflows and for any infrastructure service needing to know about the host being in maintenance. This might be used for enabling/disabling self-healing or billing. Event type 'maintenance.host' ----------------------------- This event type is meant for infrastructure services to know the host might be down and taken out of normal usage. Also after the host is back or new host added, there is another message to tell host is back in use or added. This might be meaningful for self-healing or billing. payload ~~~~~~~~ +------------+--------+------------------------------------------------------------------------------+ | Name | Type | Description | +============+========+==============================================================================+ | service | string | Origin service name: Fenix | +------------+--------+------------------------------------------------------------------------------+ | state | string | Maintenance state. values can be 'IN_MAINTENANCE' or 'MAINTENANCE_COMPLETE'. | | | | In future this might have also values like 'HOST_ADDED' or 'HOST_REMOVED'. | +------------+--------+------------------------------------------------------------------------------+ | session_id | string | UUID of the related maintenance session | +------------+--------+------------------------------------------------------------------------------+ | host | string | Host name | +------------+--------+------------------------------------------------------------------------------+ | project_id | string | workflow admin project ID | +------------+--------+------------------------------------------------------------------------------+ Example: .. code-block:: json { "service": "fenix", "state": "IN_MAINTENANCE", "session_id": "76e55df8-1c51-11e8-9928-0242ac110002", "host": "overcloud-novacompute-0.opnfvlf.org", "project_id": "ead0dbcaf3564cbbb04842e3e54960e3" } Event type 'maintenance.session' -------------------------------- This event type is meant for infrastructure admin to know the changes in the ongoing maintenance workflow session. This can be used instead of polling API. Via API you will get more detailed information if you need to troubleshoot. payload ~~~~~~~~ +--------------+--------+------------------------------------------------------------------------------+ | Name | Type | Description | +==============+========+==============================================================================+ | service | string | Origin service name: Fenix | +--------------+--------+------------------------------------------------------------------------------+ | state | string | Maintenance workflow state (States explained in the user guide) | +--------------+--------+------------------------------------------------------------------------------+ | session_id | string | UUID of the related maintenance session | +--------------+--------+------------------------------------------------------------------------------+ | percent_done | string | How many percent of hosts are maintained | +--------------+--------+------------------------------------------------------------------------------+ | project_id | string | workflow admin project ID | +--------------+--------+------------------------------------------------------------------------------+ Example: .. code-block:: json { "service": "fenix", "state": "IN_MAINTENANCE", "session_id": "76e55df8-1c51-11e8-9928-0242ac110002", "percent_done": 34, "project_id": "ead0dbcaf3564cbbb04842e3e54960e3" } Project ======= These notifications are meant for a project level user to know about a maintenance session affecting its instances. Project/application manager (VNFM) can have a 'POST /maintenance' API to catch notification through an AODH event alarm [2]_. Event type 'maintenance.planned' -------------------------------- This event type is meant for a project level user to know about a maintenance session state affecting its instances. According to this event project manager (VNFM) can know to make actions to its instances affected by maintenance and replying back to Fenix. payload ~~~~~~~ +-----------------+------------+------------------------------------------------------------------------+ | Name | Type | Description | +=================+============+========================================================================+ | service | string | Origin service name: fenix | +-----------------+------------+------------------------------------------------------------------------+ | allowed_actions | list | A list of allowed actions for an instance. Allowed values are: | | | | 'MIGRATE', 'LIVE_MIGRATE' and 'OWN_ACTION'. 'OWN_ACTION' means | | | | an action project manager can do itself. Usually this could be | | | | re-instantiation even with a new flavor. Other actions are done by | | | | Fenix as they need the admin privileges. In Kubernetes also 'EVICTION' | | | | supported. There admin will delete instance and VNF automation like | | | | ReplicaSet will make a new instance. Valid for states: | | | | 'SCALE_IN', 'PREPARE_MAINTENANCE' and 'PLANNED_MAINTENANCE'. | +-----------------+------------+------------------------------------------------------------------------+ | instance_ids | string | Link to Fenix maintenance session and project specific API to get | | | | instance IDs related to current maintenance workflow 'state'. | | | | A special case is with the 'state' 'INSTANCE_ACTION_DONE' where the | | | | value is a single instance_id only. When using Telco workflow with | | | | ETSI defined constraints value is also just a single instance_id in | | | | the 'state' 'PREPARE_MAINTENANCE' and 'PLANNED_MAINTENANCE'. | +-----------------+------------+------------------------------------------------------------------------+ | reply_url | string | Link to Fenix maintenance session and project specific API to send the | | | | reply corresponding to this notification. When using Telco workflow | | | | with ETSI defined constraints reply URL is instance specific in the | | | | the 'state' 'PREPARE_MAINTENANCE' and 'PLANNED_MAINTENANCE'. | +-----------------+------------+------------------------------------------------------------------------+ | state | string | Maintenance workflow session state. Can have different values: | | | | - 'MAINTENANCE' to tell project about a created maintenance session. | | | | - 'SCALE_IN' to tell the project should scale down instances. | | | | - 'PREPARE_MAINTENANCE' to tell the project some instances need to | | | | be moved. | | | | - 'PLANNED_MAINTENANCE' to tell project some instances are on a host | | | | going to be maintained next and are to move to a host that is | | | | already maintained. | | | | - 'MAINTENANCE_COMPLETE' to tell the project the maintenance session | | | | is complete. The Project can upscale to full capacity if scaled | | | | down before. | | | | - 'INSTANCE_ACTION_DONE' to tell project that Fenix has compeleted | | | | action like migration for a specific instance | +-----------------+------------+------------------------------------------------------------------------+ | session_id | string | UUID to related maintenance session | +-----------------+------------+------------------------------------------------------------------------+ | reply_at | string | time when need to reply to Fenix | +-----------------+------------+------------------------------------------------------------------------+ | actions_at | string | time when Fenix triggers its actions | +-----------------+------------+------------------------------------------------------------------------+ | project_id | string | workflow admin project ID | +-----------------+------------+------------------------------------------------------------------------+ | metadata | dictionary | Can tell hints; like new capabilities coming after as a result to | | | | 'state' 'PLANNED_MAINTENANCE' when instances will be moving to already | | | | maintained host. As knowing these capabilities, the project-manager | | | | can plan its own upgrade at the same time or later. This will be handy | | | | to even re-instantiate instances with a new flavor to take a new type | | | | of hardware into use. | +-----------------+------------+------------------------------------------------------------------------+ Example of notification for many instances: .. code-block:: json { "service": "fenix", "allowed_actions": ["MIGRATE", "LIVE_MIGRATE", "OWN_ACTION"], "instance_ids": "http://0.0.0.0:12347/v1/maintenance/76e55df8-1c51-11e8-9928-0242ac110002/ead0dbcaf3564cbbb04842e3e54960e3", "reply_url": "http://0.0.0.0:12347/v1/maintenance/76e55df8-1c51-11e8-9928-0242ac110002/ead0dbcaf3564cbbb04842e3e54960e3", "state": "MAINTENANCE", "session_id": "76e55df8-1c51-11e8-9928-0242ac110002", "reply_at": "2018-02-28T06:40:16", "actions_at": "2018-02-29T00:00:00", "project_id": "ead0dbcaf3564cbbb04842e3e54960e3", "metadata": {"openstack_release": "Queens"} } Example of notification for single instance. Note the instance specific 'reply_url': .. code-block:: json { "service": "fenix", "allowed_actions": ["MIGRATE", "LIVE_MIGRATE", "OWN_ACTION"], "instance_ids": ["28d226f3-8d06-444f-a3f1-c586d2e7cb39"], "reply_url": "http://0.0.0.0:12347/v1/maintenance/76e55df8-1c51-11e8-9928-0242ac110002/ead0dbcaf3564cbbb04842e3e54960e3/28d226f3-8d06-444f-a3f1-c586d2e7cb39", "state": "PREPARE_MAINTENANCE", "session_id": "76e55df8-1c51-11e8-9928-0242ac110002", "reply_at": "2018-02-28T06:40:16", "actions_at": "2018-02-29T00:00:00", "project_id": "ead0dbcaf3564cbbb04842e3e54960e3", "metadata": {"openstack_release": "Queens"} } Example of notification for single instance in Kubernetes. Note the instance specific 'reply_url' and allowed actions for Kubernetes: .. code-block:: json { "service": "fenix", "allowed_actions": ["OWN_ACTION", "EVICTION"], "instance_ids": ["28d226f3-8d06-444f-a3f1-c586d2e7cb39"], "reply_url": "http://0.0.0.0:12347/v1/maintenance/76e55df8-1c51-11e8-9928-0242ac110002/ead0dbcaf3564cbbb04842e3e54960e3/28d226f3-8d06-444f-a3f1-c586d2e7cb39", "state": "PREPARE_MAINTENANCE", "session_id": "76e55df8-1c51-11e8-9928-0242ac110002", "reply_at": "2018-02-28T06:40:16", "actions_at": "2018-02-29T00:00:00", "project_id": "ead0dbcaf3564cbbb04842e3e54960e3", "metadata": {"openstack_release": "Queens"} } .. [1] http://docs.openstack.org/developer/oslo.messaging/notifier.html .. [2] https://docs.openstack.org/aodh/latest/admin/telemetry-alarms.html#event-based-alarm