Support ETSI NFV-SOL_v3 error-handling operation

https://blueprints.launchpad.net/tacker/+spec/support-nfv-solv3-error-handling

This specification supports a new version of VNF lifecycle management APIs complying with ETSI NFV SOL v3. It adds a new version of APIs involved in error handling operations (retry, fail, rollback).

Problem description

ETSI specifications within the NFV Architecture Framework [1] describe the main aspects of NFV development and usage based on 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.

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. To integrate Tacker into a wide variety of products, it should comply with multiple versions of ETSI NFV SOL specifications. Tacker has already supported VNF lifecycle management operations defined in ETSI NFV SOL002 v2.6.1 [2] and SOL003 v2.6.1 [3]. Furthermore, Xena release supported a part of VNF lifecycle management operations defined in ETSI NFV SOL002 v3.3.1 [4] and SOL003 v3.3.1 [5]. The details of supported APIs are described in Tacker Xena Specifications [6] [7]. Tacker should support more VNF lifecycle management operations defined in ETSI NFV SOL002/003 v3.3.1.

Proposed change

Since the VNF lifecycle management interface version specified in ETSI NFV SOL v3 is “2.0.0”, the API major version included in the URI shall be set to “v2”. Supporting v2 APIs involves changing the data type of some attributes and adding or removing attributes. To avoid impact on the existing implementation, APIs corresponding to “v2” should be implemented as a process independent of that of “v1”.

This interface supports the following APIs involved in error handling of lifecycle management operation.

• Retry operation (POST /vnf_lcm_op_occs/{vnfLcmOpOccId}/retry)

• Fail operation (POST /vnf_lcm_op_occs/{vnfLcmOpOccId}/fail)

• Rollback operation (POST /vnf_lcm_op_occs/{vnfLcmOpOccId}/rollback)

1) Flow of Retry operation

LCM operations that can perform Retry operation are Instantiation, Termination, Healing, Scaling, Modify and ChangeExternalConnectivity.

The procedure consists of the following steps as illustrated in above sequence:

Precondition: VNF lifecycle management operation occurrence is in FAILED_TEMP state.

1. The Client sends a POST request with an empty body to the “Retry operation” resource.

2. VNFM sends endpoints such as Client a VNF lifecycle management operation occurrence notification with the “PROCESSING” state to indicate the processing occurrence of the lifecycle management operation.

3. On successful retry, VNFM sends endpoints such as Client a VNF lifecycle management operation occurrence notification with the “COMPLETED” state to indicate successful completion of the operation.

4. On unsuccessful retry, VNFM sends endpoints such as Client a VNF lifecycle management operation occurrence notification with the “FAILED_TEMP” state to indicate an intermediate error (retry failed) of the operation.

Postcondition: The VNF lifecycle management operation occurrence is in one of the following states: FAILED_TEMP, COMPLETED.

Note

For details on the retry procedure, refer to the specifications [6] [8] for each VNF lifecycle management operation.

2) Flow of Fail operation

LCM operations that can perform Fail operation are Instantiation, Termination, Healing, Scaling, Modify and ChangeExternalConnectivity.

The procedure consists of the following steps as illustrated in above sequence:

Precondition: VNF lifecycle management operation occurrence is in FAILED_TEMP state.

1. The client sends a POST request with an empty body to the “Fail operation” resource.

2. VNFM marks the operation as failed.

3. VNFM sends endpoints such as Client a VNF lifecycle management operation occurrence notification with the “FAILED” state to indicate the final failure of the operation.

Postcondition: The VNF lifecycle management operation occurrence is FAILED state.

3) Flow of Rollback operation

LCM operations that can perform Rollback operation are Instantiation, Scale-out, Modify, and ChangeExternalConnectivity.

When a Rollback request is received, VNFM operates to stop the lifecycle operation normally while it is terminated. As shown in the below, there are differences in flow of rollback for each VNF lifecycle management operation.

When the rollback operation is executed during VNF instantiation, VNFM removes all VMs and resources.

When the rollback operation is executed for scale-out VNF operation, VNFM reverts changes of VMs and resources specified in the middle of scale-out operation.

When the rollback operation is executed during modifying VNF Information, VNFM simply updates the state of operation.

