path: root/docs/Chapter7/VNF-On-boarding-and-package-management.rst

.. Modifications Copyright © 2017-2018 AT&T Intellectual Property.

.. Licensed under the Creative Commons License, Attribution 4.0 Intl.
   (the "License"); you may not use this documentation except in compliance
   with the License. You may obtain a copy of the License at

.. https://creativecommons.org/licenses/by/4.0/

.. Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.


VNF and PNF 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
^^^^^^^^^^^^^^^^^^^^

.. req::
    :id: R-66070
    :target: VNF HEAT PACKAGE
    :keyword: MUST
    :updated: dublin

    For HEAT package, the VNF Package **MUST** include VNF Identification Data to
    uniquely identify the resource for a given VNF provider. The identification
    data must include: an identifier for the VNF, the name of the VNF as was
    given by the VNF provider, VNF description, VNF provider, and version.

.. req::
    :id: R-69565
    :target: VNF or PNF DOCUMENTATION PACKAGE
    :keyword: MUST
    :updated: dublin

    The VNF or PNF Documentation Package **MUST** describe the VNF or PNF
    Management APIs, which must include information and tools for ONAP to
    deploy and configure (initially and ongoing) the VNF or PNF application(s)
    (e.g., NETCONF APIs) which includes a description of configurable
    parameters for the VNF or PNF and whether the parameters can be configured
    after VNF or PNF instantiation.

.. req::
    :id: R-00156
    :target: VNF or PNF DOCUMENTATION PACKAGE
    :keyword: MUST
    :updated: dublin

    The VNF or PNF Documentation Package **MUST** describe the VNF or PNF
    Management APIs, which must include information and tools for
    ONAP to monitor the health of the VNF or PNF (conditions that require
    healing and/or scaling responses).

.. req::
    :id: R-00068
    :target: VNF or PNF DOCUMENTATION PACKAGE
    :keyword: MUST
    :updated: dublin

    The VNF or PNF Documentation Package **MUST** include
    a description of parameters that can be monitored for the VNF or PNF
    and event records (status, fault, flow, session, call, control
    plane, etc.) generated by the VNF or PNF after instantiation.

.. req::
    :id: R-12678
    :target: VNF or PNF DOCUMENTATION PACKAGE
    :keyword: MUST
    :updated: dublin

    The VNF or PNF Documentation Package **MUST** include a
    description of runtime lifecycle events and related actions (e.g.,
    control responses, tests) which can be performed for the VNF or PNF.

.. req::
    :id: R-84366
    :target: VNF or PNF DOCUMENTATION PACKAGE
    :keyword: MUST
    :updated: dublin

    The VNF or PNF Documentation Package **MUST** describe the
    VNF or PNF Functional APIs that are utilized to build network and
    application services. This document describes the externally exposed
    functional inputs and outputs for the VNF or PNF, including interface
    format and protocols supported.

.. req::
    :id: R-36280
    :target: VNF or PNF DOCUMENTATION PACKAGE
    :keyword: MUST
    :updated: dublin

    The VNF or PNF Documentation Package **MUST** describe the
    VNF or PNF Functional Capabilities that are utilized to operationalize the
    VNF or PNF and compose complex services.

.. req::
    :id: R-98617
    :target: VNF PROVIDER
    :keyword: MUST
    :updated: dublin

    The VNF Provider **MUST** provide documentation regarding any dependency
    (e.g. affinity, anti-affinity) the VNF has on other VNFs and resources.

.. req::
    :id: R-22346
    :target: VNF or PNF PROVIDER
    :keyword: MUST
    :introduced: casablanca
    :updated: guilin
    :validation_mode: static

    The VNF or PNF Provider **MUST** provide :ref:`VES Event Registration <ves_event_registration_3_2>`
    for all VES events provided by that VNF or PNF.

.. req::
   :id: R-384337
   :target: VNF DOCUMENTATION PACKAGE
   :keyword: MUST
   :introduced: casablanca
   :updated: dublin

   The VNF Documentation Package **MUST** contain a list of the files within the VNF
   package that are static during the VNF's runtime.

.. req::
   :id: R-025941
   :target: VNF or PNF PROVIDER
   :keyword: MUST
   :updated: frankfurt
   :validation_mode: static
   :impacts: DCAE,Documentation,Integration,SDC

   The VNF or PNF PROVIDER **MUST** provide :ref:`FM_meta_data` to support the
   analysis of fault events delivered to DCAE. The metadata must be
   included in the VES Registration YAML file for each fault event
   supported by that VNF or PNF at onboarding time. The metadata must follow
   the VES Event Listener Specifications for Fault domain and VES Event
   Registration Specifications for YAML registration file format.


