openstack/tacker
Code Issues Proposed changes

Add docs for auto scale via PM Threshold API

Browse Source 
This patch makes the following updates to the API and CLI docs.

* Add support CNF auto scale via PM Threshold interface

Implements: blueprint support-auto-lcm
Change-Id: Ic699dd973f5a9fc14196d5f0c80e9f6ab2a9ab88
This commit is contained in:
YiFeng 2023-02-23 15:57:28 +09:00
parent 497586dffc
commit c004eb25d9
18 changed files with 1724 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -1,5 +1,5 @@
alert:
description: alert message
alerts:
description: alerts messages.
in: body
required: true
type: array
@ -25,7 +25,7 @@ endsAt:
description: |
alert expiration time.
in: body
required: true
required: false
type: string
event_type:
description: |
@ -75,6 +75,12 @@ function_type_pm:
in: body
required: true
type: string
function_type_threshold:
description: |
must be "vnfpm_threshold".
in: body
required: true
type: string
job_id:
description: |
PM job id defined in ETSI PM interface.
@ -140,13 +146,19 @@ sub_object_instance_id:
description: |
subObjectInstanceId defined in ETSI PM interface.
in: body
required: false
type: string
threshold_id:
description: |
PM Threshold id defined in ETSI PM interface.
in: body
required: true
type: string
value:
description: |
aspectId of the scaling target.
The result value returned by the PromQL statement.
in: body
required: true
required: false
type: number
vnf_instance_id:
description: |

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

@ -13,6 +13,13 @@ vnf_pm_job_report_id:
required: true
type: string
vnf_pm_threshold_id:
description: |
Identifier of this PM threshold.
in: path
required: true
type: string
# variables in body
authentication_auth_type:
description: |
@ -232,6 +239,12 @@ pm_job_links:
in: body
required: true
type: array
pm_threshold_links:
description: |
Links for this resource.
in: body
required: true
type: array
reports_expiry_time:
description: |
The time when the report will expire.
@ -355,6 +368,137 @@ vnf_pm_job_response_id:
in: body
required: true
type: string
vnf_pm_threshold_create_callback_uri:
description: |
The URI of the endpoint to send the notification to.
in: body
required: true
type: string
vnf_pm_threshold_create_metadata:
description: |
This attribute provides the access information of Prometheus Server.
in: body
required: true
type: key value pairs
vnf_pm_threshold_create_request_authentication:
description: |
Authentication parameters to configure the use of Authorization when
sending notifications corresponding to this subscription.
in: body
required: false
type: object
vnf_pm_threshold_criteria:
description: |
Criteria of the collection of performance information.
in: body
required: true
type: object
vnf_pm_threshold_criteria_performance_metric:
description: |
This defines the types of performance metrics associated with the
threshold.
in: body
required: true
type: string
vnf_pm_threshold_hysteresis:
description: |
The hysteresis of the threshold.
Shall be represented as a non-negative floating point number.
in: body
required: true
type: number
vnf_pm_threshold_id_body:
description: |
Identifier of this PM threshold.
in: body
required: true
type: string
vnf_pm_threshold_links_object:
description: |
Links to resources representing the measured object instances for which
performance information is collected. Shall be present if the measured
object instance information is accessible as a resource.
in: body
required: false
type: object
vnf_pm_threshold_object_instance_id:
description: |
Identifier of the measured object instance for which the performance metric
is reported.
in: body
required: true
type: string
vnf_pm_threshold_object_type:
description: |
Type of the measured object.
in: body
required: true
type: string
vnf_pm_threshold_report_entries_performance_metric:
description: |
Name of the metric collected.
in: body
required: true
type: string
vnf_pm_threshold_response_callback_uri:
description: |
The URI of the endpoint to send the notification to.
in: body
required: true
type: string
vnf_pm_threshold_response_id:
description: |
Identifier of this PM threshold.
in: body
required: true
type: string
vnf_pm_threshold_simple_threshold_details:
description: |
Details of a simple threshold. Shall be present if thresholdType="SIMPLE".
in: body
required: false
type: object
vnf_pm_threshold_sub_object_instance_ids:
description: |
Identifiers of the measured object instances in case of a structured
measured object.
in: body
required: false
type: array
vnf_pm_threshold_type:
description: |
Type of threshold. This attribute determines which other attributes
are present in the data structure.
"SIMPLE: Single-valued static threshold" is permitted.
in: body
required: true
type: string
vnf_pm_threshold_update_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: false
type: string
vnf_pm_threshold_update_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
vnf_pm_threshold_update_resp_callback_uri:
description: |
The URI of the endpoint to send the notification to.
in: body
required: false
type: string
vnf_pm_threshold_value:
description: |
The threshold value. Shall be represented as a floating point number.
in: body
required: true
type: number

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

