Merge "Enhanced VNF FM and VNF PM Documentation"

2024-09-11 13:26:32 +00:00
parent 80bd24be5f 5587b8e17d
commit 59e9fa2cd3
9 changed files with 575 additions and 1 deletions
--- 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
--- 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
--- 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
@@ -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"
+        }
+    }
+}
--- a/api-ref/source/v2/samples/vnffm/vnffm-alarm-notification-request.json
+++ 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"
+        }
+    }
+}
--- 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
@@ -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"
+        }
+    }
+}
--- 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
@@ -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"
+        }
+    }
+}
--- 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
--- 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
--- 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