openstack/tacker
Code Issues Proposed changes

Enhanced VNF FM and VNF PM Documentation

Browse Source 
Added notifications sent to API consumers by the VNF Fault Management
and VNF Performance Management features to the API Reference.

Added the following APIs:
- alarm notification
- AlarmClearedNotification
- PerformanceInformationAvailableNotification
- ThresholdCrossedNotification
- Test the notification endpoint

Change-Id: I5f169809c14bc980c8e2b37f1b49299cfa62086f
Signed-off-by: Yasufumi Ogawa <yasufum.o@gmail.com>
Co-Authored-By: Yoshiro Watanabe <fj3838ct@fujitsu.com>
This commit is contained in:
Yasufumi Ogawa 2024-06-18 08:46:08 +09:00 committed by Yoshiro Watanabe
parent 7be3fdf2a7
commit 5587b8e17d
9 changed files with 575 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

85
api-ref/source/v2/parameters_vnffm.yaml
View File

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

129
api-ref/source/v2/parameters_vnfpm.yaml
View File

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

16
api-ref/source/v2/samples/vnffm/vnffm-alarm-cleared-notification-request.json Normal file
View File

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

36
api-ref/source/v2/samples/vnffm/vnffm-alarm-notification-request.json Normal file
View File

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

19
api-ref/source/v2/samples/vnfpm/pm-performance-information-available-notification-request.json Normal file
View File

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

19
api-ref/source/v2/samples/vnfpm/pm-threshold-crossed-notification-request.json Normal file
View File

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

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

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

142
api-ref/source/v2/vnffm.inc
View File

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

128
api-ref/source/v2/vnfpm.inc
View File

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