@ -8,15 +8,17 @@ This interface is used for notifying alert that is detected by
the External Monitoring Tool. The External Monitoring Tool is
Prometheus based Monitoring system.
The Prometheus Plugin has 4 functions:
The Prometheus Plugin has 5 functions:
- Alerting interface for ETSI NFV-SOL 002/003 based Performance Management.
- Alerting interface for ETSI NFV-SOL 002/003 based Performance Management Job.
- Alerting interface for ETSI NFV-SOL 002/003 based Performance Management
Threshold.
- Alerting interface for ETSI NFV-SOL 002/003 based Fault Management.
- Alerting interface for Prometheus Plugin AutoScaling.
- Alerting interface for Prometheus Plugin AutoHealing.
Alerting interface for ETSI NFV-SOL 002/003 based Performance Management
========================================================================
Alerting interface for ETSI NFV-SOL 002/003 based Performance Management Job
============================================================================
.. rest_method:: POST /pm_event
@ -39,7 +41,7 @@ Request Parameters
.. rest_parameters:: parameters_prometheus_plugin.yaml
- alert: alert
- alerts: alerts
- status: status
- labels: labels
- receiver_type: receiver_type
@ -61,6 +63,52 @@ Request Example
:language: javascript
Alerting interface for ETSI NFV-SOL 002/003 based Performance Management Threshold
==================================================================================
.. rest_method:: POST /pm_threshold
Alert Tacker when one or more Performance values are obtained.
Response Codes
--------------
.. rest_status_code:: success status.yaml
- 204
.. rest_status_code:: error status.yaml
- 400
- 404: prometheus_plugin_pm
Request Parameters
------------------
.. rest_parameters:: parameters_prometheus_plugin.yaml
- alerts: alerts
- status: status
- labels: labels
- receiver_type: receiver_type
- function_type: function_type_threshold
- threshold_id: threshold_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
---------------
.. literalinclude:: samples/prometheus_plugin/alert_pm_threshold.json
:language: javascript
Alerting interface for ETSI NFV-SOL 002/003 based Fault Management
==================================================================
@ -85,7 +133,7 @@ Request Parameters
.. rest_parameters:: parameters_prometheus_plugin.yaml
- alert: alert
- alerts: alerts
- status: status
- labels: labels
- receiver_type: receiver_type
@ -132,7 +180,7 @@ Request Parameters
.. rest_parameters:: parameters_prometheus_plugin.yaml
- alert: alert
- alerts: alerts
- status: status
- labels: labels
- receiver_type: receiver_type
@ -180,7 +228,7 @@ Request Parameters
.. rest_parameters:: parameters_prometheus_plugin.yaml
- alert: alert
- alerts: alerts
- status: status
- labels: labels
- receiver_type: receiver_type

19
api-ref/source/v2/samples/prometheus_plugin/alert_pm_threshold.json Normal file
View File

@ -0,0 +1,19 @@
{
"alerts": [{
"status": "firing",
"labels": {
"receiver_type": "tacker",
"function_type": "vnfpm_threshold",
"threshold_id": "bb474274-c5eb-442b-e2a2-0c1c02437bac",
"metric": "VCpuUsageMeanVnf.4fcf78d6-52d9-4b6a-b3a6-49b2bef65843",
"object_instance_id": "4fcf78d6-52d9-4b6a-b3a6-49b2bef65843",
"sub_object_instance_id": "938f673e-1eae-44d1-8847-cce5f64ac00e"
},
"annotations": {
"value": 99
},
"startsAt": "2023-01-03T23:47:36.453Z",
"endsAt": "0001-01-01T00:00:00Z",
"fingerprint": "5ef77f1f8a3ecb8d"
}]
}

42
api-ref/source/v2/samples/vnfpm/create-pm-threshold-request.json Normal file
View File

@ -0,0 +1,42 @@
{
"objectType": "Vnf",
"objectInstanceId": "4fcf78d6-52d9-4b6a-b3a6-49b2bef65843",
"criteria": {
"performanceMetric": "VCpuUsageMeanVnf.4fcf78d6-52d9-4b6a-b3a6-49b2bef65843",
"thresholdType": "SIMPLE",
"simpleThresholdDetails": {
"thresholdValue": 55,
"hysteresis": 30
}
},
"callbackUri": "http://localhost:9990/notification/callbackuri/4fcf78d6-52d9-4b6a-b3a6-49b2bef65843",
"authentication": {
"authType": [
"BASIC"
],
"paramsBasic": {
"password": "ubuntu",
"userName": "ubuntu"
}
},
"metadata": {
"monitoring": {
"monitorName": "prometheus",
"driverType": "external",
"targetsInfo": [
{
"prometheusHost": "prometheus.example",
"prometheusHostPort": 50022,
"authInfo": {
"ssh_username": "ubuntu",
"ssh_password": "ubuntu"
},
"alertRuleConfigPath":
"/etc/prometheus/rule",
"prometheusReloadApiEndpoint":
"http://prometheus.example:9990/-/reload",
}
]
}
}
}

18
api-ref/source/v2/samples/vnfpm/create-pm-threshold-response.json Normal file
View File

@ -0,0 +1,18 @@
{
"id": "bb474274-c5eb-442b-e2a2-0c1c02437bac",
"objectType": "Vnf",
"objectInstanceId": "4fcf78d6-52d9-4b6a-b3a6-49b2bef65843",
"criteria": {
"performanceMetric": "VCpuUsageMeanVnf.4fcf78d6-52d9-4b6a-b3a6-49b2bef65843",
"thresholdType": "SIMPLE",
"simpleThresholdDetails": {
"thresholdValue": 55,
"hysteresis": 30
}
},
"callbackUri": "http://localhost:9990/notification/callbackuri/4fcf78d6-52d9-4b6a-b3a6-49b2bef65843",
"_link": {
"self": "http://127.0.0.1:9890/vnfpm/v2/thresholds/bb474274-c5eb-442b-e2a2-0c1c02437bac",
"object": "http://127.0.0.1:9890/vnflcm/v2/vnf_instances/4fcf78d6-52d9-4b6a-b3a6-49b2bef65843"
}
}

20
api-ref/source/v2/samples/vnfpm/list-pm-threshold-response.json Normal file
View File

@ -0,0 +1,20 @@
[
{
"id": "bb474274-c5eb-442b-e2a2-0c1c02437bac",
"objectType": "Vnf",
"objectInstanceId": "4fcf78d6-52d9-4b6a-b3a6-49b2bef65843",
"criteria": {
"performanceMetric": "VCpuUsageMeanVnf.4fcf78d6-52d9-4b6a-b3a6-49b2bef65843",
"thresholdType": "SIMPLE",
"simpleThresholdDetails": {
"thresholdValue": 55,
"hysteresis": 30
}
},
"callbackUri": "http://localhost:9990/notification/callbackuri/4fcf78d6-52d9-4b6a-b3a6-49b2bef65843",
"_link": {
"self": "http://127.0.0.1:9890/vnfpm/v2/thresholds/bb474274-c5eb-442b-e2a2-0c1c02437bac",
"object": "http://127.0.0.1:9890/vnflcm/v2/vnf_instances/4fcf78d6-52d9-4b6a-b3a6-49b2bef65843"
}
}
]