When the rollback operation is executed during changing external VNF connectivity, VNFM reverts changes of the external connectivity for VNF instances.

The procedure consists of the following steps as illustrated in above sequences:

Precondition: VNF lifecycle management operation occurrence is in FAILED_TEMP state.

1. The Client sends a POST request with an empty body to the “Rollback operation” resource.

2. VNFM sends endpoints such as Client a VNF lifecycle management operation occurrence notification with the “ROLLING_BACK” state to indicate the processing occurrence of the lifecycle management operation.

3. On successful rollback, VNFM sends endpoints such as Client a VNF lifecycle management operation occurrence notification with the “ROLLED_BACK” state to indicate successful completion of the operation.

4. On unsuccessful rollback, VNFM sends endpoints such as Client a VNF lifecycle management operation occurrence notification with the “FAILED_TEMP” state to indicate an intermediate error (rollback failed) of the operation.

Postcondition: The VNF lifecycle management operation occurrence is in one of the following states: FAILED_TEMP, ROLLED_BACK.

Note

API v1 supports rollback operation for Instantiation and Scale-out. API v1 does not support rollback operation for Modify and ChangeExternalConnectivity.

Data model impact

The change has no impact for data model. Since Xena release has already supported all attributes defined in SOL002 v3.3.1 [4] and SOL003 v3.3.1 [5], Data objects and Database tables do not need to be changed.

REST API impact

All defined attributes should be supported in API validation.

• Name: Retry a VNF LCM operation occurrence

  Description: Request to retry a VNF LCM operation occurrence

  Method type: POST

  URL for the resource: /vnflcm/v2/vnf_lcm_op_occs/{vnfLcmOpOccId}/retry

  Request: Resource URI variables for this resource

  Name	Description
  vnfLcmOpOccId	Identifier of a VNF lifecycle management operation occurrence to be retried.

  Response:

  Data type	Cardinality	Response Codes	Description
  n/a	n/a	Success: 202	The request has been accepted for processing, but processing has not been completed.
  ProblemDetails	0..1	Error: 404	Error: The API producer did not find a current representation for the target resource or is not willing to disclose that one exists. The general cause for this error and its handling is specified in clause 6.4 of ETSI GS NFV-SOL 013 [9], not been completed.
  ProblemDetails	1	Error: 409	Error: The operation cannot be executed currently, due to a conflict with the state of the VNF LCM operation occurrence resource.
  ProblemDetails	See clause 6.4 of [9]	Error: 4xx, 5xx	Error: Any common error response code as defined in clause 6.4 of ETSI GS NFV-SOL 013 [9] may be returned.

