Merge "Add docs for faultnotification auto heal"

api-ref/source/index.rst

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

api-ref/source/v2/fault_notification.inc

@@ -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

api-ref/source/v2/fault_notification.rst

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

api-ref/source/v2/parameters_fault_notification.yaml

@@ -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)

api-ref/source/v2/samples/fault_notification/notify.json

@@ -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."
+        }
+    }
+}

api-ref/source/v2/status.yaml

@@ -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.

doc/source/user/fault_notification_use_case_guide.rst

@@ -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

doc/source/user/index.rst

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