openstack/tacker
Code Issues Proposed changes

Update docs of User guide and API reference

Browse Source 
This patch provides the following User guide and
API documentation updates (fixes) in Tacker Antelope.

User doc:
* Update current support v2 API
  operation status in the cli doc.
* Fix the settings of "vimConnectionInfo".
* Add vimType "ETSINFV.KUBERNETES.V_1"
  to the samples of "vimConnectionInfo".

API doc:
* Fix the misdescription of VNF LCM Interface v2.
* Fix the misdescription of VNF FM Interface v1.
* Fix the misdescription of VNF PM Interface v2.
* Fix the format of request parameters
  in Prometheus Plugin Interface
  and Fault Notification Interface.

Implements: blueprint enhance-change-package
Implements: blueprint support-auto-lcm
Co-Author: Taiki Kimura <taiki.kimura@ntt-at.co.jp>
Change-Id: I50c130d5de812efac631ed8ad1432a98a9d00e6c
This commit is contained in:
Yuta Kazato 2023-02-17 17:08:51 +09:00
parent bfa184ac3f
commit bb16f78280
20 changed files with 198 additions and 96 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
api-ref/source/v2/fault_notification.inc
View File

@ -40,11 +40,11 @@ Request Parameters
- vnfInstanceId: vnf_instance_id
- server_id: server_id
- notification: notification
- \>host_id: host_id
- \>alarm_id: alarm_id
- \>fault_id: fault_id
- \>fault_type: fault_type
- \>fault_option: fault_option
- host_id: host_id
- alarm_id: alarm_id
- fault_id: fault_id
- fault_type: fault_type
- fault_option: fault_option
Request Example
---------------

2
api-ref/source/v2/parameters_fault_notification.yaml
View File

@ -47,4 +47,4 @@ notification:
Fault notification event.
in: body
required: true
type: Structure (inlined)
type: Structure

6
api-ref/source/v2/parameters_prometheus_plugin.yaml
View File

@ -2,13 +2,13 @@ alert:
description: alert message
in: body
required: true
type: array(inlined)
type: array
annotations:
description: |
dynamic properties.
in: body
required: true
type: object (inlined)
type: object
aspect_id:
description: |
aspectId of the scaling target.
@ -80,7 +80,7 @@ labels:
static properties.
in: body
required: true
type: object (inlined)
type: object
metric:
description: |
PerformanceMetric defined in ETSI PM interface.

8
api-ref/source/v2/parameters_vnffm.yaml
View File

@ -52,7 +52,7 @@ alarm_links:
Links for this resource.
in: body
required: true
type: array
type: object
alarm_raised_time:
description: |
Time stamp indicating when the alarm is raised by the managed object.
@ -83,7 +83,7 @@ correlated_alarm_ids:
List of identifiers of other alarms correlated to this fault.
in: body
required: false
type: string
type: array
event_time:
description: |
Time stamp indicating when the fault was observed.
@ -101,7 +101,7 @@ fault_details:
Provides additional information about the fault.
in: body
required: false
type: string
type: array
fault_type:
description: |
Additional information to clarify the type of the fault.
@ -294,7 +294,7 @@ subscription_links:
Links for this resource.
in: body
required: true
type: array
type: object
subscription_self:
description: |
URI of this resource.

12
api-ref/source/v2/parameters_vnfpm.yaml
View File

@ -201,8 +201,10 @@ reports_ready_time:
vnf_pm_job_create_callback_uri:
description: |
The URI of the endpoint to send the notification to.
At least one of the "callbackUri" and "authentication"
attributes shall be present in request body.
in: body
required: true
required: false
type: string
vnf_pm_job_create_criteria:
description: |
@ -233,6 +235,8 @@ vnf_pm_job_create_request_authentication:
description: |
Authentication parameters to configure the use of Authorization when
sending notifications corresponding to this subscription.
At least one of the "callbackUri" and "authentication"
attributes shall be present in request body.
in: body
required: false
type: object
@ -281,6 +285,12 @@ vnf_pm_job_reports:
in: body
required: false
type: array
vnf_pm_job_response_callback_uri:
description: |
The URI of the endpoint to send the notification to.
in: body
required: false
type: string
vnf_pm_job_response_id:
description: |
Identifier of this PM job.

78
api-ref/source/v2/prometheus_plugin.inc
View File

