From f7b6c84b6dbf05cf6846c860cb13b307da35c015 Mon Sep 17 00:00:00 2001 From: Keiko Kuriu Date: Fri, 29 May 2020 19:16:32 +0900 Subject: [PATCH] Support LCM notification based on ETSI NFV-SOL specification Introduce new interfaces to notify LCM operation status of VNF instances towards clients. Blueprint: support-etsi-nfv-specs Change-Id: I9caf0a2a4f11e38280f7c1219ce98d659f528db6 --- ...notification-api-based-on-etsi-nfv-sol.rst | 793 ++++++++++++++++++ 1 file changed, 793 insertions(+) create mode 100644 specs/victoria/support-notification-api-based-on-etsi-nfv-sol.rst diff --git a/specs/victoria/support-notification-api-based-on-etsi-nfv-sol.rst b/specs/victoria/support-notification-api-based-on-etsi-nfv-sol.rst new file mode 100644 index 00000000..b486c09c --- /dev/null +++ b/specs/victoria/support-notification-api-based-on-etsi-nfv-sol.rst @@ -0,0 +1,793 @@ +.. + This work is licensed under a Creative Commons Attribution 3.0 Unported + License. + http://creativecommons.org/licenses/by/3.0/legalcode + + +===================================================================== +Support LCM notifications for VNF based on ETSI NFV-SOL specification +===================================================================== + +https://blueprints.launchpad.net/tacker/+spec/support-etsi-nfv-specs + +ETSI specifications within the NFV Architecture Framework [#etsi_nfv]_ +describe the main aspects of NFV development and usage based on of the +industry needs, feedback from SDN/NFV vendors and telecom operators. +These specifications include the REST API and data model architecture +which is used by NFV users and developers in related products. + +Problem description +=================== + +In the current Tacker implementation based on ETSI NFV-SOL, +Tacker uses its own API which describes VNF lifecycle change +notifications which is Ability to inform the receiver that +LCM operations has been changed. + +However, those operations are not aligned with the current ETSI NFV +data-model. As a result, there might be lack of compatibility with +`3rd party VNFs` [#etsi_plugtest2]_, as they are developed according to ETSI +NFV specifications. Support of key ETSI NFV specifications will +significantly reduce efforts for Tacker integration into Telecom production +networks and also will simplify further development and support of future +standards. + +Proposed change +=============== + +Introduces new interfaces to VNFM in order to notify VNF lifecycle +management operations status for VNF instances. +The operation provided through the interfaces are: + +* Subscription (GET/POST/DELETE) +* Notification endpoint (POST) +* Individual Subscription (GET) +* individual VNF occurrence (GET) + +1）Flow of managing subscriptions +--------------------------------- + +* Register subscription + +.. seqdiag:: + + seqdiag { + Client -> "tacker-server" [label = " POST /subscriptions"]; + "tacker-server" -> "tacker-server" + [label = " generate subscription_id (uuid)"]; + Client <-- "tacker-server" [label = " Resonse 201 Created"]; + } + + +* Delete subscription + +.. seqdiag:: + + seqdiag { + Client -> "tacker-server" + [label = " DELETE /subscriptions/{subscriptionId}"]; + Client <-- "tacker-server" [label = " Resonse 204 No Content"]; + } + + +* Show subscription + +.. seqdiag:: + + seqdiag { + Client -> "tacker-server" [label = " GET /subscriptions/{subscriptionId}"]; + Client <-- "tacker-server" [label = " Resonse 200 OK"]; + } + +* List subscription + +.. seqdiag:: + + seqdiag { + Client -> "tacker-server" [label = " GET /subscriptions"]; + "tacker-server" -> "tacker-server" [label = "request validation"]; + Client <-- "tacker-server" [label = " Resonse 200 OK"]; + } + + +* VNFM holds the Callback URL sent by consumer via "Subscription API" + in advance. +* Notify the issuer of the ID associated with the received Subscription + request. +* For the registered Subscription status, read by specifying ID, reading of + all ID data and deletion of specified ID are allowed. + + +2）Flow of sending notifications +-------------------------------- + +* Depending on the progress status of the sequence, VNFM send notification + (Notify) to notify the status change and update the internal + operation_status. + +Precondition: Requesting Node has subscribed previously to notifications +related to VNF lifecycle management. + +* When the LCM request is accepted, the operation status is sent to the + consumer which registers subscription via "Subscription API". This will + be sent for the number of registrations. +* The following operation states can be notified: + STARTING/PROCESSING/COMPLETED/ROLLINGBACK/ROLLEDBACK/FAILED_TEMP +* STARTING state is sent from Tacker Server, and other Operation_state + notifications are sent from Tacker-Conductor. +* Modify VNF does not send STARTING state. +* NFVO which recieved notification infomation sends 204 No Content to Tacker. + +3) Flow of LCM Operation with notification +------------------------------------------ + +* Instantiate VNF +* Scale VNF +* Heal VNF +* Terminate VNF + +.. seqdiag:: + + seqdiag { + Client -> "tacker-server" [label = "LCM Operation Request"]; + Client <-- "tacker-server" [label = "Response 202 Accepted"]; + "tacker-server" ->> "tacker-conductor" + [label = "execute notification process"]; + Client <- "tacker-conductor" [label = "POST {callback URI} (STARTING)"]; + Client --> "tacker-conductor" [label = "Response: 204 No Content"]; + "tacker-server" -> "tacker-conductor" + [label = "trriger asynchronous task"]; + NFVO <- "tacker-conductor" [label = "POST /grants"]; + NFVO --> "tacker-conductor" [label = "201 Created"]; + "tacker-conductor" ->> "tacker-conductor" + [label = "execute notification process"]; + Client <- "tacker-conductor" [label = "POST {callback URI} (PROCESSING)"]; + Client --> "tacker-conductor" [label = "Response: 204 No Content"]; + "tacker-conductor" -> "VnfLcmDriver" [label = "execute MgmtDriver"]; + "tacker-conductor" <-- "VnfLcmDriver" [label = ""]; + "tacker-conductor" -> "VnfLcmDriver" [label = "execute VnfLcmDriver"]; + "tacker-conductor" <-- "VnfLcmDriver" [label = ""]; + "tacker-conductor" ->> "tacker-conductor" + [label = "execute notification process"]; + Client <- "tacker-conductor" [label = "POST {callback URI} (COMPLETED)"]; + Client --> "tacker-conductor" [label = "Response: 204 No Content"]; + } + + +* Modify VNF + +.. seqdiag:: + + seqdiag { + Client -> "tacker-server" [label = "LCM Operation Request"]; + Client <-- "tacker-server" [label = "Response 202 Accepted"]; + "tacker-server" -> "tacker-conductor" + [label = "trriger asynchronous task"]; + "tacker-conductor" ->> "tacker-conductor" + [label = "execute notification process"]; + Client <- "tacker-conductor" + [label = "POST {callback URI} (PROCESSING)"]; + Client --> "tacker-conductor" [label = "Response: 204 No Content"]; + "tacker-conductor" -> "VnfLcmDriver" [label = "execute MgmtDriver"]; + "tacker-conductor" <-- "VnfLcmDriver" [label = ""]; + "tacker-conductor" -> "VnfLcmDriver" [label = "execute VnfLcmDriver"]; + "tacker-conductor" <-- "VnfLcmDriver" [label = ""]; + "tacker-conductor" ->> "tacker-conductor" + [label = "execute notification process"]; + Client <- "tacker-conductor" + [label = "POST {callback URI} (COMPLETED)"]; + Client --> "tacker-conductor" [label = "Response: 204 No Content"]; + } + + +* Rollback + +.. seqdiag:: + + seqdiag { + node_width = 100; + edge_length = 160; + + Client -> "tacker-server" + [label = "POST /vnf_lcm_op_occs/{vnfLcmOpOccId}/rollback"]; + Client <-- "tacker-server" [label = "Response 202 Accepted"]; + "tacker-server" -> "tacker-conductor" + [label = "trriger asynchronous task"]; + "tacker-conductor" ->> "tacker-conductor" + [label = "execute notification process"]; + Client <- "tacker-conductor" + [label = "POST {callback URI} (ROLLING_BACK)"]; + Client --> "tacker-conductor" + [label = "Response: 204 No Content"]; + "tacker-conductor" -> "MgmtDriver" [label = "execute MgmtDriver"]; + "tacker-conductor" <-- "MgmtDriver" [label = ""]; + "tacker-conductor" -> "VnfLcmDriver" [label = "execute VnfLcmDriver"]; + "tacker-conductor" <-- "VnfLcmDriver" [label = ""]; + "tacker-conductor" ->> "tacker-conductor" + [label = "execute notification process"]; + Client <- "tacker-conductor" + [label = "POST {callback URI} (ROLLED_BACK)"]; + Client --> "tacker-conductor" + [label = "Response: 204 No Content"]; + } + + +4) Flow of VNF instance resource with notification +-------------------------------------------------- + +* CereateVNFRequest + +.. seqdiag:: + + seqdiag { + Client -> "tacker-server" [label = "POST /vnf_instances/"]; + "tacker-server" ->> "tacker-server" + [label = "Create VNF instance resource"]; + "tacker-server" -> "tacker-conductor" + [label = "execute vnf_package list process{filter}"]; + NFVO <- "tacker-conductor" + [label = "GET /vnf_packages/ with attribute filter(vnfdId)"]; + NFVO --> "tacker-conductor" + [label = "Response 200 OK with VnfPkgInfo"]; + "tacker-server" <<- "tacker-conductor" [label = "(VnfPkgInfo)"]; + "tacker-server" ->> "tacker-server" + [label = "Update VNF instance resource(VnfPkgInfo)"]; + "tacker-server" -> "tacker-conductor" + [label = "execute vnf_package content process{vnfPkgId}"]; + NFVO <- "tacker-conductor" + [label = "GET /vnf_packages/{vnfPkgId}/package_content "]; + NFVO --> "tacker-conductor" + [label = "Response 200 OK with VNF package file"]; + "tacker-server" <<- "tacker-conductor" + [label = "(VNF package content file)"]; + "tacker-server" ->> "tacker-server" + [label = "Store received package file"]; + Client <-- "tacker-server" [label = " Resonse 201 Created"]; + "tacker-server" ->> "tacker-conductor" + [label = "execute notification process"]; + Client <- "tacker-conductor" [label = "POST {callback URI}"]; + Client --> "tacker-conductor" [label = "Responce 204 No Content"]; + } + + +* DeleteVNFRequest + +.. seqdiag:: + + seqdiag { + Client -> "tacker-server" [label = "DELETE /vnf_instances/{vnfInstanceId} "]; + "tacker-server" ->> "tacker-server" + [label = "Delete VNF instance resource"]; + Client <-- "tacker-server" [label = " Resonse 204 No Content"]; + "tacker-server" ->> "tacker-conductor" + [label = "execute notification process"]; + Client <- "tacker-conductor" [label = "POST {callback URI}"]; + Client --> "tacker-conductor" [label = "Responce 204 No Content"]; + } + + +5）Flow of Getting Operation Status +----------------------------------- + +Operation status can be obtained from VNFM. + +.. seqdiag:: + + seqdiag { + Client -> "tacker-server" [label = " GET /vnf_lcm_op_occs/{vnfLcmOpOccId}"]; + Client <-- "tacker-server" [label = " Resonse 200 OK"]; + } + + +* The transmission source node specifies the vnfLcmOpOccId issued at the time + of subscription and reads the information about the resource in the + Subscription state. +* If the VNFM information read is successful, Response 200 OK is responded. + +Alternatives +------------ + +None + +Data model impact +----------------- + +Add below new tables in ‘tacker’ database. The corresponding schemas are +detailed below:- + +A list of added tables: + - vnf_lcm_filters + +details of added table: + +vnf_lcm_filters: + + .. code-block:: python + + id id varchar(36) Not Null + subscription_uuid subscription_uuid varchar(36) Not Null + filter filter json Not Null + vnf_instance_ids vnf_instance_ids MEDIUMBLOB + vnf_instance_ids_len vnf_instance_ids_len int + notification_types notification_types MEDIUMBLOB + notification_types_len notification_types_len int + operation_types operation_types MEDIUMBLOB + operation_types_len operation_types_len int + operation_states operation_states MEDIUMBLOB + operation_states_len operation_states_len int + +This table has current status of LCM. +Table for accumulating information for each event. + +vnf_lcm_op_occs: + + .. code-block:: python + + id id varchar(36) Not Null + operation_state operation_state varchar(16) Not Null + state_entered_time state_entered_time datetime Not Null + start_time start_time datetime Not Null + vnf_instance_id vnf_instance_id varchar(36) Not Null + operation operation varchar(16) Not Null + is_automatic_invocation is_automatic_invocation tinyint(1) Not Null + operation_params operation_params json + error error json + resource_changes resource_changes json + +This table has current status of operation occurrence + +vnf_lcm_subscriptions: + + .. code-block:: python + + id id varchar(36) Not Null + callback_uri callback_uri varchar(255) Not Null + subscription_authentication subscription_authentication json + +This table has registration information of Subscription + +REST API impact +--------------- + +The following restFul API will be added. This restFul API will be based on +ETSI NFV SOL002 [#NFV-SOL002]_ and SOL003 [#NFV-SOL003]_. + +* | **Name**: Subscriptions + | **Description**: Subscribe to notifications related to VNF lifecycle + management + | **Method type**: POST + | **URL for the resource**: /vnflcm/v1/subscriptions + | **Request**: + + +--------------------------+-------------+----------------------------------+ + | Data type | Cardinality | Description | + +==========================+======+======+==================================+ + | LccnSubscriptionRequest | 1 | Parameters for the Subscription. | + +--------------------------+-------------+----------------------------------+ + + .. list-table:: + :header-rows: 1 + + * - Attribute name + - Data type + - Cardinality + - Supported in (V) + * - filter + - LifecycleChangeNotificationFilter + - 0..1 + - Yes + * - callbackUri + - Uri + - 1 + - Yes + * - authentication + - SubscriptionAuthentication + - 0..1 + - Yes + + | **Response**: + + .. list-table:: + :widths: 10 10 18 50 + :header-rows: 1 + + * - Data type + - Cardinality + - Response Codes + - Description + * - LccnSubscription + - n/a + - | Success 201 + | Redirection 303 + | Error 4xx + - The subscription has been created successfully. + +* | **Name**: List Subscriptions + | **Description**: Request to list all existing subscriptions + | **Method type**: GET + | **URL for the resource**: /vnflcm/v1/subscriptions + | **Request**: + + .. list-table:: + :header-rows: 1 + + * - Data type + - Cardinality + - Description + - Supported in (V) + * - filter + - 0..1 + - Filter to list subscriptions + - No + + | **Response**: + + .. list-table:: + :widths: 10 10 18 50 + :header-rows: 1 + + * - Data type + - Cardinality + - Response Codes + - Description + * - LccnSubscription + - n/a + - | Success 200 + | Error 400 4xx + - The list of subscriptions has been queried successfully. + +* | **Name**: Query Subscriptions + | **Description**: Request to show individual subscription resource by its id + | **Method type**: GET + | **URL for the resource**: /vnflcm/v1/subscriptions/{subscriptionId} + | **Request**: + + +----------------+----------------------------------+ + | Name | Description | + +================+==================================+ + | subscriptionId | Identifier of the subscriptions. | + +----------------+----------------------------------+ + + | **Response**: + + .. list-table:: + :widths: 10 10 18 50 + :header-rows: 1 + + * - Data type + - Cardinality + - Response Codes + - Description + * - LccnSubscription + - n/a + - | Success 200 + | Error 400 4xx + - The operation has completed successfully. + +* | **Name**: Delete Subscriptions + | **Description**: Request to delete individual subscription resource by + its id + | **Method type**: DELETE + | **URL for the resource**: /vnflcm/v1/subscriptions/{subscriptionId} + | **Request**: + + +----------------+----------------------------------+ + | Name | Description | + +================+==================================+ + | subscriptionId | Identifier of the subscriptions. | + +----------------+----------------------------------+ + + | **Response**: + + .. list-table:: + :widths: 10 10 18 50 + :header-rows: 1 + + * - Data type + - Cardinality + - Response Codes + - Description + * - n/a + - n/a + - | Success 204 + | Error 400 4xx + - The individual subscription resource has been deleted successfully. + +* | **Name**: Notification endpoint + | **Description**: Send notifications related to VNF lifecycle changes + | **Method type**: POST + | **URL for the resource**: The resource URI is provided by the client when + creating the subscription. + | **Request**: + + .. list-table:: + :widths: 20 10 50 + :header-rows: 1 + + * - Data type + - Cardinality + - Description + * - VnfLcmOperationOccurrenceNotification + - 1 + - A notification about lifecycle changes triggered by a VNF LCM + operation occurrence. + * - VnfIdentifierCreationNotification + - 1 + - A notification about lthe creation of a VNF identifier and the + related individual VNF instance resource. + * - VnfIdentifierDeletionNotification + - 1 + - A notification about the deletion of a VNF identifier and the + related individual VNF instance resource. + + .. list-table:: + :header-rows: 1 + + * - Attribute name + - Data type + - Cardinality + - Supported in (V) + * - id + - Identifier + - 1 + - Yes + * - notificationType + - String + - 1 + - Yes + * - subscriptionId + - Identifier + - 1 + - Yes + * - timeStamp + - DateTime + - 1 + - Yes + * - notificationStatus + - Enum (inlined) + - 1 + - Yes + * - operationState + - LcmOperationStateType + - 1 + - Yes + * - vnfInstanceId + - Identifier + - 1 + - Yes + * - operation + - LcmOperationType + - 1 + - Yes + * - isAutomaticInvocation + - Boolean + - 1 + - Yes + * - vnfLcmOpOccId + - Identifier + - 1 + - Yes + * - affectedVnfcs + - AffectedVnfc + - 0..N + - Yes + * - affectedVirtualLinks + - AffectedVirtualLink + - 0..N + - Yes + * - affectedVirtualStorages + - AffectedVirtualStorage + - 0..N + - Yes + * - changedInfo + - VnfInfoModifications + - 0..1 + - Yes + * - changedExtConnectivity + - ExtVirtualLinkInfo + - 0..N + - No + * - error + - ProblemDetails + - 0..1 + - Yes + * - _links + - LccnLinks + - 1 + - Yes + + | **Response**: + + .. list-table:: + :widths: 12 10 18 50 + :header-rows: 1 + + * - Data type + - Cardinality + - Response Codes + - Description + * - n/a + - n/a + - | Success 204 + | Error 4xx + - The notification has been delivered successfully. + +.. note:: `virtualLinkDescId`, one of the attribute contained in + affectedVirtualLinks, is removed upon SOL003 version + 2.6.1. However, in order to enable Tacker to expand + a wide range of NFV compliant product, `virtualLinkDescId` + will be supported in Victoria release. + +* | **Name**: Query VNF occurrence + | **Description**: Request to show individual VNF lifecycle management + operation occurrence by its id + | **Method type**: GET + | **URL for the resource**: /vnflcm/v1/vnf_lcm_op_occs/{vnfLcmOpOccId} + | **Response**: + + .. list-table:: + :widths: 12 10 18 50 + :header-rows: 1 + + * - Data type + - Cardinality + - Response Codes + - Description + * - VnfLcmOpOcc + - 1 + - | Success 200 + | Error 4xx + - The operation has completed successfully. + + .. list-table:: + :header-rows: 1 + + * - Attribute name + - Data type + - Cardinality + - Supported in (V) + * - id + - Identifier + - 1 + - Yes + * - operationState + - LcmOperationStateType + - 1 + - Yes + * - stateEnteredTime + - DateTime + - 1 + - Yes + * - startTime + - DateTime + - 1 + - Yes + * - vnfInstanceId + - Identifier + - 1 + - Yes + * - grantId + - Identifier + - 1 + - No + * - operation + - LcmOperationType + - 1 + - Yes + * - isAutomaticInvocation + - Boolean + - 1 + - Yes + * - operationParams + - Object + - 1 + - Yes + * - isCancelPending + - Boolean + - 0..N + - No + * - cancelMode + - CancelModeType + - 0..N + - No + * - error + - ProblemDetails + - 0..N + - Yes + * - resourceChanges + - Structure(inlined) + - 0..1 + - Yes + * - changedInfo + - VnfInfoModifications + - 0..N + - No + * - changedExtConnectivity + - ExtVirtualLinkInfo + - 0..1 + - No + * - _links + - LccnLinks + - 1 + - Yes + +Security impact +--------------- + +None + +Notifications impact +-------------------- +Tacker will creates a new subscription to notifications related to VNF +lifecycle changes and send notification to consumer. + + +Other end user impact +--------------------- + +None + +Performance Impact +------------------ + +None + +Other deployer impact +--------------------- + +The previously created VNFs will not be allowed to be managed using the newly +introduced APIs. + +Developer impact +---------------- + +None + + +Implementation +============== + +Assignee(s) +----------- + +Primary assignee: + Keiko Kuriu + +Work Items +---------- + +* Add new REST API endpoints to Tacker-server for LCM notifications interface + of VNF instances. +* Add features which Tacker consumes Rest API for Notifications +* Add new unit and functional tests. +* Change API Tacker documentation. + +Dependencies +============ + +None + +Testing +======== + +Unit and functional test cases will be added for VNF lifecycle management +of VNF instances. + +Documentation Impact +==================== + +Complete user guide will be added to explain how to invoke VNF lifecycle +management of VNF instances with examples. + +References +========== + +.. [#etsi_nfv] https://www.etsi.org/technologies-clusters/technologies/NFV +.. [#NFV-SOL002] + https://www.etsi.org/deliver/etsi_gs/NFV-SOL/001_099/002/02.06.01_60/gs_nfv-sol002v020601p.pdf + (Chapter 5: VNF Lifecycle Management interface) +.. [#NFV-SOL003] + https://www.etsi.org/deliver/etsi_gs/NFV-SOL/001_099/003/02.06.01_60/gs_nfv-sol003v020601p.pdf + (Chapter 5: VNF Lifecycle Management interface) +.. [#etsi_plugtest2] + https://portal.etsi.org/Portals/0/TBpages/CTI/Docs/2nd_ETSI_NFV_Plugtests_Report_v1.0.0.pdf