18
api-ref/source/v2/samples/vnfpm/show-pm-threshold-response.json Normal file
View File

@ -0,0 +1,18 @@
{
"id": "bb474274-c5eb-442b-e2a2-0c1c02437bac",
"objectType": "Vnf",
"objectInstanceId": "4fcf78d6-52d9-4b6a-b3a6-49b2bef65843",
"criteria": {
"performanceMetric": "VCpuUsageMeanVnf.4fcf78d6-52d9-4b6a-b3a6-49b2bef65843",
"thresholdType": "SIMPLE",
"simpleThresholdDetails": {
"thresholdValue": 55,
"hysteresis": 30
}
},
"callbackUri": "http://localhost:9990/notification/callbackuri/4fcf78d6-52d9-4b6a-b3a6-49b2bef65843",
"_link": {
"self": "http://127.0.0.1:9890/vnfpm/v2/thresholds/bb474274-c5eb-442b-e2a2-0c1c02437bac",
"object": "http://127.0.0.1:9890/vnflcm/v2/vnf_instances/4fcf78d6-52d9-4b6a-b3a6-49b2bef65843"
}
}

3
api-ref/source/v2/samples/vnfpm/update-pm-threshold-request.json Normal file
View File

@ -0,0 +1,3 @@
{
"callbackUri": "http://localhost:9990/notification/callback/callbackUri"
}

3
api-ref/source/v2/samples/vnfpm/update-pm-threshold-response.json Normal file
View File

@ -0,0 +1,3 @@
{
"callbackUri": "http://localhost:9990/notification/callback/callbackUri"
}

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