@ -39,19 +39,19 @@ Request Parameters
.. rest_parameters:: parameters_prometheus_plugin.yaml
- alert: alert
- \>status: status
- \>labels: labels
- \>\>receiver_type: receiver_type
- \>\>function_type: function_type_pm
- \>\>job_id: job_id
- \>\>object_instance_id: object_instance_id
- \>\>sub_object_instance_id: sub_object_instance_id
- \>\>metric: metric
- \>annotations: annotations
- \>\>value: value
- \>startsAt: startsAt
- \>endsAt: endsAt
- \>fingerprint: fingerprint
- status: status
- labels: labels
- receiver_type: receiver_type
- function_type: function_type_pm
- job_id: job_id
- object_instance_id: object_instance_id
- sub_object_instance_id: sub_object_instance_id
- metric: metric
- annotations: annotations
- value: value
- startsAt: startsAt
- endsAt: endsAt
- fingerprint: fingerprint
Request Example
---------------
@ -85,21 +85,21 @@ Request Parameters
.. rest_parameters:: parameters_prometheus_plugin.yaml
- alert: alert
- \>status: status
- \>labels: labels
- \>\>receiver_type: receiver_type
- \>\>function_type: function_type_fm
- \>\>vnf_instance_id: vnf_instance_id
- \>\>pod: pod
- \>\>perceived_severity: perceived_severity
- \>\>event_type: event_type
- \>annotations: annotations
- \>\>probable_cause: probable_cause
- \>\>fault_type: fault_type
- \>\>fault_details: fault_details
- \>startsAt: startsAt
- \>endsAt: endsAt
- \>fingerprint: fingerprint
- status: status
- labels: labels
- receiver_type: receiver_type
- function_type: function_type_fm
- vnf_instance_id: vnf_instance_id
- pod: pod
- perceived_severity: perceived_severity
- event_type: event_type
- annotations: annotations
- probable_cause: probable_cause
- fault_type: fault_type
- fault_details: fault_details
- startsAt: startsAt
- endsAt: endsAt
- fingerprint: fingerprint
Request Example
---------------
@ -132,17 +132,17 @@ Request Parameters
.. rest_parameters:: parameters_prometheus_plugin.yaml
- alert: alert
- \>status: status
- \>labels: labels
- \>\>receiver_type: receiver_type
- \>\>function_type: function_type_auto_scale
- \>\>vnf_instance_id: vnf_instance_id
- \>\>auto_scale_type: auto_scale_type
- \>\>aspect_id: aspect_id
- \>annotations: annotations
- \>startsAt: startsAt
- \>endsAt: endsAt
- \>fingerprint: fingerprint
- status: status
- labels: labels
- receiver_type: receiver_type
- function_type: function_type_auto_scale
- vnf_instance_id: vnf_instance_id
- auto_scale_type: auto_scale_type
- aspect_id: aspect_id
- annotations: annotations
- startsAt: startsAt
- endsAt: endsAt
- fingerprint: fingerprint
Request Example
---------------

21
api-ref/source/v2/vnffm.inc
View File

@ -6,7 +6,7 @@ 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
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.
@ -20,7 +20,7 @@ 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
"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
@ -92,7 +92,10 @@ 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. In case of failure, appropriate error
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
@ -163,7 +166,7 @@ Modify the confirmation status (v1)
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
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.
@ -310,9 +313,10 @@ 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.
"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*
@ -337,7 +341,6 @@ Response Codes
- 401
- 404
- 406
- 409
Response Parameters
-------------------
@ -377,7 +380,7 @@ Get a subscription (v1)
.. rest_method:: GET /vnffm/v1/subscriptions/{subscriptionId}
The POST method gets the subscription in the Tacker.
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

2
api-ref/source/v2/vnflcm.inc
View File

@ -495,7 +495,7 @@ Response Parameters
.. rest_parameters:: parameters_vnflcm.yaml
- id: vnf_instance_id
- id: vnf_instance_id_response
- vnfInstanceName: vnf_instance_name
- vnfInstanceDescription: vnf_instance_description
- vnfdId: vnf_instance_vnfd_id

10
api-ref/source/v2/vnfpm.inc
View File

