openstack/tacker
Code Issues Proposed changes

Add docs for faultnotification auto heal

Browse Source 
This patch makes the following updates to the API and CLI docs.

* Add support faultnotification auto heal

Implements: blueprint support-autoheal-queue
Change-Id: I2fcb3c54ef3cca4e79bf701daebf1286a36f730c
This commit is contained in:
Koji Shimizu 2022-09-07 15:13:48 +09:00
parent 693dce5f5d
commit 72e361bb18
8 changed files with 296 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
api-ref/source/index.rst
View File

@ -21,3 +21,4 @@ NFV Orchestration API v2.0
v1/vnflcm_versions
v2/vnflcm
v2/fault_notification

53
api-ref/source/v2/fault_notification.inc Normal file
View File

@ -0,0 +1,53 @@
.. -*- rst -*-
============================
Fault Notification Interface
============================
This interface is used for notifying fault events that is detected by VIM.
When fault events occur in VIM, VIM notifies fault event to Tacker via
the interface. Tacker performs autohealing according to the fault event.
Notify a fault event
====================
.. rest_method:: POST /server_notification/vnf_instances/{vnfInstanceId}/servers/{server_id}/notify
Notifies Tacker when a fault event occur in VIM.
This interface can be alerted by multiple times in a short period.
To prevent invoking multiple heal operations to single VNF,
the multiple requests by this interface are packed for
a configured period of time (CONF.server_notification.timer_interval).
Response Codes
--------------
.. rest_status_code:: success status.yaml
- 204
.. rest_status_code:: error status.yaml
- 400
- 404: fault_notification
Request Parameters
------------------
.. rest_parameters:: parameters_fault_notification.yaml
- vnfInstanceId: vnf_instance_id
- server_id: server_id
- notification: notification
- \>host_id: host_id
- \>alarm_id: alarm_id
- \>fault_id: fault_id
- \>fault_type: fault_type
- \>fault_option: fault_option
Request Example
---------------
.. literalinclude:: samples/fault_notification/notify.json
:language: javascript

9
api-ref/source/v2/fault_notification.rst Normal file
View File

@ -0,0 +1,9 @@
:tocdepth: 2
############################
Fault Notification Interface
############################
.. rest_expand_all::
.. include:: fault_notification.inc

50
api-ref/source/v2/parameters_fault_notification.yaml Normal file
View File

@ -0,0 +1,50 @@
server_id:
description: |
Identifier of the virtual machine.
in: path
required: true
type: string
vnf_instance_id:
description: |
Identifier of Vnf instance related to this notification.
in: path
required: true
type: string
alarm_id:
description: |
ID to identify alarm.
in: body
required: true
type: Identifier
fault_id:
description: |
Target fault ID.
in: body
required: true
type: String
fault_option:
description: |
Optional information about this fault event.
in: body
required: false
type: KeyValuePairs
fault_type:
description: |
Fault type.
“10”: Physical server fault, “11”: Physical server OUS,
“20”: Inconsistency of VM status, “21”: VM reboot detection.
in: body
required: true
type: String
host_id:
description: |
Physical server ID. This is for future use and ignored for now.
in: body
required: false
type: Identifier
notification:
description: |
Fault notification event.
in: body
required: true
type: Structure (inlined)

11
api-ref/source/v2/samples/fault_notification/notify.json Normal file
View File

@ -0,0 +1,11 @@
{
"notification": {
"host_id": "host1",
"alarm_id": "e8e97eaf-ba85-4b92-aeb9-f2b2c712ca4f",
"fault_id": "1234",
"fault_type": "10",
"fault_option": {
"message": "Server is down."
}
}
}

3
api-ref/source/v2/status.yaml
View File

@ -52,6 +52,9 @@
404:
default: |
The requested resource could not be found.
fault_notification: |
The fault notification API is not enabled.
(CONF.server_notification.server_notification)
405:
default: |
Method is not valid for this endpoint.

168
doc/source/user/fault_notification_use_case_guide.rst Normal file
View File