• Name: Fail a VNF LCM operation occurrence

  Description: Request to mark a VNF LCM operation occurrence as “FAILED”.

  Method type: POST

  URL for the resource: /vnflcm/v2/vnf_lcm_op_occs/{vnfLcmOpOccId}/fail

  Request: Resource URI variables for this resource

  Name	Description
  vnfLcmOpOccId	Identifier of the related VNF lifecycle management operation occurrence to be marked as “failed”.

  Response:

  Data type	Cardinality	Response Codes	Description
  VnfLcmOpOcc	1	Success: 200	The state of the VNF lifecycle management operation occurrence has been changed successfully.
  ProblemDetails	0..1	Error: 404	Error: The API producer did not find a current representation for the target resource or is not willing to disclose that one exists. The general cause for this error and its handling is specified in clause 6.4 of ETSI GS NFV-SOL 013 [9], not been completed.
  ProblemDetails	1	Error: 409	Error: The operation cannot be executed currently, due to a conflict with the state of the VNF LCM operation occurrence resource.
  ProblemDetails	See clause 6.4 of [9]	Error: 4xx, 5xx	Error: Any common error response code as defined in clause 6.4 of ETSI GS NFV-SOL 013 [9] may be returned.

  Attribute name	Data type	Cardinality	Supported in API v2	Supported in API v1	Description
  id	Identifier	1	Yes	Yes
  operationState	LcmOperationStateType	1	Yes	Yes
  stateEnteredTime	DateTime	1	Yes	Yes
  startTime	DateTime	1	Yes	Yes
  vnfInstanceId	Identifier	1	Yes	Yes
  grantId	Identifier	0..1	Yes	Yes
  operation	LcmOperationType	1	Yes	Yes	In SOL 002/003, 11 types of values ​​are defined. See note.
  isAutomaticInvocation	Boolean	1	Yes	Yes
  operationParams	Object	0..1	Yes	Yes
  isCancelPending	Boolean	1	Yes	Yes
  cancelMode	CancelModeType	0..1	Yes	No	In SOL 002/003, 2 types of values ​​are defined: FORCEFUL, GRACEFUL
  error	ProblemDetails	0..1	Yes	Yes
  >type	URI	0..1	Yes	No
  >title	String	0..1	Yes	Yes
  >status	Integer	1	Yes	Yes
  >detail	String	1	Yes	Yes
  >instance	URI	0..N	Yes	No
  >additional attributes	Not specified.	0..N	No	No
  resourceChanges	Structure (inlined)	0..1	Yes	Yes
  >affectedVnfcs	AffectedVnfc	0..N	Yes	Yes
  >>id	IdentifierInVnf	1	Yes	Yes
  >>vduId	IdentifierInVnfd	1	Yes	Yes
  >>vnfdId	Identifier	0..1	Yes	Not defined	New attribute in API v2.
  >>changeType	Enum (inlined)	1	Yes	Yes	Permitted values: ADDED, REMOVED, MODIFIED, TEMPORARY
  >>computeResource	ResourceHandle	1	Yes	Yes
  >>>vimConnectionId	Identifier	0..1	Yes	Yes
  >>>resourceProviderId	Identifier	0..1	Yes	No
  >>>resourceId	IdentifierInVim	1	Yes	Yes
  >>>vimLevelResourceType	String	0..1	Yes	No
  >>resourceDefinitionId	IdentifierLocal	0..1	Yes	Not defined	This attribute is defined in only SOL 003. New attribute in API v2.
  >>zoneId	Identifier	0..1	Yes	Not defined	This attribute is defined in only SOL 003. New attribute in API v2.
  >>metadata	KeyValuePairs	0..1	Yes	No
  >>affectedVnfcCPIds	IdentifierInVnf	0..N	Yes	Yes
  >>addedStorageResourceIds	VnfVirtualLinkResourceInfo	0..N	Yes	Yes
  >>removedStorageResourceIds	IdentifierInVnf	0..N	Yes	Yes
  >affectedVirtualLinks	AffectedVirtualLink	0..N	Yes	Yes
  >>id	IdentifierInVnf	1	Yes	Yes
  >>vnfVirtualLinkDescId	IdentifierInVnfd	1	Yes	Yes
  >>vnfdId	Identifier	0..1	Yes	Not defined	New attribute in API v2.
  >>changeType	Enum (inlined)	1	Yes	Yes	Permitted values: ADDED, REMOVED, MODIFIED, TEMPORARY, LINK_PORT_ADDED, LINK_PORT_REMOVED
  >>networkResource	resourceHandle	1	Yes	Yes
  >>>vimConnectionId	Identifier	0..1	Yes	Yes
  >>>resourceProviderId	Identifier	0..1	Yes	No
  >>>resourceId	IdentifierInVim	1	Yes	Yes
  >>>vimLevelResourceType	String	0..1	Yes	No
  >>vnfLinkPortIds	IdentifierInVnf	0..N	Yes	Yes
  >>resourceDefinitionId	IdentifierLocal	0..1	Yes	Not defined	This attribute is defined in only SOL 003. New attribute in API v2.
  >>zoneId	Identifier	0..1	Yes	Not defined	This attribute is defined in only SOL 003. New attribute in API v2.
  >>metadata	KeyValuePairs	0..1	Yes	No
  >affectedExtLinkPorts	AffectedExtLinkPort	0..N	Yes	Not defined	New attribute in API v2.
  >>id	IdentifierInVnf	1	Yes	Not defined	New attribute in API v2.
  >>changeType	Enum (inlined)	1	Yes	Not defined	Permitted values: ADD, REMOVED New attribute in API v2.
  >>extCpInstanceId	IdentifierInVnf	1	Yes	Not defined	New attribute in API v2.
  >>resourceHandle	ResourceHandle	1	Yes	Not defined	New attribute in API v2.
  >>>vimConnectionId	Identifier	0..1	Yes	Not defined	New attribute in API v2.
  >>>resourceProviderId	Identifier	0..1	Yes	Not defined	New attribute in API v2.
  >>>resourceId	IdentifierInVim	1	Yes	Not defined	New attribute in API v2.
  >>>vimLevelResourceType	String	0..1	Yes	Not defined	New attribute in API v2.
  >>resourceDefinitionId	IdentifierLocal	0..1	Yes	Not defined	This attribute is defined in only SOL 003. New attribute in API v2.
  >affectedVirtualStorages	AffectedVirtualStorage	0..N	Yes	Yes
  >>id	IdentifierInVnf	1	Yes	Yes
  >>VirtualStorageDescId	IdentifierInVnfd	1	Yes	Yes
  >>vnfdId	Identifier	0..1	Yes	Not defined	New attribute in API v2.
  >>changeType	Enum (inlined)	1	Yes	Yes	Permitted values: ADDED, REMOVED, MODIFIED, TEMPORARY
  >>storageResource	resourceHandle	1	Yes	Yes
  >>>vimConnectionId	Identifier	0..1	Yes	Yes
  >>>resourceProviderId	Identifier	0..1	Yes	No
  >>>resourceId	IdentifierInVim	1	Yes	Yes
  >>>vimLevelResourceType	String	0..1	Yes	No
  >>resourceDefinitionId	IdentifierLocal	0..1	Yes	Not defined	This attribute is defined in only SOL 003. New attribute in API v2.
  >>zoneId	Identifier	0..1	Yes	Not defined	This attribute is defined in only SOL 003. New attribute in API v2.
  >>metadata	KeyValuePairs	0..1	Yes	No
  changedInfo	VnfInfoModifications	0..1	Yes	Yes
  >vnfInstanceName	String	0..1	Yes	Yes
  >vnfInstanceDescription	String	0..1	Yes	Yes
  >vnfConfigurableProperties	KeyValuePairs	0..1	Yes	No
  >metadata	KeyValuePairs	0..1	Yes	Yes
  >extensions	KeyValuePairs	0..1	Yes	No
  >vimConnectionInfo	map(vimConnectionInfo)	0..N	Yes	Yes	This attribute is defined only in SOL 003.
  >>vimId	Identifier	0..1	Yes	Yes
  >>vimType	String	1	Yes	Yes
  >>interfaceInfo	KeyValuePairs	0..1	Yes	Yes
  >>accessInfo	KeyValuePairs	0..1	Yes	Yes
  >>extra	KeyValuePairs	0..1	Yes	Yes
  >vnfdId	Identifier	0..1	Yes	Yes
  >vnfProvider	String	0..1	Yes	Yes
  >vnfProductName	String	0..1	Yes	Yes
  >vnfSoftwareVersion	Version	0..1	Yes	Yes
  >vnfdVersion	Version	0..1	Yes	Yes
  >vnfcInfoModifications	VnfcInfoModifications	0..N	Yes	Not defined	This attribute is defined in only SOL 002. New attribute in API v2.
  >>id	IdentifierInVnf	1	Yes	Not defined	New attribute in API v2.
  >>vnfcConfigurableProperties	KeyValuePairs	1	Yes	Not defined	New attribute in API v2.
  changedExtConnectivity	ExtVirtualLinkInfo	0..N	Yes	Yes
  >id	Identifier	1	Yes	Yes
  >resourceHandle	ResourceHandle	1	Yes	Yes
  >>vimConnectionId	Identifier	0..1	Yes	Yes
  >>resourceProviderId	Identifier	0..1	Yes	No
  >>resourceId	IdentifierInVim	1	Yes	Yes
  >>vimLevelResourceType	String	0..1	Yes	No
  >extLinkPorts	ExtLinkPortInfo	0..N	Yes	Yes
  >>id	Identifier	1	Yes	Yes
  >>resourceHandle	ResourceHandle	1	Yes	Yes
  >>>vimConnectionId	Identifier	0..1	Yes	Yes
  >>>resourceProviderId	Identifier	0..1	Yes	No
  >>>resourceId	IdentifierInVim	1	Yes	Yes
  >>>vimLevelResourceType	String	0..1	Yes	No
  >>cpInstanceId	IdentifierInVnf	0..1	Yes	Yes
  >currentVnfExtCpData	VnfExtCpData	1..N	Yes	Not defined	New attribute in API v2.
  >>cpdId	IdentifierInVnfd	1	Yes	Not defined	New attribute in API v2.
  >>cpConfig	map(VnfExtCpConfig)	1..N	Yes	Not defined	New attribute in API v2.
  >>>parentCpConfigId	IdentifierInVnf	0..1	Yes	Not defined	New attribute in API v2.
  >>>linkPortId	Identifier	0..1	Yes	Not defined	New attribute in API v2.
  >>>cpProtocolData	CpProtocolData	0..N	Yes	Not defined	New attribute in API v2.
  >>>>layerProtocol	Enum (inlined)	1	Yes	Not defined	Permitted values: IP_OVER_ETHERNET New attribute in API v2.
  >>>>ipOverEthernet	IpOverEthernetAddressData	0..1	Yes	Not defined	New attribute in API v2.
  >>>>>macAddress	MacAddress	0..1	Yes	Not defined	New attribute in API v2.
  >>>>>segmentationId	String	0..1	Yes	Not defined	New attribute in API v2.
  >>>>>ipAddresses	Structure (inlined)	0..N	Yes	Not defined	New attribute in API v2.
  >>>>>>type	Enum (inlined)	1	Yes	Not defined	Permitted values: IPV4, IPV6 New attribute in API v2.
  >>>>>>fixedAddresses	IpAddress	0..N	Yes	Not defined	New attribute in API v2.
  >>>>>>numDynamicAddresses	Integer	0..1	Yes	Not defined	New attribute in API v2.
  >>>>>>addressRange	Structure (inlined)	0..1	Yes	Not defined	New attribute in API v2.
  >>>>>>>minAddress	IpAddress	1	Yes	Not defined	New attribute in API v2.
  >>>>>>>maxAddress	IpAddress	1	Yes	Not defined	New attribute in API v2.
  >>>>>>subnetId	IdentifierInVim	0..1	Yes	Not defined	New attribute in API v2.
  modificationsTriggeredByVnfPkgChange	ModificationsTriggeredByVnfPkgChange	0..1	Yes	Not defined	New attribute in API v2.
  >vnfConfigurableProperties	KeyValuePairs	0..1	Yes	Not defined	New attribute in API v2.
  >metadata	KeyValuePairs	0..1	Yes	Not defined	New attribute in API v2.
  >extensions	KeyValuePairs	0..1	Yes	Not defined	New attribute in API v2.
  >vnfdId	Identifier	0..1	Yes	Not defined	New attribute in API v2.
  >vnfProvider	String	0..1	Yes	Not defined	New attribute in API v2.
  >vnfProductName	String	0..1	Yes	Not defined	New attribute in API v2.
  >vnfSoftwareVersion	Version	0..1	Yes	Not defined	New attribute in API v2.
  >vnfdVersion	Version	0..1	Yes	Not defined	New attribute in API v2.
  vnfSnapshotInfoId	Identifier	0..1	Yes	Not defined	New attribute in API v2.
  _links	Structure (inlined)	1	Yes	Yes
  >self	Link	1	Yes	Yes
  >vnfInstance	Link	1	Yes	Yes
  >grant	Link	0..1	Yes	Yes
  >cancel	Link	0..1	No	No
  >retry	Link	0..1	Yes	Yes
  >rollback	Link	0..1	Yes	Yes
  >fail	Link	0..1	Yes	Yes
  >vnfSnapshot	Link	0..1	No	Not defined	New attribute in API v2.

  Note

  LcmOperationType defines the permitted values to represent VNF lifecycle operation types in VNF lifecycle management operation occurrence resources and VNF lifecycle management operation occurrence notifications. It shall comply with the provisions defined in following table.

  Value	Description
  INSTANTIATE	Represents the “Instantiate VNF” LCM operation.
  SCALE	Represents the “Scale VNF” LCM operation.
  SCALE_TO_LEVEL	Represents the “Scale VNF to Level” LCM operation.
  CHANGE_FLAVOUR	Represents the “Change VNF Flavour” LCM operation.
  TERMINATE	Represents the “Terminate VNF” LCM operation.
  HEAL	Represents the “Heal VNF” LCM operation.
  OPERATE	Represents the “Operate VNF” LCM operation.
  CHANGE_EXT_CONN	Represents the “Change external VNF connectivity” LCM operation.
  MODIFY_INFO	Represents the “Modify VNF Information” LCM operation.
  CREATE_SNAPSHOT	Represents the “Create VNF Snapshot” LCM operation.
  REVERT_TO_SNAPSHOT	Represents the “Revert To VNF Snapshot” LCM operation.
  CHANGE_VNFPKG	Represents the “Change current VNF package” LCM operation.