.. req::
   :id: R-816745
   :target: VNF or PNF PROVIDER
   :keyword: MUST
   :introduced: dublin
   :updated: frankfurt
   :validation_mode: static
   :impacts: DCAE,Documentation,Integration,SDC

   THe VNF or PNF PROVIDER **MUST** provide PM Meta Data (:ref:`PM_Dictionary`)
   to support the analysis of PM data delivered to DCAE.
   The PM Dictionary is to be provided as a separate YAML artifact at
   onboarding and must follow the VES Event Registration Specification
   which contain the format and content required.

Resource Configuration
^^^^^^^^^^^^^^^^^^^^^^


.. req::
    :id: R-89571
    :target: VNF or PNF PROVIDER
    :keyword: MUST
    :updated: frankfurt

    The VNF or PNF PROVIDER **MUST** provide artifacts for configuration
    management using at least one of the following technologies;
    a) Netconf/YANG, b) Chef, or c) Ansible.


Configuration Management via NETCONF/YANG
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. req::
    :id: R-30278
    :target: VNF or PNF PROVIDER
    :keyword: SHOULD
    :updated: frankfurt

    The VNF or PNF PROVIDER **SHOULD** provide a Resource/Device YANG model
    as a foundation for creating the YANG model for configuration.

Configuration Management via Chef
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


.. req::
    :id: R-13390
    :target: VNF or PNF
    :keyword: MUST
    :updated: dublin

    The VNF or PNF provider **MUST** provide cookbooks to be loaded
    on the appropriate Chef Server.

.. req::
    :id: R-18525
    :target: VNF or PNF
    :keyword: MUST
    :updated: dublin

    The VNF or PNF provider **MUST** provide a JSON file for each
    supported action for the VNF or PNF. 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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


.. req::
    :id: R-75608
    :target: VNF or PNF
    :keyword: MUST
    :updated: dublin

    The VNF or PNF provider **MUST** provide playbooks to be loaded
    on the appropriate Ansible Server.

.. req::
    :id: R-16777
    :target: VNF or PNF
    :keyword: MUST
    :updated: dublin

    The VNF or PNF provider **MUST** provide a JSON file for each
    supported action for the VNF or PNF. 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.

.. req::
    :id: R-46567
    :target: VNF or PNF
    :keyword: MUST
    :updated: dublin

    The VNF or PNF Package **MUST** include configuration scripts
    for boot sequence and configuration.

.. req::
    :id: R-16065
    :target: VNF or PNF
    :keyword: MUST
    :updated: dublin

    The VNF or PNF provider **MUST** provide configurable parameters
    (if unable to conform to YANG model) including VNF or PNF attributes/parameters
    and valid values, dynamic attributes and cross parameter dependencies
    (e.g., customer provisioning data).

Resource Control Loop
^^^^^^^^^^^^^^^^^^^^^


.. req::
    :id: R-22888
    :target: VNF or PNF DOCUMENTATION PACKAGE
    :keyword: MUST
    :updated: dublin

    The VNF or PNF Documentation Package **MUST** provide the VNF or PNF
    Policy Description to manage the VNF or PNF runtime lifecycle. The document
    must include a description of how the policies (conditions and actions)
    are implemented in the VNF or PNF.

.. req::
    :id: R-01556
    :target: VNF or PNF DOCUMENTATION PACKAGE
    :keyword: MUST
    :updated: dublin

    The VNF or PNF Documentation Package **MUST** describe the
    fault, performance, capacity events/alarms and other event records
    that are made available by the VNF or PNF.

.. req::
    :id: R-16875
    :target: VNF or PNF DOCUMENTATION PACKAGE
    :keyword: MUST
    :updated: dublin

    The VNF or PNF Documentation Package **MUST** include documentation which must
    include a unique identification string for the specific VNF or PNF, a description
    of the problem that caused the error, and steps or procedures to perform
    Root Cause Analysis and resolve the issue.

.. req::
    :id: R-35960
    :target: VNF or PNF
    :keyword: MUST
    :updated: dublin

    The VNF or PNF 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.