@ -392,3 +392,315 @@ Response Example
.. literalinclude:: samples/vnfpm/show-pm-job-report-response.json
:language: javascript
Create a PM threshold (v2)
==========================
.. rest_method:: POST /vnfpm/v2/thresholds
The POST method creates a new PM threshold.
As the result of successfully executing this method, a new PM threshold shall
have been created, and return detailed PM threshold data. In case of failure,
including an invalid notification endpoint, appropriate error information is
provided in the response.
Response Codes
--------------
.. rest_status_code:: success status.yaml
- 201
.. rest_status_code:: error status.yaml
- 400
- 401
- 404
- 406
- 409
- 422
- 503
Request Parameters
------------------
.. rest_parameters:: parameters_vnfpm.yaml
- objectType: vnf_pm_threshold_object_type
- objectInstanceId: vnf_pm_threshold_object_instance_id
- subObjectInstanceIds: vnf_pm_threshold_sub_object_instance_ids
- criteria: vnf_pm_threshold_criteria
- performanceMetric: vnf_pm_threshold_criteria_performance_metric
- thresholdType: vnf_pm_threshold_type
- simpleThresholdDetails: vnf_pm_threshold_simple_threshold_details
- thresholdValue: vnf_pm_threshold_value
- hysteresis: vnf_pm_threshold_hysteresis
- callbackUri: vnf_pm_threshold_create_callback_uri
- authentication: vnf_pm_threshold_create_request_authentication
- authType: authentication_auth_type
- paramsBasic: authentication_params_basic
- userName: paramsBasic_userName
- password: paramsBasic_password
- paramsOauth2ClientCredentials: authentication_params_oauth2_client_credentials
- clientId: params_oauth2_client_credentials_client_id
- clientPassword: params_oauth2_client_credentials_client_password
- tokenEndpoint: params_oauth2_client_credentials_token_endpoint
- paramsOauth2ClientCert: authentication_params_oauth2_client_cert
- clientId: params_oauth2_client_cert_client_id
- certificateRef: params_oauth2_client_cert_certificate_ref
- type: params_oauth2_client_cert_type
- value: params_oauth2_client_cert_value
- tokenEndpoint: params_oauth2_client_cert_token_endpoint
- metadata: vnf_pm_threshold_create_metadata
Request Example
---------------
.. literalinclude:: samples/vnfpm/create-pm-threshold-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters_vnfpm.yaml
- id: vnf_pm_threshold_id_body
- objectType: vnf_pm_threshold_object_type
- objectInstanceId: vnf_pm_threshold_object_instance_id
- subObjectInstanceIds: vnf_pm_threshold_sub_object_instance_ids
- criteria: vnf_pm_threshold_criteria
- performanceMetric: vnf_pm_threshold_criteria_performance_metric
- thresholdType: vnf_pm_threshold_type
- simpleThresholdDetails: vnf_pm_threshold_simple_threshold_details
- thresholdValue: vnf_pm_threshold_value
- hysteresis: vnf_pm_threshold_hysteresis
- callbackUri: vnf_pm_threshold_response_callback_uri
- _links: pm_threshold_links
- self: links_self
- object: vnf_pm_threshold_links_object
Response Example
----------------
.. literalinclude:: samples/vnfpm/create-pm-threshold-response.json
:language: javascript
Get for PM thresholds (v2)
==========================
.. rest_method:: GET /vnfpm/v2/thresholds
The GET method allows users to filter out PM thresholds based on query
parameter in the request.
It supports attribute-based filtering and attribute selectors defined in ETSI
NFV SOL013 v3.4.1. The detail of attribute-based filtering is described in
SOL013 v3.4.1 clause 5.2. The detail of attribute selectors is described in
SOL013 v3.4.1 clause 5.3.
An attribute selector allows the API consumer to choose which attributes it
wants to be contained in the response.
Response Codes
--------------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 400
- 401
- 406
Response Parameters
-------------------
.. rest_parameters:: parameters_vnfpm.yaml
- id: vnf_pm_threshold_id_body
- objectType: vnf_pm_threshold_object_type
- objectInstanceId: vnf_pm_threshold_object_instance_id
- subObjectInstanceIds: vnf_pm_threshold_sub_object_instance_ids
- criteria: vnf_pm_threshold_criteria
- performanceMetric: vnf_pm_threshold_criteria_performance_metric
- thresholdType: vnf_pm_threshold_type
- simpleThresholdDetails: vnf_pm_threshold_simple_threshold_details
- thresholdValue: vnf_pm_threshold_value
- hysteresis: vnf_pm_threshold_hysteresis
- callbackUri: vnf_pm_threshold_response_callback_uri
- _links: pm_threshold_links
- self: links_self
- object: vnf_pm_threshold_links_object
Response Example
----------------
.. literalinclude:: samples/vnfpm/list-pm-threshold-response.json
:language: javascript
Get a PM threshold (v2)
=======================
.. rest_method:: GET /vnfpm/v2/thresholds/{thresholdId}
The GET method gets an individual PM threshold.
If the API consumer intends to read information about a particular PM
threshold, it sends a GET request to the "Individual PM threshold" resource,
addressed by the appropriate PM threshold identifier in its resource URI.
The VNFM returns a "200 OK" response to the API consumer, and includes one
data structure of type "PmThreshold" in the payload body. In case of failure,
appropriate error information is provided in the response.
Response Codes
--------------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 400
- 401
- 404
Request Parameters
------------------
.. rest_parameters:: parameters_vnfpm.yaml
- thresholdId: vnf_pm_threshold_id
Response Parameters
-------------------
.. rest_parameters:: parameters_vnfpm.yaml
- id: vnf_pm_threshold_id_body
- objectType: vnf_pm_threshold_object_type
- objectInstanceId: vnf_pm_threshold_object_instance_id
- subObjectInstanceIds: vnf_pm_threshold_sub_object_instance_ids
- criteria: vnf_pm_threshold_criteria
- performanceMetric: vnf_pm_threshold_criteria_performance_metric
- thresholdType: vnf_pm_threshold_type
- simpleThresholdDetails: vnf_pm_threshold_simple_threshold_details
- thresholdValue: vnf_pm_threshold_value
- hysteresis: vnf_pm_threshold_hysteresis
- callbackUri: vnf_pm_threshold_response_callback_uri
- _links: pm_threshold_links
- self: links_self
- object: vnf_pm_threshold_links_object
Response Example
----------------
.. literalinclude:: samples/vnfpm/show-pm-threshold-response.json
:language: javascript
Modify a PM threshold(v2)
=========================
.. rest_method:: PATCH /vnfpm/v2/thresholds/{thresholdId}
The PATCH method Modifies a PM threshold.
If the API consumer intends to update the callback URI in a PM threshold,
it sends a PATCH request to the "Individual PM threshold" resource, including
a data structure of type "ThresholdModifications" 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 "ThresholdModifications" to
indicate the performed modifications. However the authentication parameter
shall not be present in response body.
Response Codes
--------------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 400
- 401
- 422
Request Parameters
------------------
.. rest_parameters:: parameters_vnfpm.yaml
- thresholdId: vnf_pm_threshold_id
- callbackUri: vnf_pm_threshold_update_callback_uri
- authentication: vnf_pm_threshold_update_request_authentication
- authType: authentication_auth_type
- paramsBasic: authentication_params_basic
- userName: paramsBasic_userName
- password: paramsBasic_password
- paramsOauth2ClientCredentials: authentication_params_oauth2_client_credentials
- clientId: params_oauth2_client_credentials_client_id
- clientPassword: params_oauth2_client_credentials_client_password
- tokenEndpoint: params_oauth2_client_credentials_token_endpoint
- paramsOauth2ClientCert: authentication_params_oauth2_client_cert
- clientId: params_oauth2_client_cert_client_id
- certificateRef: params_oauth2_client_cert_certificate_ref
- type: params_oauth2_client_cert_type
- value: params_oauth2_client_cert_value
- tokenEndpoint: params_oauth2_client_cert_token_endpoint
Request Example
---------------
.. literalinclude:: samples/vnfpm/update-pm-threshold-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters_vnfpm.yaml
- callbackUri: vnf_pm_threshold_update_resp_callback_uri
Response Example
----------------
.. literalinclude:: samples/vnfpm/update-pm-threshold-response.json
:language: javascript
Delete a PM threshold (v2)
==========================
.. rest_method:: DELETE /vnfpm/v2/thresholds/{thresholdId}
The DELETE method deletes a PM threshold.
If the API consumer intends to delete a PM threshold, it sends a DELETE
request to the "Individual PM threshold" resource addressed by the
appropriate PM threshold identifier in its resource URI. The VNFM returns
a response with a "204 No Content" response code and an empty payload body
to the API consumer.
Response Codes
--------------
.. rest_status_code:: success status.yaml
- 204
.. rest_status_code:: error status.yaml
- 400
- 401
- 404
Request Parameters
------------------
.. rest_parameters:: parameters_vnfpm.yaml
- thresholdId: vnf_pm_threshold_id

BIN
doc/source/_images/etsi_cnf_auto_scaling_pm_threshold.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 88 KiB

46
doc/source/_images/etsi_cnf_auto_scaling_pm_threshold.pu Normal file
View File

@ -0,0 +1,46 @@
@startuml
frame "Prometheus" {
component "Prometheus" as prom
}
frame "NFVO" {
component "NFVO" as nfvo
}
frame "tacker" {
component "tacker-server" {
component "VnfpmControllerV2" as pm_ctl
component "PrometheusPlugin" as plugin
component "VnflcmControllerV2" as lcm_ctl
}
component "tacker-conductor" {
component "Vnfpm\ndriver" as pm_driver
component "Kubernetes\ninfra-driver" as infra
}
}
node "Kubernetes Cluster\n(Master)" as k8s_m
cloud "Hardware Resources" as hw {
node "Kubernetes Cluster\n(Worker)" as k8s_w {
node "Pod" as ins1
node "Pod" as ins2
node "Pod" as ins3
}
}
'# Relationships
nfvo --> pm_ctl: 1. Create PM threshold
pm_ctl --> plugin
plugin --> prom: 2. Set PM threshold
ins1 --> prom: 3. Trigger threshold event
ins2 --> prom
prom --> plugin: 4. POST threshold event
plugin --> pm_driver: 5. Convert threshold event to threshold state
plugin --> nfvo: 6. Send threshold state notification
nfvo --> lcm_ctl: 7. Scale
lcm_ctl --> infra
infra --> k8s_m: 8. Call Kubernetes API
k8s_m --> ins3: 9. Change the number of Pods
@enduml