@ -89,7 +89,7 @@ Response Parameters
- collectionPeriod: criteria_collection_period
- reportingPeriod: criteria_reporting_period
- reportingBoundary: criteria_reporting_boundary
- callbackUri: vnf_pm_job_create_callback_uri
- callbackUri: vnf_pm_job_response_callback_uri
- reports: vnf_pm_job_reports
- href: reports_href
- readyTime: reports_ready_time
@ -134,7 +134,6 @@ Response Codes
- 400
- 401
- 406
- 409
Response Parameters
-------------------
@ -151,7 +150,7 @@ Response Parameters
- collectionPeriod: criteria_collection_period
- reportingPeriod: criteria_reporting_period
- reportingBoundary: criteria_reporting_boundary
- callbackUri: vnf_pm_job_create_callback_uri
- callbackUri: vnf_pm_job_response_callback_uri
- reports: vnf_pm_job_reports
- href: reports_href
- readyTime: reports_ready_time
@ -216,7 +215,7 @@ Response Parameters
- collectionPeriod: criteria_collection_period
- reportingPeriod: criteria_reporting_period
- reportingBoundary: criteria_reporting_boundary
- callbackUri: vnf_pm_job_create_callback_uri
- callbackUri: vnf_pm_job_response_callback_uri
- reports: vnf_pm_job_reports
- href: reports_href
- readyTime: reports_ready_time
@ -245,6 +244,7 @@ a PATCH request to the "Individual PM job" resource, including a data
structure of type "PmJobModifications" in the payload body. The VNFM returns
a "200 OK" response to the API consumer and includes in the payload body a data
structure of type "PmJobModifications" to indicate the performed modifications.
However the authentication parameter shall not be present in response body.
Response Codes
--------------
@ -287,7 +287,7 @@ Response Parameters
.. rest_parameters:: parameters_vnfpm.yaml
- callbackUri: vnf_pm_job_create_callback_uri
- callbackUri: vnf_pm_job_response_callback_uri
Response Example
----------------

22
doc/source/cli/cli-etsi-vnflcm.rst
View File

@ -18,25 +18,19 @@ CLI Reference for VNF Lifecycle Management
------------------------------------------
.. note::
Commands call version 1 vnflcm APIs by default.
You can call the specific version of vnflcm APIs
Commands call version 1 VNF LCM APIs by default.
You can call the specific version of VNF LCM APIs
by using the option **\-\-os-tacker-api-version**.
Commands with **\-\-os-tacker-api-version 2** call version 2 vnflcm APIs.
Commands with **\-\-os-tacker-api-version 2** call version 2 VNF LCM APIs.
.. note::
In Yoga release, version 2 vnflcm APIs of instantiate vnf,
terminate vnf, change current vnf package and fail both support VNF and
CNF. Version 2 vnflcm APIs of scale vnf, heal vnf and
change external vnf connectivity only support VNF, not CNF. Rollback and
retry with all lifecycle only support VNF, rollback change current vnf
package support CNF, and retry change current vnf package and retry
terminate support CNF. Other operation by version 2 vnflcm APIs
will support CNF in future releases.
In Antelope release, version 2 VNF LCM APIs of Update
and Change External VNF Connectivity only support VNF, not CNF.
.. note::
Change current vnf package only support version 2 vnflcm APIs. In Yoga
release, it only support ``RollingUpdate`` upgrade type, ``BlueGreen``
will be supported in future releases.
Change Current VNF Package only support version 2 VNF LCM APIs.
In Antelope release, it only support ``RollingUpdate`` upgrade type,
``BlueGreen`` will be supported in future releases.
1. Create VNF Identifier
^^^^^^^^^^^^^^^^^^^^^^^^

22
doc/source/user/etsi_cnf_change_current_vnf_package.rst
View File

@ -78,6 +78,21 @@ definition file before running command for changing the VNF package.
"vdu_params": [{
"vdu_id": "VDU1"
}]
},
"vimConnectionInfo": {
"vim1": {
"vimId": "8bc6f536-e5fb-4e4f-96f7-f55b16d35850",
"vimType": "ETSINFV.KUBERNETES.V_1",
"interfaceInfo": {
"endpoint": "https://192.168.56.10:6443"
},
"accessInfo": {
"bearer_token": "bearer_token"
},
"extra": {
"dummy-key": "dummy-val"
}
}
}
}
@ -125,6 +140,13 @@ You can set following parameter in additionalParams:
OpenStack VIM. And you only need to set this parameter when you need to
update the path of the manifest file of the deployment resource.
* ``vdu_params`` is VDU information of target VDU to update.
* ``vimConnectionInfo`` is an optional parameter.
This operation can specify the ``vimConnectionInfo`` for
the VNF instance.
Even if this operation specify multiple ``vimConnectionInfo``
associated with one VNF instance, only one of them will be used
for life cycle management operations.
It is not possible to delete the key of registered ``vimConnectionInfo``.
.. note:: Currently, this operation only supports some functions of
``Change Current VNF Package``.