• Name: Rollback a VNF LCM operation occurrence

  Description: Request to rollback a VNF LCM operation occurrence

  Method type: POST

  URL for the resource: /vnflcm/v2/vnf_lcm_op_occs/{vnfLcmOpOccId}/rollback

  Resource URI variables for this resource::

  Name	Description
  vnfLcmOpOccId	Identifier of a VNF lifecycle management operation occurrence to be rolled back.

  Response:

  Data type	Cardinality	Response Codes	Description
  n/a	n/a	Success: 202	The request has been accepted for processing, but processing has not been completed.
  ProblemDetails	0..1	Error: 404	Error: The API producer did not find a current representation for the target resource or is not willing to disclose that one exists. The general cause for this error and its handling is specified in clause 6.4 of ETSI GS NFV-SOL 013 [9], not been completed.
  ProblemDetails	1	Error: 409	Error: The operation cannot be executed currently, due to a conflict with the state of the VNF LCM operation occurrence resource.
  ProblemDetails	See clause 6.4 of [9]	Error: 4xx, 5xx	Error: Any common error response code as defined in clause 6.4 of ETSI GS NFV-SOL 013 [9] may be returned.

Security impact

None

Notifications impact

None

Other end user impact

None

Performance Impact

None

Other deployer impact

None

Developer impact