361
doc/source/cli/cli-etsi-vnfpm.rst
View File

@ -499,3 +499,364 @@ Help:
--fit-width Fit the table to the display width. Implied if --max-width greater than
0. Set the environment variable CLIFF_FIT_WIDTH=1 to always enable
--print-empty Print empty table if there is no data to show.
7. Create PM threshold
^^^^^^^^^^^^^^^^^^^^^^
'param-file': Specify create VNF PM threshold request parameters in a json
file.
.. code-block:: console
$ openstack vnfpm threshold create <param-file> --os-tacker-api-version 2
Result:
.. code-block:: console
+-------------------------+------------------------------------------------------------------------------------------------------+
| Field | Value |
+-------------------------+------------------------------------------------------------------------------------------------------+
| Callback Uri | http://127.0.0.1:9990/notification/callbackuri/511a2d68-c975-4913-b7b8-d75468e3102b |
| Criteria | { |
| | "performanceMetric": "VMemoryUsageMeanVnf.511a2d68-c975-4913-b7b8-d75468e3102b", |
| | "thresholdType": "SIMPLE", |
| | "simpleThresholdDetails": { |
| | "thresholdValue": 55.0, |
| | "hysteresis": 30.0 |
| | } |
| | } |
| ID | 4787c544-c3d0-4aeb-bf60-1598125c3d4f |
| Links | { |
| | "self": { |
| | "href": "http://127.0.0.1:9890/vnfpm/v2/thresholds/4787c544-c3d0-4aeb-bf60-1598125c3d4f" |
| | }, |
| | "object": { |
| | "href": "http://127.0.0.1:9890/vnflcm/v2/vnf_instances/511a2d68-c975-4913-b7b8-d75468e3102b" |
| | } |
| | } |
| Object Instance Id | 511a2d68-c975-4913-b7b8-d75468e3102b |
| Object Type | Vnf |
| Sub Object Instance Ids | |
+-------------------------+------------------------------------------------------------------------------------------------------+
Help:
.. code-block:: console
$ openstack vnfpm threshold create --os-tacker-api-version 2 --help
usage: openstack vnfpm threshold create [-h] [-f {json,shell,table,value,yaml}]
[-c COLUMN] [--noindent] [--prefix PREFIX]
[--max-width <integer>] [--fit-width]
[--print-empty]
<param-file>
Create a new VNF PM threshold
positional arguments:
<param-file> Specify create VNF PM threshold request parameters in a json file.
optional arguments:
-h, --help show this help message and exit
output formatters:
output formatter options
-f {json,shell,table,value,yaml}, --format {json,shell,table,value,yaml}
the output format, defaults to table
-c COLUMN, --column COLUMN
specify the column(s) to include, can be repeated to
show multiple columns
json formatter:
--noindent whether to disable indenting the JSON
shell formatter:
a format a UNIX shell can parse (variable="value")
--prefix PREFIX add a prefix to all variable names
table formatter:
--max-width <integer>
Maximum display width, <1 to disable. You can also use
the CLIFF_MAX_TERM_WIDTH environment variable, but the
parameter takes precedence.
--fit-width Fit the table to the display width. Implied if --max-width
greater than 0. Set the environment variable
CLIFF_FIT_WIDTH=1 to always enable
--print-empty Print empty table if there is no data to show.
8. Update PM threshold
^^^^^^^^^^^^^^^^^^^^^^
The `<vnf-pm-threshold-id>` should be replaced with the 'ID' in result of
'7. Create PM threshold'. In the following sample,
`4787c544-c3d0-4aeb-bf60-1598125c3d4f` is used.
.. code-block:: console
$ openstack vnfpm threshold update <vnf-pm-threshold-id> <param-file> --os-tacker-api-version 2
Result:
.. code-block:: console
+----------------+------------------------------------------------------------+
| Field | Value |
+----------------+------------------------------------------------------------+
| Callback Uri | http://127.0.0.1:9990/notification/callbackuri/callbackUri |
+----------------+------------------------------------------------------------+
Help:
.. code-block:: console
$ openstack vnfpm threshold update --os-tacker-api-version 2 --help
usage: openstack vnfpm threshold update [-h] [-f {json,shell,table,value,yaml}]
[-c COLUMN] [--noindent] [--prefix PREFIX]
[--max-width <integer>] [--fit-width]
[--print-empty]
<vnf-pm-threshold-id> <param-file>
Update information about an individual VNF PM threshold
positional arguments:
<vnf-pm-threshold-id> VNF PM threshold ID to update.
<param-file> Specify update PM threshold request parameters in a json file.
optional arguments:
-h, --help show this help message and exit
output formatters:
output formatter options
-f {json,shell,table,value,yaml}, --format {json,shell,table,value,yaml}
the output format, defaults to table
-c COLUMN, --column COLUMN
specify the column(s) to include, can be repeated to
show multiple columns
json formatter:
--noindent whether to disable indenting the JSON
shell formatter:
a format a UNIX shell can parse (variable="value")
--prefix PREFIX add a prefix to all variable names
table formatter:
--max-width <integer>
Maximum display width, <1 to disable. You can also use
the CLIFF_MAX_TERM_WIDTH environment variable, but the
parameter takes precedence.
--fit-width Fit the table to the display width. Implied if
--max-width greater than 0. Set the environment variable
CLIFF_FIT_WIDTH=1 to always enable
--print-empty Print empty table if there is no data to show.
9. List PM thresholds
^^^^^^^^^^^^^^^^^^^^^
.. code-block:: console
$ openstack vnfpm threshold list --os-tacker-api-version 2
Result:
.. code-block:: console
+--------------------------------------+-------------+------------------------------------------------------------------------------------------------------+
| ID | Object Type | Links |
+--------------------------------------+-------------+------------------------------------------------------------------------------------------------------+
| 4787c544-c3d0-4aeb-bf60-1598125c3d4f | Vnf | { |
| | | "self": { |
| | | "href": "http://127.0.0.1:9890/vnfpm/v2/thresholds/4787c544-c3d0-4aeb-bf60-1598125c3d4f" |
| | | }, |
| | | "object": { |
| | | "href": "http://127.0.0.1:9890/vnflcm/v2/vnf_instances/511a2d68-c975-4913-b7b8-d75468e3102b" |
| | | } |
| | | } |
+--------------------------------------+-------------+------------------------------------------------------------------------------------------------------+
Help:
.. code-block:: console
$ openstack vnfpm threshold list --os-tacker-api-version 2 --help
usage: openstack vnfpm threshold list [-h] [-f {csv,json,table,value,yaml}] [-c COLUMN]
[--quote {all,minimal,none,nonnumeric}] [--noindent]
[--max-width <integer>]
[--fit-width] [--print-empty] [--sort-column SORT_COLUMN]
[--sort-ascending | --sort-descending] [--filter <filter>]
List VNF PM thresholds
optional arguments:
-h, --help show this help message and exit
--filter <filter> Attribute-based-filtering parameters
output formatters:
output formatter options
-f {csv,json,table,value,yaml}, --format {csv,json,table,value,yaml}
the output format, defaults to table
-c COLUMN, --column COLUMN
specify the column(s) to include, can be repeated to
show multiple columns
--sort-column SORT_COLUMN
specify the column(s) to sort the data (
columns specified first have a priority,
non-existing columns are ignored), can be repeated
--sort-ascending sort the column(s) in ascending order
--sort-descending sort the column(s) in descending order
CSV Formatter:
--quote {all,minimal,none,nonnumeric}
when to include quotes, defaults to nonnumeric
json formatter:
--noindent whether to disable indenting the JSON
table formatter:
--max-width <integer>
Maximum display width, <1 to disable. You can also
use the CLIFF_MAX_TERM_WIDTH environment variable,
but the parameter takes precedence.
--fit-width Fit the table to the display width. Implied if
--max-width greater than 0. Set the environment variable
CLIFF_FIT_WIDTH=1 to always enable
--print-empty Print empty table if there is no data to show.
10. Show PM threshold
^^^^^^^^^^^^^^^^^^^^^
The `<vnf-pm-threshold-id>` should be replaced with the 'ID' in result of
'7. Create PM threshold' or '9. List PM thresholds'. In the following sample,
`4787c544-c3d0-4aeb-bf60-1598125c3d4f` is used.
.. code-block:: console
$openstack vnfpm threshold show <vnf-pm-threshold-id> --os-tacker-api-version 2
Result:
.. code-block:: console
+-------------------------+------------------------------------------------------------------------------------------------------+
| Field | Value |
+-------------------------+------------------------------------------------------------------------------------------------------+
| Callback Uri | http://127.0.0.1:9990/notification/callbackuri/callbackUri |
| Criteria | { |
| | "performanceMetric": "VMemoryUsageMeanVnf.511a2d68-c975-4913-b7b8-d75468e3102b", |
| | "thresholdType": "SIMPLE", |
| | "simpleThresholdDetails": { |
| | "thresholdValue": 55.0, |
| | "hysteresis": 30.0 |
| | } |
| | } |
| ID | 4787c544-c3d0-4aeb-bf60-1598125c3d4f |
| Links | { |
| | "self": { |
| | "href": "http://127.0.0.1:9890/vnfpm/v2/thresholds/4787c544-c3d0-4aeb-bf60-1598125c3d4f" |
| | }, |
| | "object": { |
| | "href": "http://127.0.0.1:9890/vnflcm/v2/vnf_instances/511a2d68-c975-4913-b7b8-d75468e3102b" |
| | } |
| | } |
| Object Instance Id | 511a2d68-c975-4913-b7b8-d75468e3102b |
| Object Type | Vnf |
| Sub Object Instance Ids | |
+-------------------------+------------------------------------------------------------------------------------------------------+
Help:
.. code-block:: console
$ openstack vnfpm threshold show --os-tacker-api-version 2 --help
usage: openstack vnfpm threshold show [-h] [-f {json,shell,table,value,yaml}]
[-c COLUMN] [--noindent]
[--prefix PREFIX] [--max-width <integer>]
[--fit-width] [--print-empty]
<vnf-pm-threshold-id>
Display VNF PM threshold details
positional arguments:
<vnf-pm-threshold-id> VNF PM threshold ID to display
optional arguments:
-h, --help show this help message and exit
output formatters:
output formatter options
-f {json,shell,table,value,yaml}, --format {json,shell,table,value,yaml}
the output format, defaults to table
-c COLUMN, --column COLUMN
specify the column(s) to include, can be repeated to
show multiple columns
json formatter:
--noindent whether to disable indenting the JSON
shell formatter:
a format a UNIX shell can parse (variable="value")
--prefix PREFIX add a prefix to all variable names
table formatter:
--max-width <integer>
Maximum display width, <1 to disable. You can also use
the CLIFF_MAX_TERM_WIDTH environment variable, but the
parameter takes precedence.
--fit-width Fit the table to the display width. Implied if
--max-width greater than 0. Set the environment variable
CLIFF_FIT_WIDTH=1 to always enable
--print-empty Print empty table if there is no data to show.
11. Delete PM threshold
^^^^^^^^^^^^^^^^^^^^^^^
The `<vnf-pm-threshold-id>` should be replaced with the 'ID' in result of
'7. Create PM threshold' or '9. List PM thresholds'. In the following sample,
`4787c544-c3d0-4aeb-bf60-1598125c3d4f` is used.
.. code-block:: console
$ openstack vnfpm threshold delete <vnf-pm-threshold-id> --os-tacker-api-version 2
Result:
.. code-block:: console
VNF PM threshold '4787c544-c3d0-4aeb-bf60-1598125c3d4f' deleted successfully
Help:
.. code-block:: console
$ openstack vnfpm threshold delete --os-tacker-api-version 2 --help
usage: openstack vnfpm threshold delete [-h] <vnf-pm-threshold-id> [<vnf-pm-threshold-id> ...]
Delete VNF PM threshold
positional arguments:
<vnf-pm-threshold-id> VNF PM threshold ID(s) to delete
optional arguments:
-h, --help show this help message and exit