.. req::
    :id: R-42018
    :target: VNF or PNF
    :keyword: MUST
    :updated: el alto

    The VNF or PNF Package **MUST** include documentation which must include
    all events (fault, measurement for VNF or PNF Scaling, Syslogs, State Change
    and Mobile Flow), that need to be collected at each VM, VNFC (defined in `VNF Guidelines <https://onap.readthedocs.io/en/latest/submodules/vnfrqts/guidelines.git/docs/vnf_guidelines.html>`__ ) and for the overall VNF or PNF.


.. req::
    :id: R-01478
    :target: VNF or PNF DOCUMENTATION PACKAGE
    :keyword: MUST
    :updated: dublin

    The VNF or PNF Documentation Package **MUST** describe all
    parameters that are available to monitor the VNF or PNF after instantiation
    (includes all counters, OIDs, PM data, KPIs, etc.) that must be
    collected for reporting purposes.

.. req::
    :id: R-73560
    :target: VNF or PNF
    :keyword: MUST
    :updated: dublin

    The VNF or PNF Package **MUST** include documentation about monitoring
    parameters/counters exposed for virtual resource management and VNF or PNF
    application management.

.. req::
    :id: R-90632
    :target: VNF
    :keyword: MUST
    :updated: dublin

    The VNF Package **MUST** include documentation about KPIs and
    metrics that need to be collected at each VM for capacity planning
    and performance management purposes.

.. req::
    :id: R-86235
    :target: VNF or PNF
    :keyword: MUST
    :updated: dublin

    The VNF or PNF 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 VNF or PNF and those that must be exercised by the VNF or PNF in order to perform
    its function.

.. req::
    :id: R-33904
    :target: VNF or PNF
    :keyword: MUST
    :updated: dublin

    The VNF or PNF Package **MUST** include documentation for each KPI, provide
    lower and upper limits.

.. req::
    :id: R-53598
    :target: VNF or PNF DOCUMENTATION PACKAGE
    :keyword: MUST
    :updated: dublin

    The VNF or PNF Documentation Package **MUST**, when relevant,
    provide a threshold crossing alert point for each KPI and describe the
    significance of the threshold crossing.

.. req::
    :id: R-69877
    :target: VNF or PNF
    :keyword: MUST
    :updated: dublin

    The VNF or PNF Package **MUST** include documentation for each KPI,
    identify the suggested actions that need to be performed when a
    threshold crossing alert event is recorded.

.. req::
    :id: R-22680
    :target: VNF or PNF DOCUMENTATION PACKAGE
    :keyword: MUST
    :updated: dublin

    The VNF or PNF Documentation Package **MUST** describe
    any requirements for the monitoring component of tools for Network
    Cloud automation and management to provide these records to components
    of the VNF or PNF.

.. req::
    :id: R-33694
    :target: VNF or PNF
    :keyword: MUST
    :updated: dublin

    The VNF or PNF Package **MUST** include documentation to when applicable,
    provide calculators needed to convert raw data into appropriate reporting
    artifacts.

.. req::
    :id: R-56815
    :target: VNF or PNF DOCUMENTATION PACKAGE
    :keyword: MUST
    :updated: dublin

    The VNF or PNF Documentation Package **MUST** describe
    supported VNF or PNF scaling capabilities and capacity limits (e.g., number
    of users, bandwidth, throughput, concurrent calls).

.. req::
    :id: R-48596
    :target: VNF or PNF DOCUMENTATION PACKAGE
    :keyword: MUST
    :updated: dublin

    The VNF or PNF Documentation Package **MUST** describe
    the characteristics for the VNF or PNF reliability and high availability.



Compute, Network, and Storage Requirements
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


.. req::
    :id: R-35851
    :target: VNF HEAT PACKAGE
    :keyword: MUST
    :updated: dublin

    The VNF HEAT Package **MUST** include VNF topology that describes basic
    network and application connectivity internal and external to the VNF
    including Link type, KPIs, Bandwidth, latency, jitter, QoS (if applicable)
    for each interface.

.. req::
    :id: R-97102
    :target: VNF
    :keyword: MUST

    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.

.. req::
    :id: R-20204
    :target: VNF
    :keyword: MUST

    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.

.. req::
    :id: R-44896
    :target: VNF
    :keyword: MUST

    The VNF Package **MUST** include VM requirements via a Heat
    template that provides the necessary data for high availability
    redundancy model.

