From 72e361bb18b104848476d28589093a6136300cf9 Mon Sep 17 00:00:00 2001 From: Koji Shimizu Date: Wed, 7 Sep 2022 15:13:48 +0900 Subject: [PATCH] Add docs for faultnotification auto heal 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 --- api-ref/source/index.rst | 1 + api-ref/source/v2/fault_notification.inc | 53 ++++++ api-ref/source/v2/fault_notification.rst | 9 + .../v2/parameters_fault_notification.yaml | 50 ++++++ .../v2/samples/fault_notification/notify.json | 11 ++ api-ref/source/v2/status.yaml | 3 + .../fault_notification_use_case_guide.rst | 168 ++++++++++++++++++ doc/source/user/index.rst | 1 + 8 files changed, 296 insertions(+) create mode 100644 api-ref/source/v2/fault_notification.inc create mode 100644 api-ref/source/v2/fault_notification.rst create mode 100644 api-ref/source/v2/parameters_fault_notification.yaml create mode 100644 api-ref/source/v2/samples/fault_notification/notify.json create mode 100644 doc/source/user/fault_notification_use_case_guide.rst diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst index 887665add..789d546bf 100644 --- a/api-ref/source/index.rst +++ b/api-ref/source/index.rst @@ -21,3 +21,4 @@ NFV Orchestration API v2.0 v1/vnflcm_versions v2/vnflcm + v2/fault_notification diff --git a/api-ref/source/v2/fault_notification.inc b/api-ref/source/v2/fault_notification.inc new file mode 100644 index 000000000..f2e782a5b --- /dev/null +++ b/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 diff --git a/api-ref/source/v2/fault_notification.rst b/api-ref/source/v2/fault_notification.rst new file mode 100644 index 000000000..9977cd301 --- /dev/null +++ b/api-ref/source/v2/fault_notification.rst @@ -0,0 +1,9 @@ +:tocdepth: 2 + +############################ +Fault Notification Interface +############################ + +.. rest_expand_all:: + +.. include:: fault_notification.inc diff --git a/api-ref/source/v2/parameters_fault_notification.yaml b/api-ref/source/v2/parameters_fault_notification.yaml new file mode 100644 index 000000000..a0a8467f3 --- /dev/null +++ b/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) diff --git a/api-ref/source/v2/samples/fault_notification/notify.json b/api-ref/source/v2/samples/fault_notification/notify.json new file mode 100644 index 000000000..2405afc62 --- /dev/null +++ b/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." + } + } +} \ No newline at end of file diff --git a/api-ref/source/v2/status.yaml b/api-ref/source/v2/status.yaml index d1d2105b3..74c3c925e 100644 --- a/api-ref/source/v2/status.yaml +++ b/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. diff --git a/doc/source/user/fault_notification_use_case_guide.rst b/doc/source/user/fault_notification_use_case_guide.rst new file mode 100644 index 000000000..26f367bf3 --- /dev/null +++ b/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 diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst index 8f04d69f0..474b9a6ad 100644 --- a/doc/source/user/index.rst +++ b/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