40
doc/source/user/etsi_cnf_auto_scaling_pm.rst
View File

@ -1,9 +1,9 @@
===============================================================
ETSI NFV-SOL CNF Auto Scaling With Prometheus via PM Interfaces
===============================================================
===================================================================
ETSI NFV-SOL CNF Auto Scaling With Prometheus via PM Job Interfaces
===================================================================
This document describes how to auto scale CNF in Tacker with Prometheus
via Performance Management Interfaces.
via Performance Management Job Interfaces.
Overview
--------
@ -163,14 +163,14 @@ The following are the parameters required by this interface.
- PmJobCriteria
- 1
- Criteria of the collection of performance information.
* - >performanceMetric
* - performanceMetric
- String
- 0..N
- This defines the types of performance metrics for the specified object
instances. Valid values are specified as "Measurement Name" values in
clause 7.2 of `ETSI GS NFV-IFA 027`_. At least one of the two
attributes (performance metric or group) shall be present.
* - >performanceMetricGroup
* - performanceMetricGroup
- String
- 0..N
- Group of performance metrics. A metric group is a pre-defined list of
@ -178,19 +178,19 @@ The following are the parameters required by this interface.
metrics. Valid values are specified as "Measurement Group" values in
clause 7.2 of `ETSI GS NFV-IFA 027`_. At least one of the two
attributes (performance metric or group) shall be present.
* - >collectionPeriod
* - collectionPeriod
- UnsignedInt
- 1
- Specifies the periodicity at which the API producer will collect
performance information. The unit shall be seconds.
* - >reportingPeriod
* - reportingPeriod
- UnsignedInt
- 1
- Specifies the periodicity at which the API producer will report to
the API consumer. about performance information. The unit shall be
seconds. The reportingPeriod should be equal to or a multiple of
the collectionPeriod.
* - >reportingBoundary
* - reportingBoundary
- DateTime
- 0..1
- Identifies a time boundary after which the reporting will stop. The
@ -210,48 +210,48 @@ The following are the parameters required by this interface.
- Structure
- 1
- Additional parameters to create PM job.
* - >monitoring
* - monitoring
- Structure
- 1
- Treats to specify such as monitoring system and driver information.
* - >>monitorName
* - monitorName
- String
- 1
- In case specifying “prometheus”, backend of monitoring feature is
to be Prometheus.
* - >>driverType
* - driverType
- String
- 1
- “external”: SCP/SFTP for config file transfer.
* - >>targetsInfo
* - targetsInfo
- Structure
- 1..N
- Information about the target monitoring system.
* - >>>prometheusHost
* - prometheusHost
- String
- 1
- FQDN or ip address of target PrometheusServer.
* - >>>prometheusHostPort
* - prometheusHostPort
- Int
- 1
- Port of the ssh target PrometheusServer.
* - >>>alertRuleConfigPath
* - alertRuleConfigPath
- String
- 1
- Path of alertRuleConfig path for target Prometheus.
* - >>>prometheusReloadApiEndpoint
* - prometheusReloadApiEndpoint
- String
- 1
- Endpoint url of reload API of target Prometheus.
* - >>>authInfo
* - authInfo
- Structure
- 1
- Define authentication information to access host.
* - >>>>ssh_username
* - ssh_username
- String
- 1
- The username of the target host for ssh.
* - >>>>ssh_password
* - ssh_password
- String
- 1
- The password of the target host for ssh.

