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
This commit is contained in:
Yuta Kazato
parent
0dda8d07b6
commit
74adf22da7
|
|
@ -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
|
||||
|
|
@ -162,6 +162,7 @@ VM
|
|||
:maxdepth: 1
|
||||
|
||||
practical_sample_package_usage_guide
|
||||
coordinate_api_client_in_coordinatevnf_script
|
||||
|
||||
Prometheus Plugin
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
|
|
|||
Loading…
Reference in New Issue