diff --git a/api-ref/source/v2/parameters_vnffm.yaml b/api-ref/source/v2/parameters_vnffm.yaml index d6be697f6..6991986df 100644 --- a/api-ref/source/v2/parameters_vnffm.yaml +++ b/api-ref/source/v2/parameters_vnffm.yaml @@ -20,6 +20,13 @@ ack_state: in: body required: true type: string +alarm: + description: | + Information about an alarm including AlarmId, affected VNF identifier, + and FaultDetails. + in: body + required: true + type: object alarm_acknowledged_time: description: | Time stamp indicating when the alarm was acknowledged. It shall be present @@ -34,6 +41,25 @@ alarm_changed_time: in: body required: false type: string +alarm_cleared_notification_alarm_cleared_time: + description: | + The time stamp indicating when the alarm was cleared. + in: body + required: true + type: string +alarm_cleared_notification_alarm_id: + description: | + Alarm identifier. + in: body + required: true + type: string +alarm_cleared_notification_type: + description: | + Discriminator for the different notification types. + Set to "AlarmClearedNotification" for this notification type. + in: body + required: true + type: string alarm_cleared_time: description: | Time stamp indicating when the alarm was cleared. It shall be present if @@ -41,6 +67,14 @@ alarm_cleared_time: in: body required: false type: string +alarm_faulty_resource_vim_connection_id: + description: | + Identifier of the VIM connection to manage the resource. This attribute + shall only be supported and present if VNFrelated resource management in + direct mode is applicable. + in: body + required: false + type: string alarm_id: description: | Identifier of this Alarm information element. @@ -53,6 +87,19 @@ alarm_links: in: body required: true type: object +alarm_notification_type: + description: | + Discriminator for the different notification types. + Set to "AlarmNotification" for this notification type. + in: body + required: true + type: string +alarm_perceived_severity: + description: | + Perceived severity of the managed object failure. + in: body + required: true + type: object alarm_raised_time: description: | Time stamp indicating when the alarm is raised by the managed object. @@ -213,7 +260,7 @@ faulty_resource_vim_connection_id: type: string faulty_resource_vim_level_resource_type: description: | - Identifier of the resource in the scope of the VIM or the resource provider. + Type of the resource in the scope of the VIM or the resource provider. in: body required: false type: string @@ -278,6 +325,24 @@ managed_object_id: in: body required: true type: string +notification_id: + description: | + Identifier of this notification. + in: body + required: true + type: string +notification_links: + description: | + Links to resources related to this notification. + in: body + required: true + type: object +notification_time_stamp: + description: | + Date-time of the generation of the notification. + in: body + required: true + type: string object_instance: description: | Link to the resource representing the VNF instance to which the notified @@ -391,6 +456,24 @@ products_vnf_product_name: in: body required: true type: string +related_alarm_links: + description: | + Link to the resource that represents the related alarm. + in: body + required: true + type: object +related_subscription_id: + description: | + Identifier of the subscription that this notification relates to. + in: body + required: true + type: string +related_subscription_links: + description: | + Link to the related subscription. + in: body + required: true + type: object subscription_filter_vnf_instance_ids: description: | If present, match VNF instances with an instance identifier listed in this diff --git a/api-ref/source/v2/parameters_vnfpm.yaml b/api-ref/source/v2/parameters_vnfpm.yaml index e5fa3cfd0..649308fe4 100644 --- a/api-ref/source/v2/parameters_vnfpm.yaml +++ b/api-ref/source/v2/parameters_vnfpm.yaml @@ -132,6 +132,135 @@ links_self: in: body required: true type: object +notification_id: + description: | + Identifier of this notification. + in: body + required: true + type: string +notification_links: + description: | + Links to resources related to this notification. + in: body + required: true + type: object +notification_object_instance: + description: | + Link to the resource representing the measured object instance to which + the notified change applies. Shall be present if the measured object + instance information is accessible as a resource. + in: body + required: false + type: object +notification_object_instance_id: + description: | + Identifier of the measured object instance. + in: body + required: true + type: string +notification_object_type: + description: | + Type of the measured object. + in: body + required: true + type: string +notification_performance_information_available_notification_type: + description: | + Discriminator for the different notification types. Set to + "PerformanceInformationAvailableNotification" for this notification type. + in: body + required: true + type: string +notification_performance_information_available_performance_report: + description: | + Link from which the available performance information of data type + "PerformanceReport" can be obtained. + in: body + required: true + type: object +notification_performance_information_available_pmjob: + description: | + Link to the resource that represents the PM job for which performance + information is available. + in: body + required: true + type: object +notification_performance_information_available_pmjob_id: + description: | + Identifier of the PM job for which performance information is available. + in: body + required: true + type: string +notification_performance_information_available_sub_object_instance_ids: + description: | + Identifiers of the sub-object instances of the measured object instance + for which the measurements have been taken. + in: body + required: false + type: array +notification_sub_object_instance_id: + description: | + Identifier of the sub-object of the measured object to which the + measurement applies. + in: body + required: false + type: string +notification_threshold_crossed_context: + description: | + Measurement context information related to the measured value. + in: body + required: false + type: string +notification_threshold_crossed_crossing_direction: + description: | + An indication of whether the threshold was crossed in upward or + downward direction. + in: body + required: true + type: string +notification_threshold_crossed_notification_type: + description: | + Discriminator for the different notification types. + Set to "ThresholdCrossedNotification" for this notification type. + in: body + required: true + type: string +notification_threshold_crossed_performance_metric: + description: | + Performance metric associated with the threshold. + in: body + required: true + type: string +notification_threshold_crossed_performance_value: + description: | + Value of the metric that resulted in threshold crossing. + in: body + required: true + type: string +notification_threshold_crossed_threshold: + description: | + Link to the resource that represents the threshold that was crossed. + in: body + required: true + type: object +notification_threshold_crossed_threshold_id: + description: | + Identifier of the threshold which has been crossed. + in: body + required: true + type: string +notification_time_stamp: + description: | + Date and time of the generation of the notification. + in: body + required: true + type: string +notification_type: + description: | + Discriminator for the different notification types. + in: body + required: true + type: string params_oauth2_client_cert_certificate_ref: description: | Fingerprint of the client certificate. The hash function diff --git a/api-ref/source/v2/samples/vnffm/vnffm-alarm-cleared-notification-request.json b/api-ref/source/v2/samples/vnffm/vnffm-alarm-cleared-notification-request.json new file mode 100644 index 000000000..805c66f23 --- /dev/null +++ b/api-ref/source/v2/samples/vnffm/vnffm-alarm-cleared-notification-request.json @@ -0,0 +1,16 @@ +{ + "id": "0ab777dc-b3a0-42d6-85c1-e5f80711b988", + "notificationType": "AlarmClearedNotification", + "subscriptionId": "0155c914-8573-463c-a97a-aef5a3ca9c72", + "timeStamp": "2023-12-08T13:16:30Z", + "alarmId": "de8e74e8-1845-40dd-892c-cb7a67c26f9f", + "alarmClearedTime": "2023-12-08T13:16:30Z", + "_links": { + "subscription": { + "href": "http://127.0.0.1:9890/vnffm/v1/subscriptions/0155c914-8573-463c-a97a-aef5a3ca9c72" + }, + "alarm": { + "href": "http://127.0.0.1:9890/vnffm/v1/alarms/de8e74e8-1845-40dd-892c-cb7a67c26f9f" + } + } +} \ No newline at end of file diff --git a/api-ref/source/v2/samples/vnffm/vnffm-alarm-notification-request.json b/api-ref/source/v2/samples/vnffm/vnffm-alarm-notification-request.json new file mode 100644 index 000000000..45349b9b8 --- /dev/null +++ b/api-ref/source/v2/samples/vnffm/vnffm-alarm-notification-request.json @@ -0,0 +1,36 @@ +{ + "id": "0ab777dc-b3a0-42d6-85c1-e5f80711b988", + "notificationType": "AlarmNotification", + "subscriptionId": "0155c914-8573-463c-a97a-aef5a3ca9c72", + "timeStamp": "2023-12-08T13:16:30Z", + "alarm": { + "id": "de8e74e8-1845-40dd-892c-cb7a67c26f9f", + "managedObjectId": "c21fd71b-2866-45f6-89d0-70c458a5c32e", + "vnfcInstanceIds": ["VDU1-curry-probe-test001-798d577c96-5624p"], + "alarmRaisedTime": "2023-12-08T13:16:30+00:00", + "ackState": "UNACKNOWLEDGED", + "perceivedSeverity": "CRITICAL", + "eventTime": "2023-12-08T13:16:00Z", + "eventType": "PROCESSING_ERROR_ALARM", + "faultType": "fault_type", + "probableCause": "Process Terminated", + "isRootCause": false, + "faultDetails": [ + "fingerprint: 5ee739bb8840a190", + "detail: fault_details" + ], + "_links": { + "self": { + "href": "http://127.0.0.1:9890/vnffm/v1/alarms/de8e74e8-1845-40dd-892c-cb7a67c26f9f" + }, + "objectInstance":{ + "href": "http://127.0.0.1:9890/vnflcm/v2/vnf_instances/c21fd71b-2866-45f6-89d0-70c458a5c32e" + } + } + }, + "_links": { + "subscription": { + "href": "http://127.0.0.1:9890/vnffm/v1/subscriptions/0155c914-8573-463c-a97a-aef5a3ca9c72" + } + } +} \ No newline at end of file diff --git a/api-ref/source/v2/samples/vnfpm/pm-performance-information-available-notification-request.json b/api-ref/source/v2/samples/vnfpm/pm-performance-information-available-notification-request.json new file mode 100644 index 000000000..116353339 --- /dev/null +++ b/api-ref/source/v2/samples/vnfpm/pm-performance-information-available-notification-request.json @@ -0,0 +1,19 @@ +{ + "id": "29de3afc-0547-4f43-b921-1d6ceaf16bd4", + "notificationType": "PerformanceInformationAvailableNotification", + "timeStamp": "2023-11-20T14:25:04Z", + "pmJobId": "84b227dc-5ed0-411a-aff6-c830528eaec5", + "objectType": "Vnf", + "objectInstanceId": "a0205e7c-fdeb-4f6c-b266-962246e32626", + "_links": { + "objectInstance": { + "href": "http://127.0.0.1:9890/vnflcm/v2/vnf_instances/a0205e7c-fdeb-4f6c-b266-962246e32626" + }, + "pmJob": { + "href": "http://127.0.0.1:9890/vnfpm/v2/pm_jobs/84b227dc-5ed0-411a-aff6-c830528eaec5" + }, + "performanceReport": { + "href": "http://127.0.0.1:9890/vnfpm/v2/pm_jobs/84b227dc-5ed0-411a-aff6-c830528eaec5/reports/eab93857-eb72-49ce-9173-628a3f00ba2d" + } + } +} \ No newline at end of file diff --git a/api-ref/source/v2/samples/vnfpm/pm-threshold-crossed-notification-request.json b/api-ref/source/v2/samples/vnfpm/pm-threshold-crossed-notification-request.json new file mode 100644 index 000000000..8d0a8516f --- /dev/null +++ b/api-ref/source/v2/samples/vnfpm/pm-threshold-crossed-notification-request.json @@ -0,0 +1,19 @@ +{ + "id": "0aa6500e-cdee-41f7-aadd-af80f7622ebc", + "notificationType": "ThresholdCrossedNotification", + "timeStamp": "2023-12-06T09:08:06Z", + "thresholdId": "135db472-4f7b-4d55-abaf-27a3ab4d7ba1", + "crossingDirection": "DOWN", + "objectType": "Vnf", + "objectInstanceId": "c21fd71b-2866-45f6-89d0-70c458a5c32e", + "performanceMetric": "VCpuUsageMeanVnf.c21fd71b-2866-45f6-89d0-70c458a5c32e", + "performanceValue": "0.0004428400000000465", + "_links": { + "objectInstance": { + "href": "http://127.0.0.1:9890/vnflcm/v2/vnf_instances/c21fd71b-2866-45f6-89d0-70c458a5c32e" + }, + "threshold": { + "href": "http://127.0.0.1:9890/vnfpm/v2/thresholds/135db472-4f7b-4d55-abaf-27a3ab4d7ba1" + } + } +} \ No newline at end of file diff --git a/api-ref/source/v2/status.yaml b/api-ref/source/v2/status.yaml index 0d6df5882..68806dd38 100644 --- a/api-ref/source/v2/status.yaml +++ b/api-ref/source/v2/status.yaml @@ -15,6 +15,8 @@ 204: default: | The server has fulfilled the request by deleting the resource. + notification: | + The notification has been delivered successfully. 206: default: | Partial Content, The server has fulfilled the partial GET request for the diff --git a/api-ref/source/v2/vnffm.inc b/api-ref/source/v2/vnffm.inc index baa5cbb8f..3fcce7d04 100644 --- a/api-ref/source/v2/vnffm.inc +++ b/api-ref/source/v2/vnffm.inc @@ -489,3 +489,145 @@ Request Parameters .. rest_parameters:: parameters_vnffm.yaml - subscriptionId: subscription_id_path + +==================================================================== +Virtualized Network Function Fault Management Notification Interface +==================================================================== + +This interface is notification about VNF fault management. + +This interface is a notification sent to the endpoint configured as the +callbackUri when an event occurs that matches the filter criteria that is part +of the subscription, or when a VNF fault management subscription is created. +The detail of this interface is described in SOL002 v3.3.1 clause 7. + +AlarmNotification +================= + +.. rest_method:: POST < callbackUri (provided by API consumer) > + +The POST method delivers a notification about information of a VNF alarm from +Tacker to the API consumer. + +When an error or warning occurs on a VNF configured for monitoring with a VNF +fault management subscription, Tacker sends this notification to the endpoint +configured in the callbackUri of the "Create a subscription (v1)" API. + +Response Codes +-------------- + +Tacker expects a "204 No Content" response from the endpoint of the API consumer. +If any other response code is returned, it will be treated as an error. + +.. rest_status_code:: success status.yaml + + - 204: notification + +Request Parameters +------------------ + +.. rest_parameters:: parameters_vnffm.yaml + + - id: notification_id + - notificationType: alarm_notification_type + - subscriptionId: related_subscription_id + - timeStamp: notification_time_stamp + - alarm: alarm + - id: alarm_id + - managedObjectId: managed_object_id + - vnfcInstanceIds: vnfc_instance_ids + - rootCauseFaultyResource: faulty_resource_info + - faultyResource: faulty_resource + - vimConnectionId: alarm_faulty_resource_vim_connection_id + - resourceProviderId: faulty_resource_provider_id + - resourceId: faulty_resource_id + - vimLevelResourceType: faulty_resource_vim_level_resource_type + - faultyResourceType: faulty_resource_type + - alarmRaisedTime: alarm_raised_time + - alarmChangedTime: alarm_changed_time + - alarmClearedTime: alarm_cleared_time + - alarmAcknowledgedTime: alarm_acknowledged_time + - ackState: ack_state + - perceivedSeverity: alarm_perceived_severity + - eventTime: event_time + - eventType: event_type + - faultType: fault_type + - probableCause: probable_cause + - isRootCause: is_root_cause + - correlatedAlarmIds: correlated_alarm_ids + - faultDetails: fault_details + - _links: alarm_links + - self: alarm_self + - objectInstance: object_instance + - _links: notification_links + - subscription: related_subscription_links + +Request Example +--------------- + +.. literalinclude:: samples/vnffm/vnffm-alarm-notification-request.json + :language: javascript + +AlarmClearedNotification +======================== + +.. rest_method:: POST < callbackUri (provided by API consumer) > + +The POST method delivers a notification about information of the clearance of +a VNF alarm from Tacker to the API consumer. + +When an Error or Warning of a VNF that is set to be monitored with a VNF fault +management subscription is resolved, Tacker sends this notification to the +endpoint configured in the callbackUri of the "Create a subscription (v1)" API. + +Response Codes +-------------- + +Tacker expects a "204 No Content" response from the endpoint of the API consumer. +If any other response code is returned, it will be treated as an error. + +.. rest_status_code:: success status.yaml + + - 204: notification + +Request Parameters +------------------ + +.. rest_parameters:: parameters_vnffm.yaml + + - id: notification_id + - notificationType: alarm_cleared_notification_type + - subscriptionId: related_subscription_id + - timeStamp: notification_time_stamp + - alarmId: alarm_cleared_notification_alarm_id + - alarmClearedTime: alarm_cleared_notification_alarm_cleared_time + - _links: notification_links + - subscription: related_subscription_links + - alarm: related_alarm_links + +Request Example +--------------- + +.. literalinclude:: samples/vnffm/vnffm-alarm-cleared-notification-request.json + :language: javascript + +Test the notification endpoint (VNF FM) +======================================= + +.. rest_method:: GET < callbackUri (provided by API consumer) > + +The GET method test the notification endpoint. + +When a VNF fault management subscription is created using the "Create a +subscription (v1)" API, Tacker sends this notification to the endpoint +configured with callbackUri to confirm communication. + +Response Codes +-------------- + +Tacker expects a "204 No Content" response from the endpoint of the API consumer. +If any other response code is returned, it will be treated as an error. + +.. rest_status_code:: success status.yaml + + - 204: notification diff --git a/api-ref/source/v2/vnfpm.inc b/api-ref/source/v2/vnfpm.inc index 1443a0a4d..e1d43f8c0 100644 --- a/api-ref/source/v2/vnfpm.inc +++ b/api-ref/source/v2/vnfpm.inc @@ -704,3 +704,131 @@ Request Parameters .. rest_parameters:: parameters_vnfpm.yaml - thresholdId: vnf_pm_threshold_id + + +========================================================================== +Virtualized Network Function Performance Management Notification Interface +========================================================================== + +This interface is notification about VNF performance management. + +This interface is a notification that is sent to the endpoint configured as +the callbackUri when a performance management job or performance management +threshold is created, when an event occurs that indicates a threshold crossing +or the availability of performance information for a PM job. +The detail of this interface is described in SOL002 v3.3.1 clause 6. + +PerformanceInformationAvailableNotification +=========================================== + +.. rest_method:: POST < callbackUri (provided by API consumer) > + +The POST method delivers a notification about performance information +availability from Tacker to the API consumer. + +When an event occurs indicating the availability of performance information +for a PM job, Tacker sends this notification to the endpoint configured in the +callbackUri of the "Create a PM job (v2)" API. + +Response Codes +-------------- + +Tacker expects a "204 No Content" response from the endpoint of the API consumer. +If any other response code is returned, it will be treated as an error. + +.. rest_status_code:: success status.yaml + + - 204: notification + +Request Parameters +------------------ + +.. rest_parameters:: parameters_vnfpm.yaml + + - id: notification_id + - notificationType: notification_performance_information_available_notification_type + - timeStamp: notification_time_stamp + - pmJobId: notification_performance_information_available_pmjob_id + - objectType: notification_object_type + - objectInstanceId: notification_object_instance_id + - subObjectInstanceIds: notification_performance_information_available_sub_object_instance_ids + - _links: notification_links + - objectInstance: notification_object_instance + - pmJob : notification_performance_information_available_pmjob + - performanceReport : notification_performance_information_available_performance_report + +Request Example +--------------- + +.. literalinclude:: samples/vnfpm/pm-performance-information-available-notification-request.json + :language: javascript + +ThresholdCrossedNotification +============================ + +.. rest_method:: POST < callbackUri (provided by API consumer) > + +The POST method delivers a notification about threshold crossing from Tacker +to the API consumer. + +When a performance threshold is crossing for a VNF configured to be monitored +by VNF performance management threshold, Tacker sends this notification to the +endpoint configured in the callbackUri of the "Create a PM threshold (v2)" API. + +Response Codes +-------------- + +Tacker expects a "204 No Content" response from the endpoint of the API consumer. +If any other response code is returned, it will be treated as an error. + +.. rest_status_code:: success status.yaml + + - 204: notification + +Request Parameters +------------------ + +.. rest_parameters:: parameters_vnfpm.yaml + + - id: notification_id + - notificationType: notification_threshold_crossed_notification_type + - timeStamp: notification_time_stamp + - thresholdId: notification_threshold_crossed_threshold_id + - crossingDirection: notification_threshold_crossed_crossing_direction + - objectType: notification_object_type + - objectInstanceId: notification_object_instance_id + - subObjectInstanceId: notification_sub_object_instance_id + - performanceMetric: notification_threshold_crossed_performance_metric + - performanceValue: notification_threshold_crossed_performance_value + - context: notification_threshold_crossed_context + - _links: notification_links + - objectInstance: notification_object_instance + - threshold: notification_threshold_crossed_threshold + +Request Example +--------------- + +.. literalinclude:: samples/vnfpm/pm-threshold-crossed-notification-request.json + :language: javascript + +Test the notification endpoint (VNF PM) +======================================= + +.. rest_method:: GET < callbackUri (provided by API consumer) > + +The GET method test the notification endpoint. + +When a PM job is created using the "Create a PM job (v2)" API or a PM threshold +is created using the "Create a PM threshold (v2)" API, +Tacker sends this notification to the endpoint configured with callbackUri to +confirm communication. + +Response Codes +-------------- + +Tacker expects a "204 No Content" response from the endpoint of the API consumer. +If any other response code is returned, it will be treated as an error. + +.. rest_status_code:: success status.yaml + + - 204: notification