527
doc/source/user/etsi_cnf_auto_scaling_pm_threshold.rst Normal file
View File

@ -0,0 +1,527 @@
=========================================================================
ETSI NFV-SOL CNF Auto Scaling With Prometheus via PM Threshold Interfaces
=========================================================================
This document describes how to auto scale CNF in Tacker with Prometheus
via Performance Management Threshold Interfaces.
Overview
--------
The diagram below shows an overview of the CNF auto scaling.
1. Create PM threshold
The NFVO sends a request to the Tacker to create a PM threshold.
2. Set PM threshold
Prometheus Plugin sets PM threshold to Prometheus.
3. Trigger threshold event
Prometheus collects metrics and decides whether triggering threshold event
is needed or not.
4. POST threshold event
Prometheus sends POST request to Tacker with specified URI. Tacker
collects data related to the PM threshold event.
5. Convert threshold event to threshold state
Tacker receives informed threshold event, converts it to threshold state,
and saves it to DB.
6. Send threshold state notification
VnfPmDriverV2 finds all thresholds in the DB and matches the threshold
state to threshold. If the crossingDirection of threshold state is ``UP``
or ``DOWN``, the notification is sent to the specified path of the NFVO.
If the match is not successful or the situation does not exist, the
processing ends.
7. Scale
Upon receiving a request to scale VNF from NFVO, tacker-server
redirects it to tacker-conductor.
8. Call Kubernetes API
In tacker-conductor, the request is redirected again to an
appropriate infra-driver (in this case Kubernetes infra-driver)
according to the contents of the instantiate parameters. Then,
Kubernetes infra-driver calls Kubernetes APIs.
9. Change the number of Pods
Kubernetes Master change the number of Pods according to the
API calls.
.. figure:: ../_images/etsi_cnf_auto_scaling_pm_threshold.png
:align: left
Prerequisites
-------------
* The following packages should be installed:
* tacker
* python-tackerclient
At least one VNF instance with status of ``INSTANTIATED`` is required.
You can refer to :doc:`./etsi_containerized_vnf_usage_guide` for the
procedure to instantiate VNF.
The VNF Package used can refer to `the sample`_.
* The following third-party services should be installed
* NFVO
* Prometheus(including Alertmanager)
Each operator has its own NFVO, there is no restriction here, as long as
it conforms to `ETSI NFV-SOL 002 v3.3.1`_ and `ETSI NFV-SOL 003 v3.3.1`_,
it can be used.
For the installation of Prometheus and Alertmanager, please refer to
the `official website`_.
How to configure Prometheus Plugin
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Please refer to `How to configure Prometheus Plugin`_ to enable the
Prometheus Plugin.
.. _Create PM threshold :
How to create a PM threshold
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
After having a CNF that can scale, we need to create a PM threshold. It
determines the monitoring metrics and monitoring resources to be
used by Prometheus.
.. note::
When having an NFVO client, the request is sent by NFVO.
The interface for creating PM thresholds is defined in both
`ETSI NFV-SOL 002 v3.3.1`_ and `ETSI NFV-SOL 003 v3.3.1`_.
The following are the parameters required by this interface.
.. list-table:: additional params
:widths: 18 18 10 50
:header-rows: 1
* - Attribute name
- Data type
- Cardinality
- Description
* - objectType
- String
- 1
- Type of the measured object. The applicable measured object type for a
measurement is defined in clause 7.2 of `ETSI GS NFV-IFA 027`_.
* - objectInstanceId
- Identifier
- 1
- Identifiers of the measured object instances for which performance
information is requested to be collected.
* - subObjectInstanceIds
- IdentifierInVnf
- 0..N
- Identifiers of the measured object instances in case of a structured
measured object.
* - criteria
- ThresholdCriteria
- 1
- Criteria of the collection of performance information.
* - performanceMetric
- String
- 1
- This defines the types of performance metrics for the specified object
instances. Valid values are specified as "Measurement Name" values in
clause 7.2 of `ETSI GS NFV-IFA 027`_.
* - thresholdType
- String
- 1
- This defines the type of threshold. This attribute determines which other
attributes are present in the data structure.
* - simpleThresholdDetails
- Structure
- 0..1
- Details of a simple threshold. Shall be present if
thresholdType="SIMPLE".
* - thresholdValue
- Float
- 1
- The threshold value. Shall be represented as a floating point number.
* - hysteresis
- Float
- 1
- The hysteresis of the threshold. Shall be represented as a non-negative
floating point number.
* - callbackUri
- Uri
- 1
- The URI of the endpoint to send the notification to.
* - authentication
- SubscriptionAuthentication
- 0..1
- Authentication parameters to configure the use of Authorization when
sending notifications corresponding to this subscription. See as
clause 8.3.4 of `ETSI GS NFV-SOL 013`_.
* - metadata
- Structure
- 1
- Additional parameters to create PM threshold.
* - monitoring
- Structure
- 1
- Treats to specify such as monitoring system and driver information.
* - monitorName
- String
- 1
- In case specifying "prometheus", backend of monitoring feature is
to be Prometheus.
* - driverType
- String
- 1
- "external": SCP/SFTP for config file transfer.
* - targetsInfo
- Structure
- 1..N
- Information about the target monitoring system.
* - prometheusHost
- String
- 1
- FQDN or ip address of target PrometheusServer.
* - prometheusHostPort
- Int
- 1
- Port of the ssh target PrometheusServer.
* - alertRuleConfigPath
- String
- 1
- Path of alertRuleConfig path for target Prometheus.
* - prometheusReloadApiEndpoint
- String
- 1
- Endpoint url of reload API of target Prometheus.
* - authInfo
- Structure
- 1
- Define authentication information to access host.
* - ssh_username
- String
- 1
- The username of the target host for ssh.
* - ssh_password
- String
- 1
- The password of the target host for ssh.
.. note::
* ``objectType`` has only the following values: ``Vnf``, ``Vnfc``,
``VnfIntCp``, ``VnfExtCp``.
Create PM threshold can be executed by the following CLI command.
.. code-block:: console
$ openstack vnfpm threshold create sample_param_file.json --os-tacker-api-version 2
The content of the sample ``sample_param_file.json`` in this document is
as follows:
.. code-block:: json
{
"objectType": "Vnf",
"objectInstanceId": "511a2d68-c975-4913-b7b8-d75468e3102b",
"subObjectInstanceIds": [],
"criteria": {
"performanceMetric": "VMemoryUsageMeanVnf.511a2d68-c975-4913-b7b8-d75468e3102b",
"thresholdType": "SIMPLE",
"simpleThresholdDetails": {
"thresholdValue": 55,
"hysteresis": 30
}
},
"callbackUri": "http://localhost:9990/notification/callbackuri/511a2d68-c975-4913-b7b8-d75468e3102b",
"authentication": {
"authType": [
"BASIC",
"OAUTH2_CLIENT_CREDENTIALS",
"OAUTH2_CLIENT_CERT"
],
"paramsBasic": {
"userName": "nfvo",
"password": "nfvopwd"
},
"paramsOauth2ClientCredentials": {
"clientId": "auth_user_name",
"clientPassword": "auth_password",
"tokenEndpoint": "token_endpoint"
},
"paramsOauth2ClientCert": {
"clientId": "auth_user_name",
"certificateRef": {
"type": "x5t#S256",
"value": "certificate_fingerprint"
},
"tokenEndpoint": "token_endpoint"
}
},
"metadata": {
"monitoring": {
"monitorName": "prometheus",
"driverType": "external",