From 74adf22da7bc94a6b3f9a25b1fb9284e46496c86 Mon Sep 17 00:00:00 2001 From: Yuta Kazato Date: Fri, 24 Feb 2023 17:02:58 +0900 Subject: [PATCH] Add user docs for Coordination API sample usage This patch adds a sample usage for the client of ETSI NFV-SOL VNF Coordination API in the coordinateVNF script to user guide. User docs provides how to use the Coordination API in the coordinateVNF script and the following operations. * Request a coordination action (POST /lcmcoord/v1/coordinations) * Read the result of a coordination action (GET /lcmcoord/v1/coordinations/{coordinationId}) Note that the sample script implements the client function in the ChangeCurrentVNFPackage API only, not the VNF LCM Coordination API itself. Implements: blueprint add-sample-coordinate-script Change-Id: I789e774659e9a54e47c7b24161fddfffc4549fcf --- ...ate_api_client_in_coordinatevnf_script.rst | 511 ++++++++++++++++++ doc/source/user/etsi_use_case_guide.rst | 1 + 2 files changed, 512 insertions(+) create mode 100644 doc/source/user/coordinate_api_client_in_coordinatevnf_script.rst diff --git a/doc/source/user/coordinate_api_client_in_coordinatevnf_script.rst b/doc/source/user/coordinate_api_client_in_coordinatevnf_script.rst new file mode 100644 index 000000000..e428dc82b --- /dev/null +++ b/doc/source/user/coordinate_api_client_in_coordinatevnf_script.rst @@ -0,0 +1,511 @@ +============================================================================ +How to use ETSI NFV-SOL VNF LCM coordination API in the coordinateVNF script +============================================================================ + +This document describes how to use the sample coordinateVNF +script for ETSI NFV-SOL VNF LCM coordination API +in the ChangeCurrentVNFPackage API. + +Overview +-------- + +1. The sample coordinateVNF script for ETSI NFV-SOL VNF coordination API +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The sample coordinateVNF script of +`ETSI NFV-SOL VNF LCM coordination API` +is designed for users who want to communicate with +external management systems (e.g., Operations +Support Systems (OSS) / Element Manager (EM)) +as the client. +You can know how to use it in this user guide. + +.. warning:: + The sample script implements the client function + in the ChangeCurrentVNFPackage API only, + not formal support for the VNF LCM Coordination + API itself since Tacker is based on ETSI-NFV SOL 002 + v3.3.1 that do not support the VNF LCM Coordination API. + The sample implements the VNF LCM Coordination + API version: 1.0.0 based ETSI-NFV SOL 002 v3.6.1. + +2. Use Case +^^^^^^^^^^^^ +In this sample, the use case focuses on +the client function of the VNF LCM Coordination API +in the Coordinate VNF script when performing +the RollingUpdate with external management systems +in the ChangeCurrentVNFPackage API. +VNFM acts as a client and the external management system +like EM acts as a server in the use case. +The following operations are provided +in the sample scripts. + +* Request a coordination action + (POST /lcmcoord/v1/coordinations) +* Read the result of a coordination action + (GET /lcmcoord/v1/coordinations/{coordinationId}) + +If you want to know `ETSI NFV-SOL VNF Coordinate API` +in detail, please see `ETSI NFV-SOL 002 v3.6.1`_. + +If you want to know how to use `the Coordinate VNF script`, +please see the following documents of +ChangeCurrentVNFPackage API. + +* `ETSI NFV-SOL VNF Change Current VNF Package`_. +* `ETSI NFV-SOL VNF Change Current VNF Package for StandardUserData`_. + + + +Usage example +------------- + +Flow of VNF update +^^^^^^^^^^^^^^^^^^ + +The following diagram shows the rolling update +using the Coordinate VNF script as the client of +the VNF LCM Coordination API. + +.. code-block:: + + + +---------+ + | VNFD | + | | + +----+----+ + | + (Script is included v +-------------------+ + +--------------------+ in the package) +----------+ | Change current | + +------------>| CoordinateVNF +--------------------->| | | VNF Package | + | | script | | CSAR | | Request with | + | +---------+ | | | | Additional Params | + | | +-------+------------+ +-----+----+ +--+----------------+ + | | | ^ | | 1. Change current VNF Package + | | | | +-----v----------v------------------------------+ + | | 7. Coordination| | Coordination | +-----------------------+ VNFM | + | | request | | Result | | Tacker-server | | + | | | | | +--+--------------------+ | + | | v | | | 2. Change current VNF Package request | + | | +------------+-------+ | v | + | | | External | | +-----------------------------------------+ | + | | | management | | | | | + | | | system (EM) | | | +-------------------+ | | + | | +--------------------+ | | | VnfLcmDriver | | | + | | | | | | | | + | | | | | | | | + | | | | | | | | + | | | | | | | | + | | | | | | | | + | | 6. Coordinate | | +-+-----------------+ | | + | | resource | | | | | + | | +--------------------+ | | v | | + | | | | 3. Get stack resource| | +-------------------+ | | + | | | +--------------+ | to update | | | InfraDriver | 8. Repeat steps | | + | | | | Resource |<-+----------------------+--+---+ | 4 through 7 | | + | +---------+->| | | 4. Update VNFC | | | | for each VNFC| | + | | | |<-+----------------------+--+---+ +--------+ | | + | | +--------------+ | | | | | | | | + | | VNF | | | | |<-------+ | | + | +--------------------+ | | | | | | + | 5. Execute CoordinateVNF script | | | | | | + +---------------------------------------------------------+--+---+ | | | + | | +-------------------+ | | + | | Tacker-conductor | | + +--------------------+ | +-----------------------------------------+ | + | Hardware Resources | | | + +--------------------+ +-----------------------------------------------+ + +1. Execute Change current VNF Package operation + + User sends a ChangeCurrentVNFPackage request + to the "Individual VNF instance" resource with + Additional Params. + + .. code-block:: console + + $ openstack vnflcm change-vnfpkg VNF_INSTANCE_ID \ + ./sample_param_file_for_coordination.json \ + --os-tacker-api-version 2 + + Tacker-server calls Tacker-conductor, then Tacker-conductor fetches + an on-boarded VNF package and calls VnfLcmDriver. + + You can set following parameter in additionalParams + in the ChangeCurrentVnfPkgRequest to specify + the information of the external coordination server. + + * additionalParams + + .. list-table:: + :widths: 15 10 30 + :header-rows: 1 + + * - Attribute name + - Cardinality + - Parameter description + * - upgrade_type + - 1 + - Type of file update operation method. Specify Blue-Green or Rolling update. + * - lcm-operation-coordinate-old-vnf + - 1 + - The file path of the script that simulates the behavior of CoordinateVNF for old VNF. + * - lcm-operation-coordinate-new-vnf + - 1 + - The file path of the script that simulates the behavior of CoordinateVNF for new VNF. + * - vdu_params + - 0..N + - VDU information of target VDU to update. + Specifying a vdu_params is required for OpenStack VIM and not required for Kubernetes VIM. + * - > vdu_id + - 1 + - VDU name of target VDU to update. + * - > old_vnfc_param + - 0..1 + - Old VNFC connection information. + Required for ssh connection in CoordinateVNF operation for application configuration to VNFC. + * - >> cp_name + - 1 + - Connection point name of old VNFC to update. + * - >> username + - 1 + - User name of old VNFC to update. + * - >> password + - 1 + - Password of old VNFC to update. + * - >> endpoint + - 1 + - Endpoint URL of coordination server. + * - >> authentication + - 0..1 + - Authentication parameters to configure the use of Authorization + when connecting to coordination server. + * - \>>> authType + - 1..N + - Defines the types of Authentication/Authorization + which the API consumer is willing to accept + when receiving a notification. Permitted values: + + * ``BASIC``: use HTTP Basic authentication + with the client credentials. + * ``OAUTH2_CLIENT_CREDENTIALS``: use an OAuth 2.0 + token, obtained using the client credentials + grant type after authenticating using client + identifier and client password. + * - \>>> paramsBasic + - 0..1 + - Parameters for authentication/authorization + using authType ``BASIC``. + * - >>>> userName + - 0..1 + - Username to be used in HTTP Basic authentication. + * - >>>> password + - 0..1 + - Password to be used in HTTP Basic authentication. + * - \>>> paramsOauth2ClientCredentials + - 0..1 + - Parameters for authentication/authorization using + authType ``OAUTH2_CLIENT_CREDENTIALS``. + * - >>>> clientId + - 0..1 + - Client identifier to be used in the access token + request of the OAuth 2.0 client credentials + grant type. + * - >>>> clientPassword + - 0..1 + - Client password to be used in the access token + request of the OAuth 2.0 client credentials + grant type. + * - >>>> tokenEndpoint + - 0..1 + - The token endpoint from which the access token + can be obtained. + * - >> coordination_server_param + - 0..1 + - Information to access coordination server. + It is required when using coordinateVNF script which calling Coordination API. + * - > new_vnfc_param + - 0..1 + - New VNFC connection information. + Required for ssh connection in CoordinateVNF operation for application configuration to VNFC. + * - >> cp_name + - 1 + - Connection point name of new VNFC to update. + * - >> username + - 1 + - User name of new VNFC to update. + * - >> password + - 1 + - Password of new VNFC to update. + * - >> endpoint + - 1 + - Endpoint URL of coordination server. + * - >> authentication + - 0..1 + - Authentication parameters to configure the use of Authorization + when connecting to coordination server. + * - \>>> authType + - 1..N + - Defines the types of Authentication/Authorization + which the API consumer is willing to accept + when receiving a notification. Permitted values: + + * ``BASIC``: use HTTP Basic authentication + with the client credentials. + * ``OAUTH2_CLIENT_CREDENTIALS``: use an OAuth 2.0 + token, obtained using the client credentials + grant type after authenticating using client + identifier and client password. + * - \>>> paramsBasic + - 0..1 + - Parameters for authentication/authorization + using authType ``BASIC``. + * - >>>> userName + - 0..1 + - Username to be used in HTTP Basic authentication. + * - >>>> password + - 0..1 + - Password to be used in HTTP Basic authentication. + * - \>>> paramsOauth2ClientCredentials + - 0..1 + - Parameters for authentication/authorization using + authType ``OAUTH2_CLIENT_CREDENTIALS``. + * - >>>> clientId + - 0..1 + - Client identifier to be used in the access token + request of the OAuth 2.0 client credentials + grant type. + * - >>>> clientPassword + - 0..1 + - Client password to be used in the access token + request of the OAuth 2.0 client credentials + grant type. + * - >>>> tokenEndpoint + - 0..1 + - The token endpoint from which the access token + can be obtained. + * - >> coordination_server_param + - 0..1 + - Information to access coordination server. + It is required when using coordinateVNF script which calling Coordination API. + * - external_lb_param + - 0..1 + - Load balancer information that requires configuration changes. + Required only for the Blue-Green deployment process of OpenStack VIM. + * - > ip_address + - 1 + - IP address of load balancer server. + * - > username + - 1 + - User name of load balancer server. + * - > password + - 1 + - Password of load balancer server. + + The example of the request of additionalParams as below. + + .. code-block:: json + + { + "additionalParams": { + "upgrade_type": "RollingUpdate", + "lcm-operation-coordinate-new-vnf": "./Scripts/coordinate_vnf.py", + "lcm-operation-coordinate-old-vnf": "./Scripts/coordinate_vnf.py", + "vdu_params": [{ + "vdu_id": "VDU1", + "old_vnfc_param": { + "cp_name": "VDU1_CP1", + "username": "ubuntu", + "password": "ubuntu", + "endpoint": "http://127.0.0.1:6789", + "authentication": { + "authType": ["BASIC"], + "paramsBasic": { + "userName": "tacker", + "password": "tacker" + } + } + }, + "new_vnfc_param": { + "cp_name": "VDU1_CP1", + "username": "ubuntu", + "password": "ubuntu", + "endpoint": "http://127.0.0.1:6789", + "authentication": { + "authType": ["BASIC"], + "paramsBasic": { + "userName": "tacker", + "password": "tacker" + } + } + } + }, + { + "vdu_id": "VDU2", + "old_vnfc_param": { + "cp_name": "VDU2_CP1", + "username": "ubuntu", + "password": "ubuntu", + "endpoint": "http://127.0.0.1:6789", + "authentication": { + "authType": ["BASIC"], + "paramsBasic": { + "userName": "tacker", + "password": "tacker" + } + } + }, + "new_vnfc_param": { + "cp_name": "VDU2_CP1", + "username": "ubuntu", + "password": "ubuntu", + "endpoint": "http://127.0.0.1:6789", + "authentication": { + "authType": ["BASIC"], + "paramsBasic": { + "userName": "tacker", + "password": "tacker" + } + } + } + }] + } + } + +2. Request Change current VNF Package Process to InfraDriver + + VnfLcmDriver sends a request to the InfraDriver to change vnfpkg process. + +3. Get stack resource to update + + InfraDriver sends a request to the VIM to get stack resource to update. + +4. Update VNFC + + InfraDriver sends a request to the VIM to update stack. + +5. Execute CoordinateVNF script + + InfraDriver runs CoordinateVNF script. + The script is included in the VNF package + and you can modify them for your environments. + + The sample class for Coordination API and + main methods in the CoordinateVNF script + ``coordinate_vnf.py`` as below. + + .. code-block:: console + + class CoordScript(object): + def __init__(self, vnfc_param): + self.vnfc_param = vnfc_param + + def run(self): + if not os.path.exists('/tmp/change_vnfpkg_coordination'): + return + + coord_req = self.vnfc_param['LcmCoordRequest'] + coord_req['coordinationActionName'] = ( + "prv.tacker_organization.coordination_test") + endpoint = self.vnfc_param.get('endpoint') + authentication = self.vnfc_param.get('authentication') + + input_params = self.vnfc_param.get('inputParams') + if input_params is not None: + coord_req['inputParams'] = input_params + + if endpoint is None: + raise Exception('endpoint must be specified.') + if authentication is None: + raise Exception('authentication must be specified.') + + coord = coord_client.create_coordination(endpoint, authentication, + coord_req) + if coord['coordinationResult'] != "CONTINUE": + raise Exception( + f"coordinationResult is {coord['coordinationResult']}") + + def main(): + script = CoordScript(vnfc_param) + script.run() + + .. note:: + According to ETSI-NFV SOL 002 v3.6.1, the coordination + action `coordinationActionName` is defined to be declared + in the VNFD. However, the CoordinateVNF script does not + refer to the VNFD, it must be described in the script. + (e.g., "prv.tacker_organization.coordination_test") + +6. Coordinate resource + + CoordinateVNF script sends a request to the VNF to Coordinate VNF. + +7. Coordination request to the external management system (EM) + + CoordinateVNF script sends a Coordination request to + the external management system (EM). The endpoint URL of EM is + obtained from the ChangeCurrentVNFPackage request. + The target VNFC obtained from Tacker is specified as inputParams + in the LcmCoordRequest. (e.g. it is specified by vnfcInstanceId). + + Tacker can use 2 operations of VNF LCM Coordination API supported in + utility functions ``tacker/sol_refactored/common/coord_client.py``. + You can use them via the CoordinateVNF script. + + * Request a coordination action + (POST /lcmcoord/v1/coordinations) + + VNFM requests Coordination actions + to the Coordination API Server (e.g. EM). + + * Read the result of a coordination action + (GET /lcmcoord/v1/coordinations/{coordinationId}) + + VNFM requests the result of a coordination action + to the Coordination API Server (e.g. EM). + + The process after receiving Coordination response diverges + depending on whether the Synchronous or Asynchronous mode. + + .. note:: + | According to ETSI-NFV SOL 002 v3.6.1, the Coordination interface supports + Synchronous and Asynchronous modes. + API server decides the mode, and API client can know it by the API response. + Thus, since VNFM cannot control the mode, Tacker will support both modes. + The following shows the Coordination processes of VNFM. + | + | Synchronous mode: The EM returns to the Tacker a "201 Created" response + with a "LcmCoord" data structure in the body + and then VNFM continues the process on the basis of the result. + Alternatively, EM returns a "503 Service Unavailable" response with + a "ProblemDetails" data structure in the body and a "Retry-After" + HTTP header that indicates the length of a delay after which a retry + of the coordination is suggested. + After the delay interval has passed, the VNFM sends coordination request again. + | + | Asynchronous mode: The EM returns to the Tacker a "202 Accepted" response + with an empty body and a "Location" HTTP header that indicates + the URI of the "Individual coordination action" resource. + Tacker waits for a certain time interval + (as indicated in the Retry-After header of the previous 202 response if signalled, + or determined by other means otherwise) before the next iteration of the loop. + Tacker polls the status of the coordination by sending a GET request to the EM, + using the URI that was returned in the "Location" header. + After obtaining the coordination result, Tacker continues the process on the basis of it. + +8. Repeat steps 4 through 7 for each VNFC + + Each VNFC is executed starting with the higher value of + the vnfcResourceInfo index in the StandardUserData + (or newer in the DefaultUserData). + +9. Finish VNF LCM coordination API operation + + When finish VNF LCM coordination API operation via the CoordinateVNF script, + Change current VNF Package operation will finish successfully. + +.. _ETSI NFV-SOL 002 v3.6.1: https://www.etsi.org/deliver/etsi_gs/NFV-SOL/001_099/002/03.06.01_60/gs_nfv-sol002v030601p.pdf +.. _ETSI NFV-SOL VNF Change Current VNF Package: https://docs.openstack.org/tacker/latest/user/etsi_vnf_change_current_vnf_package.html +.. _ETSI NFV-SOL VNF Change Current VNF Package for StandardUserData: https://docs.openstack.org/tacker/latest/user/etsi_vnf_change_current_vnf_package_with_standard_user_data.html +.. _VNF Package for Common instantiate: https://opendev.org/openstack/tacker/src/branch/master/tacker/tests/functional/sol_v2/samples/test_instantiate_vnf_with_old_image_or_volume/contents +.. _change from image to image: https://opendev.org/openstack/tacker/src/branch/master/tacker/tests/functional/sol_v2/samples/test_change_vnf_pkg_with_new_image/contents diff --git a/doc/source/user/etsi_use_case_guide.rst b/doc/source/user/etsi_use_case_guide.rst index 4b56840a8..aa8ce38a9 100644 --- a/doc/source/user/etsi_use_case_guide.rst +++ b/doc/source/user/etsi_use_case_guide.rst @@ -162,6 +162,7 @@ VM :maxdepth: 1 practical_sample_package_usage_guide + coordinate_api_client_in_coordinatevnf_script Prometheus Plugin ^^^^^^^^^^^^^^^^^