None

Implementation

Assignee(s)

Primary assignee:

Hirofumi Noguchi <hirofumi.noguchi.rs@hco.ntt.co.jp>

Work Items

• Add new version API endpoints to Tacker-server.

• Implement new version API processings for Tacker-conductor.

• Add new unit and functional tests.

• Update the Tacker’s API reference.

Dependencies

• Instantiate/Terminate operation

  Depends on spec “Support NFV SOL_v3 starting and terminating” [6].

• Scale/Heal/Modify/Change external vnf connectivity operation

  Depends on spec “Enhance NFV SOL_v3 LCM operation” [8].

Testing

Unit and functional test cases will be added for VNF lifecycle management of VNF instances.

Documentation Impact

New supported APIs need to be added into Tacker API reference.

References

[1]

https://www.etsi.org/technologies-clusters/technologies/NFV

[2]

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)

[3]

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)

[4] (1,2)

https://www.etsi.org/deliver/etsi_gs/NFV-SOL/001_099/002/03.03.01_60/gs_nfv-sol002v030301p.pdf (Chapter 5: VNF Lifecycle Management interface)

[5] (1,2)

https://www.etsi.org/deliver/etsi_gs/NFV-SOL/001_099/003/03.03.01_60/gs_nfv-sol003v030301p.pdf (Chapter 5: VNF Lifecycle Management interface)

[6] (1,2,3)

https://specs.openstack.org/openstack/tacker-specs/specs/xena/support-nfv-solv3-start-and-terminate-vnf.html

[7]

https://specs.openstack.org/openstack/tacker-specs/specs/xena/support-nfv-solv3-get-information.html

[8] (1,2)

https://specs.openstack.org/openstack/tacker-specs/specs/yoga/enhance-nfv-solv3-lcm-operation.html

[9] (1,2,3,4,5,6,7,8,9)

https://www.etsi.org/deliver/etsi_gs/NFV-SOL/001_099/013/03.04.01_60/gs_nfv-sol013v030401p.pdf