@ -0,0 +1,168 @@
==============================================
VNF AutoHealing triggered by FaultNotification
==============================================
Overview
--------
Tacker supports ``AutoHealing`` using ``FaultNotification`` interface.
When fault events occur in VIM, VIM notifies fault event to Tacker via
the interface. Tacker takes initiative of AutoHealing. Tacker checks
faultID attribute in the fault event and determines whether
AutoHealing should be performed. In case of performing AutoHealing,
VMs are deleted or created.
Configuration
-------------
FaultNotification is disabled by default.
To enable FaultNotification, be sure to set true for
``CONF.server_notification.server_notification``.
.. list-table::
:header-rows: 1
:widths: 20 10 40
* - Configuration
- Default
- Description
* - ``CONF.server_notification.server_notification``
- false
- Enable FaultNotification interface.
* - ``CONF.server_notification.uri_path_prefix``
- /server_notification
- Uri path prefix string for FaultNotification interface.
When changing this configuration,
server_notification description in api-paste.ini
must be changed to the same value.
* - ``CONF.server_notification.timer_interval``
- 20
- When multiple fault events for a vnf instance are
notified in the ``timer_interval`` seconds,
Tacker packs these notifications into single event.
By doing this, Tacker can avoid making too many healing request.
System
------
FaultNotification AutoHealing needs external service called
Server Notifier.
The ``Server Notifier`` is a monitoring service that is implemented
by each operators, thus it is not included in Tacker.
When the Server Notifier detects fault events in VIM, it will send
FaultNotification to Tacker.
Setting FaultNotification interface uri or enabling monitoring
for the Server Notifier is performed along the vnf lifecycle.
So Tacker provides a sample implementation of the ``mgmt driver script``
to achieve interface registration and enabling monitoring.
.. code-block:: console
+--------------------------+
| Client (NFVO) +--------+
+--------------------------+ | 1. Vnf instantiation
+-----------------------------------v--------------------------------+
| 2.Create VM Tacker |
6.FaultNotification | 3.Interface registration (in mgmt driver) |
+--------------> 7.Perform Healing |
| | 8.Delete failed VM and Create new VM |
| +---------------------------------------+-------------+--------------+
| +----------------------------------------------+ |
+------|-------|------------------------------------------------------------|--------------+
| | | 4.Start monitoring +---------------+--------+ VIM/NFVI |
| | | | | |
| +--+-------v--+ +--------v----+ +------v------+ |
| | Server | 5.Detects fault event | +--------+ | | +--------+ | |
| | Notifier +-------------------------> VNF | | | | VNF | | |
| | | | +--------+ | | +--------+ | |
| | | | VM | | VM | |
| +-------------+ +-------------+ +-------------+ |
+------------------------------------------------------------------------------------------+
For details about the interface,
please refer to [#fault_notification_apiref]_.
Mgmt driver script
------------------
Sample mgmt driver script to achieve
interface registration and enabling monitoring is
``tacker/sol_refactored/mgmt_drivers/server_notification.py``
Put this script into target VNF package and Server Notifier
can detect fault event on the VNF.
LCM interface
-------------
The LCM interface is modified to set parameters for Server Notifier.
The ``additionalParams`` must be set when using FaultNotification.
* | **Name**: Instantiate VNF task
| **Description**: This task resource represents the ``Instantiate VNF``
operation. The client can use this resource to instantiate a VNF instance.
``Only the additionalParams for FaultNotification are described here``.
| **Method type**: POST
| **URL for the resource**: /vnflcm/v2/vnf_instances/
{vnfInstanceId}/instantiate
| **Request**:
.. list-table::
:header-rows: 1
:widths: 18 18 10 50
* - Attribute name (InstantiateVnfRequest)
- Data type
- Cardinality
- Description
* - additionalParams
- 0..1
- KeyValuePairs (inlined)
- Additional input parameters for the instantiation process,
specific to the VNF being instantiated.
* - >ServerNotifierUri
- 1
- String
- Base Uri for ServerNotifier.
* - >ServerNotifierFaultID
- 1..N
- String
- List of string that indicates which type of alarms to detect.
The value of ``ServerNotifierUri`` and ``ServerNotifierFaultID`` are stored
in ``instantiatedVnfInfo`` of vnfInstance. The values can be shown
with vnflcm show command. For example:
.. code-block:: console
$ openstack vnflcm show 6fd264ea-78fb-4862-90c0-1a9597734d95 --os-tacker-api-version 2
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Field | Value |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ID | 6fd264ea-78fb-4862-90c0-1a9597734d95 |
| Instantiated Vnf Info | { |
| | .... |
| | "metadata": { |
| | "ServerNotifierUri": "http://localhost:9990/server_notification", |
| | "ServerNotifierFaultID": "1234" |
| | } |
| | .... |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Auto Healing
------------
When fault events occur in VIM, ServerNotifier notifies fault event
to Tacker via the FaultNotification interface.
Tacker checks ``fault_id`` attribute in the fault event and determines
whether AutoHealing should be performed. In case of performing
AutoHealing, VMs are deleted and created via Heat. The client is
no need to handle healing.
References
==========
.. [#fault_notification_apiref] https://docs.openstack.org/api-ref/nfv-orchestration/v2/fault_notification.html

1
doc/source/user/index.rst
View File

@ -51,3 +51,4 @@ Use Case Guide
etsi_use_case_guide
legacy_use_case_guide
oauth2_usage_guide
fault_notification_use_case_guide