diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/Chapter7.rst | 786 | ||||
| -rw-r--r-- | docs/Chapter8.rst | 613 | ||||
| -rw-r--r-- | docs/Data_Model_For_Event_Records.png | bin | 79667 -> 61638 bytes | |||
| -rw-r--r-- | docs/Protocol_Buffers_Driven_Model.png | bin | 0 -> 14280 bytes | |||
| -rw-r--r-- | docs/VES_JSON_Driven_Model.png | bin | 0 -> 9218 bytes | |||
| -rw-r--r-- | docs/YANG_Driven_Model.png | bin | 0 -> 13313 bytes |
6 files changed, 1047 insertions, 352 deletions
diff --git a/docs/Chapter7.rst b/docs/Chapter7.rst index d10b4e0..90ca743 100644 --- a/docs/Chapter7.rst +++ b/docs/Chapter7.rst @@ -69,8 +69,6 @@ and GS NFV IFA011 V0.3.0 (2015-10) - Network Functions Virtualization * R-75608 The VNF Vendor **MUST** provide playbooks to be loaded on the appropriate Ansible Server. * R-16777 The VNF Vendor **MUST** provide a JSON file for each supported action for the VNF. The JSON file must contain key value pairs with all relevant values populated with sample data that illustrates its usage. The fields and their description are defined in Appendix B. - Note: Ansible support in ONAP is not currently available and planned for 4Q 2017. - * R-46567 The VNF Package **MUST** include configuration scripts for boot sequence and configuration. * R-16065 The VNF Vendor **MUST** provide configurable parameters (if unable to conform to YANG model) including VNF attributes/parameters and valid values, dynamic attributes and cross parameter dependencies (e.g., customer provisioning data). @@ -254,25 +252,28 @@ NETCONF RFCs. VNF REST APIs ------------- -Healthcheck is a command for which no NETCONF support exists. Therefore, -this must be supported using a RESTful interface which we have defined. +Healthcheck is a command for which no NETCONF support exists. Therefore, this must be supported using a RESTful interface (defined in this section) or +with a Chef cookbook/Ansible playbook (defined in sections `Chef Standards and Capabilities`_ and `Ansible Standards and Capabilities`_). -The VNF via APP-C must provide a REST formatted GET RPCs to support Healthcheck -queries via the GET method over HTTP(s). +HealthCheck Definition: The VNF level HealthCheck is a check over the entire scope of the VNF. +The VNF must be 100% healthy, ready to take requests and provide services, with all VNF required +capabilities ready to provide services and with all active and standby resources fully ready with +no open MINOR, MAJOR or CRITICAL alarms. NOTE: A switch may need to be turned on, but the VNF +should be ready to take service requests or be already processing service requests successfully. -The VNF via VF-C must provide REST APIs to make the configurations of -associated VNFs. +The VNF must provide a REST formatted GET RPCs to support Healthcheck queries via the GET method +over HTTP(s). The port number, url, and other authentication information is provided by the VNF vendor. **REST APIs** -* R-31809 The VNF **MUST** support the HealthCheck RPC. The HealthCheck RPC, executes a vendor-defined VNF Healthcheck over the scope of the entire VNF (e.g., if there are multiple VNFCs, then run a health check, as appropriate, for all VNFCs). It returns a 200 OK if the test completes. A JSON object is returned indicating state (healthy, unhealthy), scope identifier, time-stamp and one or more blocks containing info and fault information. If the VNF is unable to run the HealthCheck, return a standard http error code and message. +* R-31809 The VNF **MUST** support the HealthCheck RPC. The HealthCheck RPC executes a vendor-defined VNF Healthcheck over the scope of the entire VNF (e.g., if there are multiple VNFCs, then run a health check, as appropriate, for all VNFCs). It returns a 200 OK if the test completes. A JSON object is returned indicating state (healthy, unhealthy), scope identifier, time-stamp and one or more blocks containing info and fault information. If the VNF is unable to run the HealthCheck, return a standard http error code and message. Examples: -.. code-block:: python +.. code-block:: java 200 { @@ -297,16 +298,6 @@ Examples: } -**Table 5. VNF REST APIs** - -+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------+------------+ -| **Principal** | **Description** | **Type** | **ID #** | -+=================+=======================================================================================================================================================================================================================================================================================================================================================================================================+============+============+ -+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------+------------+ -| REST APIs | **/configuration** This API executes a vendor-defined VNF configuration action over the scope of the entire VNF(e.g if there are multiple VMs, then run configuration on all VMs according to the input parameters). | Must | 12200 | -| | **/configuration** returns a 201 Created if the configuration succeeds or a 4XX/5XX response if it fails. A JSON object is returned indicating the outcome of the VNF configuration including all the necessary configuration info. | | | -+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------+------------+ - Chef Standards and Capabilities ------------------------------- @@ -390,22 +381,16 @@ action request against a Chef managed VNF. unique Request Id. An example push job posted by ONAP is listed below: - { - - "command": "chef-client", - - "run\_timeout": 300, - - "nodes”: [“node1.vnf\_a.onap.com”, “node2.vnf\_a.onap.com”], - - "env": { - - “RequestId”:”8279-abcd-aksdj-19231”, - - “CallbackUrl”:”<callback>” - - }, +.. code-block:: java + { + "command": "chef-client", + "run\_timeout": 300, + "nodes”: [“node1.vnf\_a.onap.com”, “node2.vnf\_a.onap.com”], + "env": { + “RequestId”:”8279-abcd-aksdj-19231”, + “CallbackUrl”:”<callback>” + }, } 5. If CallbackCapable field in the template is not present or set to @@ -423,45 +408,102 @@ Ansible Standards and Capabilities ONAP will support configuration of VNFs via Ansible subject to the requirements and guidelines defined in this section. -Ansible allows agentless management of VMs via execution of ‘playbooks’ -over ssh. The ‘playbooks’ are a structured set of tasks which contain -all the necessary data and execution capabilities to take the necessary -action on one or more target VMs of the VNF. ONAP will utilize the -framework of an Ansible Server that will host and invoke playbooks to -manage VNFs that support Ansible. +Ansible allows agentless management of VNFs/VMs/VNFCs via execution of ‘playbooks’ +over ssh. The ‘playbooks’ are a structured set of tasks which contain all the necessary +data and execution capabilities to take the necessary action on one or more target VMs +(and/or VNFCs) of the VNF. ONAP will utilize the framework of an Ansible Server that +will host and run playbooks to manage VNFs that support Ansible. **VNF Configuration via Ansible Requirements** **Ansible Client Requirements** * R-32217 The VNF **MUST** have routable FQDNs that are reachable via the Ansible Server for the endpoints (VMs) of a VNF on which playbooks will be executed. ONAP will initiate requests to the Ansible Server for invocation of playbooks against these end points [3]_. -* R-98929 The VNF **MAY** have a single endpoint. * R-54373 The VNF **MUST** have Python >= 2.7 on the endpoint VM(s) of a VNF on which an Ansible playbook will be executed. -* R-35401 The VNF **MUST** must support SSH and allow SSH access to the Ansible server for the endpoint VM(s) and comply with the Network Cloud Service Provider guidelines for authentication and access. +* R-35401 The VNF **MUST** support SSH and allow SSH access to the Ansible server for the endpoint VM(s) and comply with the Network Cloud Service Provider guidelines for authentication and access. +* R-NNNNN The VNF **SHOULD** load the SSH key onto VNF VM(s) as part of instantiation. This will allow the Ansible Server to authenticate to perform post-instantiation configuration without manual intervention and without requiring specific VNF login IDs and passwords. + + CAUTION: For VNFs configured using Ansible, to eliminate the need for manual steps, post-instantiation and pre-configuration, to upload of SSH keys, SSH keys loaded during (heat) instantiation shall be preserved and not removed by (heat) embedded scripts. + +* R-NNNNN The VNF **MUST** include as part of post-instantiation configuration done by Ansible Playbooks the removal/update of SSH keys loaded through instantiation to support Ansible. This may include download and install of new SSH keys. +* R-NNNNN The VNF **MUST** update the Ansible Server and other entities storing and using the SSH key for authentication when the SSH key used by Ansible is regenerated/updated. **Ansible Playbook Requirements** An Ansible playbook is a collection of tasks that is executed on the Ansible server (local host) and/or the target VM (s) in order to complete the desired action. -* R-40293 The VNF **MUST** make available (or load on VNF Ansible Server) playbooks that conform to the ONAP requirement. -* R-49396 The VNF **MUST** support each VNF action by invocation of **one** playbook [4]_. The playbook will be responsible for executing all necessary tasks (as well as calling other playbooks) to complete the request. +* R-40293 The VNF **MUST** make available playbooks that conform to the ONAP requirement. +* R-49396 The VNF **MUST** support each VNF action be supported by ONAP (APPC) by invocation of **one** playbook [4]_. The playbook will be responsible for executing all necessary tasks (as well as calling other playbooks) to complete the request. * R-33280 The VNF **MUST NOT** use any instance specific parameters in a playbook. -* R-48698 The VNF **MUST** utilize information from key value pairs that will be provided by the Ansible Server as extra-vars during invocation to execute the desired VNF action. If the playbook requires files, they must also be supplied using the methodology detailed in the Ansible Server API. +* R-48698 The VNF **MUST** utilize information from key value pairs that will be provided by the Ansible Server as extra-vars during invocation to execute the desired VNF action. If the playbook requires files, they must also be supplied using the methodology detailed in the Ansible Server API. The Ansible Server will determine if a playbook invoked to execute a VNF action finished successfully or not using the “PLAY_RECAP” summary in Ansible log. The playbook will be considered to successfully finish only if the “PLAY RECAP” section at the end of playbook execution output has no unreachable hosts and no failed tasks. Otherwise, the playbook will be considered to have failed. * R-43253 The VNF **MUST** use playbooks designed to allow Ansible Server to infer failure or success based on the “PLAY_RECAP” capability. -* R-50252 The VNF **MUST** write to a specific set of text files that will be retrieved and made available by the Ansible Server If, as part of a VNF action (e.g., audit), a playbook is required to return any VNF information. +* R-50252 The VNF **MUST** write to a specific set of text files that will be retrieved and made available by the Ansible Server if, as part of a VNF action (e.g., audit), a playbook is required to return any VNF information. The text files must be written in the same directory as the one from which the playbook is being executed. A text file must be created for each host the playbook run targets/affects, with the name ‘<hostname>_results.txt’ into which any desired output from each respective VM/VNF must be written. * R-51442 The VNF **SHOULD** use playbooks that are designed to automatically ‘rollback’ to the original state in case of any errors for actions that change state of the VNF (e.g., configure). + NOTE: In case rollback at the playbook level is not supported or possible, vendor shall provide alternative locking mechanism (e.g., for a small VNF the rollback mechanism may rely on workflow to terminate and re-instantiate VNF VMs and then re-run playbook(s)). Backing up updated files also recommended to support rollback when soft rollback is feasible. + +* R-NNNNN The VNF **SHOULD NOT** use playbooks that make requests to Cloud resources e.g. Openstack (nova, neutron, glance, heat, etc.); therefore, there is no use for Cloud specific variables like Openstack UUIDs in Ansible Playbooks. + + Rationale: Flows that require interactions with Cloud services e.g. Openstack shall rely on workflows run by an Orchestrator or other capability (such as a control loop or Operations GUI) outside Ansible Server which can be executed by a Controller such as APPC. There are policies, as part of Control Loop models, that send remediation action requests to APPC; these are triggered as a response to an event or correlated events published to Event Bus. + +* R-NNNNN The VNF **SHOULD** use the Ansible backup feature to save a copy of configuration files before implementing changes to support operations such as backing out of software upgrades, configuration changes or other work as this will help backing out of configuration changes when needed. +* R-NNNNN The VNF **MUST** return control from Ansible Playbooks only after tasks are fully complete, signaling that the playbook completed all tasks. When starting services, return control only after all services are up. This is critical for workflows where the next steps are dependent on prior tasks being fully completed. + + Detailed examples: + + StopApplication Playbook – StopApplication Playbook shall return control and a completion status only after VNF application is fully stopped, all processes/services stopped. + StartApplication Playbook – StartApplication Playbook shall return control and a completion status only after all VNF application services are fully up, all processes/services started and ready to provide services. NOTE: Start Playbook should not be declared complete/done after starting one or several processes that start the other processes. + + HealthCheck Playbook: + + SUCCESS – HealthCheck success shall be returned (return code 0) by a Playbook or Cookbook only when VNF is 100% healthy, ready to take requests and provide services, with all VNF required capabilities ready to provide services and with all active and standby resources fully ready with no open MINOR, MAJOR or CRITICAL alarms. + + NOTE: In some cases, a switch may need to be turned on, but a VNF reported as healthy, should be ready to take service requests or be already processing service requests successfully. + + A successful execution of a health-check playbook shall also create one file per VNF VM, named using IP address or VM name followed by “_results.txt (<hostname>_results.txt) to indicate health-check was executed and completed successfully, example: 1xx.2yy.zzz.105_results.txt, with the following contents: + + "status”:"healthy” + + Example: + + $ cat 1xx.2yy.zzz.105_results.txt + + "status”:"healthy” + + FAILURE – A health check playbook shall return a non-zero return code in case VNF is not 100% healthy because one or more VNF application processes are stopped or not ready to take service requests or because critical or non-critical resources are not ready or because there are open MINOR, MAJOR or CRITICAL traps/alarms or because there are issues with the VNF that need attention even if they do not impact services provided by the VNF. + + A failed health-check playbook shall also create one file per VNF VM, named using Playbook Name plus IP address or VM name, followed by “_results.txt to indicate health-check was executed and found issues in the health of the VNF. This is to differentiate from failure to run health-check playbook or tasks to verify the health of the VNF, example: 1xx.2yy.zzz.105_results.txt, with the following contents: + + "status”:"unhealthy” + + Example: + + $ cat 1xx.2yy.zzz.105_results.txt + + "status”:"unhealthy” + + See `VNF REST APIs`_ for additional details on HealthCheck. + +ONAP Controller / Ansible API Usage +----------------------------------- + +This section outlines the workflow that ONAP Controller invokes when it receives an action request against an Ansible managed VNF. + + #. When ONAP Controller receives a request for an action for an AnsibleManaged VNF, it retrieves the corresponding template (based on **action** and **VNF**) from its database and sets necessary values (such as an Id, NodeList, and EnvParameters) from either information in the request or data obtained from other sources. This is referred to as the payload that is sent as a JSON object to the Ansible server. + #. The ONAP Controller sends a request to the Ansible server to execute the action. + #. The ONAP Controller polls the Ansible Server for result (success or failure). The ONAP Controllers has a timeout value which is contained in the template. If the result is not available when the timeout is reached, the ONAP Controller stops polling and returns a timeout error to the requester. The Ansible Server continues to process the request. + + ONAP Controller APIs and Behavior --------------------------------- -ONAP Controllers support the following operations which act directly -upon the VNF. Most of these utilize the NETCONF interface. There are -additional commands in use but these either act internally on Controller -itself or depend upon network cloud components for implementation. Those -actions do not put any special requirement on the VNF provider. +ONAP Controllers such as APPC expose a northbound API to clients which offer a set of commands. The following commands are expected to be supported +on all VNF’s if applicable, either directly (via the Netconf interface) or indirectly (via a Chef or Ansible server). There are additional commands +offered to northbound clients that are not listed here, as these commands either act internally on the Controller itself or depend upon network cloud +components for implementation (thus, these actions do not put any special requirement on the VNF provider). The following table summarizes how the VNF must act in response to commands from ONAP. @@ -487,17 +529,17 @@ Table 8. ONAP Controller APIs and NETCONF Commands | | | | | ConfigModify | | | +---------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Health | Executes a VNF health check and returns the result. A health check is VNF-specific. | The ONAP health check interface is defined over REST and requires the target VNF to expose a standardized HTTP(S) interface for that purpose. See Section 8.c VNF REST APIs. | +| Health | Executes a VNF health check and returns the result. A health check is VNF-specific. | This command has no existing NETCONF RPC action. It must be supported either by REST (see `VNF REST APIs`_) or using Ansible or Chef. | | | | | | Check | | | +---------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| StartApplication, | ONAP requests application to be started or stopped on the VNF or VNFC. These actions do not need to be supported if (1) the application starts automatically after Configure or if the VM’s are started and (2) the application gracefully shuts down if the VM’s are stopped. | These commands have no specific NETCONF RPC action. | +| StartApplication, | ONAP requests application to be started or stopped on the VNF. These actions do not need to be supported if (1) the application starts automatically after Configure or if the VM’s are started and (2) the application gracefully shuts down if the VM’s are stopped. | These commands have no specific NETCONF RPC action. | | | | | -| StopApplication | | They can be supported using Ansible or Chef (see Table 9 below). | +| StopApplication | | If applicable, these commands must be supported using Ansible or Chef (see Table 9 below). | +---------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| SoftwareUpload, | Upgrades the target VNF to a new version without interrupting VNF operation. | These commands have no specific NETCONF RPC action. | +| ConfigBackup, | ONAP requests the VNF configuration parameters to be backed up or restored (replacing existing configuration parameters on the VNF). | These commands have no specific NETCONF RPC action. | | | | | -| LiveUpgrade | | They can be supported using Ansible or Chef (see Table 9 below). | +| ConfigRestore | | They can be supported using Ansible or Chef (see Table 9 below). | +---------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ Table 9 lists the required Chef and Ansible support for commands from @@ -505,198 +547,105 @@ ONAP. Table 9. ONAP Controller APIs and Chef/Ansible Support -+---------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| **Action** | **Chef** | **Ansible** | -+=====================+==================================================================================================================================================================================================================================================================================================+=========================================================================================================================================================================================================================================================+ -| Action | Not needed. ActionStatus is managed internally by the ONAP controller. | Not needed. ActionStatus is managed internally by the ONAP controller. | -| | | | -| Status | | | -+---------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Audit, Sync | VNF Vendor must provide any necessary roles, cookbooks, recipes to retrieve the running configuration from a VNF and place it in the respective Node Objects ‘PushJobOutput’ attribute of all nodes in NodeList when triggered by a chef-client run. | VNF Vendor must provide an Ansible playbook to retrieve the running configuration from a VNF and place the output on the Ansible server in a manner aligned with playbook requirements listed in this document. | -| | | | -| | The JSON file for this VNF action is required to set “PushJobFlag” to “True” and “GetOutputFlag” to “True”. The “Node” JSON dictionary must have the run list populated with the necessary sequence of roles, cookbooks, recipes. | The PlaybookName must be provided in the JSON file. | -| | | | -| | The Environment and Node values should contain all appropriate configuration attributes. | NodeList must list FQDNs of an example VNF on which to execute playbook. | -| | | | -| | NodeList must list sample FQDNs that are required to conduct a chef-client run for this VNF Action. | | -+---------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Lock, | Not needed. VNF locking and unlocking is managed internally by the ONAP controller. | Not needed. VNF locking and unlocking is managed internally by the ONAP controller. | -| | | | -| Unlock, | | | -| | | | -| CheckLock | | | -+---------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Configure, | VNF Vendor must provide any necessary roles, cookbooks, recipes to apply configuration attributes to the VNF when triggered by a chef-client run. All configurable attributes must be obtained from the Environment and Node objects on the Chef Server. | VNF Vendor must provide an Ansible playbook that can configure the VNF with parameters supplied by the Ansible Server. | -| | | | -| ConfigModify | The JSON file for this VNF action should include all configurable attributes in the Environment and/or Node JSON dictionary. | The PlaybookName must be provided in the JSON file. | -| | | | -| | The “PushJobFlag” must be set to “True”. | The “EnvParameters” and/or “FileParameters” field values should be provided and contain all configurable parameters for the VNF. | -| | | | -| | The “Node” JSON dictionary must have the run list populated with necessary sequence of roles, cookbooks, recipes. This action is not expected to return an output. | NodeList must list FQDNs of an example VNF on which to execute playbook. | -| | | | -| | “GetOutputFlag” must be set to “False”. | | -| | | | -| | NodeList must list sample FQDNs that are required to conduct a chef-client run for this VNF Action. | | -+---------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Health | The ONAP health check interface is defined over REST and requires the target VNF to expose a standardized HTTP(S) interface for that purpose. See Section 8.c VNF REST APIs. | The ONAP health check interface is defined over REST and requires the target VNF to expose a standardized HTTP(S) interface for that purpose. See Section 8.c VNF REST APIs. | -| | | | -| Check | | | -+---------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| StartApplication, | VNF Vendor must provide roles, cookbooks, recipes to start an application on the VNF when triggered by a chef-client run. If application does not start, the run must fail or raise an exception. If application is already started, or starts successfully, the run must finish successfully. | VNF Vendor must provide an Ansible playbook to start the application on the VNF. If application does not start, the playbook must indicate failure. If application is already started, or starts successfully, the playbook must finish successfully. | -| | | | -| StopApplication | For StopApplication, the application must be stopped gracefully (no loss of traffic). | For StopApplication, the application must be stopped gracefully (no loss of traffic). | -+---------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| SoftwareUpload, | VNF Vendor must provide any necessary roles, cookbooks, recipes to apply a software upgrade to the VNF when triggered by a chef-client run. | VNF Vendor must provide an Ansible playbook that can apply a software upgrade to the VNF when triggered by the Ansible server | -| | | | -| LiveUpgrade | | | -+---------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ ++---------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| **Action** | **Chef** | **Ansible** | ++=====================+==================================================================================================================================================================================================================================================================================================+=============================================================================================================================================================================================================================================================================================+ +| Action | Not needed. ActionStatus is managed internally by the ONAP controller. | Not needed. ActionStatus is managed internally by the ONAP controller. | +| | | | +| Status | | | ++---------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Audit, Sync | VNF Vendor must provide any necessary roles, cookbooks, recipes to retrieve the running configuration from a VNF and place it in the respective Node Objects ‘PushJobOutput’ attribute of all nodes in NodeList when triggered by a chef-client run. | VNF Vendor must provide an Ansible playbook to retrieve the running configuration from a VNF and place the output on the Ansible server in a manner aligned with playbook requirements listed in this document. | +| | | | +| | The JSON file for this VNF action is required to set “PushJobFlag” to “True” and “GetOutputFlag” to “True”. The “Node” JSON dictionary must have the run list populated with the necessary sequence of roles, cookbooks, recipes. | The PlaybookName must be provided in the JSON file. | +| | | | +| | The Environment and Node values should contain all appropriate configuration attributes. | NodeList must list FQDNs of an example VNF on which to execute playbook. | +| | | | +| | NodeList must list sample FQDNs that are required to conduct a chef-client run for this VNF Action. | | ++---------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Lock, | Not needed. VNF locking and unlocking is managed internally by the ONAP controller. | Not needed. VNF locking and unlocking is managed internally by the ONAP controller. | +| | | | +| Unlock, | | | +| | | | +| CheckLock | | | ++---------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Configure, | VNF Vendor must provide any necessary roles, cookbooks, recipes to apply configuration attributes to the VNF when triggered by a chef-client run. All configurable attributes must be obtained from the Environment and Node objects on the Chef Server. | VNF Vendor must provide an Ansible playbook that can configure the VNF with parameters supplied by the Ansible Server. | +| | | | +| ConfigModify | The JSON file for this VNF action should include all configurable attributes in the Environment and/or Node JSON dictionary. | The PlaybookName must be provided in the JSON file. | +| | | | +| | The “PushJobFlag” must be set to “True”. | The “EnvParameters” and/or “FileParameters” field values should be provided and contain all configurable parameters for the VNF. | +| | | | +| | The “Node” JSON dictionary must have the run list populated with necessary sequence of roles, cookbooks, recipes. This action is not expected to return an output. | NodeList must list FQDNs of an example VNF on which to execute playbook. | +| | | | +| | “GetOutputFlag” must be set to “False”. | | +| | | | +| | NodeList must list sample FQDNs that are required to conduct a chef-client run for this VNF Action. | | ++---------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Health | The VNF level HealthCheck run a check over the entire scope of the VNF (for more details, see `VNF REST APIs`_). It can be supported either via a REST interface or with Chef roles, cookbooks, and recipes. | The VNF level HealthCheck run a check over the entire scope of the VNF (for more details, see `VNF REST APIs`_). It can be supported either via a REST interface or with an Ansible playbook. | +| | | | +| Check | | | ++---------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| StartApplication, | VNF Vendor must provide roles, cookbooks, recipes to start an application on the VNF when triggered by a chef-client run. If application does not start, the run must fail or raise an exception. If application is already started, or starts successfully, the run must finish successfully. | VNF Vendor must provide an Ansible playbook to start the application on the VNF. If application does not start, the playbook must indicate failure. If application is already started, or starts successfully, the playbook must finish successfully. | +| | | | +| StopApplication | For StopApplication, the application must be stopped gracefully (no loss of traffic). | For StopApplication, the application must be stopped gracefully (no loss of traffic). | ++---------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ConfigBackup, | VNF Vendor must provide roles, cookbooks, recipes to backup or restore the configuration parameters on the VNF when triggered by an ECOMP request. | VNF Vendor must provide an Ansible playbook to backup or restore the configuration parameters on the VNF when triggered by an ECOMP request. | +| | | | +| | When the ConfigBackup command is executed, the current VNF configuration parameters are copied over to the Ansible or Chef server (if there is an existing set of backed up parameters, they are overwritten). When the ConfigRestore command is executed, the VNF configuration parameters | When the ConfigBackup command is executed, the current VNF configuration parameters are copied over to the Ansible or Chef server (if there is an existing set of backed up parameters, they are overwritten). When the ConfigRestore command is executed, the VNF configuration parameters | +| ConfigRestore | which are backed up on the Ansible or Chef server are applied to the VNF (replacing existing parameters). It can be assumed that the VNF is not in service when a ConfigRestore command is executed. | which are backed up on the Ansible or Chef server are applied to the VNF (replacing existing parameters). It can be assumed that the VNF is not in service when a ConfigRestore command is executed. | +| | | | +| | If either command fails, the run must fail or raise an exception. | If either command fails, the run must fail or raise an exception. | ++---------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ For information purposes, the following ONAP controller functions are planned in the future: Table 10. Planned ONAP Controller Functions -+------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ConfigSave, | ConfigSave stores the VNF running configuration to a url or file using a specified name. ConfigRestore replaces the VNF running configuration with the configuration previously stored with a url or file with the specified name. | -| | | -| ConfigRestore | | -+==================+==================================================================================================================================================================================================================================================================================================================+ -| Reconfigure | If the audit fails, Reconfigure may be used to be replace the VNF running configuration using a previously uploaded configuration in the ONAP controller. | -+------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ConfigStartup | ConfigStartup is used to store a running configuration to be used when a VNF is rebooted. | -+------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ConfigRecovery | ConfigRecovery is used to replace the running configuration with a recovery configuration. This recovery configuration is stored in the ONAP Controller and is the configuration uploaded after instantiation. It will only be used if there is no other option to restore the VNF to a working configuration. | -+------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| StatusQuery | Executes a VNF status query and returns the result. A status query is VNF-specific. | -+------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - - ++------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Action | Description | ++==================+=================================================================================================================================================================================+ +| UpgradeSoftware | Upgrades the target VNF to a new software version. | ++------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| QuiesceTraffic, | Quiesces traffic (stops traffic gracefully) and resume traffic on the VNF. These commands do not stop the application processes (which is done using StopApplication). | +| ResumeTraffic | | ++------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + + d. Monitoring & Management =========================== -This section addresses data collection and event processing -functionality that is directly dependent on the interfaces provided by -the VNFs’ APIs. These can be in the form of asynchronous interfaces for -event, fault notifications, and autonomous data streams. They can also -be synchronous interfaces for on-demand requests to retrieve various -performance, usage, and other event information. - -The target direction for VNF interfaces is to employ APIs that are -implemented utilizing standardized messaging and modeling protocols over -standardized transports. Migrating to a virtualized environment presents -a tremendous opportunity to eliminate the need for proprietary -interfaces for vendor equipment while removing the traditional -boundaries between Network Management Systems and Element Management -Systems. Additionally, VNFs provide the ability to instrument the -networking applications by creating event records to test and monitor -end-to-end data flow through the network, similar to what physical or -virtual probes provide without the need to insert probes at various -points in the network. The VNF vendors must be able to provide the -aforementioned set of required data directly to the ONAP collection -layer using standardized interfaces. - -Additional details can be found in the `Data Collection, Analytics, and Events (DCAE) <http://onap.readthedocs.io/en/latest/submodules/dcaegen2.git/docs/index.html>`_ project documentation. - -Transports and Protocols Supporting Resource Interfaces -------------------------------------------------------- - -Delivery of data from VNFs to ONAP must use the same common transport -mechanisms and protocols for all VNFs. Transport mechanisms and -protocols have been selected to enable both high volume and moderate -volume datasets, as well as asynchronous and synchronous communications -over secure connections. The specified encoding provides -self-documenting content, so data fields can be changed as needs evolve, -while minimizing changes to data delivery. - -The term ‘Event Record’ is used throughout this document to represent -various forms instrumentation/telemetry made available by the VNF -including, faults, status events and various other types of VNF -measurements and logs. Headers received by themselves must be used as -heartbeat indicators. The common structure and delivery protocols for -other types of data will be given in future versions of this document as -we get more insight into data volumes and required processing. - -In the following guidelines, we provide options for encoding, -serialization and data delivery. Agreements between Service Providers -and VNF vendors shall determine which encoding, serialization and -delivery method to use for particular data sets. The selected methods -must be agreed to prior to the on-boarding of the VNF into ONAP design -studio. - -Monitoring & Management Requirements - -**VNF telemetry via standardized interface** - -* R-51910 The VNF **MUST** provide all telemetry (e.g., fault event records, syslog records, performance records etc.) to ONAP using the model, format and mechanisms described in this section. - -**Encoding and Serialization** - -* R-19624 The VNF **MUST** encode and serialize content delivered to ONAP using JSON (option 1). High-volume data is to be encoded and serialized using Avro, where Avro data format are described using JSON (option 2) [5]_. - - - JSON plain text format is preferred for moderate volume data sets (option 1), as JSON has the advantage of having well-understood simple processing and being human-readable without additional decoding. Examples of moderate volume data sets include the fault alarms and performance alerts, heartbeat messages, measurements used for VNF scaling and syslogs. - - Binary format using Avro is preferred for high volume data sets (option 2) such as mobility flow measurements and other high-volume streaming events (such as mobility signaling events or SIP signaling) or bulk data, as this will significantly reduce the volume of data to be transmitted. As of the date of this document, all events are reported using plain text JSON and REST. - - Avro content is self-documented, using a JSON schema. The JSON schema is delivered along with the data content (http://avro.apache.org/docs/current/ ). This means the presence and position of data fields can be recognized automatically, as well as the data format, definition and other attributes. Avro content can be serialized as JSON tagged text or as binary. In binary format, the JSON schema is included as a separate data block, so the content is not tagged, further compressing the volume. For streaming data, Avro will read the schema when the stream is established and apply the schema to the received content. - - In the future, we may consider support for other types of encoding & serialization (e.g., gRPC) based on industry demand. - -**Reporting Frequency** - -* R-98191 The VNF **MUST** vary the frequency that asynchronous data is delivered based on the content and how data may be aggregated or grouped together. For example, alarms and alerts are expected to be delivered as soon as they appear. In contrast, other content, such as performance measurements, KPIs or reported network signaling may have various ways of packaging and delivering content. Some content should be streamed immediately; or content may be monitored over a time interval, then packaged as collection of records and delivered as block; or data may be collected until a package of a certain size has been collected; or content may be summarized statistically over a time interval, or computed as a KPI, with the summary or KPI being delivered. - - - We expect the reporting frequency to be configurable depending on the virtual network function’s needs for management. For example, Service Provider may choose to vary the frequency of collection between normal and trouble-shooting scenarios. - - Decisions about the frequency of data reporting will affect the size of delivered data sets, recommended delivery method, and how the data will be interpreted by ONAP. However, this should not affect deserialization and decoding of the data, which will be guided by the accompanying JSON schema. - -**Addressing and Delivery Protocol** - -ONAP destinations can be addressed by URLs for RESTful data PUT. Future data sets may also be addressed by host name and port number for TCP streaming, or by host name and landing zone directory for SFTP transfer of bulk files. - -* R-88482 The VNF **SHOULD** use REST using HTTPS delivery of plain text JSON for moderate sized asynchronous data sets, and for high volume data sets when feasible. -* R-84879 The VNF **MUST** have the capability of maintaining a primary and backup DNS name (URL) for connecting to ONAP collectors, with the ability to switch between addresses based on conditions defined by policy such as time-outs, and buffering to store messages until they can be delivered. At its discretion, the service provider may choose to populate only one collector address for a VNF. In this case, the network will promptly resolve connectivity problems caused by a collector or network failure transparently to the VNF. -* R-81777 The VNF **MUST** be configured with initial address(es) to use at deployment time. After that the address(es) may be changed through ONAP-defined policies delivered from ONAP to the VNF using PUTs to a RESTful API, in the same way that other controls over data reporting will be controlled by policy. -* R-08312 The VNF **MAY** use other options which are expected to include - - - REST delivery of binary encoded data sets. - - TCP for high volume streaming asynchronous data sets and for other high volume data sets. TCP delivery can be used for either JSON or binary encoded data sets. - - SFTP for asynchronous bulk files, such as bulk files that contain large volumes of data collected over a long time interval or data collected across many VNFs. This is not preferred. Preferred is to reorganize the data into more frequent or more focused data sets, and deliver these by REST or TCP as appropriate. - - REST for synchronous data, using RESTCONF (e.g., for VNF state polling). - -* R-03070 The VNF **MUST**, by ONAP Policy, provide the ONAP addresses as data destinations for each VNF, and may be changed by Policy while the VNF is in operation. We expect the VNF to be capable of redirecting traffic to changed destinations with no loss of data, for example from one REST URL to another, or from one TCP host and port to another. - -**Asynchronous and Synchronous Data Delivery** - -* R-06924 The VNF **MUST** deliver asynchronous data as data becomes available, or according to the configured frequency. -* R-73285 The VNF **MUST** must encode the delivered data using JSON or Avro, addressed and delivered as described in the previous paragraphs. -* R-42140 The VNF **MUST** respond to data requests from ONAP as soon as those requests are received, as a synchronous response. -* R-34660 The VNF **MUST** use the RESTCONF/NETCONF framework used by the ONAP configuration subsystem for synchronous communication. -* R-86585 The VNF **MUST** use the YANG configuration models and RESTCONF (https://tools.ietf.org/html/draft-ietf-netconf-restconf-09#page-46). -* R-11240 The VNF **MUST** respond with content encoded in JSON, as described in the RESTCONF specification. This way the encoding of a synchronous communication will be consistent with Avro. -* R-70266 The VNF **MUST** respond to an ONAP request to deliver the current data for any of the record types defined in Section 8.d “Data Model for Event Records” by returning the requested record, populated with the current field values. (Currently the defined record types include the common header record, technology independent records such as Fault, Heartbeat, State Change, Syslog, and technology specific records such as Mobile Flow, Signaling and Voice Quality records. Additional record types will be added in the future as they are standardized and become available.) -* R-46290 The VNF **MUST** respond to an ONAP request to deliver granular data on device or subsystem status or performance, referencing the YANG configuration model for the VNF by returning the requested data elements. -* R-43327 The VNF **SHOULD** use “Modeling JSON text with YANG”, https://trac.tools.ietf.org/id/draft-lhotka-netmod-yang-json-00.html, If YANG models need to be translated to and from JSON. YANG configuration and content can be represented via JSON, consistent with Avro, as described in “Encoding and Serialization” section. - -**Security** - -* R-42366 The VNF **MUST** support secure connections and transports. -* R-44290 The VNF **MUST** control access to ONAP and to VNFs, and creation of connections, through secure credentials, log-on and exchange mechanisms. -* R-47597 The VNF **MUST** carry data in motion only over secure connections. -* R-68165 The VNF **MUST** encrypt any content containing Sensitive Personal Information (SPI) or certain proprietary data, in addition to applying the regular procedures for securing access and delivery. +This section addresses data collection and event processing functionality that is directly +dependent on the interfaces provided by the VNFs’ APIs. These can be in the form of asynchronous +interfaces for event, fault notifications, and autonomous data streams. They can also be +synchronous interfaces for on-demand requests to retrieve various performance, usage, +and other event information. + +The target direction for VNF interfaces is to employ APIs that are implemented +utilizing standardized messaging and modeling protocols over standardized transports. +Migrating to a virtualized environment presents a tremendous opportunity to eliminate +the need for proprietary interfaces for vendor equipment while removing the traditional +boundaries between Network Management Systems and Element Management Systems. Additionally, +VNFs provide the ability to instrument the networking applications by creating event +records to test and monitor end-to-end data flow through the network, similar to what +physical or virtual probes provide without the need to insert probes at various points +in the network. The VNF vendors must be able to provide the aforementioned set of required +data directly to the ONAP collection layer using standardized interfaces. Data Model for Event Records ---------------------------- -This section describes the data model for the collection of telemetry -data from VNFs by Service Providers (SPs) to manage VNF health and -runtime lifecycle. This data model is referred to as the VNF Event -Streaming (VES) specifications. While this document is focused on -specifying some of the records from the ONAP perspective, there may be -other external bodies using the same framework to specify additional -records. For example, OPNFV has a VES project [6]_ that is looking to -specify records for OpenStack’s internal telemetry to manage Application -(VNFs), physical and virtual infrastructure (compute, storage, network -devices), and virtual infrastructure managers (cloud controllers, SDN -controllers). Note that any configurable parameters for these data -records (e.g., frequency, granularity, policy-based configuration) will -be managed using the “Configuration” framework described in the prior -sections of this document. +This section describes the data model for the collection of telemetry data from VNFs +by Service Providers (SPs) to manage VNF health and runtime lifecycle. This data +model is referred to as the VNF Event Streaming (VES) specifications. While this +document is focused on specifying some of the records from the ONAP perspective, +there may be other external bodies using the same framework to specify additional +records. For example, OPNFV has a VES project that is looking to specify records +for OpenStack’s internal telemetry to manage Application (VNFs), physical and +virtual infrastructure (compute, storage, network devices), and virtual infrastructure +managers (cloud controllers, SDN controllers). Note that any configurable parameters +for these data records (e.g., frequency, granularity, policy-based configuration) +will be managed using the “Configuration” framework described in the prior sections +of this document. The Data Model consists of: @@ -704,26 +653,23 @@ The Data Model consists of: Technology Independent and Technology Specific records sections of the data model. -- Technology Independent Records: This version of the document - specifies the model for Fault, Heartbeat, State Change, Syslog, - Threshold Crossing Alerts, and VF Scaling\* (short for - measurementForVfScalingFields) records. In the future, these may be - extended to support other types of technology independent records. - Each of these records allows additional fields (name/ value pairs) - for extensibility. The vendors can use these vendor-specific - additional fields to provide additional information that may be - relevant to the managing systems. - -- Technology Specific Records: This version of the document specifies - the model for Mobile Flow records, Signaling and Voice Quality - records. In the future, these may be extended to support other types - of records (e.g., Network Fabric, Security records, etc.). Each of - these records allows additional fields (name/value pairs) for - extensibility. The VNF vendors can use these VNF-specific additional - fields to provide additional information that may be relevant to the - managing systems. A placeholder for additional technology specific - areas of interest to be defined in the future documents has been - depicted. +- Technology Independent Records: This version of the document specifies + the model for Fault, Heartbeat, State Change, Syslog, Threshold Crossing + Alerts, and VNF Scaling* (short for measurementForVfScalingFields – actual + name used in JSON specification) records. In the future, these may be + extended to support other types of technology independent records. Each + of these records allows additional fields (name/ value pairs) for extensibility. + The vendors can use these vendor-specific additional fields to provide + additional information that may be relevant to the managing systems. + +- Technology Specific Records: This version of the document specifies the model + for Mobile Flow records, Signaling and Voice Quality records. In the future, + these may be extended to support other types of records (e.g. Network Fabric, + Security records, etc.). Each of these records allows additional fields + (name/value pairs) for extensibility. The VNF vendors can use these VNF-specific + additional fields to provide additional information that may be relevant to the + managing systems. A placeholder for additional technology specific areas of + interest to be defined in the future documents has been depicted. |image0| @@ -745,112 +691,104 @@ The data structure for event records consists of: - e.g., Mobile Flow domain, Signaling domain, Voice Quality domain, etc. -Note: Heartbeat records would only have the Common Event Header block. -An optional heartbeat domain is available if required by the heartbeat -implementation. - Common Event Header ~~~~~~~~~~~~~~~~~~~~~ -The common header that precedes any of the domain-specific records -contains information identifying the type of record to follow, -information about the sender and other identifying characteristics -related to timestamp, sequence number, etc. +The common header that precedes any of the domain-specific records contains +information identifying the type of record to follow, information about +the sender and other identifying characteristics related to timestamp, +sequence number, etc. Technology Independent Records – Fault Fields ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The Fault Record, describing a condition in the Fault domain, contains -information about the fault such as the entity under fault, the +The Fault Record, describing a condition in the Fault domain, contains +information about the fault such as the entity under fault, the severity, resulting status, etc. Technology Independent Records – Heartbeat Fields ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The Heartbeat Record provides an optional structure for communicating -information about heartbeat or watchdog signaling events. It can contain -information about service intervals, status information etc. as required -by the heartbeat implementation. +The Heartbeat Record provides an optional structure for communicating +information about heartbeat or watchdog signaling events. It can +contain information about service intervals, status information etc. +as required by the heartbeat implementation. + +Note: Heartbeat records would only have the Common Event Header block. +An optional heartbeat domain is available if required by the heartbeat +implementation. Technology Independent Records – State Change Fields ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The State Change Record provides a structure for communicating -information about data flow through the VNF. It can contain information -about state change related to physical device that is reported by VNF. -As an example, when cards or port name of the entity that has changed -state. +The State Change Record provides a structure for communicating information +about data flow through the VNF. It can contain information about state +change related to physical device that is reported by VNF. As an example, +when cards or port name of the entity that has changed state. Technology Independent Records – Syslog Fields ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The Syslog Record provides a structure for communicating any type of -information that may be logged by the VNF. It can contain information +The Syslog Record provides a structure for communicating any type of +information that may be logged by the VNF. It can contain information about system internal events, status, errors, etc. Technology Independent Records – Threshold Crossing Alert Fields ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The Threshold Crossing Alert (TCA) Record provides a structure for -communicating information about threshold crossing alerts. It can -contain alert definitions and types, actions, events, timestamps and -physical or logical details. +The Threshold Crossing Alert (TCA) Record provides a structure for +communicating information about threshold crossing alerts. It can +contain alert definitions and types, actions, events, timestamps +and physical or logical details. -Technology Independent Records - VF Scaling Fields +Technology Independent Records - VNF Scaling Fields ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The VF Scaling\* (short for measurementForVfScalingFields) Record -contains information about VF and VNF resource structure and its -condition to help in the management of the resources for purposes of -elastic scaling. +The VNF Scaling\* (short for measurementForVfScalingFields – +actual name used in JSON specification) Record contains information +about VNF and VNF resource structure and its condition to help in +the management of the resources for purposes of elastic scaling. Technology Independent Records – otherFields ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The otherFields Record defines fields for events belonging to the -otherFields domain of the Technology Independent domain enumeration. -This record provides a mechanism to convey a complex set of fields -(possibly nested or opaque) and is purely intended to address -miscellaneous needs such as addressing time-to-market considerations or -other proof-of-concept evaluations. Hence, use of this record type is -discouraged and should be minimized. +The otherFields Record defines fields for events belonging to the +otherFields domain of the Technology Independent domain enumeration. +This record provides a mechanism to convey a complex set of fields +(possibly nested or opaque) and is purely intended to address +miscellaneous needs such as addressing time-to-market considerations +or other proof-of-concept evaluations. Hence, use of this record +type is discouraged and should be minimized. Technology Specific Records – Mobile Flow Fields ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The Mobile Flow Record provides a structure for communicating -information about data flow through the VNF. It can contain information -about connectivity and data flows between serving elements for mobile -service, such as between LTE reference points, etc. +The Mobile Flow Record provides a structure for communicating +information about data flow through the VNF. It can contain +information about connectivity and data flows between serving +elements for mobile service, such as between LTE reference points, etc. Technology Specific Records – Signaling Fields ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The Signaling Record provides a structure for communicating information -about signaling messages, parameters and signaling state. It can contain -information about data flows for -`signaling <https://en.wikipedia.org/wiki/Signaling_%28telecommunications%29>`__ -and controlling -`multimedia <https://en.wikipedia.org/wiki/Multimedia>`__ communication -`session <https://en.wikipedia.org/wiki/Session_%28computer_science%29>`__\ s -such as `voice <https://en.wikipedia.org/wiki/Telephone_call>`__ and -`video calls <https://en.wikipedia.org/wiki/Video_call>`__. +The Signaling Record provides a structure for communicating information +about signaling messages, parameters and signaling state. It can +contain information about data flows for signaling and controlling +multimedia communication sessions such as voice and video calls. Technology Specific Records – Voice Quality Fields ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The Voice Quality Record provides a structure for communicating -information about voice quality statistics including media connection -information, such as transmitted octet and packet counts, packet loss, -packet delay variation, round-trip delay, QoS parameters and codec -selection. +The Voice Quality Record provides a structure for communicating information +about voice quality statistics including media connection information, +such as transmitted octet and packet counts, packet loss, packet delay +variation, round-trip delay, QoS parameters and codec selection. Technology Specific Records – Future Domains ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The futureDomains Record is a placeholder for additional technology -specific areas of interest that will be defined and described in the -future documents. +The futureDomains Record is a placeholder for additional technology +specific areas of interest that will be defined and described +in the future documents. Data Structure Specification of the Event Record ------------------------------------------------ @@ -859,6 +797,211 @@ For additional information on the event record formats of the data structures mentioned above, please refer to `VES Event Listener <https://github.com/att/evel-test-collector/tree/master/docs/att_interface_definition>`__. +Transports and Protocols Supporting Resource Interfaces +------------------------------------------------------- + +Delivery of data from VNFs to ONAP must use the common transport mechanisms and protocols +for all VNFs as defined in this document. Transport mechanisms and protocols have been +selected to enable both high volume and moderate volume datasets, as well as asynchronous +and synchronous communications over secure connections. The specified encoding provides +self-documenting content, so data fields can be changed as needs evolve, while minimizing +changes to data delivery. + +The term ‘Event Record’ is used throughout this document to represent various forms of +telemetry or instrumentation made available by the VNF including, faults, status events, +various other types of VNF measurements and logs. Headers received by themselves must be +used as heartbeat indicators. Common structures and delivery protocols for other types of +data will be given in future versions of this document as we get more insight into data +volumes and required processing. + +In the following sections, we provide options for encoding, serialization and data +delivery. Agreements between Service Providers and VNF vendors shall determine which +encoding, serialization and delivery method to use for particular data sets. The selected +methods must be agreed to prior to the on-boarding of the VNF into ONAP design studio. + +VNF Telemetry using VES/JSON Model +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The preferred model for data delivery from a VNF to ONAP DCAE is the JSON driven model as depicted in Figure 2. + +|image1| + +Figure 2. VES/JSON Driven Model + +VNF vendors will provide a YAML artifact to the Service Provider that describes: + +* standard VES/JSON model information elements (key/values) that the VNF provides +* any additional non-standard (custom) VES/JSON model information elements (key/values) that the VNF provides + +Using the semantics and syntax supported by YAML, vendors will indicate specific conditions that may +arise, and recommend actions that should be taken at specific thresholds, or if specific conditions +repeat within a specified time interval. + +Based on the vendor’s recommendations, the Service Provider may create additional YAML artifacts +(using ONAP design Studio), which finalizes Service Provider engineering rules for the processing of +the vendor’s events. The Service Provider may alter the threshold levels recommended by the vendor, +and may modify and more clearly specify actions that should be taken when specified conditions arise. +The Service Provider-created version of the YAML artifact will be distributed to ONAP applications +by the Design framework. + +VNF Telemetry using YANG Model +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In addition to the JSON driven model described above, a YANG driven model can also be +supported, as depicted in Figure 3. + +|image2| + +Figure 3. YANG Driven Model + +VNF vendors will provide to the Service Provider the following YANG model artifacts: + +* common IETF YANG modules that support the VNF +* native (vendor-supplied) YANG modules that support the VNF +* open (OpenConfig) YANG modules and the following configuration-related information, including: + + * telemetry configuration and operational state data; such as: + + * sensor paths + * subscription bindings + * path destinations + * delivery frequency + * transport mechanisms + * data encodings + +* a YAML artifact that provides all necessary mapping relationships between YANG model data types to VES/JSON information elements +* YANG helper or decoder functions that automate the conversion between YANG model data types to VES/JSON information elements +* OPTIONAL: YANG Telemetry modules in JSON format per RFC 7951 + +Using the semantics and syntax supported by YANG, vendors will indicate specific conditions that may +arise, and recommend actions that should be taken at specific thresholds, or if specific conditions +repeat within a specified time interval. + +Based on the vendor’s recommendations, the Service Provider may create additional YAML artifacts +(using ONAP design Studio), which finalizes Service Provider engineering rules for the processing +of the vendor’s events. The Service Provider may alter the threshold levels recommended by the +vendor, and may modify and more clearly specify actions that should be taken when specified +conditions arise. The Service Provided-created version of the YAML will be distributed to ONAP +applications by the Design framework. + +Note: While supporting the YANG model described above, we are still leveraging the VES JSON +based model in DCAE. The purpose of the diagram above is to illustrate the concept only and +not to imply a specific implementation. + +VNF Telemetry using Google Protocol Buffers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In addition to the data delivery models described above, support for delivery of VNF telemetry +using Google Protocol Buffers (GPB) can also be supported, as depicted in Figure 4. + +VNF vendors will provide to the Service Provider the additional following artifacts to +support the delivery of VNF telemetry to DCAE via the open-source gRPC mechanism using +Google's Protocol Buffers: + +* the YANG model artifacts described in support of the "VNF Telemetry using YANG Model" +* valid definition file(s) for all GPB / KV-GPB encoded messages +* valid definition file(s) for all gRPC services +* gRPC method parameters and return types specified as Protocol Buffers messages + +|image3| + +Figure 4. Protocol Buffers Driven Model + +Note: if Google Protocol Buffers are employed for delivery of VNF telemetry, Key-Value +Google Protocol Buffers (KV-GPB) is the preferred serialization method. Details of +specifications and versioning corresponding to a release can be found +at: `VES Event Listener <https://github.com/att/evel-test-collector/tree/master/docs/att_interface_definition>`__. + +Note: While supporting the VNF telemetry delivery approach described above, we are +still leveraging the VES JSON based model in DCAE. The purpose of the diagram above +is to illustrate the concept only and not to imply a specific implementation. + +Monitoring & Management Requirements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**VNF telemetry via standardized interface** + +* R-51910 The VNF **MUST** provide all telemetry (e.g., fault event records, syslog records, performance records etc.) to ONAP using the model, format and mechanisms described in this section. + +**Encoding and Serialization** + +Content delivered from VNFs to ONAP is to be encoded and serialized using JSON: + +**JSON** + +* R-19624 The VNF **MUST** encode and serialize content delivered to ONAP using JSON (RFC 7159) plain text format. High-volume data + is to be encoded and serialized using `Avro <http://avro.apache.org/>`_, where the Avro [5]_ data format are described using JSON. + + - JSON plain text format is preferred for moderate volume data sets (option 1), as JSON has the advantage of having well-understood simple processing and being human-readable without additional decoding. Examples of moderate volume data sets include the fault alarms and performance alerts, heartbeat messages, measurements used for VNF scaling and syslogs. + - Binary format using Avro is preferred for high volume data sets (option 2) such as mobility flow measurements and other high-volume streaming events (such as mobility signaling events or SIP signaling) or bulk data, as this will significantly reduce the volume of data to be transmitted. As of the date of this document, all events are reported using plain text JSON and REST. + - Avro content is self-documented, using a JSON schema. The JSON schema is delivered along with the data content (http://avro.apache.org/docs/current/ ). This means the presence and position of data fields can be recognized automatically, as well as the data format, definition and other attributes. Avro content can be serialized as JSON tagged text or as binary. In binary format, the JSON schema is included as a separate data block, so the content is not tagged, further compressing the volume. For streaming data, Avro will read the schema when the stream is established and apply the schema to the received content. + +In addition to the preferred method (JSON), content can be delivered from VNFs to ONAP can be encoded and serialized using Google Protocol Buffers (GPB). + +**KV-GPB/GPB** + +Telemetry data delivered using Google Protocol Buffers v3 (proto3) can be serialized in one of the following methods: + +* Key-value Google Protocol Buffers (KV-GPB) is also known as self-describing GPB: + + * keys are strings that correspond to the path of the system resources for the VNF being monitored. + * values correspond to integers or strings that identify the operational state of the VNF resource, such a statistics counters and the state of a VNF resource. + +* VNF vendors must supply valid KV-GPB definition file(s) to allow for the decoding of all KV-GPB encoded telemetry messages. + +* Native Google Protocol Buffers (GPB) is also known as compact GPB: + + * keys are represented as integers pointing to the system resources for the VNF being monitored. + * values correspond to integers or strings that identify the operational state of the VNF resource, such a statistics counters and the state of a VNF resource. + +* Google Protocol Buffers (GPB) requires metadata in the form of .proto files. VNF vendors must supply the necessary GPB .proto files such that GPB telemetry messages can be encoded and decoded. + +* In the future, we may consider support for other types of encoding & serialization methods based on industry demand + + +**Reporting Frequency** + +* R-98191 The VNF **MUST** vary the frequency that asynchronous data is delivered based on the content and how data may be aggregated or grouped together. For example, alarms and alerts are expected to be delivered as soon as they appear. In contrast, other content, such as performance measurements, KPIs or reported network signaling may have various ways of packaging and delivering content. Some content should be streamed immediately; or content may be monitored over a time interval, then packaged as collection of records and delivered as block; or data may be collected until a package of a certain size has been collected; or content may be summarized statistically over a time interval, or computed as a KPI, with the summary or KPI being delivered. + + - We expect the reporting frequency to be configurable depending on the virtual network function’s needs for management. For example, Service Provider may choose to vary the frequency of collection between normal and trouble-shooting scenarios. + - Decisions about the frequency of data reporting will affect the size of delivered data sets, recommended delivery method, and how the data will be interpreted by ONAP. These considerations should not affect deserialization and decoding of the data, which will be guided by the accompanying JSON schema or GPB definition files. + +**Addressing and Delivery Protocol** + +ONAP destinations can be addressed by URLs for RESTful data PUT. Future data sets may also be addressed by host name and port number for TCP streaming, or by host name and landing zone directory for SFTP transfer of bulk files. + +* R-88482 The VNF **SHOULD** use REST using HTTPS delivery of plain text JSON for moderate sized asynchronous data sets, and for high volume data sets when feasible. +* R-84879 The VNF **MUST** have the capability of maintaining a primary and backup DNS name (URL) for connecting to ONAP collectors, with the ability to switch between addresses based on conditions defined by policy such as time-outs, and buffering to store messages until they can be delivered. At its discretion, the service provider may choose to populate only one collector address for a VNF. In this case, the network will promptly resolve connectivity problems caused by a collector or network failure transparently to the VNF. +* R-81777 The VNF **MUST** be configured with initial address(es) to use at deployment time. Subsequently, address(es) may be changed through ONAP-defined policies delivered from ONAP to the VNF using PUTs to a RESTful API, in the same manner that other controls over data reporting will be controlled by policy. +* R-08312 The VNF **MAY** use other options which are expected to include + + - REST delivery of binary encoded data sets. + - TCP for high volume streaming asynchronous data sets and for other high volume data sets. TCP delivery can be used for either JSON or binary encoded data sets. + - SFTP for asynchronous bulk files, such as bulk files that contain large volumes of data collected over a long time interval or data collected across many VNFs. This is not preferred. Preferred is to reorganize the data into more frequent or more focused data sets, and deliver these by REST or TCP as appropriate. + - REST for synchronous data, using RESTCONF (e.g., for VNF state polling). + +* R-03070 The VNF **MUST**, by ONAP Policy, provide the ONAP addresses as data destinations for each VNF, and may be changed by Policy while the VNF is in operation. We expect the VNF to be capable of redirecting traffic to changed destinations with no loss of data, for example from one REST URL to another, or from one TCP host and port to another. + +**Asynchronous and Synchronous Data Delivery** + +* R-06924 The VNF **MUST** deliver asynchronous data as data becomes available, or according to the configured frequency. +* R-73285 The VNF **MUST** must encode, address and deliver the data as described in the previous paragraphs. +* R-42140 The VNF **MUST** respond to data requests from ONAP as soon as those requests are received, as a synchronous response. +* R-34660 The VNF **MUST** use the RESTCONF/NETCONF framework used by the ONAP configuration subsystem for synchronous communication. +* R-86585 The VNF **MUST** use the YANG configuration models and RESTCONF [RFC8040] (https://tools.ietf.org/html/rfc8040). +* R-11240 The VNF **MUST** respond with content encoded in JSON, as described in the RESTCONF specification. This way the encoding of a synchronous communication will be consistent with Avro. +* R-70266 The VNF **MUST** respond to an ONAP request to deliver the current data for any of the record types defined in `Event Records - Data Structure Description`_ by returning the requested record, populated with the current field values. (Currently the defined record types include fault fields, mobile flow fields, measurements for VNF scaling fields, and syslog fields. Other record types will be added in the future as they become standardized and are made available.) +* R-46290 The VNF **MUST** respond to an ONAP request to deliver granular data on device or subsystem status or performance, referencing the YANG configuration model for the VNF by returning the requested data elements. +* R-43327 The VNF **SHOULD** use `Modeling JSON text with YANG <https://tools.ietf.org/html/rfc7951>`_, If YANG models need to be translated to and from JSON{RFC7951]. YANG configuration and content can be represented via JSON, consistent with Avro, as described in “Encoding and Serialization” section. + +**Security** + +* R-42366 The VNF **MUST** support secure connections and transports such as Transport Layer Security (TLS) protocol [`RFC5246 <https://tools.ietf.org/html/rfc5246>`_] and should adhere to the best current practices outlined in `RFC7525 <https://tools.ietf.org/html/rfc7525>`_. +* R-44290 The VNF **MUST** control access to ONAP and to VNFs, and creation of connections, through secure credentials, log-on and exchange mechanisms. +* R-47597 The VNF **MUST** carry data in motion only over secure connections. +* R-68165 The VNF **MUST** encrypt any content containing Sensitive Personal Information (SPI) or certain proprietary data, in addition to applying the regular procedures for securing access and delivery. + + .. [1] https://github.com/mbj4668/pyang @@ -883,3 +1026,16 @@ Listener <https://github.com/att/evel-test-collector/tree/master/docs/att_interf .. |image0| image:: Data_Model_For_Event_Records.png :width: 7in :height: 8in + + +.. |image1| image:: VES_JSON_Driven_Model.png + :width: 5in + :height: 3in + +.. |image2| image:: YANG_Driven_Model.png + :width: 5in + :height: 3in + +.. |image3| image:: Protocol_Buffers_Driven_Model.png + :width: 4.74in + :height: 3.3in
\ No newline at end of file diff --git a/docs/Chapter8.rst b/docs/Chapter8.rst index 4ce9895..19bb026 100644 --- a/docs/Chapter8.rst +++ b/docs/Chapter8.rst @@ -30,73 +30,42 @@ Table A1. Chef JSON File key value description Chef Template example: -“Environment”:{ +.. code-block:: chef + “Environment”:{ "name": "HAR", - "description": "VNF Chef environment for HAR", - "json\_class": "Chef::Environment", - "chef\_type": "environment", - "default\_attributes": { }, - "override\_attributes": { - “Retry\_Time”:”50”, - “MemCache”: “1024”, - “Database\_IP”:”10.10.1.5” - }, - -} - -} - -“Node”: { - + } + } + “Node”: { “name” : “signal.network.com “ - "chef\_type": "node", - "json\_class": "Chef::Node", - "attributes": { - “IPAddress1”: “192.168.1.2”, - “IPAddress2”:”135.16.162.5”, - “MyRole”:”BE” - }, - "override": {}, - "default": {}, - “normal”:{}, - “automatic”:{}, - “chef\_environment” : “\_default” - "run\_list": [ "configure\_signal" ] - }, - “NodeList”:[“node1.vnf\_a.onap.com”, “node2.vnf\_a.onap.com”], - “PushJobFlag”: “True” - “CallbackCapable”:True - “GetOutputFlag” : “False” - -} + } The example JSON file provided by the vendor for each VNF action will be turned into a template by ONAP, that can be updated with instance @@ -1324,6 +1293,576 @@ R-49945: The VNF **MUST** authorize vendor access through a client application A R-20912: The VNF **MUST** support alternative monitoring capabilities when VNFs do not expose data or control traffic or use proprietary and optimized protocols for inter VNF communication. +e. - Ansible Playbook Examples +============================== + +The following sections contain examples of Ansible playbook contents +which follow the guidelines. + +Guidelines for Playbooks to properly integrate with APPC +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +NOTE: To support concurrent requests to multiple VNF instances of same +or different type, VNF hosts and other files with VNF specific default +values are kept or created in separate directories. + +Example of an Ansible command (after pwd) to run playbook again +vfdb9904v VNF instance: + +.. code-block:: none + + $ pwd + /storage/vfdb/V16.1/ansible/configure + $ ansible-playbook -i ../inventory/vfdb9904v/hosts site.yml --extra-vars "vnf_instance=vfdb9904v" + +Example of corresponding APPC API Call from ONAP – Ansible Server +Specifications: + +An example POST for requesting execution of configure Playbook: + +.. code-block:: none + + {"Id": "10", "PlaybookName": + "/storage/vfdb/latest/ansible/configure/site.yml", "NodeList": + ["vfdb9904v"], "Timeout": 60, "EnvParameters": {"Retry": 3, "Wait": 5}, + "LocalParameters": {"vfdb9904v": {"T_true": 10, "T_false": 5, + "T_nfo": 5}}} + +Comments: + +- An ID number is assigned to each request. This ID number is used to + track request down to completion and provide status to APPC when + requested. + +- Playbook Name provided in the request (full path in this case) + +- Playbook path (in this example provided as part of playbook name as + full path) or, later in a separate variable, playbook root directory + needs to be part of APPC template. + +Ansible Playbooks will use the VNF instance name (passed using +--extra-vars "vnf\_instance=vfdb9904v") to identify other default values +to run the playbook(s) against the target VNF instance. Same example as +above: + +.. code-block:: none + + $ ansible-playbook -i ../inventory/vfdb9904v/hosts site.yml --extra-vars "vnf_instance=vfdb9904v" + +SSH key info (name/path), used to authenticate with the VNF VMs, is one +of the attributes stored in the Ansible Server inventory hosts file for +the VNF instance and later will be passed down by APPC, in the inventory +hosts file, to the Ansible Server as part of the request. Here hosts +file to run ansible-playbook listed in this example above (IP addresses +were scrubbed): + +.. code-block:: none + + $ more ../inventory/vfdb9904v/hosts + [host] + localhost ansible_connection=local + + [oam] + 1xx.2yy.zzz.109 ansible_ssh_private_key_file=/storage/.ssh/Kilo-SSH-Key.pem + 1xx.2yy.zzz.110 ansible_ssh_private_key_file=/storage/.ssh/Kilo-SSH-Key.pem + + [rdb] + 1xx.2yy.zzz.105 ansible_ssh_private_key_file=/storage/.ssh/Kilo-SSH-Key.pem + 1xx.2yy.zzz.106 ansible_ssh_private_key_file=/storage/.ssh/Kilo-SSH-Key.pem + +NOTE: APPC requests to run Playbooks/Cookbooks are specific to a VNF, +but could be more limited to one VM or one type of VM by the request +parameters. Actions that may impact a site (LCP), a service, or an +entire platform must be orchestrated by MSO in order to execute requests +via APPC which then invoke VNF level playbooks. Playbooks that impact +more than a single VNF are not the current focus of these guidelines. + +And here the scrubbed default arguments for this VNF instance: + +.. code-block:: none + + vnf_instance=vfdb9904v + + $ more ../vars/vfdb9904v/default_args.yml + vnf_provider_network_network: d69fea03-xxx-yyy-zzz-nnnnnnnnnnnn + vnf_provider_network_subnet: a07f6a3d-xxxx-yyy-zzz-ssssssssssss + vm_config_oam_vnfc_name: vfdb9904vm001oam001 + vm_config_oam_hostname: vfdb9904vm001 + vm_config_oam_provider_ip_address: 1xx.2yy.zzz.109 + … + +IMPORTANT: The APPC and default file attribute name for +vm\_config\_oam\_vnfc\_name, as an example, is derived from vm\_config +array structure (list) in the CSAR package ENV file, with dots replaced +by underscore: + +.. code-block:: none + + vm_config: + + oam: {vnfc_name: {{ vm_config_oam_vnfc_name }}, hostname: {{ + vm_config_oam_hostname }}, provider_ip_address: {{ + vm_config_oam_provider_ip_address } + + }, + + … + +Parameters like VNF names, VNFC names, OA&M IP addresses, after +February, 2018 ONAP release, will be extracted from A&AI by APPC and +then passed down to Ansible Server, as part of APPC request through REST +API. In the meantime, these VNF instance specific required values, will +be stored on VNF instance directory, default arguments file and will be +used as defaults. For parameterized playbooks attribute-value pairs +passed down by APPC to Ansible Server always take precedence over +template or VNF instance specific defaults stored in defaults file(s). + +.. code-block:: none + + $ pwd + /storage/vfdb/latest/ansible + + $ more vars/vfdb9904v/default_args.yml + + vm_config_oam1_vnfc_name: vfdb9904vm001oam001 + vm_config_oam1_hostname: vfdb9904vm001 + vm_config_oam1_provider_ip_address: 1xx.2yy.zzz.109 + + vm_config_oam2_vnfc_name: vfdb9904vm002oam001 + vm_config_oam2_hostname: vfdb9904vm002 + vm_config_oam2_provider_ip_address: 1xx.2yy.zzz.110 + + vm_config_rdb1_vnfc_name: vfdb9904vm003rdb001 + vm_config_rdb1_hostname: vfdb9904vm003 + vm_config_rdb1_provider_ip_address: 1xx.2yy.zzz.105 + + vm_config_rdb2_vnfc_name: vfdb9904vm004rdb001 + vm_config_rdb2_hostname: vfdb9904vm004 + vm_config_rdb2_provider_ip_address: 1xx.2yy.zzz.106 + + vm_config_rdb3_vnfc_name: vfdb9904vm005rdb001 + vm_config_rdb3_hostname: vfdb9904vm005 + vm_config_rdb3_provider_ip_address: 1xx.2yy.zzz.xxx + + vm_config_rdb4_vnfc_name: vfdb9904vm006rdb001 + vm_config_rdb4_hostname: vfdb9904vm006 + vm_config_rdb4_provider_ip_address: 1xx.2yy.zzz.yyy + +One of the first tasks on the Ansible Playbooks is to combine the VNF +type generic template, derived from ENV files in CSAR or other files, +with these default values stored on the Ansible Server, together with +the overriding parameters passed down from APPC, to create the VNF +instance specific set of attribute-value pairs to be used for the run in +YAML format. Here is an excerpt from such a file that should look +somewhat similar to ENV files: + +.. code-block:: none + + $ more tmp/vfdb9904v/all.yml + + deployment_prefix: vfdb9904v + vm_config: + oam1: { vnfc_name: vfdb9904vm001oam001, hostname: vfdb9904vm001, provider_ip_address: 1xx.2yy.zzz.109, private_ip_address: 192.168.10.107 } + oam2: { vnfc_name: vfdb9904vm002oam001, hostname: vfdb9904vm002, provider_ip_address: 1xx.2yy.zzz.110, private_ip_address: 192.168.10.108 } + rdb1: { vnfc_name: vfdb9904vm003rdb001, hostname: vfdb9904vm003, provider_ip_address: 1xx.2yy.zzz.105, private_ip_address: 192.168.10.109 } + rdb2: { vnfc_name: vfdb9904vm004rdb001, hostname: vfdb9904vm004, provider_ip_address: 1xx.2yy.zzz.106, private_ip_address: 192.168.10.110 } + rdb3: { vnfc_name: vfdb9904vm005rdb001, hostname: vfdb9904vm005, provider_ip_address: 1xx.2yy.zzz.xxx, private_ip_address: 192.168.10.111 } + rdb4: { vnfc_name: vfdb9904vm006rdb001, hostname: vfdb9904vm006, provider_ip_address: 1xx.2yy.zzz.yyy, private_ip_address: 192.168.10.112 } + … + timezone: Etc/UTC + … + template_version: '2014-10-16' + stack_name: vfdb9904v + key_name: ONAPkilo-keypair + c3dbtype: OAM + stackName: vfdb9904v + juno_base: true + … + +# logins list contain 'login name', 'login group', 'login password' + +.. code-block:: none + + logins: + - { name: 'm99999', group: 'm99999', password: 'abcdefgha' } + - { name: 'gsuser', group: 'gsuser', password: ' abcdefgha' } + - { name: 'peruser', group: 'peruser', password: ' abcdefgha' } + - { name: 'dbuser', group: 'dbuser', password: ' abcdefgha' } + +NOTE: Arguments passed by APPC to Ansible Server to run a playbook take +precedence over any defaults stored in Ansible Server. + +Ansible Playbooks – Notes On Artifacts Required to Run Playbooks +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Inventory hosts file: should be VNF instance specific. + +Default variables: should be VNF instance specific/ + +NOTE: Some playbooks may rely on inventory directory contents to target +the collection of VNFs in the Services Platform supported through +Ansible. + +Playbooks and paths to referenced files: Playbooks shall not use +absolute paths for file include entries (variables or playbooks) or +other types of references. + +For this to work properly when running playbooks, the directory where +the playbook resides shall be the current directory. + +Playbook includes use paths relative to the main playbook directory when +necessary. + +Root directory named ansible - Any files provided with playbooks, +included or referenced by playbooks, shall reside under the ansible +playbooks (root) directory, containing all playbook subdirectories, or +below that ansible root directory, in other subdirectories to support +on-boarding and portability of VNF collection of playbooks and related +artifacts. + +Designing for a shared environment, concurrently running playbooks, +targeting multiple VNF instances – inventory hosts file: + +To avoid inventory hosts file overwrites or collisions between multiple +concurrently running VNF instance requests, chosen approach is for each +VNF instance hosts file, to be stored under the Ansible Server Playbooks +root directory, under the inventory subdirectory, and under a directory +for each VNF instance, named after the VNF instance, as follows: + +ansible/inventory/<VNF\_instance\_name>/hosts + +Example of inventory hosts file path, relative to ansible playbooks root +directory (playbooks\_dir): ansible/inventory/vnfx0001v/hosts + +Designing for a shared environment, concurrently running playbooks, +targeting multiple VNF instances – default argument variables for +specific VNF instances: + +Files containing attribute name value pairs (variable name and default +values), referenced/included by playbooks – Files containing VNF +instance specific default values – in a later APPC release, some or all +the default attribute value pairs contained in the defaults file, may be +passed down by APPC, to the Ansible Server, overriding these defaults: + +Following the same approach for inventory hosts files, files +referenced/included by playbooks containing default values, +default\_args.yml, shall be stored under a directory with VNF instance +name on the path. + +Example: + +ansible/vars/<VNF\_instance\_name>/default\_args.yml + +Files containing attribute name value pairs (variable name and default +values), referenced/included by playbooks – created dynamically by +playbooks: + +Following the same approach for inventory hosts files, to avoid +overwrites or collisions of multiple concurrently running VNF instance +requests, files created dynamically by playbooks, based on VNF generic +templates, combined with default values and arguments passed down by +APPC (as part of the request), shall be stored under a directory with +VNF instance name on the path. + +Example: + +tmp/<VNF\_instance\_name>/all.yml + +Files containing site specific (Openstack location non-instance +specific) attribute name value pairs, like NTP server and DNS server’s +IP addresses and other parameters, referenced/included by playbooks, not +VNF specific – Could/should be stored under vars directory, in a +subdirectory named after the string used to identify the site (nyc1, +lax2,…). + +Examples: + +ansible/vars/<Site>/default\_args.yml + +ansible/vars/nyc1/default\_args.yml + +ansible/vars/lax2/default\_args.yml + +\ **Ansible Server Design - Directory Structure** + +To help understanding the contents of this section, here are few basic +definitions: + +**VNF type a.k.a VNF Function Code** - Based on current Services +Platform naming convention, each Virtual Network Function is assigned a +4 character string (example vfdb), they are the first 4 characters on +the VNF instance name, which is 9 characters long. VNF instance name in +some cases corresponds to the stack name for the VNF when VNF instance +is built based on a single module, single stack. Example of VNF instance +name: vfdb9904v. All VNF performing this function, running the same +software, coming from the same vendor will start with the same 4 +characters, in this example, vfdb. + +VNF type, determined through these 4 characters, is also known as VNF +Function Code and is assigned by inventory team. All Services Platform +VNF Function Codes can be found in inventory database and/or A&AI as +well as Services Platform Network Design Documents. + +NOTE: Current Services Platform naming convention is undergoing changes +to include geographical location to the VNF names. + +Version – As in VNF software version is the release of the software +running on the VNF for which the playbooks were developed. VNF +configuration steps may change from release to release and this +<Version> in the path will allow the Ansible Server to host playbooks +associated with each software release. And run the playbooks that match +the software release running on each VNF instance. APPC initially will +not support playbook versioning only latest playbook is supported. + +Playbook Function - Is a name associated with a life cycle management +task(s) performed by the playbook(s) stored in this directory. It should +clearly identify the type of action(s) performed by the main playbook +and possibly other playbooks stored in this same directory. Ideally, +playbook function would match APPC corresponding function that executes +the main playbook in this directory. Following Ansible Naming standards +main playbook is usually named site.yml. There can be other playbooks on +the same directory that use a subset of the roles used by the main +playbook site.yml. Examples of Playbook Function directory names: + +- configure – Contains post-instantiation (bulk) configuration + playbooks, roles,… + +- healthcheck – Contains VNF health check playbook(s), roles,… + +- stop – Contains VNF application stop playbook(s), roles,… + +- start – Contains VNF application start playbook(s), roles,… + +Directory structure to allow hosting multiple version sets of playbooks, +for the same VNF type, to be hosted in the runtime environment on the +Ansible Servers. Generic directory structure: + +Ansible Playbooks – Function directory and main playbook: + +.. code-block:: none + + /storage/<VNF type>/<Version>/ansible/<Playbook Function>/site.yml + +Example – Post-instantiation (bulk) configuration –APPC Function - +Configure: + +.. code-block:: none + + /storage/<VNF type>/<Version>/ansible/configure/site.yml + +Example – Health-check –APPC Function - HealthCheck: + +.. code-block:: none + + /storage/<VNF type>/<Version>/ansible/healthcheck/site.yml + +OR (Function directory name does not need to match APPC function name) + +.. code-block:: none + + /storage/<VNF type>/<Version>/ansible/check/site.yml + +Ansible Directories for other artifacts – VNF inventory hosts file - +Required: + +.. code-block:: none + + /storage/<VNF type>/<Version>/ansible/inventory/<VNF instance name>/hosts + +Ansible Directories for other artifacts – VNF inventory hosts file – +Required: + +.. code-block:: none + + /storage/<VNF type>/<Version>/ansible/vars/<VNF instance name>/default\_args.yml + +NOTE: This requirement is expected to be deprecated in part in the +future, for automated actions, once APPC can pass down all VNF specific +arguments for each action. Requirement remains while manual actions are +to be supported. Other automated inventory management mechanisms may be +considered in the future, Ansible supports many automated inventory +management mechanisms/tools/solutions. + +Ansible Directories for other artifacts – VNF (special) groups – +Optional: + +.. code-block:: none + + /storage/<VNF type>/<Version>/ansible/groups/<VNF instance name>/common\_groups.yml + +NOTE: Default groups will be created based on VNFC type, 3 characters, +on VNFC name. Example: “oam”, “rdb”, “dbs”, “man”, “iox”, “app”,… + +Ansible Directories for other artifacts – VNF (special) other files – +Optional – Example – License file: + +.. code-block:: none + + /storage/<VNF type>/<Version>/ansible/<Other directory(s)> + +CAUTION: On referenced files used/required by playbooks. + +- To avoid missing files, during on-boarding or uploading of Ansible + Playbooks and related artifacts, all permanent files (not generated + by playbooks as part of execution), required to run any playbook, + shall reside under the ansible root directory or below on other + subdirectories. + +- Any references to files, on includes or other playbook entries, shall + use relative paths. + +- This is the ansible (root directory) directory referenced on this + note: + +.. code-block:: none + + /storage/<VNF type>/<Version>/ansible/ + +There will be a soft link to the latest set of Ansible Playbooks for +each VNF type and this is the default set of playbooks that are executed +unless a different release is specified in APPC request. + +VNF type directories use A&AI inventory VNF function code. Ansible +Playbooks will be stored on a Cinder Volume mounted on the Ansible +Servers as /storage. Example: + +/storage/vfdb/latest/ansible – This soft link point to the latest set of +playbooks (or the only set) + +/storage/vfdb/V16.1/ansible – Root directory for database VNF Ansible +Playbooks for release 16.1 + +CAUTION: To support this directory structure as the repository to store +Ansible Playbooks run by APPC, APPC API in the Ansible Server side needs +to be configured to run playbooks from directory, not MySQL database. + +Ansible Server HTTP will be configured to support APPC REST API requests +to run playbooks as needed, against specific VNF instances, or specific +VM(s) as specified in the request. + +ONAP APPC REST API to Ansible Server is documented separately and can be +found under ONAP (onap.org). + +\ **Ansible Server – On-boarding Ansible Playbooks ** + +Once playbooks are developed following the guidelines listed in prior +section(s), playbooks need to be on-boarded onto Ansible Server(s). In +the future, they’ll be on-boarded and distributed through ONAP, at least +that is the proposed plan, but for now they need to be uploaded +manually. + +These are the basic steps to on-board playbooks manually onto the +Ansible Server. + +1. Upload CSAR, zip, or tar file containing VNF playbooks and related + artifacts. + +2. Create full directory (using –p option below) to store Ansible + Playbooks and other artifacts under /storage file system. + + a. Includes VNF type using VNF function code 4 characters under + /storage. + + b. Includes VNF “Version” directory as part of the path to store + playbooks for this VNF version. + + c. Include generic ansible root directory. Creating full directory + path as an example: + +.. code-block:: none + + $ mkdir –p /storage/vfdb/V16.1/ansible**/** + +3. Make this directory (VNF ansible root directory) current directory + for next few steps: + +.. code-block:: none + + cd /storage/vfdb/V16.1/ansible/ + +4. Extract Ansible Playbooks and other Ansible artifacts associated with + the playbooks onto the ansible directory. Command depends on the type + of file uploaded, examples would be: + +.. code-block:: none + + tar xvf .. + unzip … + bunzip .. + +5. Create directory for VNF (VMs) inventory hosts file with all VMs and + OA&M IP addresses for all VNF instances with known OA&M IP addresses + for respective VMs, example: + +.. code-block:: none + + $ mkdir –p inventory/vfdb9904v + + $ touch inventory/vfdb9904v/hosts + + $ cat inventory/vfdb9904v/hosts + + [host] + localhost ansible\_connection=local + + [oam] + 1xx.2yy.zzz.109 ansible\_ssh\_private\_key\_file=/storage/.ssh/Kilo-SSH-Key.pem + 1xx.2yy.zzz.110 ansible\_ssh\_private\_key\_file=/storage/.ssh/Kilo-SSH-Key.pem + + [rdb] + 1xx.2yy.zzz.105 ansible\_ssh\_private\_key\_file=/storage/.ssh/Kilo-SSH-Key.pem + 1xx.2yy.zzz.106 ansible\_ssh\_private\_key\_file=/storage/.ssh/Kilo-SSH-Key.pem + +6. Create directory to hold default arguments for each VNF instance, + example: + +.. code-block:: none + + $ mkdir –p vars/vfdb9904v + $ touch vars/vfdb9904v/default\_args.yml + $ cat vars/vfdb9904v/default\_args.yml + vm\_config\_oam1\_vnfc\_name: vfdb9904vm001oam001 + vm\_config\_oam1\_hostname: vfdb9904vm001 + vm\_config\_oam1\_provider\_ip\_address: 1xx.2yy.zzz.109 + + vm\_config\_oam2\_vnfc\_name: vfdb9904vm002oam001 + vm\_config\_oam2\_hostname: vfdb9904vm002 + vm\_config\_oam2\_provider\_ip\_address: 1xx.2yy.zzz.110 + + vm\_config\_rdb1\_vnfc\_name: vfdb9904vm003rdb001 + vm\_config\_rdb1\_hostname: vfdb9904vm003 + vm\_config\_rdb1\_provider\_ip\_address: 1xx.2yy.zzz.105 + + vm\_config\_rdb2\_vnfc\_name: vfdb9904vm004rdb001 + vm\_config\_rdb2\_hostname: vfdb9904vm004 + vm\_config\_rdb2\_provider\_ip\_address: 1xx.2yy.zzz.106 + + vm\_config\_rdb3\_vnfc\_name: vfdb9904vm005rdb001 + vm\_config\_rdb3\_hostname: vfdb9904vm005 + vm\_config\_rdb3\_provider\_ip\_address: 1xx.2yy.zzz.xxx + + vm\_config\_rdb4\_vnfc\_name: vfdb9904vm006rdb001 + vm\_config\_rdb4\_hostname: vfdb9904vm006 + vm\_config\_rdb4\_provider\_ip\_address: 1xx.2yy.zzz.yyy + +NOTE: Please note names in this file shall use underscore “\_” not dots +“.” or dashes “-“. + +7. Perform some basic playbook validation running with “--check” option, + running dummy playbooks or other. + +8. Upload any SSH keys referenced on hosts file to appropriate + directory. + +NOTE: HOT templates used by heat to instantiate VNF configured by these +playbooks shall include the same SSH key to be installed as part of +instantiation. + +Other non-vendor specific playbook tasks need to be incorporated on +overall post-instantiation configuration playbooks or company Playbooks +need to be uploaded and executed after VNF vendor provided or internally +developed playbooks for the VNF. + .. [1] The “name” field is a mandatory field in a valid Chef Node Object diff --git a/docs/Data_Model_For_Event_Records.png b/docs/Data_Model_For_Event_Records.png Binary files differindex 1cb7464..0d42770 100644 --- a/docs/Data_Model_For_Event_Records.png +++ b/docs/Data_Model_For_Event_Records.png diff --git a/docs/Protocol_Buffers_Driven_Model.png b/docs/Protocol_Buffers_Driven_Model.png Binary files differnew file mode 100644 index 0000000..0fc9fbb --- /dev/null +++ b/docs/Protocol_Buffers_Driven_Model.png diff --git a/docs/VES_JSON_Driven_Model.png b/docs/VES_JSON_Driven_Model.png Binary files differnew file mode 100644 index 0000000..8b8afb2 --- /dev/null +++ b/docs/VES_JSON_Driven_Model.png diff --git a/docs/YANG_Driven_Model.png b/docs/YANG_Driven_Model.png Binary files differnew file mode 100644 index 0000000..54d642b --- /dev/null +++ b/docs/YANG_Driven_Model.png |
