From 2cbffc5b71c88fd858b654335731ea72fd80220c Mon Sep 17 00:00:00 2001 From: "stark, steven" Date: Tue, 26 Jun 2018 13:34:59 -0700 Subject: [VNFRQTS] break up larger rst files into toxtree Broke all chapter files up so they follow the same patter Change-Id: I8a2152b92f0568cf4858615054bb66fabf0ea343 Issue-ID: VNFRQTS-253 Signed-off-by: stark, steven --- docs/Chapter7/Configuration-Management.rst | 1022 ++++++++++++++++++++ docs/Chapter7/Monitoring-And-Management.rst | 563 +++++++++++ docs/Chapter7/Service-Design.rst | 12 + .../VNF-On-boarding-and-package-management.rst | 272 ++++++ docs/Chapter7/index.rst | 67 ++ 5 files changed, 1936 insertions(+) create mode 100644 docs/Chapter7/Configuration-Management.rst create mode 100644 docs/Chapter7/Monitoring-And-Management.rst create mode 100644 docs/Chapter7/Service-Design.rst create mode 100644 docs/Chapter7/VNF-On-boarding-and-package-management.rst create mode 100644 docs/Chapter7/index.rst (limited to 'docs/Chapter7') diff --git a/docs/Chapter7/Configuration-Management.rst b/docs/Chapter7/Configuration-Management.rst new file mode 100644 index 0000000..075c005 --- /dev/null +++ b/docs/Chapter7/Configuration-Management.rst @@ -0,0 +1,1022 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. Copyright 2017 AT&T Intellectual Property. All rights reserved. + +Configuration Management +------------------------ + +Controller Interactions With VNF +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +ONAP Controllers (such as APPC) expose a northbound API to clients +(such as SO) in order for the clients to initiate an activity +(aka command) on a VNF. ONAP controllers interact with VNFs through +Network and Application Adapters to perform configuration and other +lifecycle management activities within NFV environment. +The standardized models, protocols and mechanisms by which network +functions are configured are equally applicable to VNFs and PNFs. + +This section describes the list of commands that should be supported +by the VNF. The following sections describe the standard protocols +that are supported (NETCONF, Chef, Ansible, and REST). + +The commands below are expected to be supported on all VNF’s, unless +noted otherwise, either directly (via the NETCONF or REST interface) +or indirectly (via a Chef Cookbook or Ansible server). Note that there +are additional commands offered to northbound clients that are not shown +below, 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 commands allow for parametric data to be passed from the controller +to the VNF or Ansible/Chef server in the request. The format of the +parameter data can be either xml (for NETCONF) or JSON (for Ansible, +Chef, or REST). + +Configuration Commands +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**Configure**: The Controller client is requesting that a post-instantiation +configuration be applied to the target VNF instance. After the Configure +action is completed, the VNF instance should be ready for service. +Note that customer specific configurations may need to be applied using +the ConfigModify action. + +**ConfigModify**: The Controller client is requesting a configuration +update to a subset of the total configuration parameters of a VNF or to +apply customer specific configurations. The configuration update is +typically done while the VNF is in service and should not disrupt traffic. + +**ConfigBackup**: The Controller client is requesting a backup of the +configuration parameters where the parameters are stored on the VNF. +This command is typically requested as part of an orchestration flow +for scenarios such as a software upgrade. The ConfigBackup is typically +done while the VNF is not in service (i.e., in a maintenance state). +When the ConfigBackup command is executed, the current VNF configuration +parameters are saved in storage that is preserved (if there is an existing +set of backed up parameters, they are overwritten). + +**ConfigRestore**: The Controller client is requesting a restore action of +the configuration parameters to the VNF that were saved by ConfigBackup +command. This command is typically requested as part of an orchestration +flow for scenarios such as a software upgrade where the software upgrade +may have failed and the VNF needs to be rolled back to the prior configuration. +When the ConfigRestore command is executed, the VNF configuration parameters +which were backed to persistent preserved storage are applied to the VNF +(replacing existing parameters). The ConfigRestore is typically done while +the VNF is not in service (i.e., in a maintenance state). + +**ConfigScaleOut**: The Controller client is requesting that a configuration +be applied after the VNF instance has been scaled out (i.e., one or more +additional VM’s instantiated to increase capacity). For some VNF’s, +ConfigScaleOut is not needed because the VNF is auto-configured after +scale-out. This command is being introduced in the Beijing release. + +**Audit**: The Controller client is requesting that the current (last known +configuration update) is audited against the running configuration on the VNF. + +* R-20741 The xNF **MUST** support ONAP Controller’s **Configure** command. +* R-19366 The xNF **MUST** support ONAP Controller’s **ConfigModify** command. +* R-32981 The xNF **MUST** support ONAP Controller’s **ConfigBackup** command. +* R-48247 The xNF **MUST** support ONAP Controller’s **ConfigRestore** command. +* R-94084 The xNF **MUST** support ONAP Controller’s **ConfigScaleOut** + command. +* R-56385 The xNF **MUST** support ONAP Controller’s **Audit** command. + +LifeCycle Management Related Commands +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**The following commands are needed to support various lifecycle management +flows where the VNF may need to be removed for service.** + +**QuiesceTraffic**: The Controller client is requesting the VNF gracefully +stop traffic (aka block and drain traffic). The method for quiescing traffic +is specific to the VNF architecture. The action is completed when all +(in-flight transactions) traffic has stopped. The VNF remains in an active +state where the VNF is able to process traffic (initiated using the +StartTraffic action). + +**ResumeTraffic**: The Controller client is requesting the VNF resume +processing traffic. The method to resume traffic is specific to the VNF +architecture. + +**StopApplication**: The Controller client is requesting that the application +running on the VNF is stopped gracefully (i.e., without traffic loss). +This is equivalent to quiescing the traffic and then stopping the application +processes. The processes can be restarted using the StartApplication command. + +**StartApplication**: The Controller client is requesting that the application +running on the VNF is started. Get ready to process traffic. + +**The following commands are needed to support software upgrades, in-place or +other type of software upgrade. The VNF instance may be removed from service +for the upgrade.** + +**UpgradePrecheck**: The Controller client is requesting a confirmation that +the VNF can (and needs to) be upgraded to a specific software version +(specified in the request). + +**UpgradeSoftware**: The Controller client is requesting that a (in-place) +software upgrade be performed on the VNF. The software to be applied is +pre-loaded to a specified location. + +**UpgradePostCheck**: The Controller client is requesting a confirmation that +the VNF software upgrade has been completed successfully (VNF upgraded to +the new software version). + +**UpgradeBackup**: The Controller client is requesting that the VNF is backed +up prior to the UpgradeSoftware. + +**UpgradeBackOut**: The Controller client is requesting that the VNF upgrade +is backed out (in the event that the SoftwareUpgrade or UpgradePostCheck +failed). + +* R-12706 The xNF **MUST** support ONAP Controller’s **QuiesceTraffic** + command. +* R-07251 The xNF **MUST** support ONAP Controller’s **ResumeTraffic** + command. +* R-83146 The xNF **MUST** support ONAP Controller’s **StopApplication** + command. +* R-82811 The xNF **MUST** support ONAP Controller’s **StartApplication** + command. +* R-19922 The xNF **MUST** support ONAP Controller’s **UpgradePrecheck** + command. +* R-49466 The xNF **MUST** support ONAP Controller’s **UpgradeSoftware** + command. +* R-45856 The xNF **MUST** support ONAP Controller’s **UpgradePostCheck** + command. +* R-97343 The xNF **MUST** support ONAP Controller’s **UpgradeBackup** + command. +* R-65641 The xNF **MUST** support ONAP Controller’s **UpgradeBackOut** + command. + +Virtual Function - Container Recovery Requirements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +As part of life cycle management, for Cloud environment, VNFs need to +support a set of basic recovery capabilities to maintain the health +and extend the life of the VNF, eliminating and reducing the frequency +that an entire VNF needs to be rebuilt or re-instantiated to recover one +or more of its containers. For instance, a VNF in an Openstack environment +is composed of one or more containers called VMs (Virtual Machines). During +the life of a VNF it is expected that Cloud infrastructure hardware will +fail or they would need to be taken down for maintenance or hardware and +software upgrades (e.g. firmware upgrades, HostOS (Hypervisor), power +maintenance, power outages, etc.) To deal with such life cycle events +without having to rebuild entire VNFs or even entire sites these basic +recovery capabilities of individual containers, Virtual Machines or other, +must be supported. + +* R-11790 The VNF **MUST** support ONAP Controller’s + **Restart (stop/start or reboot)** command. +* R-56218 The VNF **MUST** support ONAP Controller’s Migrate command that + moves container (VM) from a live Physical Server / Compute Node to + another live Physical Server / Compute Node. + +NOTE: Container migrations MUST be transparent to the VNF and no more +intrusive than a stop, followed by some down time for the migration to +be performed from one Compute Node / Physical Server to another, followed +by a start of the same VM with same configuration on the new Compute +Node / Physical Server. + +* R-38001 The VNF MUST support ONAP Controller’s **Rebuild** command. +* R-76901 VNF MUST support a container rebuild mechanism based on existing + image (e.g. Glance image in Openstack environment) or a snapshot. + +HealthCheck and Failure Related Commands +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**HealthCheck**: The Controller client is requesting a health 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: In addition to the commands above, the Controller supports a set of +Openstack failure recovery related commands that are executed on-demand or via +Control Loop at the VM level. The VNF must support these commands in a fully +automated fashion. + +* R-41430 The xNF **MUST** support ONAP Controller’s **HealthCheck** + command. + +Notes On Command Support Using Controller Southbound Protocols +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ONAP Controllers are designed to support a standard set of protocols in +order to communicate with the VNF instance. The supported protocols are +NETCONF, Ansible, Chef, and REST. + +NETCONF and REST require the VNF to implement a server which supports the RPC +or REST calls. + +Ansible and Chef require the use of a Ansible or Chef server which communicates +with the Controller (northbound) and the VNF VM’s (southbound). + +The vendor must select which protocol to support for the commands listed above. +Notes: + +* NETCONF is most suitable for configuration related commands + +* Ansible and Chef are suitable for any command. + Ansible has the advantage that it is agentless. + +* REST is specified as an option only for the HealthCheck. + + +Additional details can be found in the `ONAP Application Controller (APPC) API Guide `_, `ONAP VF-C project `_ and the `ONAP SDNC project `_. + +NETCONF Standards and Capabilities +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +ONAP Controllers and their Adapters utilize device YANG model and +NETCONF APIs to make the required changes in the VNF state and +configuration. The VNF providers must provide the Device YANG model and +NETCONF server supporting NETCONF APIs to comply with target ONAP and +industry standards. + +VNF Configuration via NETCONF Requirements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Configuration Management ++++++++++++++++++++++++++++ + +* R-88026 The xNF **MUST** include a NETCONF server enabling + runtime configuration and lifecycle management capabilities. +* R-95950 The xNF **MUST** provide a NETCONF interface fully defined + by supplied YANG models for the embedded NETCONF server. + +NETCONF Server Requirements +++++++++++++++++++++++++++++++ + +* R-73468 The xNF **MUST** allow the NETCONF server connection + parameters to be configurable during virtual machine instantiation + through Heat templates where SSH keys, usernames, passwords, SSH + service and SSH port numbers are Heat template parameters. +* R-90007 The xNF **MUST** implement the protocol operation: + **close-session()**- Gracefully close the current session. +* R-70496 The xNF **MUST** implement the protocol operation: + **commit(confirmed, confirm-timeout)** - Commit candidate + configuration datastore to the running configuration. +* R-18733 The xNF **MUST** implement the protocol operation: + **discard-changes()** - Revert the candidate configuration + datastore to the running configuration. +* R-44281 The xNF **MUST** implement the protocol operation: + **edit-config(target, default-operation, test-option, error-option, + config)** - Edit the target configuration datastore by merging, + replacing, creating, or deleting new config elements. +* R-60106 The xNF **MUST** implement the protocol operation: + **get(filter)** - Retrieve (a filtered subset of) the running + configuration and device state information. This should include + the list of xNF supported schemas. +* R-29488 The xNF **MUST** implement the protocol operation: + **get-config(source, filter)** - Retrieve a (filtered subset of + a) configuration from the configuration datastore source. +* R-11235 The xNF **MUST** implement the protocol operation: + **kill-session(session)** - Force the termination of **session**. +* R-02597 The xNF **MUST** implement the protocol operation: + **lock(target)** - Lock the configuration datastore target. +* R-96554 The xNF **MUST** implement the protocol operation: + **unlock(target)** - Unlock the configuration datastore target. +* R-29324 The xNF **SHOULD** implement the protocol operation: + **copy-config(target, source) -** Copy the content of the + configuration datastore source to the configuration datastore target. +* R-88031 The xNF **SHOULD** implement the protocol operation: + **delete-config(target) -** Delete the named configuration + datastore target. +* R-97529 The xNF **SHOULD** implement the protocol operation: + **get-schema(identifier, version, format) -** Retrieve the YANG schema. +* R-62468 The xNF **MUST** allow all configuration data to be + edited through a NETCONF operation. Proprietary + NETCONF RPCs that make configuration changes are not sufficient. +* R-01382 The xNF **MUST** allow the entire configuration of the + xNF to be retrieved via NETCONF's and , + independently of whether it was configured via NETCONF or other + mechanisms. +* R-28756 The xNF **MUST** support **:partial-lock** and + **:partial-unlock** capabilities, defined in RFC 5717. This + allows multiple independent clients to each write to a different + part of the configuration at the same time. +* R-83873 The xNF **MUST** support **:rollback-on-error** value for + the parameter to the operation. If any + error occurs during the requested edit operation, then the target + database (usually the running configuration) will be left unaffected. + This provides an 'all-or-nothing' edit mode for a single + request. +* R-68990 The xNF **MUST** support the **:startup** capability. It + will allow the running configuration to be copied to this special + database. It can also be locked and unlocked. +* R-68200 The xNF **MUST** support the **:url** value to specify + protocol operation source and target parameters. The capability URI + for this feature will indicate which schemes (e.g., file, https, sftp) + that the server supports within a particular URL value. The 'file' + scheme allows for editable local configuration databases. The other + schemes allow for remote storage of configuration databases. +* R-20353 The xNF **MUST** implement both **:candidate** and + **:writable-running** capabilities. When both **:candidate** and + **:writable-running** are provided then two locks should be supported. +* R-11499 The xNF **MUST** fully support the XPath 1.0 specification + for filtered retrieval of configuration and other database contents. + The 'type' attribute within the parameter for and + operations may be set to 'xpath'. The 'select' attribute + (which contains the XPath expression) will also be supported by the + server. A server may support partial XPath retrieval filtering, but + it cannot advertise the **:xpath** capability unless the entire XPath + 1.0 specification is supported. +* R-83790 The xNF **MUST** implement the **:validate** capability +* R-49145 The xNF **MUST** implement **:confirmed-commit** If + **:candidate** is supported. +* R-58358 The xNF **MUST** implement the **:with-defaults** capability + [RFC6243]. +* R-59610 The xNF **MUST** implement the data model discovery and + download as defined in [RFC6022]. +* R-93443 The xNF **MUST** define all data models in YANG [RFC6020], + and the mapping to NETCONF shall follow the rules defined in this RFC. +* R-26115 The xNF **MUST** follow the data model upgrade rules defined + in [RFC6020] section 10. All deviations from section 10 rules shall + be handled by a built-in automatic upgrade mechanism. +* R-10716 The xNF **MUST** support parallel and simultaneous + configuration of separate objects within itself. +* R-29495 The xNF **MUST** support locking if a common object is + being manipulated by two simultaneous NETCONF configuration operations + on the same xNF within the context of the same writable running data + store (e.g., if an interface parameter is being configured then it + should be locked out for configuration by a simultaneous configuration + operation on that same interface parameter). +* R-53015 The xNF **MUST** apply locking based on the sequence of + NETCONF operations, with the first configuration operation locking + out all others until completed. +* R-02616 The xNF **MUST** permit locking at the finest granularity + if a xNF needs to lock an object for configuration to avoid blocking + simultaneous configuration operations on unrelated objects (e.g., BGP + configuration should not be locked out if an interface is being + configured or entire Interface configuration should not be locked out + if a non-overlapping parameter on the interface is being configured). +* R-41829 The xNF **MUST** be able to specify the granularity of the + lock via a restricted or full XPath expression. +* R-66793 The xNF **MUST** guarantee the xNF configuration integrity + for all simultaneous configuration operations (e.g., if a change is + attempted to the BUM filter rate from multiple interfaces on the same + EVC, then they need to be sequenced in the xNF without locking either + configuration method out). +* R-54190 The xNF **MUST** release locks to prevent permanent lock-outs + when/if a session applying the lock is terminated (e.g., SSH session + is terminated). +* R-03465 The xNF **MUST** release locks to prevent permanent lock-outs + when the corresponding operation succeeds. +* R-63935 The xNF **MUST** release locks to prevent permanent lock-outs + when a user configured timer has expired forcing the NETCONF SSH Session + termination (i.e., product must expose a configuration knob for a user + setting of a lock expiration timer) +* R-10173 The xNF **MUST** allow another NETCONF session to be able to + initiate the release of the lock by killing the session owning the lock, + using the operation to guard against hung NETCONF sessions. +* R-88899 The xNF **MUST** support simultaneous operations + within the context of this locking requirements framework. +* R-07545 The xNF **MUST** support all operations, administration and + management (OAM) functions available from the supplier for xNFs using + the supplied YANG code and associated NETCONF servers. +* R-60656 The xNF **MUST** support sub tree filtering. +* R-80898 The xNF **MUST** support heartbeat via a with null filter. +* R-25238 The xNF PACKAGE **MUST** validated YANG code using the open + source pyang [1]_ program using the following commands: + +.. code-block:: python + + $ pyang --verbose --strict + $ echo $! + +* R-63953 The xNF **MUST** have the echo command return a zero value + otherwise the validation has failed +* R-26508 The xNF **MUST** support a NETCONF server that can be mounted on + OpenDaylight (client) and perform the operations of: modify, update, + change, rollback configurations using each configuration data element, + query each state (non-configuration) data element, execute each YANG + RPC, and receive data through each notification statement. + + +The following requirements provides the Yang models that suppliers must +conform, and those where applicable, that suppliers need to use. + +* R-28545 The xNF **MUST** conform its YANG model to RFC 6060, + “YANG - A Data Modeling Language for the Network Configuration + Protocol (NETCONF)” +* R-22700 The xNF **MUST** conform its YANG model to RFC 6470, + “NETCONF Base Notifications”. +* R-10353 The xNF **MUST** conform its YANG model to RFC 6244, + “An Architecture for Network Management Using NETCONF and YANG”. +* R-53317 The xNF **MUST** conform its YANG model to RFC 6087, + “Guidelines for Authors and Reviewers of YANG Data Model Documents”. +* R-33955 The xNF **SHOULD** conform its YANG model to RFC 6991, + “Common YANG Data Types”. +* R-22946 The xNF **SHOULD** conform its YANG model to RFC 6536, + “NETCONF Access Control Model”. +* R-10129 The xNF **SHOULD** conform its YANG model to RFC 7223, + “A YANG Data Model for Interface Management”. +* R-12271 The xNF **SHOULD** conform its YANG model to RFC 7223, + “IANA Interface Type YANG Module”. +* R-49036 The xNF **SHOULD** conform its YANG model to RFC 7277, + “A YANG Data Model for IP Management”. +* R-87564 The xNF **SHOULD** conform its YANG model to RFC 7317, + “A YANG Data Model for System Management”. +* R-24269 The xNF **SHOULD** conform its YANG model to RFC 7407, + “A YANG Data Model for SNMP Configuration”, if Netconf used to + configure SNMP engine. + +The NETCONF server interface shall fully conform to the following +NETCONF RFCs. + +* R-33946 The xNF **MUST** conform to the NETCONF RFC 4741, + “NETCONF Configuration Protocol”. +* R-04158 The xNF **MUST** conform to the NETCONF RFC 4742, + “Using the NETCONF Configuration Protocol over Secure Shell (SSH)”. +* R-13800 The xNF **MUST** conform to the NETCONF RFC 5277, + “NETCONF Event Notification”. +* R-01334 The xNF **MUST** conform to the NETCONF RFC 5717, + “Partial Lock Remote Procedure Call”. +* R-08134 The xNF **MUST** conform to the NETCONF RFC 6241, + “NETCONF Configuration Protocol”. +* R-78282 The xNF **MUST** conform to the NETCONF RFC 6242, + “Using the Network Configuration Protocol over Secure Shell”. + +VNF REST APIs +^^^^^^^^^^^^^^^ + +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`_). + +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 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 provider. + +REST APIs +~~~~~~~~~ + +* R-31809 The xNF **MUST** support the HealthCheck RPC. The HealthCheck + RPC executes a xNF Provider-defined xNF HealthCheck over the scope of + the entire xNF (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 xNF is unable to run the HealthCheck, return a + standard http error code and message. + +Examples of responses when HealthCheck runs and is able to provide a healthy +or unhealthy response: + +.. code-block:: java + + { + "identifier": "scope represented", + "state": "healthy", + "time": "01-01-1000:0000" + } + + { + "identifier": "scope represented", + "state": "unhealthy", + {[ + "info": "System threshold exceeded details", + "fault": + { + "cpuOverall": 0.80, + "cpuThreshold": 0.45 + } + ]}, + "time": "01-01-1000:0000" + } + + +Chef Standards and Capabilities +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +ONAP will support configuration of VNFs via Chef subject to the +requirements and guidelines defined in this section. + +The Chef configuration management mechanism follows a client-server +model. It requires the presence of a Chef-Client on the VNF that will be +directly managed by a Chef Server. The Chef-client will register with +the appropriate Chef Server and are managed via ‘cookbooks’ and +configuration attributes loaded on the Chef Server which contain all +necessary information to execute the appropriate actions on the VNF via +the Chef-client. + +ONAP will utilize the open source Chef Server, invoke the documented +Chef REST APIs to manage the VNF and requires the use of open source +Chef-Client and Push Jobs Client on the VNF +(https://downloads.chef.io/). + +VNF Configuration via Chef Requirements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Chef Client Requirements ++++++++++++++++++++++++++ + +* R-79224 The xNF **MUST** have the chef-client be preloaded with + validator keys and configuration to register with the designated + Chef Server as part of the installation process. +* R-72184 The xNF **MUST** have routable FQDNs for all the endpoints + (VMs) of a xNF that contain chef-clients which are used to register + with the Chef Server. As part of invoking xNF actions, ONAP will + trigger push jobs against FQDNs of endpoints for a xNF, if required. +* R-47068 The xNF **MAY** expose a single endpoint that is + responsible for all functionality. +* R-67114 The xNF **MUST** be installed with Chef-Client >= 12.0 and + Chef push jobs client >= 2.0. + +Chef Roles/Requirements +++++++++++++++++++++++++++ + +* R-27310 The xNF Package **MUST** include all relevant Chef artifacts + (roles/cookbooks/recipes) required to execute xNF actions requested by + ONAP for loading on appropriate Chef Server. +* R-26567 The xNF Package **MUST** include a run list of + roles/cookbooks/recipes, for each supported xNF action, that will + perform the desired xNF action in its entirety as specified by ONAP + (see Section 7.c, ONAP Controller APIs and Behavior, for list of xNF + actions and requirements), when triggered by a chef-client run list + in JSON file. +* R-98911 The xNF **MUST NOT** use any instance specific parameters + for the xNF in roles/cookbooks/recipes invoked for a xNF action. +* R-37929 The xNF **MUST** accept all necessary instance specific + data from the environment or node object attributes for the xNF + in roles/cookbooks/recipes invoked for a xNF action. +* R-62170 The xNF **MUST** over-ride any default values for + configurable parameters that can be set by ONAP in the roles, + cookbooks and recipes. +* R-78116 The xNF **MUST** update status on the Chef Server + appropriately (e.g., via a fail or raise an exception) if the + chef-client run encounters any critical errors/failures when + executing a xNF action. +* R-44013 The xNF **MUST** populate an attribute, defined as node + [‘PushJobOutput’] with the desired output on all nodes in the push job + that execute chef-client run if the xNF action requires the output of a + chef-client run be made available (e.g., get running configuration). +* R-30654 The xNF Package **MUST** have appropriate cookbooks that are + designed to automatically ‘rollback’ to the original state in case of + any errors for actions that change state of the xNF (e.g., configure). +* R-65755 The xNF **SHOULD** support callback URLs to return information + to ONAP upon completion of the chef-client run for any chef-client run + associated with a xNF action. + +- As part of the push job, ONAP will provide two parameters in the + environment of the push job JSON object: + + - ‘RequestId’ a unique Id to be used to identify the request, + - ‘CallbackUrl’, the URL to post response back. + +- If the CallbackUrl field is empty or missing in the push job, then + the chef-client run need not post the results back via callback. + +* R-15885 The xNF **MUST** Upon completion of the chef-client run, + POST back on the callback URL, a JSON object as described in Table + A2 if the chef-client run list includes a cookbook/recipe that is + callback capable. Failure to POST on the Callback Url should not be + considered a critical error. That is, if the chef-client successfully + completes the xNF action, it should reflect this status on the Chef + Server regardless of whether the Callback succeeded or not. + +ONAP Chef API Usage +~~~~~~~~~~~~~~~~~~~ + +This section outlines the workflow that ONAP invokes when it receives an +action request against a Chef managed VNF. + +1. When ONAP receives a request for an action for a Chef Managed VNF, it + retrieves the corresponding template (based on **action** and + **VNF)** from its database and sets necessary values in the + “Environment”, “Node” and “NodeList” keys (if present) from either + the payload of the received action or internal data. + +2. If “Environment” key is present in the updated template, it posts the + corresponding JSON dictionary to the appropriate Environment object + REST endpoint on the Chef Server thus updating the Environment + attributes on the Chef Server. + +3. Next, it creates a Node Object from the “Node” JSON dictionary for + all elements listed in the NodeList (using the FQDN to construct the + endpoint) by replicating it [2]_. As part of this process, it will + set the name field in each Node Object to the corresponding FQDN. + These node objects are then posted on the Chef Server to + corresponding Node Object REST endpoints to update the corresponding + node attributes. + +4. If PushJobFlag is set to “True” in the template, ONAP requests a push + job against all the nodes in the NodeList to trigger + chef-client\ **.** It will not invoke any other command via the push + job. ONAP will include a callback URL in the push job request and a + unique Request Id. An example push job posted by ONAP is listed + below: + +.. 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”:”” + }, + } + +5. If CallbackCapable field in the template is not present or set to + “False” ONAP will poll the Chef Server to check completion status of + the push job. + +6. If “GetOutputFlag” is set to “True” in the template and + CallbackCapable is not set to “True”, ONAP will retrieve any output + from each node where the push job has finished by accessing the Node + Object attribute node[‘PushJobOutput’]. + +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 VNFs/VMs/VNFCs via execution +of ‘playbooks’ over ssh. The ‘playbooks’ are a structured set of +tasks which contain all the necessary resources 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 all Ansible artifacts and run playbooks to manage VNFs that support +Ansible. + +VNF Configuration via Ansible Requirements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Ansible Client Requirements ++++++++++++++++++++++++++++++ + +* R-32217 The xNF **MUST** have routable FQDNs that are reachable via + the Ansible Server for the endpoints (VMs) of a xNF on which playbooks + will be executed. ONAP will initiate requests to the Ansible Server + for invocation of playbooks against these end points [3]_. +* R-54373 The xNF **MUST** have Python >= 2.6 on the endpoint VM(s) + of a xNF on which an Ansible playbook will be executed. +* R-35401 The xNF **MUST** support SSH and allow SSH access by the + Ansible server for the endpoint VM(s) and comply with the Network + Cloud Service Provider guidelines for authentication and access. +* R-82018 The xNF **MUST** load the Ansible Server SSH public key onto xNF + 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 xNF 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 public keys, SSH public keys loaded during (heat) instantiation shall + be preserved and not removed by (heat) embedded (userdata) scripts. + +* R-92866 The xNF **MUST** include as part of post-instantiation configuration + done by Ansible Playbooks the removal/update of the SSH public key from + /root/.ssh/authorized_keys, and update of SSH keys loaded through + instantiation to support Ansible. This may include download and install of + new SSH keys and new mechanized IDs. +* R-91745 The xNF **MUST** update the Ansible Server and other entities + storing and using the SSH keys for authentication when the SSH keys used + by Ansible are regenerated/updated. + + NOTE: Ansible Server itself may be used to upload new SSH public keys + onto supported VNFs. + +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 xNF **MUST** make available playbooks that conform + to the ONAP requirement. +* R-49396 The xNF **MUST** support each ONAP (APPC) xNF 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-33280 The xNF **MUST NOT** use any instance specific parameters + in a playbook. +* R-48698 The xNF **MUST** utilize information from key value pairs + that will be provided by the Ansible Server as "extra-vars" during + invocation to execute the desired xNF action. If the playbook requires + files, they must also be supplied using the methodology detailed in + the Ansible Server API, unless they are bundled with playbooks, example, + generic templates. + +The Ansible Server will determine if a playbook invoked to execute a +xNF 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 xNF **MUST** use playbooks designed to allow Ansible + Server to infer failure or success based on the “PLAY_RECAP” capability. + NOTE: There are cases where playbooks need to interpret results of a task + and then determine success or failure and return result accordingly + (failure for failed tasks). +* R-50252 The xNF **MUST** write to a specific one text files that + will be retrieved and made available by the Ansible Server if, as part + of a xNF action (e.g., audit), a playbook is required to return any + xNF 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 the xNF playbook run targets/affects, with the name + ‘_results.txt’ into which any desired output from each + respective VM/xNF must be written. +* R-51442 The xNF **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 xNF (e.g., configure). + + NOTE: In case rollback at the playbook level is not supported or possible, + the xNF provider shall provide alternative locking mechanism (e.g., for a + small xNF 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-58301 The xNF **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 + (Change Management) 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-02651 The xNF **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-43353 The xNF **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 after the VNF instance name followed by + “_results.txt (_results.txt) to indicate health-check was + executed and completed successfully, example: vfdb9904v_results.txt, + with the following contents: + +.. code-block:: java + + { + "identifier": "VNF", + "state": "healthy", + "time": "2018-03-16:1139" + } + +Example: + +.. code-block:: java + + $ cat vfdb9904v_results.txt + { + "identifier": "VNF", + "state": "healthy", + "time": "2018-03-16:1139" + } +.. + + 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, + named after the VNF instance 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 playbook tasks to verify the health of the VNF, + example: vfdb9904v_results.txt, with the following contents: + +.. code-block:: java + + { + "identifier": "VNF", + "state": "unhealthy", + "info": "Error in following VM(s). Check hcstatus files + under /tmp/ccfx9901v for details", + "fault": [ + "vfdb9904vm001", + "vfdb9904vm002" + ], + "time": "2018-03-16:4044" + } +.. + + Example: + +.. code-block:: java + + $ cat vfdb9904v_results.txt + { + "identifier": "VNF", + "state": "unhealthy", + "info": "Error in following VM(s). Check hcstatus files + under /tmp/ccfx9901v for details", + "fault": [ + "vfdb9904vm001", + "vfdb9904vm002" + ], + "time": "2018-03-16:4044" + } +.. + + 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. + + +Support of Controller Commands And Southbound Protocols +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following table summarizes the commands and possible protocols selected. +Note that the HealthCheck can also be supported via REST. + +Table 8. ONAP Controller APIs and NETCONF Commands + ++-------------+--------------------+--------------------+--------------------+ +|**Command** |**NETCONF Support** |**Chef Support** |**Ansible** | ++=============+====================+====================+====================+ +|General |For each RPC, the |VNF Vendor must |VNF Vendor must | +|Comments |appropriate RPC |provide any |provide an Ansible | +| |operation is listed.|necessary roles, |playbook to retrieve| +| | |cookbooks, recipes |the running | +| | |to retrieve the |configuration from a| +| | |running |VNF and place the | +| | |configuration from |output on the | +| | |a VNF and place it |Ansible server in | +| | |in the respective |a manner aligned | +| | |Node Objects |with playbook | +| | |‘PushJobOutput’ |requirements listed | +| | |attribute of all |in this document. | +| | |nodes in NodeList | | +| | |when triggered |The PlaybookName | +| | |by a chef-client |must be provided | +| | |run. |in the JSON file. | +| | | | | +| | |The JSON file for |NodeList must list | +| | |this VNF action is |IP addresses or DNS | +| | |required to set |supported FQDNs of | +| | |“PushJobFlag” to |an example VNF | +| | |“True” and |on which to | +| | |“GetOutputFlag” to |execute playbook. | +| | |“True”. The “Node” | | +| | |JSON dictionary | | +| | |must have the run | | +| | |list populated | | +| | |with the necessary | | +| | |sequence of roles, | | +| | |cookbooks, recipes. | | +| | | | | +| | |The Environment | | +| | |and Node values | | +| | |should contain all | | +| | |appropriate | | +| | |configuration | | +| | |attributes. | | +| | | | | +| | |NodeList must | | +| | |list sample FQDNs | | +| | |that are required to| | +| | |conduct a | | +| | |chef-client run for | | +| | |this VNF Action. | | ++-------------+--------------------+--------------------+--------------------+ +|Audit |The is |Supported via a |Supported via a | +| |used to return the |cookbook that |playbook that | +| |running |returns the running |returns the running | +| |configuration. |configuration. |configuration. | ++-------------+--------------------+--------------------+--------------------+ +|Configure, |The |Supported via a |Supported via a | +|ModifyConfig |operation loads all |cookbook that |playbook that | +| |or part of a |updates the VNF |updates the VNF | +| |specified data set |configuration. |configuration. | +| |to the specified | | | +| |target database. If | | | +| |there is no | | | +| | | | | +| |database, then the | | | +| |target is the | | | +| | database.| | | +| |A follows. | | | ++-------------+--------------------+--------------------+--------------------+ +|Other |This command has no |Supported via a |Supported via a | +|Configuration|existing NETCONF RPC|cookbook that |playbook that | +|Commands |action. |performs |performs | +| | |the action. |the action. | ++-------------+--------------------+--------------------+--------------------+ +|Lifecycle |This command has no |Supported via a |Supported via a | +|Management |existing NETCONF RPC|cookbook that |playbook that | +|Commands |action. |performs |performs | +| | |the action. |the action. | ++-------------+--------------------+--------------------+--------------------+ +|Health Check |This command has no |Supported via a |Supported | +| |existing NETCONF RPC|cookbook |via a | +| |action. |that |playbook | +| | |performs |that | +| | |a HealthCheck and |performs | +| | |returns the results.|the | +| | | |HealthCheck | +| | | |and returns | +| | | |the | +| | | |results. | ++-------------+--------------------+--------------------+--------------------+ + +.. [1] + https://github.com/mbj4668/pyang + +.. [2] + Recall that the Node Object **is required** to be identical across + all VMs of a VNF invoked as part of the action except for the “name”. + +.. [3] + Upstream elements must provide the appropriate FQDN in the request to + ONAP for the desired action. + +.. [4] + Multiple ONAP actions may map to one playbook. + +.. |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 + diff --git a/docs/Chapter7/Monitoring-And-Management.rst b/docs/Chapter7/Monitoring-And-Management.rst new file mode 100644 index 0000000..a54671f --- /dev/null +++ b/docs/Chapter7/Monitoring-And-Management.rst @@ -0,0 +1,563 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. Copyright 2017 AT&T Intellectual Property. All rights reserved. + +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 VNF provider 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 providers 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 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: + +- Common Header Record: This data structure precedes each of the + 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 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 VNF provider can use these VNF Provider-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 + providers 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| + +Figure 1. Data Model for Event Records + +Event Records - Data Structure Description +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The data structure for event records consists of: + +- a Common Event Header block; + +- zero or more technology independent domain blocks; and + + - e.g., Fault domain, State Change domain, Syslog domain, etc. + +- zero or more technology specific domain blocks. + + - e.g., Mobile Flow domain, Signaling domain, Voice Quality domain, + etc. + +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. + +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 +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. + +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. + +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 +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. + +Technology Independent Records - VNF Scaling Fields +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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. + +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. + +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 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. + +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. + +Data Structure Specification of the Event Record +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For additional information on the event record formats of the data +structures mentioned above, please refer to `VES Event +Listener `__. + +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 providers +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 providers 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, VNF providers +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 VNF provider'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 VNF events. The Service Provider may alter the threshold levels +recommended by the VNF providor, 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 providers will provide to the Service Provider the following +YANG model artifacts: + +* common IETF YANG modules that support the VNF +* native (VNF provider-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, VNF providers +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 VNF provider'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 +VNF events. The Service Provider may alter the threshold levels recommended +by the VNF provider, 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 providers 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 `__. + +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 xNF **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 xNF **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 `_, where the Avro [1]_ data format are described using JSON. + + Note: + + - 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 xNF 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 xNFs 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 providers 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 providers 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 xNF **MUST** vary the frequency that asynchronous data + is delivered based on the content and how data may be aggregated or + grouped together. + + Note: + + - 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 xNF **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 xNF **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 xNF. In this case, the network will + promptly resolve connectivity problems caused by a collector or network + failure transparently to the xNF. +* R-81777 The xNF **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 xNF using PUTs to a + RESTful API, in the same manner that other controls over data reporting + will be controlled by policy. +* R-08312 The xNF **MAY** use another option which is expected to include REST + delivery of binary encoded data sets. +* R-79412 The xNF **MAY** use another option which is expected to include 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. +* R-01033 The xNF **MAY** use another option which is expected to include 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 xNFs. + (Preferred is to reorganize the data into more frequent or more focused data + sets, and deliver these by REST or TCP as appropriate.) +* R-63229 The xNF **MAY** use another option which is expected to include REST + for synchronous data, using RESTCONF (e.g., for xNF state polling). +* R-03070 The xNF **MUST**, by ONAP Policy, provide the ONAP addresses + as data destinations for each xNF, and may be changed by Policy while + the xNF is in operation. We expect the xNF 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 xNF **MUST** deliver asynchronous data as data becomes + available, or according to the configured frequency. +* R-73285 The xNF **MUST** must encode, address and deliver the data + as described in the previous paragraphs. +* R-42140 The xNF **MUST** respond to data requests from ONAP as soon + as those requests are received, as a synchronous response. +* R-34660 The xNF **MUST** use the RESTCONF/NETCONF framework used by + the ONAP configuration subsystem for synchronous communication. +* R-86586 The xNF **MUST** use the YANG configuration models and RESTCONF + [RFC8040] (https://tools.ietf.org/html/rfc8040). +* R-11240 The xNF **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 xNF **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 + xNF 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 xNF **MUST** respond to an ONAP request to deliver granular + data on device or subsystem status or performance, referencing the YANG + configuration model for the xNF by returning the requested data elements. +* R-43327 The xNF **SHOULD** use `Modeling JSON text with YANG + `_, 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 xNF **MUST** support secure connections and transports such as + Transport Layer Security (TLS) protocol + [`RFC5246 `_] and should adhere to + the best current practices outlined in + `RFC7525 `_. +* R-44290 The xNF **MUST** control access to ONAP and to xNFs, and creation + of connections, through secure credentials, log-on and exchange mechanisms. +* R-47597 The xNF **MUST** carry data in motion only over secure connections. +* R-68165 The xNF **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] + This option is not currently supported in ONAP and it is currently + under consideration. + +.. |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 + diff --git a/docs/Chapter7/Service-Design.rst b/docs/Chapter7/Service-Design.rst new file mode 100644 index 0000000..472badc --- /dev/null +++ b/docs/Chapter7/Service-Design.rst @@ -0,0 +1,12 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. Copyright 2017 AT&T Intellectual Property. All rights reserved. + + +Service Design +-------------- + +This section, Service Design, has been left intentionally blank. It +is out-of-scope for the VNF Requirements project for the Amsterdam +release and no numbered requirements are expected. Content may be +added in future updates of this document. diff --git a/docs/Chapter7/VNF-On-boarding-and-package-management.rst b/docs/Chapter7/VNF-On-boarding-and-package-management.rst new file mode 100644 index 0000000..7628aaa --- /dev/null +++ b/docs/Chapter7/VNF-On-boarding-and-package-management.rst @@ -0,0 +1,272 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. Copyright 2017 AT&T Intellectual Property. All rights reserved. + + +VNF On-boarding and package management +-------------------------------------- + +Design Definition +^^^^^^^^^^^^^^^^^^ + +The ONAP Design Time Framework provides the ability to design NFV +resources including VNFs, Services, and products. The VNF provider must +provide VNF packages that include a rich set of recipes, management and +functional interfaces, policies, configuration parameters, and +infrastructure requirements that can be utilized by the ONAP Design +module to onboard and catalog these resources. Initially this +information may be provided in documents, but in the near future a +method will be developed to automate as much of the transfer of data as +possible to satisfy its long term requirements. + +The current VNF Package Requirement is based on a subset of the +Requirements contained in the ETSI Document: ETSI GS NFV-MAN 001 v1.1.1 +and GS NFV IFA011 V0.3.0 (2015-10) - Network Functions Virtualization +(NFV), Management and Orchestration, VNF Packaging Specification. + +Resource Description +^^^^^^^^^^^^^^^^^^^^^^ + +* R-77707 The xNF provider **MUST** include a Manifest File that + contains a list of all the components in the xNF package. +* R-66070 The xNF Package **MUST** include xNF Identification Data to + uniquely identify the resource for a given xNF provider. The identification + data must include: an identifier for the xNF, the name of the xNF as was + given by the xNF provider, xNF description, xNF provider, and version. +* R-69565 The xNF Package **MUST** include documentation describing xNF + Management APIs, which must include information and tools for ONAP to + deploy and configure (initially and ongoing) the xNF application(s) + (e.g., NETCONF APIs) which includes a description of configurable + parameters for the xNF and whether the parameters can be configured + after xNF instantiation. +* R-00156 The xNF Package **MUST** include documentation describing xNF + Management APIs, which must include information and tools for ONAP + to monitor the health of the xNF (conditions that require healing + and/or scaling responses). +* R-00068 The xNF Package **MUST** include documentation which includes + a description of parameters that can be monitored for the xNF and + event records (status, fault, flow, session, call, control plane, + etc.) generated by the xNF after instantiation. +* R-12678 The xNF Package **MUST** include documentation which includes a + description of runtime lifecycle events and related actions (e.g., + control responses, tests) which can be performed for the xNF. +* R-84366 The xNF Package **MUST** include documentation describing + xNF Functional APIs that are utilized to build network and + application services. This document describes the externally exposed + functional inputs and outputs for the xNF, including interface + format and protocols supported. +* R-36280 The xNF provider **MUST** provide documentation describing + xNF Functional Capabilities that are utilized to operationalize the + xNF and compose complex services. +* R-98617 The xNF provider **MUST** provide information regarding any + dependency (e.g., affinity, anti-affinity) with other xNFs and resources. + +Resource Configuration +^^^^^^^^^^^^^^^^^^^^^^^ + +* R-89571 The xNF **MUST** support and provide artifacts for configuration + management using at least one of the following technologies; + a) Netconf/YANG, b) Chef, or c) Ansible. + + Note: The requirements for Netconf/YANG, Chef, and Ansible protocols + are provided separately and must be supported only if the corresponding + protocol option is provided by the xNF providor. + +Configuration Management via NETCONF/YANG +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* R-30278 The xNF provider **MUST** provide a Resource/Device YANG model + as a foundation for creating the YANG model for configuration. This will + include xNF attributes/parameters and valid values/attributes configurable + by policy. + +Configuration Management via Chef +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* R-13390 The xNF provider **MUST** provide cookbooks to be loaded + on the appropriate Chef Server. +* R-18525 The xNF provider **MUST** provide a JSON file for each + supported action for the xNF. 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 Tables A1 + and A2 in the Appendix. + + Note: Chef support in ONAP is not currently available and planned for 4Q 2017. + +Configuration Management via Ansible +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* R-75608 The xNF provider **MUST** provide playbooks to be loaded + on the appropriate Ansible Server. +* R-16777 The xNF provider **MUST** provide a JSON file for each + supported action for the xNF. 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 Table B1 + in the Appendix. + +* R-46567 The xNF Package **MUST** include configuration scripts + for boot sequence and configuration. +* R-16065 The xNF provider **MUST** provide configurable parameters + (if unable to conform to YANG model) including xNF attributes/parameters + and valid values, dynamic attributes and cross parameter dependencies + (e.g., customer provisioning data). + +Resource Control Loop +^^^^^^^^^^^^^^^^^^^^^^^ + +* R-22888 The xNF provider **MUST** provide documentation for the xNF + Policy Description to manage the xNF runtime lifecycle. The document + must include a description of how the policies (conditions and actions) + are implemented in the xNF. +* R-01556 The xNF Package **MUST** include documentation describing the + fault, performance, capacity events/alarms and other event records + that are made available by the xNF. +* R-16875 The xNF Package **MUST** include documentation which must include + a unique identification string for the specific xNF, a description of + the problem that caused the error, and steps or procedures to perform + Root Cause Analysis and resolve the issue. +* R-35960 The xNF Package **MUST** include documentation which must include + all events, severity level (e.g., informational, warning, error) and + descriptions including causes/fixes if applicable for the event. +* R-42018 The xNF Package **MUST** include documentation which must include + all events (fault, measurement for xNF Scaling, Syslogs, State Change + and Mobile Flow), that need to be collected at each VM, VNFC (defined in `VNF Guidelines `__ ) and for the overall xNF. +* R-27711 The xNF provider **MUST** provide an XML file that contains a + list of xNF error codes, descriptions of the error, and possible + causes/corrective action. +* R-01478 The xNF Package **MUST** include documentation describing all + parameters that are available to monitor the xNF after instantiation + (includes all counters, OIDs, PM data, KPIs, etc.) that must be + collected for reporting purposes. +* R-73560 The xNF Package **MUST** include documentation about monitoring + parameters/counters exposed for virtual resource management and xNF + application management. +* R-90632 The xNF Package **MUST** include documentation about KPIs and + metrics that need to be collected at each VM for capacity planning + and performance management purposes. +* R-86235 The xNF Package **MUST** include documentation about the monitoring + parameters that must include latencies, success rates, retry rates, load + and quality (e.g., DPM) for the key transactions/functions supported by + the xNF and those that must be exercised by the xNF in order to perform + its function. +* R-33904 The xNF Package **MUST** include documentation for each KPI, provide + lower and upper limits. +* R-53598 The xNF Package **MUST** include documentation to, when relevant, + provide a threshold crossing alert point for each KPI and describe the + significance of the threshold crossing. +* R-69877 The xNF Package **MUST** include documentation for each KPI, + identify the suggested actions that need to be performed when a + threshold crossing alert event is recorded. +* R-22680 The xNF Package **MUST** include documentation that describes + any requirements for the monitoring component of tools for Network + Cloud automation and management to provide these records to components + of the xNF. +* R-33694 The xNF Package **MUST** include documentation to when applicable, + provide calculators needed to convert raw data into appropriate reporting + artifacts. +* R-56815 The xNF Package **MUST** include documentation describing + supported xNF scaling capabilities and capacity limits (e.g., number + of users, bandwidth, throughput, concurrent calls). +* R-48596 The xNF Package **MUST** include documentation describing + the characteristics for the xNF reliability and high availability. +* R-74763 The xNF provider **MUST** provide an artifact per xNF that contains + all of the xNF Event Records supported. The artifact should include + reference to the specific release of the xNF Event Stream Common Event + Data Model document it is based on. (e.g., + `VES Event Listener `__) + +Compute, Network, and Storage Requirements +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* R-35851 The xNF Package **MUST** include xNF topology that describes + basic network and application connectivity internal and external to the + xNF including Link type, KPIs, Bandwidth, latency, jitter, QoS (if + applicable) for each interface. +* R-97102 The VNF Package **MUST** include VM requirements via a Heat + template that provides the necessary data for VM specifications + for all VNF components - for hypervisor, CPU, memory, storage. +* R-20204 The VNF Package **MUST** include VM requirements via a Heat + template that provides the necessary data for network connections, + interface connections, internal and external to VNF. +* R-44896 The VNF Package **MUST** include VM requirements via a Heat + template that provides the necessary data for high availability + redundancy model. +* R-55802 The VNF Package **MUST** include VM requirements via a Heat + template that provides the necessary data for scaling/growth VM + specifications. + + Note: Must comply with the *Heat requirements in 5.b*. + +* R-26881 The xNF provider **MUST** provide the binaries and images + needed to instantiate the xNF (xNF and VNFC images). +* R-96634 The xNF provider **MUST** describe scaling capabilities + to manage scaling characteristics of the xNF. + + +Testing +^^^^^^^^^^ + +* R-43958 The xNF Package **MUST** include documentation describing + the tests that were conducted by the xNF providor and the test results. +* R-04298 The xNF provider **MUST** provide their testing scripts to + support testing. +* R-58775 The xNF provider **MUST** provide software components that + can be packaged with/near the xNF, if needed, to simulate any functions + or systems that connect to the xNF system under test. This component is + necessary only if the existing testing environment does not have the + necessary simulators. + +Licensing Requirements +^^^^^^^^^^^^^^^^^^^^^^^ + +* R-85653 The xNF **MUST** provide metrics (e.g., number of sessions, + number of subscribers, number of seats, etc.) to ONAP for tracking + every license. +* R-44125 The xNF provider **MUST** agree to the process that can + be met by Service Provider reporting infrastructure. The Contract + shall define the reporting process and the available reporting tools. +* R-40827 The xNF provider **MUST** enumerate all of the open + source licenses their xNF(s) incorporate. +* R-97293 The xNF provider **MUST NOT** require audits of + Service Provider’s business. +* R-44569 The xNF provider **MUST NOT** require additional + infrastructure such as a xNF provider license server for xNF provider + functions and metrics. +* R-13613 The VNF **MUST** provide clear measurements for licensing + purposes to allow automated scale up/down by the management system. +* R-27511 The VNF provider **MUST** provide the ability to scale + up a VNF provider supplied product during growth and scale down a + VNF provider supplied product during decline without “real-time” + restrictions based upon VNF provider permissions. +* R-85991 The xNF provider **MUST** provide a universal license key + per xNF to be used as needed by services (i.e., not tied to a VM + instance) as the recommended solution. The xNF provider may provide + pools of Unique xNF License Keys, where there is a unique key for + each xNF instance as an alternate solution. Licensing issues should + be resolved without interrupting in-service xNFs. +* R-47849 The xNF provider **MUST** support the metadata about + licenses (and their applicable entitlements) as defined in this + document for xNF software, and any license keys required to authorize + use of the xNF software. This metadata will be used to facilitate + onboarding the xNF into the ONAP environment and automating processes + for putting the licenses into use and managing the full lifecycle of + the licenses. The details of this license model are described in + Tables C1 to C8 in the Appendix. Note: License metadata support in + ONAP is not currently available and planned for 1Q 2018. + +.. |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 + diff --git a/docs/Chapter7/index.rst b/docs/Chapter7/index.rst new file mode 100644 index 0000000..e5c1462 --- /dev/null +++ b/docs/Chapter7/index.rst @@ -0,0 +1,67 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. Copyright 2017 AT&T Intellectual Property. All rights reserved. + +ONAP Management Requirements +============================ + +.. toctree:: + :maxdepth: 2 + + Service-Design + VNF-On-boarding-and-package-management + Configuration-Management + Monitoring-And-Management + + +The ONAP platform is the part of the larger Network Function +Virtualization/Software Defined Network (NFV/SDN) ecosystem that +is responsible for the efficient control, operation and management +of Virtual Network Function (VNF) capabilities and functions. It +specifies standardized abstractions and interfaces that enable +efficient interoperation of the NVF/SDN ecosystem components. It +enables product/service independent capabilities for design, creation +and runtime lifecycle management (includes all aspects of installation, +change management, assurance, and retirement) of resources in NFV/SDN +environment (see ECOMP white paper ). These capabilities are provided +using two major architectural frameworks: (1) a Design Time Framework +to design, define and program the platform (uniform onboarding), and +(2) a Runtime Execution Framework to execute the logic programmed in +the design environment (uniform delivery and runtime lifecycle +management). The platform delivers an integrated information model +based on the VNF package to express the characteristics and behavior +of these resources in the Design Time Framework. The information model +is utilized by Runtime Execution Framework to manage the runtime +lifecycle of the VNFs. The management processes are orchestrated +across various modules of ONAP to instantiate, configure, scale, +monitor, and reconfigure the VNFs using a set of standard APIs +provided by the VNF developers. + +Although the guidelines and requirements specified in this document +were originally driven by the need to standardize and automate the +management of the virtualized environments (with VNFs) operated by +Service Providers, we believe that most of the requirements are equally +applicable to the operation of the physical network functions (PNFs), +those network functions provided by traditional physical network +elements (e.g. whitebox switches) or customized peripherals (e.g. a +video rendering engine for augmented reality). The primary area of +difference will be in how the network function is orchestrated into +place – VNFs can be much more dynamically created & placed by ONAP +to support varying geographic, availability and scalability needs, +whereas the PNFs have to be deployed a priori in specific locations +based on planning and engineering – their availability and scalability +will be determined by the capabilities offered by the PNFs. + +**PNF** is a vendor-provided Network Function(s) implemented using a +bundled set of hardware and software while VNFs utilize cloud resources +to provide Network Functions through virtualized software modules. PNF +can be supplied by a vendor as a Black BOX (provides no knowledge of its +internal characteristics, logic, and software design/architecture) or as +a White Box (provides detailed knowledge and access of its internal +components and logic) or as a Grey Box (provides limited knowledge and +access to its internal components). + +* Requirements that equally apply to both VNFs and PNFs are defined as + "The xNF MUST/SHOULD/..." +* Requirements that only apply to VNFs are defined as "The VNF MUST/SHOULD/..." +* Requirements that only apply to PNFs are defined as "The PNF MUST/SHOULD/..." -- cgit 1.2.3-korg