13
doc/source/user/etsi_cnf_healing.rst
View File

@ -169,6 +169,11 @@ includes path of Kubernetes resource definition file and that
$ openstack vnflcm instantiate 92cf0ccb-e575-46e2-9c0d-30c67e75aaf6 instance_kubernetes.json
Instantiate request for VNF Instance 92cf0ccb-e575-46e2-9c0d-30c67e75aaf6 has been accepted.
.. note::
In the case of version 2 API, you can also set
``vimType`` as ``ETSINFV.KUBERNETES.V_1`` in ``vimConnectionInfo``.
CNF Healing Procedure
---------------------
@ -315,7 +320,7 @@ Pod information after heal:
vdu1-heal-simple-75b5566444-ks785 1/1 Running 0 60s
vdu1-heal-simple-75b5566444-p5mjv 1/1 Running 0 60s
All ``vnfcResourcecInfo`` in ``Instnatiated Vnf Info`` will be updated from
All ``vnfcResourceInfo`` in ``Instantiated Vnf Info`` will be updated from
the VNF Instance displayed in :ref:`labelCapHealingtargetVNFinstance`.
.. code-block:: console
@ -415,7 +420,7 @@ Heal specified with VNFC instances can be executed by running
In the example of this procedure, specify the ID
``686b356f-8096-4e24-99e5-3c81d36341be`` of the first ``vnfcResourceInfo`` as
``VNFC_INATANCE_ID``.
``VNFC_INSTANCE_ID``.
.. note:: In the case of version 1 API,
``VNFC_INSTANCE_ID`` is ``instantiatedVnfInfo.vnfcResourceInfo.id``.
@ -441,8 +446,8 @@ Pod information after heal:
vdu1-heal-simple-75b5566444-ks785 1/1 Running 0 24s
vdu1-heal-simple-75b5566444-wwzcm 1/1 Running 0 20m
Only the ``resourceId`` of target ``vnfcResourcecInfo`` in
``Instnatiated Vnf Info`` will be updated from the VNF Instance displayed in
Only the ``resourceId`` of target ``vnfcResourceInfo`` in
``Instantiated Vnf Info`` will be updated from the VNF Instance displayed in
:ref:`labelCapHealingtargetVNFinstance`.
.. code-block:: console

8
doc/source/user/etsi_cnf_helm_v2.rst
View File

@ -719,7 +719,7 @@ The following shows a sample json file.
"vimConnectionInfo": {
"vim1": {
"vimId": "d0f0cef9-5890-4a68-8974-61ed71b9f5d9",
"vimType": "kubernetes"
"vimType": "ETSINFV.KUBERNETES.V_1"
}
},
"additionalParams": {
@ -744,7 +744,7 @@ In the case of specifying ``vimId`` in the ``vimConnectionInfo``,
vim information is complemented by registered vim information.
.. note::
When using Helm, ``vimType`` shall be set as ``kubernetes``.
When using Helm, ``vimType`` shall be set as ``ETSINFV.KUBERNETES.V_1``.
It is treated as Helm VIM inside tacker on the basis of
the value of ``extra.use_helm``.
@ -770,6 +770,10 @@ The following shows the sample json.
}
}
.. note::
Even if this operation specify multiple ``vimConnectionInfo``
associated with one VNF instance, only one of them will be used for
life cycle management operations.
Also, a json file must include some parameters for Helm
as additional parameters

5
doc/source/user/etsi_cnf_scaling.rst
View File

@ -168,6 +168,11 @@ includes path of Kubernetes resource definition file and that
$ openstack vnflcm instantiate 92cf0ccb-e575-46e2-9c0d-30c67e75aaf6 instance_kubernetes.json
Instantiate request for VNF Instance 92cf0ccb-e575-46e2-9c0d-30c67e75aaf6 has been accepted.
.. note::
In the case of version 2 API, you can also set
``vimType`` as ``ETSINFV.KUBERNETES.V_1`` in ``vimConnectionInfo``.
CNF Scaling Procedure
---------------------

10
doc/source/user/etsi_containerized_vnf_usage_guide.rst
View File

