openstack/tacker
Code Issues Proposed changes
Files
f3b72022e7b332ca7b1c38c549edb8096f5da8fe
tacker/api-ref/source/v2/vnffm.inc
Yasufumi Ogawa 5587b8e17d Enhanced VNF FM and VNF PM Documentation 
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>
2024-09-06 08:36:45 +00:00

634 lines
19 KiB
ReStructuredText
Raw Blame History

.. -*- rst -*-
================================================================
Virtualized Network Function Fault Management Interface (VNF FM)
================================================================
This interface manages the VNF fault management operations of VNF instances.
This interface allows the NFVO to invoke VNF fault management operations of
VNF instances towards the VNFM. The detail of this interface is described in
SOL002 v3.3.1 clause 7. The parameters of some specific standards need
reference SOL013 v3.4.1 clause 5.
Get all alarms (v1)
===================
.. rest_method:: GET /vnffm/v1/alarms
The GET method gets all alarms, Allow users to filter out alarms based on query
parameter in the request.
If the API consumer intends to query all alarms, it sends a GET request to the
"Alarms" resource. The VNFM returns a "200 OK" response to the API consumer, and
includes zero or more data structures of type "Alarm" in the payload body.
An attribute selector allows the API consumer to choose which attributes it
wants to be contained in the response. *all_fields*, *fields*, *exclude_fields*
and *exclude_default* can be set as query parameters.
Attribute-based filtering expression. The following attribute names shall be
supported by the Tacker in the attribute-based filtering expression: id,
managedObjectId, rootCauseFaultyResource/faultyResourceType, eventType,
perceivedSeverity, probableCause.
Response Codes
--------------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 400
- 401
- 406
Response Parameters
-------------------
.. rest_parameters:: parameters_vnffm.yaml
- id: alarm_id
- managedObjectId: managed_object_id
- vnfcInstanceIds: vnfc_instance_ids
- rootCauseFaultyResource: faulty_resource_info
- faultyResource: faulty_resource
- vimConnectionId: 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: 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
Response Example
----------------
.. literalinclude:: samples/vnffm/list-vnffm-alarm-response.json
:language: javascript
Get the individual alarm (v1)
=============================
.. rest_method:: GET /vnffm/v1/alarms/{alarmId}
The GET method gets the alarm specified in the Tacker.
If the API consumer intends to read a particular alarm, it sends a GET request
to the "Individual alarm" resource, addressed by the appropriate alarm
identifier in its resource URI.
The VNFM returns a "200 OK" response to the API consumer,
and includes the data structure of type "Alarm" in the payload body.
In case of failure, appropriate error
information is provided in the response.
Response Codes
--------------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 400
- 401
- 404
- 406
Request Parameters
------------------
.. rest_parameters:: parameters_vnffm.yaml
- alarmId: alarm_id_path
Response Parameters
-------------------
.. rest_parameters:: parameters_vnffm.yaml
- id: alarm_id
- managedObjectId: managed_object_id
- vnfcInstanceIds: vnfc_instance_ids
- rootCauseFaultyResource: faulty_resource_info
- faultyResource: faulty_resource
- vimConnectionId: 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: 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
Response Example
----------------
.. literalinclude:: samples/vnffm/show-vnffm-alarm-response.json
:language: javascript
Modify the confirmation status (v1)
===================================
.. rest_method:: PATCH /vnffm/v1/alarms/{alarmId}
The PATCH method modifies the confirmation status of the alarm specified in the
Tacker.
The API consumer sends a PATCH request to the individual alarm. The VNFM
returns a "200 OK" response to the API consumer, and includes a data structure
of type "AlarmModifications" in the payload body. In case of failure,
appropriate error information is provided in the response.
Response Codes
--------------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 400
- 401
- 404
- 406
- 409
Request Parameters
------------------
.. rest_parameters:: parameters_vnffm.yaml
- alarmId: alarm_id_path
- ackState: ack_state
Request Example
---------------
.. literalinclude:: samples/vnffm/modify-vnffm-alarm-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters_vnffm.yaml
- ackState: ack_state
Response Example
----------------
.. literalinclude:: samples/vnffm/modify-vnffm-alarm-response.json
:language: javascript
Create a subscription (v1)
==========================
.. rest_method:: POST /vnffm/v1/subscriptions
The POST method creates a new VNF FM-Subscription.
As the result of successfully executing this method, a new VNF FM-Subscription
shall have been created, and return detailed FM subscription data. In case of
failure, including an invalid notification endpoint, appropriate error
information is provided in the response.
Response Codes
--------------
.. rest_status_code:: success status.yaml
- 201
.. rest_status_code:: error status.yaml
- 400
- 401
- 406
- 422
Request Parameters
------------------
.. rest_parameters:: parameters_vnffm.yaml
- filter: fm_notification_filter
- vnfInstanceSubscriptionFilter: filter_subscription_filter
- vnfdIds: subscription_filter_vnfd_ids
- vnfProductsFromProviders: subscription_filter_vnf_products_from_providers
- vnfProvider: vnf_products_from_providers_vnf_provider
- vnfProducts: vnf_products_from_providers_vnf_products
- vnfProductName: products_vnf_product_name
- versions: products_versions
- vnfSoftwareVersion: versions_vnf_software_version
- vnfdVersions: versions_vnfd_versions
- vnfInstanceIds: subscription_filter_vnf_instance_ids
- vnfInstanceNames: subscription_filter_vnf_instance_names
- notificationTypes: filter_notification_types
- faultyResourceTypes: filter_faulty_resource_types
- perceivedSeverities: filter_perceived_severities
- eventTypes: filter_event_types
- probableCauses: filter_probable_causes
- callbackUri: callback_uri
- authentication: authentication
- authType: authentication_auth_type
- paramsBasic: authentication_params_basic
- userName: paramsBasic_userName
- password: paramsBasic_password
- paramsOauth2ClientCredentials: authentication_params_oauth2_client_credentials
- clientId: params_oauth2_client_credentials_client_id
- clientPassword: params_oauth2_client_credentials_client_password
- tokenEndpoint: params_oauth2_client_credentials_token_endpoint
- paramsOauth2ClientCert: authentication_params_oauth2_client_cert
- clientId: params_oauth2_client_cert_client_id
- certificateRef: params_oauth2_client_cert_certificate_ref
- type: params_oauth2_client_cert_type
- value: params_oauth2_client_cert_value
- tokenEndpoint: params_oauth2_client_cert_token_endpoint
Request Example
---------------
.. literalinclude:: samples/vnffm/create-vnffm-subscription-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters_vnffm.yaml
- id: subscription_id
- filter: fm_notification_filter
- vnfInstanceSubscriptionFilter: filter_subscription_filter
- vnfdIds: subscription_filter_vnfd_ids
- vnfProductsFromProviders: subscription_filter_vnf_products_from_providers
- vnfProvider: vnf_products_from_providers_vnf_provider
- vnfProducts: vnf_products_from_providers_vnf_products
- vnfProductName: products_vnf_product_name
- versions: products_versions
- vnfSoftwareVersion: versions_vnf_software_version
- vnfdVersions: versions_vnfd_versions
- vnfInstanceIds: subscription_filter_vnf_instance_ids
- vnfInstanceNames: subscription_filter_vnf_instance_names
- notificationTypes: filter_notification_types
- faultyResourceTypes: filter_faulty_resource_types
- perceivedSeverities: filter_perceived_severities
- eventTypes: filter_event_types
- probableCauses: filter_probable_causes
- callbackUri: callback_uri
- _links: subscription_links
- self: subscription_self
Response Example
----------------
.. literalinclude:: samples/vnffm/create-vnffm-subscription-response.json
:language: javascript
Get all subscriptions (v1)
==========================
.. rest_method:: GET /vnffm/v1/subscriptions
The GET method allows users to filter out subscriptions based on query parameter
in the request.
If desired, e.g. to recover from an error situation, the API consumer can query
information about its subscriptions by sending a GET request to the
"Subscriptions" resource. In that case, the VNFM returns a "200 OK" response
that contains the list of representations of all existing subscriptions that
were created by the API consumer, and includes zero or more data structures
of type "FmSubscription" in the payload body.
An attribute selector allows the API consumer to choose which attributes it
wants to be contained in the response. *all_fields*, *fields*, *exclude_fields*
and *exclude_default* can be set as query parameters.
Attribute-based filtering expression. The following attribute names shall be
supported by the Tacker in the attribute-based filtering expression. All
attribute names that appear in the FmSubscription and in data types referenced
from it shall be supported by the VNFM in the filter expression. For example,
below URI query parameter will match alarms with perceivedSeverity=WARNING
Response Codes
--------------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 400
- 401
- 404
- 406
Response Parameters
-------------------
.. rest_parameters:: parameters_vnffm.yaml
- id: subscription_id
- filter: fm_notification_filter
- vnfInstanceSubscriptionFilter: filter_subscription_filter
- vnfdIds: subscription_filter_vnfd_ids
- vnfProductsFromProviders: subscription_filter_vnf_products_from_providers
- vnfProvider: vnf_products_from_providers_vnf_provider
- vnfProducts: vnf_products_from_providers_vnf_products
- vnfProductName: products_vnf_product_name
- versions: products_versions
- vnfSoftwareVersion: versions_vnf_software_version
- vnfdVersions: versions_vnfd_versions
- vnfInstanceIds: subscription_filter_vnf_instance_ids
- vnfInstanceNames: subscription_filter_vnf_instance_names
- notificationTypes: filter_notification_types
- faultyResourceTypes: filter_faulty_resource_types
- perceivedSeverities: filter_perceived_severities
- eventTypes: filter_event_types
- probableCauses: filter_probable_causes
- callbackUri: callback_uri
- _links: subscription_links
- self: subscription_self
Response Example
----------------
.. literalinclude:: samples/vnffm/list-vnffm-subscription-response.json
:language: javascript
Get a subscription (v1)
=======================
.. rest_method:: GET /vnffm/v1/subscriptions/{subscriptionId}
The GET method gets the subscription in the Tacker.
If desired, e.g. to recover from an error situation, the API consumer can read
information about a particular subscription by sending a GET request to the
resource representing that individual subscription. In that case, the VNFM
returns a "200 OK" response that contains a representation of that individual
subscription.
Response Codes
--------------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 400
- 401
- 404
- 406
Request Parameters
------------------
.. rest_parameters:: parameters_vnffm.yaml
- subscriptionId: subscription_id_path
Response Parameters
-------------------
.. rest_parameters:: parameters_vnffm.yaml
- id: subscription_id
- filter: fm_notification_filter
- vnfInstanceSubscriptionFilter: filter_subscription_filter
- vnfdIds: subscription_filter_vnfd_ids
- vnfProductsFromProviders: subscription_filter_vnf_products_from_providers
- vnfProvider: vnf_products_from_providers_vnf_provider
- vnfProducts: vnf_products_from_providers_vnf_products
- vnfProductName: products_vnf_product_name
- versions: products_versions
- vnfSoftwareVersion: versions_vnf_software_version
- vnfdVersions: versions_vnfd_versions
- vnfInstanceIds: subscription_filter_vnf_instance_ids
- vnfInstanceNames: subscription_filter_vnf_instance_names
- notificationTypes: filter_notification_types
- faultyResourceTypes: filter_faulty_resource_types
- perceivedSeverities: filter_perceived_severities
- eventTypes: filter_event_types
- probableCauses: filter_probable_causes
- callbackUri: callback_uri
- _links: subscription_links
- self: subscription_self
Request Example
---------------
.. literalinclude:: samples/vnffm/show-vnffm-subscription-response.json
:language: javascript
Delete a subscription (v1)
==========================
.. rest_method:: DELETE /vnffm/v1/subscriptions/{subscriptionId}
The DELETE method deletes the subscription in the Tacker
When the API consumer does not need the subscription anymore, it terminates the
subscription by sending a DELETE request to the resource that represents the
individual subscription. The VNFM acknowledges the successful termination of
the subscription by returning a "204 No Content" response.
Response Codes
--------------
.. rest_status_code:: success status.yaml
- 204
.. rest_status_code:: error status.yaml
- 400
- 401
- 404
- 406
- 409
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
View Git Blame Copy Permalink