.. req::
    :id: R-55802
    :target: VNF
    :keyword: MUST

    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*.

.. req::
    :id: R-26881
    :target: VNF
    :keyword: MUST
    :updated: dublin

    The VNF provider **MUST** provide the binaries and images
    needed to instantiate the VNF (VNF and VNFC images).

.. req::
    :id: R-96634
    :target: VNF or PNF PROVIDER
    :keyword: MUST
    :updated: dublin

    The VNF or PNF Provider **MUST** provide human readable documentation
    (not in the on-boarding package) to describe scaling capabilities to manage
    scaling characteristics of the VNF or PNF.


Testing
^^^^^^^

.. req::
    :id: R-43958
    :target: VNF DOCUMENTATION PACKAGE
    :keyword: MUST
    :updated: dublin

    The VNF Documentation Package **MUST** describe
    the tests that were conducted by the VNF provider and the test results.

.. req::
    :id: R-04298
    :target: VNF
    :keyword: MUST
    :updated: dublin

    The VNF provider **MUST** provide their testing scripts to
    support testing.

.. req::
    :id: R-58775
    :target: VNF
    :keyword: MUST
    :updated: dublin

    The VNF provider **MUST** provide software components that
    can be packaged with/near the VNF, if needed, to simulate any functions
    or systems that connect to the VNF system under test. This component is
    necessary only if the existing testing environment does not have the
    necessary simulators.

Licensing Requirements
^^^^^^^^^^^^^^^^^^^^^^
ONAP can support external licensing management solutions. For example, a vendor-specific solution where
the VNF or PNF obtains its licenses from an external source and ONAP licensing management solution is not used. 
If the licensing management solution is provided by ONAP, then ONAP operators will build the VNF license using SDC during onboarding.
Refer to the ONAP User Guide for details.
The operators require certain information regarding VNF licences.
This information currently is delivered out of band.
HEAT or TOSCA VNF packages may support such information in future.
VNF licensing behavior also has some constraints.

.. req::
    :id: R-85653
    :target: VNF or PNF
    :keyword: MUST
    :updated: guilin

    If ONAP licensing management solution is used, then the VNF or PNF **MUST** provide metrics (e.g., number of sessions,
    number of subscribers, number of seats, etc.) to ONAP for tracking
    every license.

.. req::
    :id: R-40827
    :target: VNF or PNF
    :keyword: MUST
    :updated: dublin

    The VNF or PNF provider **MUST** enumerate all of the open
    source licenses their VNF or PNF(s) incorporate.

.. req::
    :id: R-44569
    :target: VNF or PNF
    :keyword: MUST NOT
    :updated: guilin

    If ONAP licensing management solution is used, then the VNF or PNF provider **MUST NOT** require additional
    infrastructure such as a VNF or PNF provider license server for VNF or PNF provider
    functions and metrics.

.. req::
    :id: R-13613
    :target: VNF
    :keyword: MUST
    :updated: guilin

    The VNF **MUST** provide clear measurements for licensing
    purposes if needed to allow automated scale up/down by the management system.

.. req::
    :id: R-27511
    :target: VNF
    :keyword: MUST

    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.

.. req::
    :id: R-85991
    :target: VNF or PNF PROVIDER
    :keyword: MUST
    :updated: guilin

    If the VNF or PNF requires a license then the VNF or PNF provider **MUST** provide a universal license key
    per VNF or PNF to be used as needed by services (i.e., not tied to a VM
    instance) as the recommended solution. The VNF or PNF provider may provide
    pools of Unique VNF or PNF License Keys, where there is a unique key for
    each VNF or PNF instance as an alternate solution. In all cases, licensing issues should
    be resolved without interrupting in-service VNFs or PNFs.

.. req::
    :id: R-47849
    :target: VNF or PNF
    :keyword: MUST
    :updated: guilin

    If ONAP licensing management solution is used, then the VNF or PNF provider
    **MUST** support the metadata about licenses (and their applicable
    entitlements) as defined in the
    `ONAP License Management Information Model <https://docs.onap.org/projects/onap-modeling-modelspec/en/latest/ONAP%20Model%20Spec/im/License/LicenseModel.html>`__,
    and any license keys required to authorize use of the VNF or PNF software.
    This metadata will be used to facilitate onboarding the VNF or PNF into the
    ONAP environment and automating processes for putting the licenses into use
    and managing the full lifecycle of the licenses.