@ -711,6 +711,12 @@ vimId and vimType.
]
}
.. note::
This operation can specify the ``vimConnectionInfo``
for the VNF instance.
Even if this operation specify multiple ``vimConnectionInfo``
associated with one VNF instance, only one of them will be used for
life cycle management operations.
.. note::
@ -733,6 +739,10 @@ In this case, specify the type and name of the resource corresponding to the
Although specifying it does not cause an error,
it is meaningless.
.. note::
In the case of version 2 API, you can also set
``vimType`` as ``ETSINFV.KUBERNETES.V_1`` in ``vimConnectionInfo``.
.. code-block:: console

27
doc/source/user/etsi_vnf_change_current_vnf_package.rst
View File

@ -109,6 +109,26 @@ definition file before running command for changing the VNF package.
"password": "ubuntu"
}
}]
},
"vimConnectionInfo": {
"vim1": {
"accessInfo": {
"password": "devstack",
"project": "nfv",
"projectDomain": "Default",
"region": "RegionOne",
"userDomain": "Default",
"username": "nfv_user"
},
"extra": {
"new-key": "new-val"
},
"interfaceInfo": {
"endpoint": "http://localhost/identity/v3"
},
"vimId": "defb2f96-5670-4bef-8036-27bf61267fc1",
"vimType": "ETSINFV.OPENSTACK_KEYSTONE.V_3"
}
}
}
@ -211,6 +231,13 @@ You can set following parameter in additionalParams:
to simulate the coordination interface in `ETSI SOL002 v3.5.1`_. Mainly a
script that can communicate with the VM after the VM is created, perform
special customization of the VM or confirm the status of the VM.
* ``vimConnectionInfo`` is an optional parameter.
This operation can specify the ``vimConnectionInfo`` for
the VNF instance.
Even if this operation specify multiple ``vimConnectionInfo``
associated with one VNF instance, only one of them will be used
for life cycle management operations.
It is not possible to delete the key of registered ``vimConnectionInfo``.
.. note:: Currently, this operation only supports some functions of
``Change Current VNF Package``.

7
doc/source/user/etsi_vnf_change_external_vnf_connectivity.rst
View File

@ -94,6 +94,13 @@ definition file before running command for changing the connectivity.
.. note:: sample_param_file.json contains all the data of port resource information.
if no setting is contained, it is treated as a change in information.
.. note::
The change external VNF Connectivity operation can change the
``vimConnectionInfo`` associated with an existing VNF instance.
Even if change external VNF Connectivity operation specify multiple
``vimConnectionInfo`` associated with one VNF instance, only one of
them will be used for life cycle management operations.
It is not possible to delete the key of registered ``vimConnectionInfo``.
How to Change the Specific Port Setting
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

10
doc/source/user/etsi_vnf_deployment_as_vm_with_tosca.rst
View File

@ -259,9 +259,17 @@ Optional parameters:
* vimConnectionInfo
.. note::
You can skip `vimConnectionInfo` only when you have
You can skip ``vimConnectionInfo`` only when you have
the default VIM described in :doc:`../cli/cli-legacy-vim`.
.. note::
This operation can specify the ``vimConnectionInfo``
for the VNF instance.
Even if this operation specify multiple ``vimConnectionInfo``
associated with one VNF instance, only one of them will be used for
life cycle management operations.
Param file with only required parameters:
.. code-block:: console

9
doc/source/user/etsi_vnf_deployment_as_vm_with_user_data.rst
View File

@ -129,9 +129,16 @@ Optional parameters:
* vimConnectionInfo
.. note::
You can skip `vimConnectionInfo` only when you have
You can skip ``vimConnectionInfo`` only when you have
the default VIM described in :doc:`../cli/cli-legacy-vim`.
.. note::
This operation can specify the ``vimConnectionInfo``
for the VNF instance.
Even if this operation specify multiple ``vimConnectionInfo``
associated with one VNF instance, only one of them will be used for
life cycle management operations.
Param file with only required parameters:
.. code-block:: console

12
doc/source/user/etsi_vnf_update.rst
View File

@ -96,12 +96,12 @@ Result:
Tacker does not refer the value of these parameters specified in VNFD.
.. note::
The update operation can change the vimConnectionInfo associated with an
existing VNF instance.
Even if instantiate operation and update operation specify multiple
vimConnectionInfo associated with one VNF instance, only one of them will
be used for life cycle management operations.
It is not possible to delete the key of registered vimConnectionInfo.
The update operation can change the ``vimConnectionInfo``
associated with an existing VNF instance.
Even if update operation specify multiple ``vimConnectionInfo``
associated with one VNF instance, only one of them will be used for life
cycle management operations.
It is not possible to delete the key of registered ``vimConnectionInfo``.
VNF instance name after operation: