VNF or PNF Requirements Documentation

Purpose

  • The purpose of these requirements is to accelerate adoption of VNF or PNF best practices which will increase innovation, minimize customization needed to onboard VNFs or PNFs as well as reduce implementation complexity, time and cost for all impacted stakeholders.

  • The consolidated requirements provide common VNF or PNF requirements across the industry in order to drive interoperability, simplify management, and reduce cost to build, deploy and manage VNFs or PNFs.

  • These requirements serve multiple purposes:
    • Primarily it provides a detailed list of requirements for VNF or PNF providers to meet to be compatible with ONAP; VNF or PNF providers will use the VNF or PNF requirements to build VNFs/PNFs that are compatible with ONAP.

    • It can also serve as a list of requirements that service providers can use in RFPs for selecting VNFs/PNFs.

    • It will also be used as a basis for testing and certification of VNFs or PNFs for compliance with ONAP; ONAP projects such as the VNF Validation Project will uses these VNFs or PNFs requirements to build test cases to validate VNFs or PNFs for compliance with ONAP.

Scope

  • The audience for this document are VNF or PNF providers, NCSPs and other interested 3rd parties who need to know the design, build and lifecycle management requirements for VNFs or PNFs to be compliant with ONAP.

  • These requirements are strictly from a standpoint of what the VNF or PNF developer needs to know to operate and be compliant with ONAP.

  • Requirements that are not applicable to VNF or PNF providers such as those that applicable to service providers are not included in this document.

  • These requirements are applicable to the current release of ONAP.

  • Scope of the ONAP versions/release and future functionality

  • The VNF Requirements should include support for the functionality of the ONAP E-E use cases.

  • These requirements apply to VNFs or PNFs at both ONAP Design-Time and ONAP Run-Time.

  • Network Service Descriptions are beyond the scope of these requirements.

References

This section contains a list of normative and informative references along with information on acquiring the identified references. Normative references are required to be implemented by this document. Informative references are for informational purposes only.

Release Notes

Release notes for the VNF Requirements can be found here

Glossary

ACL

Access Control List

ACME

Automated Certificate Management

API

Application Programming Interface

BGP

Border Gateway Protocol

CA

Certificate Authority

CCL

Commerce Control List

CLLI

Common Language Location Identification

CMOS

Complementary metal-oxide-semiconductor

CMP

Certificate Management Protocol

CRL

Certificate Revocation List

CSAR

Cloud Service Archive

DBaaS

Database as a Service

DDOS

Distributer Denial-of-Service

DNS

Domain Name System

DPDK

Data Plane Development Kit

DPI

Deep Packet Inspection

DPM

Data Position Measurement

DSS

Digital Signature Services

ECCN

Export Control Classification Number

EMS

Element Management Systems

EVC

Ethernet Virtual Connection

FIPS

Federal Information Processing Standards

FQDN

Fully Qualified Domain Name

FTPES

File Transfer Protocol Secure

GPB

Google Protocol Buffers

GUI

Graphical User Interface

GVNFM

Generic Virtualized Network Function Manager

HSM

Hardware Security Module

IDAM

Identity and Access Management

IPSec

IP Security

JMS

Java Message Service

JSON

JavaScript Object Notation

KPI

Key Performance Indicator

LCM

Life Cycle Management

LCP

Link Control Protocol

LDAP

Lightweight Directory Access Protocol

LTE

Long-Term Evolution

MD5

Message-Digest Algorithm

MIME

Multipurpose Internet Mail Extensions

MTTI

Mean Time to Identify

MTTR

Mean Time to Repair

NCSP

Network Cloud Service Providers

NFS

Network File System

NFV

Network Functions Virtualization

NIC

Network Interface Controller

NIST

National Institute of Standards and Technology

NTP

Network Time Protocol

OA&M

Operations, administration and management

OAuth

Open Authorization

OID

Object Identifier

OPNFV

Open Platform for Network Functions Virtualization

OWASP

Open Web Application Security Project

PCEF

Policy and Charging Enforcement Function

PCRF

Policy and Charging Rules Function

PKI

Public Key Infrastructure

PM

Performance Monitoring

PNF

Physical Network Function

PnP

Plug and Play

QoS

Quality of Service

RAN

Radio Access Network

RBAC

Role-Based Access Control

RTPM

Real Time Performance Monitoring

RFC

Remote Function Call

RFP

Request For Proposal

RPC

Remote Procedure Call

SAML

Security Assertion Markup Language

SCEP

Simple Certificate Enrollment Protocol

SDN

Software-Defined Networking

SFTP

SSH File Transfer Protocol

SHA

Secure Hash Algorithm

SLA

Service Level Agreement

SNMP

Simple Network Management Protocol

SP

Service Provider

SPI

Sensitive Personal Information

SR-IOV

Single-Root Input/Output Virtualization

SSL

Secure Sockets Layer

SSH

Secure Shell

TACACS

Terminal Access Controller Access Control System

TCA

Threshold Crossing Alert

TLS

Transport Layer Security

TOSCA

Topology and Orchestration Specification for Cloud Applications

TPM

Trusted Platform Module

UUID

Universally Unique Identifier

VDU

Virtualization Deployment Unit

VES

VNF Event Streaming

VLAN

Virtual LAN

VM

Virtual Machine

VNF

Virtual Network Function

VNFC

Virtual Network Function Component

VNF-D

Virtual Network Function Descriptor

VPN

Virtual Private Network

XML

eXtensible Markup Language

YAML

YAML Ain’t Markup Languag

YANG

Yet Another Next Generation

NFVI

Network Function Virtualization Infrastructure

VNFC

Virtualized Network Function Components

MANO

Management And Network Orchestration

VNFM

Virtualized Network Function Manager

BUM

Broadcast, Unknown-Unicast and Multicast traffic

Normative References

Reference

Description

[RFC 2119]

IETF RFC2119, Key words for use in RFCs to Indicate Requirement Levels, S. Bradner, March 1997.

Informative References

Reference

Description

Reference Acquisition

IETF Specifications:

  • Internet Engineering Task Force (IETF) Secretariat, 48377 Fremont Blvd., Suite 117, Fremont, California 94538, USA; Phone: +1-510-492-4080, Fax: +1-510-492-4001.

Submitting Feedback

Please refer to the VNF Requirements - How to Contribute guide for instructions on how to create issues or contribute changes to the VNF Requirements project.

Introduction

  • Requirements are identified as either MUST, MUST NOT, SHOULD, SHOULD NOT, or MAY as defined in RFC 2119.

  • Requirements should be targeted to a restricted set of nouns related to VNFs or PNFs and within the control of the VNF or PNF provider. The current list of VNF or PNF Requirement targets is:

Target

When is it used

VNF

Functional behavior of a VNF

PNF

Functional behavior of a PNF

VNF or PNF

Function behavior to both VNFs and PNFs

{VNF|PNF|VNF or PNF} PROVIDER

Something the provider of the VNF, PNF, or VNF/PNF must do. This is often used to describe delivering artifacts or specific documentation that may not be part of a standard VNF package format.

VNF HEAT PACKAGE

The archive/zip file that includes Heat templates. The subject of the requirement my be further refined (Ex: Heat Environment File), but the metadata stay at the package level.

{VNF|PNF|VNF or PNF} CSAR PACKAGE

A requirement related to the contents of what should be in the CSAR package. The subject of the requirement might be further refined (ex: CSAR manifest file, VNF Descriptor, etc.), but the :target: metadata would stay at the package level.

{VNF|PNF|VNF or PNF} DOCUMENTATION PACKAGE

VNFs and PNFs are expected to provide human readable documentation. This may come in the form of URLs or pdfs. This documentation may vary by VNF or PNF. The structure of the documentation is intended for human consumption and is not highly structured for machine ingestion. The human readable documentation may be provided through the RFP/acquisition process.

  • Chapter 4 contains the VNF or PNF requirements involving the design and development of VNFs or PNF. These requirements help VNFs or PNFs operate efficiently within a cloud environment. Requirements cover design, resiliency, security, modularity and DevOps.

  • Chapter 5 describes the different data models the VNF or PNF provider needs to understand. There are currently 2 models described in this document:

    • The first model is the onboarding package data model. This is a TOSCA model that will describe how all the elements passed from the VNF or PNF Provider to the Service provider should be formatted and packaged.

    • The second model is HEAT template used for orchestrating and instantiating virtual resources in an OpenStack environment. At this time the HEAT files will be passed to the Service provider as a data element within the TOSCA onboarding package.

  • Chapter 6 details the requirements specific to an implementation. The current implementations documented are OpenStack and Azure.

  • Chapter 7 provides the comprehensive set of requirements for xNFs to be on-boarded, configured and managed by ONAP.

  • Chapter 8 is the appendix that provide a number of detailed data record formats. It also contains a list of the requirements that are listed in the other chapters as well as examples and models that are referenced throughout the rest of the chapters.

VNF Development Requirements

VNF Design

Services are composed of VNFs and common components and are designed to be agnostic of the location to leverage capacity where it exists in the Network Cloud. VNFs can be instantiated in any location that meets the performance and latency requirements of the service.

A key design principle for virtualizing services is decomposition of network functions using NFV concepts into granular VNFs. This enables instantiating and customizing only essential functions as needed for the service, thereby making service delivery more nimble. It provides flexibility of sizing and scaling and also provides flexibility with packaging and deploying VNFs as needed for the service. It enables grouping functions in a common cloud data center to minimize inter-component latency. The VNFs should be designed with a goal of being modular and reusable to enable using best-in-breed vendors.

Section 4.1 VNF Design in VNF Guidelines describes the overall guidelines for designing VNFs from VNF Components (VNFCs). Below are more detailed requirements for composing VNFs.

VNF Design Requirements

Requirement: R-58421 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD

The VNF SHOULD be decomposed into granular re-usable VNFCs.

Requirement: R-82223 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST be decomposed if the functions have significantly different scaling characteristics (e.g., signaling versus media functions, control versus data plane functions).

Requirement: R-16496 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST enable instantiating only the functionality that is needed for the decomposed VNF (e.g., if transcoding is not needed it should not be instantiated).

Requirement: R-02360 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNFC MUST be designed as a standalone, executable process.

Requirement: R-34484 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD

The VNF SHOULD create a single component VNF for VNFCs that can be used by other VNFs.

Requirement: R-23035 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST be designed to scale horizontally (more instances of a VNF or VNFC) and not vertically (moving the existing instances to larger VMs or increasing the resources within a VM) to achieve effective utilization of cloud resources.

Requirement: R-30650 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST utilize cloud provided infrastructure and VNFs (e.g., virtualized Local Load Balancer) as part of the VNF so that the cloud can manage and provide a consistent service resiliency and methods across all VNF’s.

Requirement: R-12709 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD

The VNFC SHOULD be independently deployed, configured, upgraded, scaled, monitored, and administered by ONAP.

Requirement: R-37692 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNFC MUST provide API versioning to allow for independent upgrades of VNFC.

Requirement: R-86585 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD

The VNFC SHOULD minimize the use of state within a VNFC to facilitate the movement of traffic from one instance to another.

Requirement: R-65134 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD

The VNF SHOULD maintain state in a geographically redundant datastore that may, in fact, be its own VNFC.

Requirement: R-75850 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD

The VNF SHOULD decouple persistent data from the VNFC and keep it in its own datastore that can be reached by all instances of the VNFC requiring the data.

Requirement: R-88199 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST utilize a persistent datastore service that can meet the data performance/latency requirements. (For example: Datastore service could be a VNFC in VNF or a DBaaS in the Cloud execution environment)

Requirement: R-99656 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST NOT terminate stable sessions if a VNFC instance fails.

Requirement: R-84473 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST enable DPDK in the guest OS for VNF’s requiring high packets/sec performance. High packet throughput is defined as greater than 500K packets/sec.

Requirement: R-54430 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST use the NCSP’s supported library and compute flavor that supports DPDK to optimize network efficiency if using DPDK. 1

Requirement: R-18864 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT

The VNF MUST NOT use technologies that bypass virtualization layers (such as SR-IOV) unless approved by the NCSP (e.g., if necessary to meet functional or performance requirements).

Requirement: R-64768 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST limit the size of application data packets to no larger than 9000 bytes for SDN network-based tunneling when guest data packets are transported between tunnel endpoints that support guest logical networks.

Requirement: R-74481 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT

The VNF MUST NOT require the use of a dynamic routing protocol unless necessary to meet functional requirements.

1

Refer to NCSP’s Network Cloud specification

VNF Resiliency

The VNF is responsible for meeting its resiliency goals and must factor in expected availability of the targeted virtualization environment. This is likely to be much lower than found in a traditional data center. Resiliency is defined as the ability of the VNF to respond to error conditions and continue to provide the service intended. A number of software resiliency dimensions have been identified as areas that should be addressed to increase resiliency. As VNFs are deployed into the Network Cloud, resiliency must be designed into the VNF software to provide high availability versus relying on the Network Cloud to achieve that end.

Section 4.2 Resiliency in VNF Guidelines describes the overall guidelines for designing VNFs to meet resiliency goals. Below are more detailed resiliency requirements for VNFs.

All Layer Redundancy

Design the VNF to be resilient to the failures of the underlying virtualized infrastructure (Network Cloud). VNF design considerations would include techniques such as multiple vLANs, multiple local and geographic instances, multiple local and geographic data replication, and virtualized services such as Load Balancers.

All Layer Redundancy Requirements

Requirement: R-52499 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST meet their own resiliency goals and not rely on the Network Cloud.

Requirement: R-42207 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST design resiliency into a VNF such that the resiliency deployment model (e.g., active-active) can be chosen at run-time.

Requirement: R-03954 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST survive any single points of failure within the Network Cloud (e.g., virtual NIC, VM, disk failure).

Requirement: R-89010 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST survive any single points of software failure internal to the VNF (e.g., in memory structures, JMS message queues).

Requirement: R-67709 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST be designed, built and packaged to enable deployment across multiple fault zones (e.g., VNFCs deployed in different servers, racks, OpenStack regions, geographies) so that in the event of a planned/unplanned downtime of a fault zone, the overall operation/throughput of the VNF is maintained.

Requirement: R-35291 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST support the ability to failover a VNFC automatically to other geographically redundant sites if not deployed active-active to increase the overall resiliency of the VNF.

Requirement: R-36843 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST support the ability of the VNFC to be deployable in multi-zoned cloud sites to allow for site support in the event of cloud zone failure or upgrades.

Requirement: R-00098 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT

The VNF MUST NOT impact the ability of the VNF to provide service/function due to a single container restart.

Requirement: R-79952 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD

The VNF SHOULD support container snapshots if not for rebuild and evacuate for rollback or back out mechanism.

Minimize Cross Data-Center Traffic

Avoid performance-sapping data center-to-data center replication delay by applying techniques such as caching and persistent transaction paths - Eliminate replication delay impact between data centers by using a concept of stickiness (i.e., once a client is routed to data center “A”, the client will stay with Data center “A” until the entire session is completed).

Minimize Cross Data-Center Traffic Requirements

Requirement: R-92935 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD

The VNF SHOULD minimize the propagation of state information across multiple data centers to avoid cross data center traffic.

Application Resilient Error Handling

Ensure an application communicating with a downstream peer is equipped to intelligently handle all error conditions. Make sure code can handle exceptions seamlessly - implement smart retry logic and implement multi-point entry (multiple data centers) for back-end system applications.

Application Resilient Error Handling Requirements

Requirement: R-26371 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST detect communication failure for inter VNFC instance and intra/inter VNF and re-establish communication automatically to maintain the VNF without manual intervention to provide service continuity.

Requirement: R-18725 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST handle the restart of a single VNFC instance without requiring all VNFC instances to be restarted.

Requirement: R-06668 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST handle the start or restart of VNFC instances in any order with each VNFC instance establishing or re-establishing required connections or relationships with other VNFC instances and/or VNFs required to perform the VNF function/role without requiring VNFC instance(s) to be started/restarted in a particular order.

Requirement: R-80070 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST handle errors and exceptions so that they do not interrupt processing of incoming VNF requests to maintain service continuity (where the error is not directly impacting the software handling the incoming request).

Requirement: R-32695 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST provide the ability to modify the number of retries, the time between retries and the behavior/action taken after the retries have been exhausted for exception handling to allow the NCSP to control that behavior, where the interface and/or functional specification allows for altering behaviour.

Requirement: R-48356 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST fully exploit exception handling to the extent that resources (e.g., threads and memory) are released when no longer needed regardless of programming language.

Requirement: R-67918 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST handle replication race conditions both locally and geo-located in the event of a data base instance failure to maintain service continuity.

Requirement: R-36792 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST automatically retry/resubmit failed requests made by the software to its downstream system to increase the success rate.

Requirement: R-70013 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT

The VNF MUST NOT require any manual steps to get it ready for service after a container rebuild.

Requirement: R-65515 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST provide a mechanism and tool to start VNF containers (VMs) without impacting service or service quality assuming another VNF in same or other geographical location is processing service requests.

Requirement: R-94978 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST provide a mechanism and tool to perform a graceful shutdown of all the containers (VMs) in the VNF without impacting service or service quality assuming another VNF in same or other geographical location can take over traffic and process service requests.

System Resource Optimization

Ensure an application is using appropriate system resources for the task at hand; for example, do not use network or IO operations inside critical sections, which could end up blocking other threads or processes or eating memory if they are unable to complete. Critical sections should only contain memory operation, and should not contain any network or IO operation.

System Resource Optimization Requirements

Requirement: R-22059 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT

The VNF MUST NOT execute long running tasks (e.g., IO, database, network operations, service calls) in a critical section of code, so as to minimize blocking of other operations and increase concurrent throughput.

Requirement: R-63473 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST automatically advertise newly scaled components so there is no manual intervention required.

Requirement: R-74712 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST utilize FQDNs (and not IP address) for both Service Chaining and scaling.

Requirement: R-41159 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST deliver any and all functionality from any VNFC in the pool (where pooling is the most suitable solution). The VNFC pool member should be transparent to the client. Upstream and downstream clients should only recognize the function being performed, not the member performing it.

Requirement: R-85959 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD

The VNF SHOULD automatically enable/disable added/removed sub-components or component so there is no manual intervention required.

Requirement: R-06885 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD

The VNF SHOULD support the ability to scale down a VNFC pool without jeopardizing active sessions. Ideally, an active session should not be tied to any particular VNFC instance.

Requirement: R-12538 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD

The VNF SHOULD support load balancing and discovery mechanisms in resource pools containing VNFC instances.

Requirement: R-98989 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD

The VNF SHOULD utilize resource pooling (threads, connections, etc.) within the VNF application so that resources are not being created and destroyed resulting in resource management overhead.

Requirement: R-55345 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD

The VNF SHOULD use techniques such as “lazy loading” when initialization includes loading catalogues and/or lists which can grow over time, so that the VNF startup time does not grow at a rate proportional to that of the list.

Requirement: R-35532 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD

The VNF SHOULD release and clear all shared assets (memory, database operations, connections, locks, etc.) as soon as possible, especially before long running sync and asynchronous operations, so as to not prevent use of these assets by other entities.

Application Configuration Management

Leverage configuration management audit capability to drive conformity to develop gold configurations for technologies like Java, Python, etc.

Application Configuration Management Requirements

Requirement: R-77334 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST allow configurations and configuration parameters to be managed under version control to ensure consistent configuration deployment, traceability and rollback.

Requirement: R-99766 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST allow configurations and configuration parameters to be managed under version control to ensure the ability to rollback to a known valid configuration.

Requirement: R-73583 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST allow changes of configuration parameters to be consumed by the VNF without requiring the VNF or its sub-components to be bounced so that the VNF availability is not effected.

Intelligent Transaction Distribution & Management

Leverage Intelligent Load Balancing and redundant components (hardware and modules) for all transactions, such that at any point in the transaction: front end, middleware, back end – a failure in any one component does not result in a failure of the application or system; i.e., transactions will continue to flow, albeit at a possibly reduced capacity until the failed component restores itself. Create redundancy in all layers (software and hardware) at local and remote data centers; minimizing interdependencies of components (i.e. data replication, deploying non-related elements in the same container).

Intelligent Transaction Distribution & Management Requirements

Requirement: R-21558 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD

The VNF SHOULD use intelligent routing by having knowledge of multiple downstream/upstream endpoints that are exposed to it, to ensure there is no dependency on external services (such as load balancers) to switch to alternate endpoints.

Requirement: R-08315 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD

The VNF SHOULD use redundant connection pooling to connect to any backend data source that can be switched between pools in an automated/scripted fashion to ensure high availability of the connection to the data source.

Requirement: R-27995 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD

The VNF SHOULD include control loop mechanisms to notify the consumer of the VNF of their exceeding SLA thresholds so the consumer is able to control its load against the VNF.

Deployment Optimization

Reduce opportunity for failure, by human or by machine, through smarter deployment practices and automation. This can include rolling code deployments, additional testing strategies, and smarter deployment automation (remove the human from the mix).

Deployment Optimization Requirements

Requirement: R-73364 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST support at least two major versions of the VNF software and/or sub-components to co-exist within production environments at any time so that upgrades can be applied across multiple systems in a staggered manner.

Requirement: R-02454 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST support the existence of multiple major/minor versions of the VNF software and/or sub-components and interfaces that support both forward and backward compatibility to be transparent to the Service Provider usage.

Requirement: R-57855 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST support hitless staggered/rolling deployments between its redundant instances to allow “soak-time/burn in/slow roll” which can enable the support of low traffic loads to validate the deployment prior to supporting full traffic loads.

Requirement: R-64445 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST support the ability of a requestor of the service to determine the version (and therefore capabilities) of the service so that Network Cloud Service Provider can understand the capabilities of the service.

Requirement: R-56793 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST test for adherence to the defined performance budgets at each layer, during each delivery cycle with delivered results, so that the performance budget is measured and the code is adjusted to meet performance budget.

Requirement: R-77667 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST test for adherence to the defined performance budget at each layer, during each delivery cycle so that the performance budget is measured and feedback is provided where the performance budget is not met.

Requirement: R-49308 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD

The VNF SHOULD test for adherence to the defined resiliency rating recommendation at each layer, during each delivery cycle with delivered results, so that the resiliency rating is measured and the code is adjusted to meet software resiliency requirements.

Requirement: R-16039 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD

The VNF SHOULD test for adherence to the defined resiliency rating recommendation at each layer, during each delivery cycle so that the resiliency rating is measured and feedback is provided where software resiliency requirements are not met.

Monitoring & Dashboard

Promote dashboarding as a tool to monitor and support the general operational health of a system. It is critical to the support of the implementation of many resiliency patterns essential to the maintenance of the system. It can help identify unusual conditions that might indicate failure or the potential for failure. This would contribute to improve Mean Time to Identify (MTTI), Mean Time to Repair (MTTR), and post-incident diagnostics.

Monitoring & Dashboard Requirements

Requirement: R-34957 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: dublin

The VNF MUST provide a method of metrics gathering for each layer’s performance to identify variances in the allocations so they can be addressed.

Requirement: R-49224 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST provide unique traceability of a transaction through its life cycle to ensure quick and efficient troubleshooting.

Requirement: R-52870 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST provide a method of metrics gathering and analysis to evaluate the resiliency of the software from both a granular as well as a holistic standpoint. This includes, but is not limited to thread utilization, errors, timeouts, and retries.

Requirement: R-92571 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST provide operational instrumentation such as logging, so as to facilitate quick resolution of issues with the VNF to provide service continuity.

Requirement: R-48917 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST monitor for and alert on (both sender and receiver) errant, running longer than expected and missing file transfers, so as to minimize the impact due to file transfer errors.

Requirement: R-28168 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD

The VNF SHOULD use an appropriately configured logging level that can be changed dynamically, so as to not cause performance degradation of the VNF due to excessive logging.

Requirement: R-87352 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD

The VNF SHOULD utilize Cloud health checks, when available from the Network Cloud, from inside the application through APIs to check the network connectivity, dropped packets rate, injection, and auto failover to alternate sites if needed.

Requirement: R-16560 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD

The VNF SHOULD conduct a resiliency impact assessment for all inter/intra-connectivity points in the VNF to provide an overall resiliency rating for the VNF to be incorporated into the software design and development of the VNF.

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.

Evacuate(VM): The Controller client is requesting moving a specified VM from its current host to another (when the host is down). Moving from a specified Host will be supported at in a later release (Openstack).

Migrate (VM): The Controller client is requesting migrating a running target VM from its current host to another. Migrating a running target VM from a specified Host will be supported at in a later release (Openstack).

Reboot(VM): The Controller client is requesting to reboot the VM. Options are soft (graceful) or hard (Openstack).

Rebuild (VM): The Controller client is recreating a target VM instance to a known (good) state (Openstack).

Restart (VM): The Controller client is requesting to restart the VM (Openstack).

Snapshot (VM): The Controller client is requesting to create a snapshot of a VNF or VM and store it (Openstack).

Start (VM): The Controller client is requesting to start the VM (Openstack).

Stop (VM): The Controller client is requesting to stop the VM (Openstack).

Requirement: R-11790 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST support ONAP Controller’s Restart (stop/start or reboot) command.

Requirement: R-56218 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

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.

Requirement: R-38001 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST support ONAP Controller’s Rebuild command.

Requirement: R-76901 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST support a container rebuild mechanism based on existing image (e.g. Glance image in Openstack environment) or a snapshot.

Requirement: R-46851 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: casablanca

The VNF MUST support ONAP Controller’s Evacuate command.

Requirement: R-48761 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: casablanca

The VNF MUST support ONAP Controller’s Snapshot command.

VNF Security

The objective of this section is to provide the key security requirements that need to be met by VNFs. The security requirements are grouped into five areas as listed below. Other security areas will be addressed in future updates. These security requirements are applicable to all VNFs. Additional security requirements for specific types of VNFs will be applicable and are outside the scope of these general requirements.

Section 4.3 Security in VNF Guidelines outlines the five broad security areas for VNFs that are detailed in the following sections:

  • VNF General Security: This section addresses general security requirements for the VNFs that the VNF provider will need to address.

  • VNF Identity and Access Management: This section addresses security requirements with respect to Identity and Access Management as these pertain to generic VNFs.

  • VNF API Security: This section addresses the generic security requirements associated with APIs. These requirements are applicable to those VNFs that use standard APIs for communication and data exchange.

  • VNF Security Analytics: This section addresses the security requirements associated with analytics for VNFs that deal with monitoring, data collection and analysis.

  • VNF Data Protection: This section addresses the security requirements associated with data protection.

VNF General Security Requirements

This section provides details on the VNF general security requirements on various security areas such as user access control, network security, ACLs, infrastructure security, and vulnerability management. These requirements cover topics associated with compliance, security patching, logging/accounting, authentication, encryption, role-based access control, least privilege access/authorization. The following security requirements need to be met by the solution in a virtual environment:

General Security Requirements

Integration and operation within a robust security environment is necessary and expected. The security architecture will include one or more of the following: IDAM (Identity and Access Management) for all system and applications access, Code scanning, network vulnerability scans, OS, Database and application patching, malware detection and cleaning, DDOS prevention, network security gateways (internal and external) operating at various layers, host and application based tools for security compliance validation, aggressive security patch application, tightly controlled software distribution and change control processes and other state of the art security solutions. The VNF is expected to function reliably within such an environment and the developer is expected to understand and accommodate such controls and can expected to supply responsive interoperability support and testing throughout the product’s lifecycle.

Requirement: R-23740 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca

The VNF MUST implement and enforce the principle of least privilege on all protected interfaces.

Requirement: R-61354 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca

The VNF MUST provide a mechanism (e.g., access control list) to permit and/or restrict access to services on the VNF by source, destination, protocol, and/or port.

Requirement: R-92207 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD
updated: casablanca

The VNF SHOULD provide a mechanism that enables the operators to perform automated system configuration auditing at configurable time intervals.

Requirement: R-46986 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt

The VNF provider MUST follow GSMA vendor practices and SEI CERT Coding Standards when developing the VNF in order to minimize the risk of vulnerabilities. See GSMA NESAS Network Equipment Security Assurance Scheme – Development and Lifecycle Security Requirements Version 1.0 (https://www.gsma.com/ security/wp-content/uploads/2019/11/FS.16-NESAS-Development-and-Lifecycle-Security- Requirements-v1.0.pdf) and SEI CERT Coding Standards (https://wiki.sei.cmu.edu/ confluence/display/seccode/SEI+CERT+Coding+Standards).

Requirement: R-99771 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: dublin

The VNF MUST have all code (e.g., QCOW2) and configuration files (e.g., HEAT template, Ansible playbook, script) hardened, or with documented recommended configurations for hardening and interfaces that allow the Operator to harden the VNF. Actions taken to harden a system include disabling all unnecessary services, and changing default values such as default credentials and community strings.

Requirement: R-19768 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD
updated: frankfurt

The VNF SHOULD support the separation of (1) signaling and payload traffic (i.e., customer facing traffic), (2) operations, administration and management traffic, and (3) internal VNF traffic (i.e., east-west traffic such as storage access) using technologies such as VPN and VLAN.

Requirement: R-56904 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt

The VNF MUST interoperate with the ONAP (SDN) Controller so that it can dynamically modify the firewall rules, ACL rules, QoS rules, virtual routing and forwarding rules. This does not preclude the VNF providing other interfaces for modifying rules.

Requirement: R-69649 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca

The VNF Provider MUST have patches available for vulnerabilities in the VNF as soon as possible. Patching shall be controlled via change control process with vulnerabilities disclosed along with mitigation recommendations.

Requirement: R-62498 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt

The VNF MUST support only encrypted access protocols, e.g., TLS, SSH, SFTP.

Requirement: R-872986 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: casablanca

The VNF MUST store Authentication Credentials used to authenticate to other systems encrypted except where there is a technical need to store the password unencrypted in which case it must be protected using other security techniques that include the use of file and directory permissions. Ideally, credentials SHOULD rely on a HW Root of Trust, such as a TPM or HSM.

Requirement: R-80335 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca

For all GUI and command-line interfaces, the VNF MUST provide the ability to present a warning notice that is set by the Operator. A warning notice is a formal statement of resource intent presented to everyone who accesses the system.

Requirement: R-19082 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt

The VNF MUST not contain undocumented functionality.

Requirement: R-21819 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: el alto

VNFs that are subject to regulatory requirements MUST provide functionality that enables the Operator to comply with ETSI TC LI requirements, and, optionally, other relevant national equivalents.

Requirement: R-86261 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt

The VNF MUST be able to authenticate and authorize all remote access.

Requirement: R-638682 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: casablanca
validation_mode: in_service

The VNF MUST log any security event required by the VNF Requirements to Syslog using LOG_AUTHPRIV for any event that would contain sensitive information and LOG_AUTH for all other relevant events.

Requirement: R-756950 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: casablanca

The VNF MUST be operable without the use of Network File System (NFS).

Requirement: R-240760 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
introduced: casablanca

The VNF MUST NOT contain any backdoors.

Requirement: R-256267 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: casablanca

If SNMP is utilized, the VNF MUST support at least SNMPv3 with message authentication.

Requirement: R-258686 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD NOT
introduced: casablanca
updated: el alto

The VNF application processes SHOULD NOT run as root. If a VNF application process must run as root, the technical reason must be documented.

Requirement: R-118669 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: casablanca

Login access (e.g., shell access) to the operating system layer, whether interactive or as part of an automated process, MUST be through an encrypted protocol such as SSH or TLS.

Requirement: R-842258 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: casablanca
updated: frankfurt

The VNF MUST include a configuration (e.g. a heat template or CSAR package) that specifies the targeted parameters (e.g. a limited set of ports) over which the VNF will communicate; including internal, external and management communication.

Requirement: R-353637 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD
introduced: frankfurt

Containerized components of VNFs SHOULD follow the recommendations for Container Base Images and Build File Configuration in the latest available version of the CIS Docker Community Edition Benchmarks to ensure that containerized VNFs are secure. All non-compliances with the benchmarks MUST be documented.

Requirement: R-381623 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD
introduced: frankfurt

Containerized components of VNFs SHOULD execute in a Docker run-time environment that follows the Container Runtime Configuration in the latest available version of the CIS Docker Community Edition Benchmarks to ensure that containerized VNFs are secure. All non-compliances with the benchmarks MUST be documented.

VNF Identity and Access Management Requirements

The following security requirements for logging, identity, and access management need to be met by the solution in a virtual environment:

Identity and Access Management Requirements

Requirement: R-99174 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca

The VNF MUST, if not integrated with the Operator’s Identity and Access Management system, support the creation of multiple IDs so that individual accountability can be supported.

Requirement: R-42874 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt

The VNF MUST allow the Operator to restrict access to protected resources based on the assigned permissions associated with an ID in order to support Least Privilege (no more privilege than required to perform job functions).

Requirement: R-358699 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: frankfurt

The VNF MUST support at least the following roles: system administrator, application administrator, network function O&M.

Requirement: R-373737 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: frankfurt

The VNF MUST, if not integrated with the operator’s IAM system, provide a mechanism for assigning roles and/or permissions to an identity.

Requirement: R-59391 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
updated: casablanca

The VNF MUST NOT allow the assumption of the permissions of another account to mask individual accountability. For example, use SUDO when a user requires elevated permissions such as root or admin.

Requirement: R-86835 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt

The VNF MUST set the default settings for user access to deny authorization, except for a super user type of account.

Requirement: R-81147 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt

The VNF MUST, if not integrated with the Operator’s Identity and Access Management system, support multifactor authentication on all protected interfaces exposed by the VNF for use by human users.

Requirement: R-39562 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST disable unnecessary or vulnerable cgi-bin programs.

Requirement: R-75041 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca

The VNF MUST, if not integrated with the Operator’s Identity and Access Management system, support configurable password expiration.

Requirement: R-46908 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca

The VNF MUST, if not integrated with the Operator’s Identity and Access Management system, comply with “password complexity” policy. When passwords are used, they shall be complex and shall at least meet the following password construction requirements: (1) be a minimum configurable number of characters in length, (2) include 3 of the 4 following types of characters: upper-case alphabetic, lower-case alphabetic, numeric, and special, (3) not be the same as the UserID with which they are associated or other common strings as specified by the environment, (4) not contain repeating or sequential characters or numbers, (5) not to use special characters that may have command functions, and (6) new passwords must not contain sequences of three or more characters from the previous password.

Requirement: R-844011 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: casablanca
updated: frankfurt

The VNF MUST not store authentication credentials to itself in clear text or any reversible form and must use salting.

Requirement: R-79107 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt

The VNF MUST, if not integrated with the Operator’s Identity and Access Management system, support the ability to lock out the userID after a configurable number of consecutive unsuccessful authentication attempts using the same userID. The locking mechanism must be reversible by an administrator and should be reversible after a configurable time period.

Requirement: R-23135 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt

The VNF MUST, if not integrated with the Operator’s identity and access management system, authenticate all access to protected resources.

Requirement: R-78010 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt

The VNF MUST support LDAP in order to integrate with an external identity and access manage system. It MAY support other identity and access management protocols.

Requirement: R-814377 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: casablanca
updated: frankfurt

The VNF MUST have the capability of allowing the Operator to create, manage, and automatically provision user accounts using one of the protocols specified in Chapter 7.

Requirement: R-931076 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: casablanca
updated: frankfurt

The VNF MUST support account names that contain at least A-Z, a-z, and 0-9 character sets and be at least 6 characters in length.

Requirement: R-581188 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
introduced: casablanca
updated: frankfurt

The VNF MUST NOT identify the reason for a failed authentication, only that the authentication failed.

Requirement: R-479386 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: casablanca
updated: frankfurt

The VNF MUST provide the capability of setting a configurable message to be displayed after successful login. It MAY provide a list of supported character sets.

Requirement: R-231402 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: casablanca
updated: frankfurt

The VNF MUST provide a means to explicitly logout, thus ending that session.

Requirement: R-251639 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: frankfurt

The VNF MUST provide explicit confirmation of a session termination such as a message, new page, or rerouting to a login page.

Requirement: R-45719 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: casablanca
updated: frankfurt

The VNF MUST, if not integrated with the Operator’s Identity and Access Management system, enforce a configurable “terminate idle sessions” policy by terminating the session after a configurable period of inactivity.

VNF API Security Requirements

This section covers API security requirements when these are used by the VNFs. Key security areas covered in API security are Access Control, Authentication, Passwords, PKI Authentication Alarming, Anomaly Detection, Lawful Intercept, Monitoring and Logging, Input Validation, Cryptography, Business continuity, Biometric Authentication, Identification, Confidentiality and Integrity, and Denial of Service.

The solution in a virtual environment needs to meet the following API security requirements:

API Requirements

Requirement: R-43884 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD
updated: casablanca

The VNF SHOULD integrate with the Operator’s authentication and authorization services (e.g., IDAM).

Requirement: R-21652 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST implement the following input validation control: Check the size (length) of all input. Do not permit an amount of input so great that it would cause the VNF to fail. Where the input may be a file, the VNF API must enforce a size limit.

Requirement: R-54930 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca

The VNF MUST implement the following input validation controls: Do not permit input that contains content or characters inappropriate to the input expected by the design. Inappropriate input, such as SQL expressions, may cause the system to execute undesirable and unauthorized transactions against the database or allow other inappropriate access to the internal network (injection attacks).

Requirement: R-21210 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca

The VNF MUST implement the following input validation control on APIs: Validate that any input file has a correct and valid Multipurpose Internet Mail Extensions (MIME) type. Input files should be tested for spoofed MIME types.

VNF Security Analytics Requirements

This section covers VNF security analytics requirements that are mostly applicable to security monitoring. The VNF Security Analytics cover the collection and analysis of data following key areas of security monitoring:

  • Anti-virus software

  • Logging

  • Data capture

  • Tasking

  • DPI

  • API based monitoring

  • Detection and notification

  • Resource exhaustion detection

  • Proactive and scalable monitoring

  • Mobility and guest VNF monitoring

  • Closed loop monitoring

  • Interfaces to management and orchestration

  • Malformed packet detections

  • Service chaining

  • Dynamic security control

  • Dynamic load balancing

  • Connection attempts to inactive ports (malicious port scanning)

The following requirements of security monitoring need to be met by the solution in a virtual environment.

Security Analytics Requirements

Requirement: R-48470 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST support Real-time detection and notification of security events.

Requirement: R-32636 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST support API-based monitoring to take care of the scenarios where the control interfaces are not exposed, or are optimized and proprietary in nature.

Requirement: R-22367 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca

The VNF MUST support detection of malformed packets due to software misconfiguration or software vulnerability, and generate an error to the syslog console facility.

Requirement: R-73223 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST support proactive monitoring to detect and report the attacks on resources so that the VNFs and associated VMs can be isolated, such as detection techniques for resource exhaustion, namely OS resource attacks, CPU attacks, consumption of kernel memory, local storage attacks.

Requirement: R-58370 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD
updated: casablanca

The VNF SHOULD operate with anti-virus software which produces alarms every time a virus is detected.

Requirement: R-56920 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST protect all security audit logs (including API, OS and application-generated logs), security audit software, data, and associated documentation from modification, or unauthorized viewing, by standard OS access control mechanisms, by sending to a remote system, or by encryption.

Requirement: R-54520 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca

The VNF MUST log successful and unsuccessful authentication attempts, e.g., authentication associated with a transaction, authentication to create a session, authentication to assume elevated privilege.

Requirement: R-55478 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST log logoffs.

Requirement: R-13344 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST log starting and stopping of security logging.

Requirement: R-07617 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca

The VNF MUST log success and unsuccessful creation, removal, or change to the inherent privilege level of users.

Requirement: R-94525 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca

The VNF MUST log connections to the network listeners of the resource.

Requirement: R-31614 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST log the field “event type” in the security audit logs.

Requirement: R-97445 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST log the field “date/time” in the security audit logs.

Requirement: R-25547 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST log the field “protocol” in the security audit logs.

Requirement: R-06413 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST log the field “service or program used for access” in the security audit logs.

Requirement: R-15325 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST log the field “success/failure” in the security audit logs.

Requirement: R-89474 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST log the field “Login ID” in the security audit logs.

Requirement: R-04982 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT

The VNF MUST NOT include an authentication credential, e.g., password, in the security audit logs, even if encrypted.

Requirement: R-63330 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca

The VNF MUST detect when its security audit log storage medium is approaching capacity (configurable) and issue an alarm.

Requirement: R-41252 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST support the capability of online storage of security audit logs.

Requirement: R-41825 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca

The VNF MUST activate security alarms automatically when a configurable number of consecutive unsuccessful login attempts is reached.

Requirement: R-43332 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca

The VNF MUST activate security alarms automatically when it detects the successful modification of a critical system or application file.

Requirement: R-74958 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca

The VNF MUST activate security alarms automatically when it detects an unsuccessful attempt to gain permissions or assume the identity of another user.

Requirement: R-15884 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST include the field “date” in the Security alarms (where applicable and technically feasible).

Requirement: R-23957 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST include the field “time” in the Security alarms (where applicable and technically feasible).

Requirement: R-71842 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST include the field “service or program used for access” in the Security alarms (where applicable and technically feasible).

Requirement: R-57617 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST include the field “success/failure” in the Security alarms (where applicable and technically feasible).

Requirement: R-99730 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST include the field “Login ID” in the Security alarms (where applicable and technically feasible).

Requirement: R-29705 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca

The VNF MUST restrict changing the criticality level of a system security alarm to users with administrative privileges.

Requirement: R-13627 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST monitor API invocation patterns to detect anomalous access patterns that may represent fraudulent access or other types of attacks, or integrate with tools that implement anomaly and abuse detection.

Requirement: R-04492 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca

The VNF MUST generate security audit logs that can be sent to Security Analytics Tools for analysis.

Requirement: R-30932 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca

The VNF MUST log successful and unsuccessful access to VNF resources, including data.

Requirement: R-54816 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca

The VNF MUST support the storage of security audit logs for a configurable period of time.

Requirement: R-84160 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST have security logging for VNFs and their OSs be active from initialization. Audit logging includes automatic routines to maintain activity records and cleanup programs to ensure the integrity of the audit/logging systems.

Requirement: R-34552 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca

The VNF MUST be implemented so that it is not vulnerable to OWASP Top 10 web application security risks.

Requirement: R-33488 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca

The VNF MUST protect against all denial of service attacks, both volumetric and non-volumetric, or integrate with external denial of service protection tools.

Requirement: R-629534 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: casablanca

The VNF MUST be capable of automatically synchronizing the system clock daily with the Operator’s trusted time source, to assure accurate time reporting in log files. It is recommended that Coordinated Universal Time (UTC) be used where possible, so as to eliminate ambiguity owing to daylight savings time.

Requirement: R-303569 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: casablanca

The VNF MUST log the Source IP address in the security audit logs.

Requirement: R-703767 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: casablanca

The VNF MUST have the capability to securely transmit the security logs and security events to a remote system before they are purged from the system.

Requirement: R-465236 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD
introduced: casablanca

The VNF SHOULD provide the capability of maintaining the integrity of its static files using a cryptographic method.

Requirement: R-859208 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: casablanca

The VNF MUST log automated remote activities performed with elevated privileges.

VNF Data Protection Requirements

This section covers VNF data protection requirements that are mostly applicable to security monitoring.

Data Protection Requirements

Requirement: R-58964 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca

The VNF MUST provide the capability to restrict read and write access to data handled by the VNF.

Requirement: R-83227 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST Provide the capability to encrypt data in transit on a physical or virtual network.

Requirement: R-32641 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca

The VNF MUST provide the capability to encrypt data on non-volatile memory.Non-volative memory is storage that is capable of retaining data without electrical power, e.g. Complementary metal-oxide-semiconductor (CMOS) or hard drives.

Requirement: R-13151 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD

The VNF SHOULD disable the paging of the data requiring encryption, if possible, where the encryption of non-transient data is required on a device for which the operating system performs paging to virtual memory. If not possible to disable the paging of the data requiring encryption, the virtual memory should be encrypted.

Requirement: R-73067 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca

The VNF MUST use NIST and industry standard cryptographic algorithms and standard modes of operations when implementing cryptography.

Requirement: R-12467 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
updated: casablanca

The VNF MUST NOT use compromised encryption algorithms. For example, SHA, DSS, MD5, SHA-1 and Skipjack algorithms. Acceptable algorithms can be found in the NIST FIPS publications (https://csrc.nist.gov/publications/fips) and in the NIST Special Publications (https://csrc.nist.gov/publications/sp).

Requirement: R-02170 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca

The VNF MUST use, whenever possible, standard implementations of security applications, protocols, and formats, e.g., S/MIME, TLS, SSH, IPSec, X.509 digital certificates for cryptographic implementations. These implementations must be purchased from reputable vendors or obtained from reputable open source communities and must not be developed in-house.

Requirement: R-70933 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca

The VNF MUST provide the ability to migrate to newer versions of cryptographic algorithms and protocols with minimal impact.

Requirement: R-95864 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca

The VNF MUST support digital certificates that comply with X.509 standards.

Requirement: R-12110 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT

The VNF MUST NOT use keys generated or derived from predictable functions or values, e.g., values considered predictable include user identity information, time of day, stored/transmitted data.

Requirement: R-69610 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca

The VNF MUST provide the capability of using X.509 certificates issued by an external Certificate Authority.

Requirement: R-47204 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca

The VNF MUST be capable of protecting the confidentiality and integrity of data at rest and in transit from unauthorized access and modification.

VNF Cryptography Requirements

This section covers VNF cryptography requirements that are mostly applicable to encryption or protocol meethods.

Requirement: R-48080 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD
updated: casablanca

The VNF SHOULD support an automated certificate management protocol such as CMPv2, Simple Certificate Enrollment Protocol (SCEP) or Automated Certificate Management Environment (ACME).

Requirement: R-93860 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD
updated: casablanca

The VNF SHOULD provide the capability to integrate with an external encryption service.

Requirement: R-44723 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca

The VNF MUST use symmetric keys of at least 112 bits in length.

Requirement: R-25401 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca

The VNF MUST use asymmetric keys of at least 2048 bits in length.

Requirement: R-52060 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca

The VNF MUST provide the capability to configure encryption algorithms or devices so that they comply with the laws of the jurisdiction in which there are plans to use data encryption.

Requirement: R-83500 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca

The VNF MUST provide the capability of allowing certificate renewal and revocation.

Requirement: R-29977 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca

The VNF MUST provide the capability of testing the validity of a digital certificate by validating the CA signature on the certificate.

Requirement: R-24359 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca

The VNF MUST provide the capability of testing the validity of a digital certificate by validating the date the certificate is being used is within the validity period for the certificate.

Requirement: R-39604 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca

The VNF MUST provide the capability of testing the validity of a digital certificate by checking the Certificate Revocation List (CRL) for the certificates of that type to ensure that the certificate has not been revoked.

Requirement: R-75343 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca

The VNF MUST provide the capability of testing the validity of a digital certificate by recognizing the identity represented by the certificate - the “distinguished name”.

Requirement: R-49109 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: el alto

The VNF or PNF MUST support HTTPS using TLS v1.2 or higher with strong cryptographic ciphers.

Requirement: R-41994 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca

The VNF MUST support the use of X.509 certificates issued from any Certificate Authority (CA) that is compliant with RFC5280, e.g., a public CA such as DigiCert or Let’s Encrypt, or an RFC5280 compliant Operator CA.

Note: The VNF provider cannot require the use of self-signed certificates in an Operator’s run time environment.

VNF Modularity

ONAP Heat Orchestration Templates: Overview

ONAP supports a modular Heat Orchestration Template design pattern, referred to as VNF Modularity.

ONAP VNF Modularity Overview

With VNF Modularity, a single VNF may be composed from one or more Heat Orchestration Templates, each of which represents a subset of the overall VNF. These component parts are referred to as “VNF Modules“. During orchestration, these modules are deployed incrementally to create the complete VNF.

A modular Heat Orchestration Template can be either one of the following types:

  1. Base Module

  2. Incremental Module

  3. Cinder Volume Module

(R-37028) - The VNF MUST be composed of one “base” module.

Requirement: R-41215 _images/arrow-right-circle.svg
target: VNF
keyword: MAY

The VNF MAY have zero to many “incremental” modules.

ONAP also supports the concept of an optional, independently deployed Cinder volume via a separate Heat Orchestration Templates, referred to as a Cinder Volume Module. This allows the volume to persist after a Virtual Machine (VM) (i.e., OS::Nova::Server) is deleted, allowing the volume to be reused on another instance (e.g., during a failover activity).

(R-11200) - The VNF MUST keep the scope of a Cinder volume module, when it exists, to be 1:1 with the VNF Base Module or Incremental Module.

(R-38474) - The VNF MUST have a corresponding environment file for a Base Module.

(R-81725) - The VNF MUST have a corresponding environment file for an Incremental Module.

(R-53433) - The VNF MUST have a corresponding environment file for a Cinder Volume Module.

These concepts will be described in more detail throughout the document. This overview is provided to set the stage and help clarify the concepts that will be introduced.

ONAP VNF Modularity

ONAP supports a modular Heat Orchestration Template design pattern, referred to as VNF Modularity. With this approach, a single VNF may be composed from one or more Heat Orchestration Templates, each of which represents a subset of the overall VNF. These component parts are referred to as “VNF Modules“. During orchestration, these modules are deployed incrementally to create the complete VNF.

A modular Heat Orchestration Template can be either one of the following types:

  1. Base Module

  2. Incremental Module

  3. Cinder Volume Module

A VNF must be composed of one “base” module and may be composed of zero to many “incremental” modules. The base module must be deployed first, prior to the incremental modules.

ONAP also supports the concept of an optional, independently deployed Cinder volume via a separate Heat Orchestration Templates, referred to as a Cinder Volume Module. This allows the volume to persist after a VM (i.e., OS::Nova::Server) is deleted, allowing the volume to be reused on another instance (e.g., during a failover activity).

The scope of a Cinder volume module, when it exists, must be 1:1 with a Base module or Incremental Module.

A Base Module must have a corresponding environment file.

An Incremental Module must have a corresponding environment file.

A Cinder Volume Module must have a corresponding environment file.

A VNF module (base, incremental, cinder) may support nested templates.

A shared Heat Orchestration Template resource must be defined in the base module. A shared resource is a resource that that will be referenced by another resource that is defined in the Base Module and/or one or more incremental modules.

When the shared resource needs to be referenced by a resource in an incremental module, the UUID of the shared resource must be exposed by declaring an ONAP Base Module Output Parameter.

Note that a Cinder volume is not a shared resource. A volume template must correspond 1:1 with a base module or incremental module.

An example of a shared resource is the resource OS::Neutron::SecurityGroup. Security groups are sets of IP filter rules that are applied to a VNF’s networking. The resource OS::Neutron::Port has a property security_groups which provides the security groups associated with port. The value of parameter(s) associated with this property must be the UUIDs of the resource(s) OS::Neutron::SecurityGroup.

Note: A Cinder volume is not considered a shared resource. A volume template must correspond 1:1 with a base template or add-on module template.

Suggested Patterns for Modular VNFs

There are numerous variations of VNF modularity. Below are two suggested usage patterns.

Option 1: Modules per VNFC type

  1. Base module contains only the shared resources.

  2. Group all VMs (e.g., VNFCs) of a given type (i.e. {vm-type}) into its own incremental module. That is, the VNF has an incremental module for each {vm-type}.

  3. For a given {vm-type} incremental module, the VNF may have

    1. One incremental module used for both initial turn up and re-used for scaling. This approach is used when the number of VMs instantiated will be the same for initial deployment and scaling.

    2. Two incremental modules, where one is used for initial turn up and one is used for scaling. This approach is used when the number of VMs instantiated will be different for initial deployment and scaling.

Option 2: Base VNF with Incremental Growth Modules

  1. Base module contains a complete initial VNF instance

  2. Incremental modules for incremental scaling units

    1. May contain VMs of multiple types in logical scaling combinations

    2. May be separated by VM type for multi-dimensional scaling

With no growth units, Option 2 is equivalent to the “One Heat Template per VNF” model.

Note that modularization of VNFs is not required. A single Heat Orchestration Template (a base module) may still define a complete VNF, which might be appropriate for smaller VNFs that do not have any scaling options.

Modularity Rules

There are some rules to follow when building modular VNF templates:

  1. All VNFs must have one Base VNF Module (template) that must be the first one deployed. The base template:

    1. Must include all shared resources (e.g., private networks, server groups, security groups)

    2. Must expose all shared resources (by UUID) as “outputs” in its associated Heat template (i.e., ONAP Base Module Output Parameters)

    3. May include initial set of VMs

    4. May be operational as a stand-alone “minimum” configuration of the VNF

  2. VNFs may have one or more incremental modules which:

    1. Defines additional resources that can be added to an existing VNF

    2. Must be complete Heat templates

      1. i.e. not snippets to be incorporated into some larger template

    3. Should define logical growth-units or sub-components of an overall VNF

    4. On creation, receives appropriate Base Module outputs as parameters

      1. Provides access to all shared resources (by UUID)

      2. must not be dependent on other Add-On VNF Modules

    5. Multiple instances of an incremental Module may be added to the same VNF (e.g., incrementally grow a VNF by a fixed “add-on” growth units)

  3. Each VNF Module (base or incremental) may have (optional) an associated Cinder Volume Module (see Cinder Volume Templates)

    1. Volume modules must correspond 1:1 with a base module or incremental module

    2. A Cinder volume may be embedded within the base module or incremental module if persistence is not required

  4. Shared resource UUIDs are passed between the base module and incremental modules via Heat Outputs Parameters (i.e., Base Module Output Parameters)

    1. The output parameter name in the base must match the parameter name in the add-on module

VNF Modularity Examples

Example: Base Module creates SecurityGroup

A VNF has a base module, named base.yaml, that defines a OS::Neutron::SecurityGroup. The security group will be referenced by an OS::Neutron::Port resource in an incremental module, named INCREMENTAL_MODULE.yaml. The base module defines a parameter in the out section named dns_sec_grp_id. dns_sec_grp_id is defined as a parameter in the incremental module. ONAP captures the UUID value of dns_sec_grp_id from the base module output statement and provides the value to the incremental module.

Note that the example below is not a complete Heat Orchestration Template. The {network-role} has been defined as oam to represent an oam network and the {vm-type} has been defined as dns.

base_MODULE.yaml

parameters:
  . . .

resources:
  DNS_SECURITY_GROUP:
    type: OS::Neutron::SecurityGroup
    properties:
      description: vDNS security group
      name:
        str_replace:
          template: VNF_NAME_sec_grp_DNS
          params:
            VMF_NAME: {get_param: vnf_name}
      rules: [. . . . .

  . . .

outputs:
  dns_sec_grp_id:
    description: UUID of DNS Resource SecurityGroup
    value: { get_resource: DNS_SECURITY_GROUP }

INCREMENTAL_MODULE.yaml

parameters:
  dns_sec_grp_id:
    type: string
    description: security group UUID
  . . .

resources:
  dns_oam_0_port:
    type: OS::Neutron::Port
    properties:
      name:
        str_replace:
          template: VNF_NAME_dns_oam_port
          params:
            VNF_NAME: {get_param: vnf_name}
      network: { get_param: oam_net_name }
      fixed_ips: [{ "ip_address": { get_param: dns_oam_ip_0 }}]
      security_groups: [{ get_param: dns_sec_grp_id }]

Examples: Base Module creates an internal network

A VNF has a base module, named base_module.yaml, that creates an internal network. An incremental module, named incremental_module.yaml, will create a VM that will connect to the internal network. The base module defines a parameter in the out section named int_oam_net_id. int_oam_net_id is defined as a parameter in the incremental module. ONAP captures the UUID value of int_oam_net_id from the base module output statement and provides the value to the incremental module.

Note that the example below is not a complete Heat Orchestration Template. The {network-role} has been defined as oam to represent an oam network and the {vm-type} has been defined as lb for load balancer.

base.yaml

heat_template_version: 2013-05-23

resources:
   int_oam_network:
      type: OS::Neutron::Network
      properties:
         name: { }
         . . .
outputs:
   int_oam_net_id:
      value: {get_resource: int_oam_network }

incremental.yaml

heat_template_version: 2013-05-23

parameters:
   int_oam_net_id:
      type: string
      description: ID of shared private network from Base template
   lb_name_0:
      type: string
      description: name for the add-on VM instance

Resources:
   lb_server:
      type: OS::Nova::Server
      properties:
         name: {get_param: lb_name_0}
         networks:
            - port: { get_resource: lb_port }
         . . .

   lb_port:
      type: OS::Neutron::Port
      properties:
         network_id: { get_param: int_oam_net_id }
...

VNF Devops

This section includes guidelines for VNF providers to ensure that a Network Cloud Service Provider’s operations personnel have a common and consistent way to support VNFs and VNFCs.

NCSPs may elect to support standard images to enable compliance with security, audit, regulatory and other needs. As part of the overall VNF software bundle, VNF suppliers using standard images would typically provide the NCSP with an install package consistent with the default OS package manager (e.g. aptitude for Ubuntu, yum for Redhat/CentOS).

Section 4.5 DevOps in VNF Guidelines describes the DevOps guidelines for VNFs.

DevOps Requirements

Requirement: R-46960 _images/arrow-right-circle.svg
target: VNF
keyword: MAY

NCSPs MAY operate a limited set of Guest OS and CPU architectures and families, virtual machines, etc.

Requirement: R-23475 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD

VNFCs SHOULD be agnostic to the details of the Network Cloud (such as hardware, host OS, Hypervisor or container technology) and must run on the Network Cloud with acknowledgement to the paradigm that the Network Cloud will continue to rapidly evolve and the underlying components of the platform will change regularly.

Requirement: R-33846 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST install the NCSP required software on Guest OS images when not using the NCSP provided Guest OS images. 1

Requirement: R-09467 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST utilize only NCSP standard compute flavors. 1

Requirement: R-02997 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST preserve their persistent data. Running VMs will not be backed up in the Network Cloud infrastructure.

Requirement: R-29760 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNFC MUST be installed on non-root file systems, unless software is specifically included with the operating system distribution of the guest image.

Requirement: R-20860 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST be agnostic to the underlying infrastructure (such as hardware, host OS, Hypervisor), any requirements should be provided as specification to be fulfilled by any hardware.

Requirement: R-89800 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT

The VNF MUST NOT require Hypervisor-level customization from the cloud provider.

Requirement: R-86758 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD

The VNF SHOULD provide an automated test suite to validate every new version of the software on the target environment(s). The tests should be of sufficient granularity to independently test various representative VNF use cases throughout its lifecycle. Operations might choose to invoke these tests either on a scheduled basis or on demand to support various operations functions including test, turn-up and troubleshooting.

Requirement: R-39650 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD

The VNF SHOULD provide the ability to test incremental growth of the VNF.

Requirement: R-14853 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST respond to a “move traffic” 2 command against a specific VNFC, moving all existing session elsewhere with minimal disruption if a VNF provides a load balancing function across multiple instances of its VNFCs.

Note: Individual VNF performance aspects (e.g., move duration or disruption scope) may require further constraints.

Requirement: R-06327 _images/arrow-right-circle.svg
target: VNF
keyword: MUST

The VNF MUST respond to a “drain VNFC” 2 command against a specific VNFC, preventing new session from reaching the targeted VNFC, with no disruption to active sessions on the impacted VNFC, if a VNF provides a load balancing function across multiple instances of its VNFCs. This is used to support scenarios such as proactive maintenance with no user impact.

Requirement: R-64713 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD

The VNF SHOULD support a software promotion methodology from dev/test -> pre-prod -> production in software, development & testing and operations.

1(1,2)

Refer to NCSP’s Network Cloud specification

2(1,2)

Not currently supported in ONAP release 1

VNF Develop Steps

Aid to help the VNF provider to fasten the integration with the GVNFM, the ONAP provides the VNF SDK tools, and the documents. In this charter, the develop steps for VNF providers will be introduced.

First, using the VNF SDK tools to design the VNF with TOSCA model and output the VNF TOSCA package. The VNF package can be validated, and tested.

Second, the VNF provider should provide the VNF Rest API to integrate with the GVNFM if needed. The VNF Rest API is aligned to the ETSI IFA document.

Third, the TOSCA model supports the HPA feature.

Note:

  1. The scripts to extend capacity to satisfy some special requirements. In the R2, the scripts is not implemented fully, and will be provided in the next release.

  2. The monitoring and scale policy also be provide the next release.

VNF and PNF Modeling Requirements

ONAP TOSCA VNFD or PNFD Requirements

Introduction

The following sub-clauses describe the numbered requirements for VNF Descriptor (VNFD) and PNF Descriptor (PNFD) or in other words the VNF/PNF Service Template based on the most updated draft of ETSI NFV-SOL001 standard for VNF/PNF Descriptor. The ETSI standard specifies a NFV specific data model using TOSCA/YAML data model constructs specified in TOSCA Simple Profile in YAML v.1.2.

The requirements for TOSCA/CSAR based VNF/PNF package are described as well and they are based on ETSI NFV-SOL004 standard.

References
  1. ETSI GS NFV-SOL001 v.2.5.1

  2. TOSCA SIMPLE Profile in YAML v.1.2

  3. ETSI GS NFV-SOL004 v.2.6.1 + NFV CR NFVSOL(18)000746r3.

Intended Audience

This document is intended for developers of VNF TOSCA templates that will be orchestrated by ONAP. The document is also applicable for creating RFP’s with the list of required TOSCA/YAML features supported by VNF provider.

Scope

ONAP implementations of Network Cloud supports TOSCA Templates, also referred to as TOSCA in this document.

ONAP requires the TOSCA Templates to follow a specific format. This document provides the mandatory, recommended, and optional requirements associated with this format.

Overview

The document includes three charters to help the VNF or PNF providers to use the VNF or PNF model design tools and understand the VNF or PNF package structure and VNF or PNF TOSCA templates.

In the ONAP, VNF or PNF Package and VNFD or PNFD template can be designed by manually or via model designer tools. VNF or PNF model designer tools can provide the GUI and CLI tools for the VNF or PNF provider to develop the VNF or PNF Package and VNFD or PNFD template.

The VNF or PNF package structure is align to the NFV TOSCA protocol, and supports CSAR

The VNFD or PNFD and VNF or PNF package are all align to the NFV TOSCA protocol, which supports multiple TOSCA template yaml files, and also supports self-defined node or other extensions.

TOSCA Introduction

TOSCA defines a Meta model for defining IT services. This Meta model defines both the structure of a service as well as how to manage it. A Topology Template (also referred to as the topology model of a service) defines the structure of a service. Plans define the process models that are used to create and terminate a service as well as to manage a service during its whole lifetime.

A Topology Template consists of a set of Node Templates and Relationship Templates that together define the topology model of a service as a (not necessarily connected) directed graph. A node in this graph is represented by a Node Template. A Node Template specifies the occurrence of a Node Type as a component of a service. A Node Type defines the properties of such a component (via Node Type Properties) and the operations (via Interfaces) available to manipulate the component. Node Types are defined separately for reuse purposes and a Node Template references a Node Type and adds usage constraints, such as how many times the component can occur.

image1

Figure 1: Structural Elements of Service Template and their Relations

TOSCA Modeling Principles & Data Model

This section describing TOSCA modeling principles and data model for NFV, which shall be based on [TOSCA-1.0] and [TOSCA-Simple-Profile-YAML V1.0], or new type based on ETSI NFV requirements, etc.

VNF or PNF CSAR Package

CSAR Overview

TOSCA YAML CSAR file is an archive file using the ZIP file format whose structure complies with the TOSCA Simple Profile YAML v1.2 Specification. The CSAR file may have one of the two following structures:

  • CSAR containing a TOSCA-Metadata directory, which includes the TOSCA.meta metadata file providing an entry information for processing a CSAR file.

  • CSAR containing a single yaml (.yml or .yaml) file at the root of the archive. The yaml file is a TOSCA definition template that contains a metadata section with template_name and template_version metadata. This file is the CSAR Entry-Definitions file.

VNF or PNF Package Structure and Format
Requirement: R-51347 _images/arrow-right-circle.svg
target: VNF or PNF CSAR PACKAGE
keyword: MUST
introduced: casablanca
updated: frankfurt

The VNF or PNF CSAR package MUST be arranged as a CSAR archive as specified in TOSCA Simple Profile in YAML 1.2.

Requirement: R-87234 _images/arrow-right-circle.svg
target: VNF or PNF CSAR PACKAGE
keyword: MUST
introduced: casablanca
updated: frankfurt

The VNF or PNF CSAR package provided by a VNF or PNF vendor MUST be with TOSCA-Metadata directory (CSAR Option 1) as specified in ETSI GS NFV-SOL004.

Note: SDC supports only the CSAR Option 1 in Dublin. The Option 2 will be considered in future ONAP releases.

Requirement: R-506221 _images/arrow-right-circle.svg
target: VNF or PNF CSAR PACKAGE
keyword: MUST
introduced: dublin
updated: frankfurt

The VNF or PNF CSAR file MUST be a zip file with .csar extension.

VNF or PNF Package Contents
Requirement: R-10087 _images/arrow-right-circle.svg
target: VNF or PNF CSAR PACKAGE
keyword: MUST
introduced: casablanca
updated: dublin

The VNF or PNF CSAR package MUST include all artifacts required by ETSI GS NFV-SOL004 including Manifest file, VNFD or PNFD (or Main TOSCA/YAML based Service Template) and other optional artifacts.

Requirement: R-01123 _images/arrow-right-circle.svg
target: VNF or PNF CSAR PACKAGE
keyword: MUST
introduced: casablanca
updated: frankfurt

The VNF or PNF CSAR package Manifest file MUST contain: VNF or PNF package meta-data, a list of all artifacts (both internal and external) entry’s including their respected URI’s, as specified in ETSI GS NFV-SOL 004

Requirement: R-21322 _images/arrow-right-circle.svg
target: VNF CSAR PACKAGE
keyword: MUST
introduced: casablanca
updated: frankfurt

The VNF provider MUST provide their testing scripts to support testing as specified in ETSI NFV-SOL004 - Testing directory in CSAR

Requirement: R-40820 _images/arrow-right-circle.svg
target: VNF CSAR PACKAGE
keyword: MUST
introduced: casablanca
updated: guilin

The VNF CSAR PACKAGE MUST enumerate all of the open source licenses their VNF(s) incorporate. CSAR License directory as per ETSI SOL004.

for example ROOT\Licenses\ License_term.txt

Requirement: R-293901 _images/arrow-right-circle.svg
target: VNF or PNF CSAR PACKAGE
keyword: MUST
introduced: dublin

The VNF or PNF CSAR PACKAGE with TOSCA-Metadata MUST include following additional keywords pointing to TOSCA files:

  • ETSI-Entry-Manifest

  • ETSI-Entry-Change-Log

Note: For a CSAR containing a TOSCA-Metadata directory, which includes the TOSCA.meta metadata file. The TOSCA.meta metadata file includes block_0 with the Entry-Definitions keyword pointing to a TOSCA definitions YAML file used as entry for parsing the contents of the overall CSAR archive.

Requirement: R-146092 _images/arrow-right-circle.svg
target: VNF or PNF CSAR PACKAGE
keyword: MUST
introduced: dublin
updated: frankfurt

If one or more non-MANO artifact(s) is included in the VNF or PNF CSAR package, the Manifest file in this CSAR package MUST contain one or more of the following ONAP non-MANO artifact set identifier(s):

  • onap_ves_events: contains VES registration files

  • onap_pm_dictionary: contains the PM dictionary files

  • onap_yang_modules: contains Yang module files for configurations

  • onap_ansible_playbooks: contains any ansible_playbooks

  • onap_pnf_sw_information: contains the PNF software information file

  • onap_others: contains any other non_MANO artifacts, e.g. informational documents

NOTE: According to ETSI SOL004 v.2.6.1, every non-MANO artifact set shall be identified by a non-MANO artifact set identifier which shall be registered in the ETSI registry. Approved ONAP non-MANO artifact set identifiers are documented in the following page https://wiki.onap.org/display/DW/ONAP+Non-MANO+Artifacts+Set+Identifiers

Requirement: R-221914 _images/arrow-right-circle.svg
target: VNF or PNF CSAR PACKAGE
keyword: MUST
introduced: dublin
updated: frankfurt

The VNF or PNF CSAR package MUST contain a human-readable change log text file. The Change Log file keeps a history describing any changes in the VNF or PNF package. The Change Log file is kept up to date continuously from the creation of the CSAR package.

Requirement: R-57019 _images/arrow-right-circle.svg
target: PNF CSAR PACKAGE
keyword: MUST
introduced: dublin
updated: frankfurt

The PNF CSAR PACKAGE Manifest file MUST start with the PNF package metadata in the form of a name-value pairs. Each pair shall appear on a different line. The name is specified as following:

  • pnfd_provider

  • pnfd_name

  • pnfd_release_date_time

  • pnfd_archive_version

Requirement: R-795126 _images/arrow-right-circle.svg
target: VNF CSAR PACKAGE
keyword: MUST
introduced: dublin
updated: frankfurt

The VNF CSAR package Manifest file MUST start with the VNF package metadata in the form of a name-value pairs. Each pair shall appear on a different line. The name is specified as following:

  • vnf_provider_id

  • vnf_product_name

  • vnf_release_date_time

  • vnf_package_version

Requirement: R-972082 _images/arrow-right-circle.svg
target: PNF CSAR PACKAGE
keyword: MUST
introduced: frankfurt

If the Manifest file in the PNF CSAR package includes “onap_pnf_sw_information” as a non-MANO artifact set identifiers, then the PNF software information file is included in the package and it MUST be compliant to:

  • The file extension which contains the PNF software version must be .yaml

  • The PNF software version information must be specified as following:

pnf_software_information:

 - pnf_software_version:  "<version>"
VNF or PNF Package Authenticity and Integrity

VNF or PNF CSAR package shall support a method for authenticity and integrity assurance. According to ETSI SOL004 the onboarding package shall be secured. ETSI SOL004 provides two options:

Option 1 - One Digest for each components of the VNF or PNF package. The table of hashes is included in the manifest file, which is signed with the VNF or PNF provider private key. A signing certificate including the provider’s public key shall be included in the package.

Option 2 - The complete CSAR file shall be digitally signed with the provider private key. The provider delivers one zip file consisting of the CSAR file, a signature file and a certificate file that includes the VNF provider public key.

Guilin Release Note

In ONAP, there are two key components involved with the creation, validations, and reading of a CSAR package. The VNFSDK can be used to create and validate a CSAR package prior to ONAP via the SDC application. The SDC application, then opens, parses, and reads the CSAR package. Their support for these two signing options, as defined in ETSI NFV SOL004 2.7.1, is as follows:

  • VNFSDK pre-onboarding validation: - Option 1: Supported - Option 2: Supported

  • SDC onboarding procedure: - Option 1: Will be supported in the future releases. - Option 2: Supported

Requirement: R-787965 _images/arrow-right-circle.svg
target: VNF or PNF CSAR PACKAGE
keyword: MUST
introduced: dublin

If the VNF or PNF CSAR Package utilizes Option 2 for package security, then the complete CSAR file MUST be digitally signed with the VNF or PNF provider private key. The VNF or PNF provider delivers one zip file consisting of the CSAR file, a signature file and a certificate file that includes the VNF or PNF provider public key. The certificate may also be included in the signature container, if the signature format allows that. The VNF or PNF provider creates a zip file consisting of the CSAR file with .csar extension, signature and certificate files. The signature and certificate files must be siblings of the CSAR file with extensions .cms and .cert respectively.

Requirement: R-130206 _images/arrow-right-circle.svg
target: VNF or PNF CSAR PACKAGE
keyword: MUST
introduced: dublin
updated: el alto

If the VNF or PNF CSAR Package utilizes Option 1 for package security, then the complete CSAR file MUST contain a Digest (a.k.a. hash) for each of the components of the VNF or PNF package. The table of hashes is included in the package manifest file, which is signed with the VNF or PNF provider private key. In addition, the VNF or PNF provider MUST include a signing certificate that includes the VNF or PNF provider public key, following a TOSCA pre-defined naming convention and located either at the root of the archive or in a predefined location specified by the TOSCA.meta file with the corresponding entry named “ETSI-Entry-Certificate”.

VNF Package ONAP Extensions
  1. TOSCA data type extension tosca.datatypes.nfv.injectFile is used for vCPE use case.

  2. ONAP extensions for VNF package that is currently proposed for Dublin release is VES extension described below.

TOSCA VNF Descriptor

General
Requirement: R-35854 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: casablanca

The VNF Descriptor (VNFD) provided by VNF vendor MUST comply with TOSCA/YAML based Service template for VNF descriptor specified in ETSI NFV-SOL001.

Note: As the ETSI NFV-SOL001 is work in progress the below tables summarizes the TOSCA definitions agreed to be part of current version of NFV profile and that VNFD MUST comply with in ONAP Release 2+ Requirements.

Requirement: R-65486 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: casablanca
updated: dublin

The VNFD MUST comply with ETSI GS NFV-SOL001 specification endorsing the above mentioned NFV Profile and maintaining the gaps with the requirements specified in ETSI GS NFV-IFA011 standard.

Requirement: R-17852 _images/arrow-right-circle.svg
target: VNF
keyword: MAY
introduced: casablanca

The VNFD MAY include TOSCA/YAML definitions that are not part of NFV Profile. If provided, these definitions MUST comply with TOSCA Simple Profile in YAML v.1.2.

Requirement: R-46527 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: casablanca

A VNFD is a deployment template which describes a VNF in terms of deployment and operational behavior requirements. It contains virtualized resources (nodes) requirements as well as connectivity and interfaces requirements and MUST comply with info elements specified in ETSI GS NFV-IFA 011. The main parts of the VNFD are the following:

  • VNF topology: it is modeled in a cloud agnostic way using virtualized containers and their connectivity. Virtual Deployment Units (VDU) describe the capabilities of the virtualized containers, such as virtual CPU, RAM, disks; their connectivity is modeled with VDU Connection Point Descriptors (VduCpd), Virtual Link Descriptors (VnfVld) and VNF External Connection Point Descriptors (VnfExternalCpd);

  • VNF deployment aspects: they are described in one or more deployment flavours, including configurable parameters, instantiation levels, placement constraints (affinity / antiaffinity), minimum and maximum VDU instance numbers. Horizontal scaling is modeled with scaling aspects and the respective scaling levels in the deployment flavours;

Note: The deployment aspects (deployment flavour etc.) are postponed for future ONAP releases.

  • VNF lifecycle management (LCM) operations: describes the LCM operations supported per deployment flavour, and their input parameters; Note, thatthe actual LCM implementation resides in a different layer, namely referring to additional template artifacts.

Requirement: R-15837 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: casablanca

The following table defines the major TOSCA Types specified in ETSI NFV-SOL001 standard draft. The VNFD provided by a VNF vendor MUST comply with the below definitions:

TOSCA Definition

Info Element

From ETSI GS NFV-IFA 011

Implementation in TOSCA NFV Profile and Endorsement in ETSI GS NFV-SOL001

Derived from

Description

Supported in ONAP Casablanca release

VNFD

tosca.nodes.nfv.VNF

tosca.nodes.Root

TOSCA main service template and describes a VNF in terms of deployment and operational behavior requirements, connectivity, interfaces and virtualized resource requirements.

Y

VDU Compute Descriptor

R-09467

tosca.nodes.nfv.VDU.Compute

tosca.nodes.Root

Represents VNF-C (or VM) with deployment flavours.

Represents the virtual compute part of a VDU entity which it mainly describes the deployment and operational behavior of a VNFC.

Note: Currently not directly supported but allowed via tosca.capabilities.nfv.VirtualCompute

Y but different way

VDU VirtualCompute Descriptor

tosca.capabilities.nfv.VirtualCompute

tosca.capabilities.Root

Represents the virtual compute part of a VDU entity which it mainly describes the deployment and operational behavior of a VNFC

Y

VDU VirtualStorage Descriptor

R-09467

tosca.nodes.nfv.VDU.VirtualStorage

tosca.nodes.Root

Represents a virtual storage entity which it describes the deployment and operational behavior of a virtual storage resources.

Note: This node type is split into three in latest SOL001 draft how the data model uses an older version for Casablanca release.

Y

Cpd - Connection Point Descriptor

tosca.nodes.nfv.Cp

tosca.nodes.Root

Represents network connectivity to a compute resource or a VL - abstract type used as parent for the various Cpd types.

Y

VduCpd

R-35851

tosca.nodes.nfv.VduCp

tosca.nodes.nfv.Cp

Represents a type of TOSCA Cpd node and describes network connectivity between a VNFC instance (based on this VDU) and an internal VL

Y

VnfVirtualLinkDesc

R-35851

tosca.nodes.nfv.VnfVirtualLink

tosca.nodes.Root

Node type represents a logical internal virtual link

Y

VnfExtCpd (External Connection Point)

R-35851

tosca.nodes.nfv.VnfExtCp

tosca.nodes.Root

Represents a logical external connection point, exposed by this VNF enabling connecting with Virtual Link,

N

SwImageDesc

R-02454

tosca.artifacts.nfv.SwImage

tosca.artifacts.Deployment.Image

Artifact type describes the software image which is directly loaded on the Virtualisation container of the VDU or is to be loaded on a virtual storage resource.

Note: Currently not supported in Casablanca release as well as SW image artifact in CSAR

N

DeploymentFlavour

VnfDf info element

R-41215

tosca.capabilities.nfv.DeploymentFlavour

tosca.capabilities.Root

Note: Current ONAP release support a single deployment flavour

N

Scaling Aspect

R-96634 The VNF providerMUSTdescribe scaling capabilities to manage scaling characteristics of the VNF.

tosca.datatypes.nfv.ScalingAspect

tosca.datatypes.Root

TBD in ETSI NFV-SOL001

N

Data Types
Requirement: R-54356 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: casablanca

The below table includes the data types used by NFV node and is based on TOSCA/YAML constructs specified in draft GS NFV-SOL 001. The node data definitions/attributes used in VNFD MUST comply with the below table.

NFV Data Types

Info Element From ETSI GS NFV-IFA 011

Implementation in ETSI NFV-SOL001

Derived from

Description

Supported in ONAP Casablanca release

l2AddressData

tosca.datatype.nfv.L2AddressData

tosca.datatypes.Root

Describes the information on the MAC addresses to be assigned to the connection point(s) instantiated from the parent Connection Point Descriptor

Y

L3AddressData

tosca.datatypes.nfv.L3AddressData

tosca.datatypes.Root

A complex TOSCA data type describe L3AddressData information element, it provides the information on the IP addresses to be assigned to the connection point instantiated from the parent Connection Point Descriptor

Y

AddressData

tosca.datatypes.nfv.AddressData

tosca.datatypes.Root

A complex TOSCA data type describe AddressData information elemen, it provides information on the addresses to be assigned to the connection point(s) instantiated from a Connection Point

Y

VirtualNetworkInterfaceRequirements

tosca.datatypes.nfv.VirtualNetworkInterfaceRequirements

tosca.datatypes.Root

A complex TOSCA data type describe VirtualNetworkInterfaceRequirements information element, it provides the information to specify requirements on a virtual network interface realizing the CPs instantiated from this CPD

Y

ConnectivityType

tosca.datatypes.nfv.ConnectivityType

tosca.datatypes.Root

A complex TOSCA data type used to describe ConnectivityType information element

Y

RequestedAdditionalCapabilityData

tosca.datatypes.nfv.RequestedAdditionalCapability

tosca.datatypes.Root

Describes additional capability for a particular VDU e.g. acceleration

Y

VirtualMemoryData

tosca.datatypes.nfv.VirtualMemory

tosca.datatypes.Root

Describes virtual memory for virtualized compute descriptor

Y

VirtualCpuData

tosca.datatypes.nfv.VirtualCpu

tosca.datatypes.Root

Describes virtual CPU (s) for virtualized compute descriptor

Y

VirtualCpuPinning

tosca.datatypes.nfv.VirtualCpuPinning

tosca.datatypes.Root

Describes CPU pinning configuration for a particular CPU

Y

VnfcConfigurableProperties

tosca.datatypes.nfv.VnfcConfigurableProperties

tosca.datatypes.Root

Describes additional configurable properties of a VNFC

Y

VduProfile

tosca.datatypes.nfv.VduProfile

tosca.datatypes.Root

Describes additional instantiation data for a given VDU used in the a specific deployment flavour.

Note: Deployment flavour is not supported in Casablanca release.

N

VirtualLinkProfile

tosca.datatypes.nfv.VlProfile

tosca.datatypes.Root

Describes additional instantiation data for a given VL used in the a specific deployment flavour.

Note: Deployment flavour is not supported in Casablanca release.

N

InstantiationLevel

tosca.datatypes.nfv.InstantiationLevel

tosca.datatypes.Root

Describes a given level of resources to be instantiated within a deployment flavour in term of the number VNFC instances to be created from each VDU.

Note: Deployment flavour is not supported in Casablanca release.

N

VduLevel

tosca.datatypes.nfv.VduLevel

tosca.datatypes.Root

Indicates for a given VDU in a given level the number of instances to deploy

Y

ScaleInfo

tosca.datatypes.nfv.ScaleInfo

tosca.datatypes.Root

Indicates for a given Scaling Aspect the corresponding Scaling Level

Y

Inject File

tosca.datatypes.nfv.injectFile

tosca.datatypes.Root

Note: ONAP extension used for vCPE use case

Y

Scaling Aspect

tosca.datatypes.nfv.ScalingAspect

tosca.datatypes.Root

Y

Link Bit Rate Requirements

tosca.datatypes.nfv.LinkBitRateRequirements

tosca.datatypes.Root

Y

Quality of service data (loss ratio etc.)

tosca.datatypes.nfv.Qos

tosca.datatypes.Root

Y

Connection point protocol

tosca.datatypes.nfv.CpProtocolData

tosca.datatypes.Root

Y

VNF Configurable Properties

tosca.datatypes.nfv.VnfConfigurableProperties

tosca.datatypes.Root

Y

VNF Additional Configurable Properties

tosca.datatypes.nfv.VnfAdditionalConfigurableProperties

tosca.datatypes.Root

Y?

VnfInfo Modifiable Attributes

tosca.datatypes.nfv.VnfInfoModifiableAttributes

tosca.datatypes.Root

Y

VnfInfo Modifiable Attributes Extension

tosca.datatypes.nfv.VnfInfoModifiableAttributesExtensions

tosca.datatypes.Root

Y

VnfInfo Modifiable Attributes Metadata

tosca.datatypes.nfv.VnfInfoModifiableAttributesMetadata

tosca.datatypes.Root

Y

Requirement: R-54876 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: casablanca

The below table describes the data types used for LCM configuration and is based on TOSCA constructs specified in draft GS NFV-SOL 001. The LCM configuration data elements used in VNFD MUST comply with the below table.

LCM Configuration

Info Element

From ETSI GS NFV-IFA 011

Implementation in

ETSI NFV-SOL001

Derived from

Description

Supported in ONAP Casablanca release

VnfLcmOperationsConfiguration

tosca.datatypes.nfv.VnfLcmOperationsConfiguration

tosca.datatypes.Root

Represents information to configure lifecycle management operations. Each VNF LCM operation configuration represent as a container for all attributes that effect the invocation of the VNF Lifecycle Management operations ? see below per LCM operation

Y

InstantiateVnfOpConfig

tosca.datatypes.nfv.VnfInstantiateOperationConfiguration

tosca.datatypes.Root

Represents information that affect the invocation of the InstantiateVnf operation

Y

ScaleVnfOpConfig

tosca.datatypes.nfv.VnfScaleOperationConfiguration

tosca.datatypes.Root

Represents information that affect the invocation of the ScaleVnf operation

Y

ScaleVnfToLevelOpConfig

tosca.datatypes.nfv.VnfScaleToLevelOperationConfiguration

tosca.datatypes.Root

Represents information that affect the invocation of the ScaleVnfToLevel operation

Y

HealVnfOpConfig

tosca.datatypes.nfv.VnfHealOperationConfiguration

tosca.datatypes.Root

Represents information that affect the invocation of the HealVnf operation

Y

TerminateVnfOpConfig

tosca.datatypes.nfv.VnfTerminateOperationConfiguration

tosca.datatypes.Root

Represents information that affect the invocation of the TerminateVnf

Y

OperateVnfOpConfig

tosca.datatypes.nfv.VnfOperateOperationConfiguration

tosca.datatypes.Root

Represents information that affect the invocation of the OperateVnf operation

Y

ChangeVnfFlavourOpConfig

tosca.datatypes.nfv.VnfChangeFlavourOperationConfiguration

tosca.datatypes.Root

Defines attributes for invocation of ChangeVnfFlavour operation

N

ChangeExtVnfConnectivityOpConfig

tosca.datatypes.nfv.VnfExtConnectivityOperationConfiguration

tosca.datatypes.Root

Defines attributes for invocation of ChangeExtVnfConnectivty operation.

Note: External VNF connectivity is postponed to future ONAP releases.

N

Artifact Types

No artifact type is currently supported in ONAP.

Capability Types
Requirement: R-67895 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: casablanca

The VNFD provided by VNF vendor may use the below described TOSCA capabilities. An on-boarding entity (ONAP SDC) MUST support them.

tosca.capabilities.nfv.VirtualBindable

A node type that includes the VirtualBindable capability indicates that it can be pointed by tosca.relationships.nfv.VirtualBindsTo relationship type.

tosca.capabilities.nfv.VirtualLinkable

A node type that includes the VirtualLinkable capability indicates that it can be pointed by tosca.relationships.nfv.VirtualLinksTo relationship.

tosca.capabilities.nfv.ExtVirtualLinkable

A node type that includes the ExtVirtualLinkable capability indicates that it can be pointed by tosca.relationships.nfv.VirtualLinksTo relationship.

Note: This capability type is used in Casablanca how it does not exist in the last SOL001 draft

tosca.capabilities.nfv.VirtualCompute and tosca.capabilities.nfv.VirtualStorage includes flavours of VDU

Relationship Types
Requirement: R-95321 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: casablanca

The VNFD provided by VNF vendor may use the below described TOSCA relationships. An on-boarding entity (ONAP SDC) MUST support them.

tosca.relationships.nfv.VirtualBindsTo

This relationship type represents an association relationship between VDU and CP node types.

tosca.relationships.nfv.VirtualLinksTo

This relationship type represents an association relationship between the VduCpd’s and VirtualLinkDesc node types.

Interface Types
Requirement: R-32155 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: casablanca

The VNFD provided by VNF vendor may use the below described TOSCA interface types. An on-boarding entity (ONAP SDC) MUST support them.

tosca.interfaces.nfv.vnf.lifecycle.Nfv supports LCM operations

tosca_definitions_version: tosca_simple_yaml_1_0

description: VNFD TOSCA file demo

imports:

  • TOSCA_definition_nfv_1_0.yaml

  • TOSCA_definition_nfv_ext_1_0.yaml

node_types: tosca.nodes.nfv.VNF.vOpenNAT: derived_from: tosca.nodes.nfv.VNF
requirements: **- **sriov_plane: capability: tosca.capabilities.nfv.VirtualLinkable
node: tosca.nodes.nfv.VnfVirtualLinkDesc
relationship: tosca.relationships.nfv.VirtualLinksTo

TOSCA PNF Descriptor

General
Requirement: R-24632 _images/arrow-right-circle.svg
target: PNF
keyword: MUST
introduced: dublin

The PNF Descriptor (PNFD) provided by PNF vendor MUST comply with TOSCA/YAML based Service template for PNF descriptor specified in ETSI NFV-SOL001.

Data Types
Requirement: R-484843 _images/arrow-right-circle.svg
target: PNF
keyword: MUST
introduced: dublin

The PNFD provided by a PNF vendor MUST comply with the following Data Types as specified in ETSI NFV-SOL001 standard:

  • tosca.datatypes.nfv.CpProtocolData

  • tosca.datatypes.nfv.AddressData

  • tosca.datatypes.nfv.L2AddressData

  • tosca.datatypes.nfv.L3AddressData

  • tosca.datatypes.nfv.LocationInfo

  • tosca.datatypes.nfv.CivicAddressElement

Artifact Types

No artifact type is currently supported in ONAP.

Capability Types
Requirement: R-177937 _images/arrow-right-circle.svg
target: PNF
keyword: MUST
introduced: guilin

The PNFD provided by a PNF vendor MUST comply with the following Capabilities Types as specified in ETSI NFV-SOL001 standard:

  • tosca.capabilities.nfv.VirtualLinkable

Requirements Types
Relationship Types
Requirement: R-64064 _images/arrow-right-circle.svg
target: PNF
keyword: MUST
introduced: guilin

The PNFD provided by a PNF vendor MUST comply with the following Relationship Types as specified in ETSI NFV-SOL001 standard:

  • tosca.relations.nfv.VirtualLinksTo

Interface Types

No interface type is currently supported in ONAP.

Node Types
Requirement: R-535009 _images/arrow-right-circle.svg
target: PNF
keyword: MUST
introduced: dublin

The PNFD provided by a PNF vendor MUST comply with the following Node Types as specified in ETSI NFV-SOL001 standard:

  • tosca.nodes.nfv.PNF

  • tosca.nodes.nfv.PnfExtCp

  • tosca.nodes.nfv.Cp

Group Types

No group type is currently supported in ONAP.

Policy Types
Requirement: R-596064 _images/arrow-right-circle.svg
target: PNF
keyword: MUST
introduced: guilin

The PNFD provided by a PNF vendor MUST comply with the following Policy Types as specified in ETSI NFV-SOL001 standard:

  • tosca.policies.nfv.SecurityGroupRule

HPA Requirements

  1. SR-IOV Passthrought

Definitions of SRIOV_Port are necessary if VDU supports SR-IOV. Here is an example.

node_templates:

vdu_vNat:

SRIOV_Port:

attributes:

tosca_name: SRIOV_Port

properties:

virtual_network_interface_requirements:

- name: sriov

support_mandatory: false

description: sriov

requirement:

SRIOV: true

role: root

description: sriov port

layer_protocol: ipv4

requirements:

- virtual_binding:

capability: virtual_binding

node: vdu_vNat

relationship:

type: tosca.relationships.nfv.VirtualBindsTo

- virtual_link:

node: tosca.nodes.Root

type: tosca.nodes.nfv.VduCpd

substitution_mappings:

requirements:

sriov_plane:

- SRIOV_Port

- virtual_link

node_type: tosca.nodes.nfv.VNF.vOpenNAT
  1. Hugepages

Definitions of mem_page_size as one property shall be added to Properties and set the value to large if one VDU node supports huagepages. Here is an example.

node_templates:

vdu_vNat:

Hugepages:

attributes:

tosca_name: Huge_pages_demo

properties:

mem_page_size:large
  1. NUMA (CPU/Mem)

Likewise, we shall add definitions of numa to requested_additional_capabilities if we wand VUD nodes to support NUMA. Here is an example.

topology_template:

node_templates:

vdu_vNat:

capabilities:

virtual_compute:

properties:

virtual_memory:

numa_enabled: true

virtual_mem_size: 2 GB

requested_additional_capabilities:

numa:

support_mandatory: true

requested_additional_capability_name: numa

target_performance_parameters:

hw:numa_nodes: "2"

hw:numa_cpus.0: "0,1"

hw:numa_mem.0: "1024"

hw:numa_cpus.1: "2,3,4,5"

hw:numa_mem.1: "1024"
  1. Hyper-Theading

Definitions of Hyper-Theading are necessary as one of requested_additional_capabilities of one VUD node if that node supports Hyper-Theading. Here is an example.

topology_template:

node_templates:

vdu_vNat:

capabilities:

virtual_compute:

properties:

virtual_memory:

numa_enabled: true

virtual_mem_size: 2 GB

requested_additional_capabilities:

hyper_threading:

support_mandatory: true

requested_additional_capability_name: hyper_threading

target_performance_parameters:

hw:cpu_sockets : "2"

hw:cpu_threads : "2"

hw:cpu_cores : "2"

hw:cpu_threads_policy: "isolate"
  1. OVS+DPDK

Definitions of ovs_dpdk are necessary as one of requested_additional_capabilities of one VUD node if that node supports dpdk. Here is an example.

topology_template:

node_templates:

vdu_vNat:

capabilities:

virtual_compute:

properties:

virtual_memory:

numa_enabled: true

virtual_mem_size: 2 GB

requested_additional_capabilities:

ovs_dpdk:

support_mandatory: true

requested_additional_capability_name: ovs_dpdk

target_performance_parameters:

sw:ovs_dpdk: "true"

NFV TOSCA Type Definition

tosca.capabilites.nfv.VirtualCompute

This capability is used with the properties specified in ETSI SOL001 draft.

tosca.nodes.nfv.VDU.Compute

The NFV Virtualization Deployment Unit (VDU) compute node type represents a VDU entity which it describes the deployment and operational behavior of a VNF component (VNFC), as defined by [ETSI NFV IFA011].

Shorthand Name

VDU.Compute

Type Qualified Name

tosca:VDU.Compute

Type URI

tosca.nodes.nfv.VDU.Compute

derived_from

tosca.nodes.Compute

Attributes

None

Capabilities

Name

Type

Constraints

Description

virtual_compute

tosca.capabilities.nfv.VirtualCompute

Describes virtual compute resources capabilities.

monitoring_parameter

tosca.capabilities.nfv.Metric

None

Monitoring parameter, which can be tracked for a VNFC based on this VDU

Examples include: memory-consumption, CPU-utilisation, bandwidth-consumption, VNFC downtime, etc.

Virtual_binding

tosca.capabilities.nfv.VirtualBindable

editor note: need to create a capability type

Defines ability of VirtualBindable

Definition
tosca.nodes.nfv.VDU.Compute:

derived_from: tosca.nodes.Compute

properties:

name:

type: string

required: true

description:

type: string

required: true

boot_order:

type: list # explicit index (boot index) not necessary, contrary to IFA011

entry_schema:

type: string

required: false

nfvi_constraints:

type: list

entry_schema:

type: string

required: false

configurable_properties:

type: map

entry_schema:

type: tosca.datatypes.nfv.VnfcConfigurableProperties

required: true

attributes:

private_address:

status: deprecated

public_address:

status: deprecated

networks:

status: deprecated

ports:

status: deprecated

capabilities:

virtual_compute:

type: tosca.capabilities.nfv.VirtualCompute

virtual_binding:

type: tosca.capabilities.nfv.VirtualBindable

#monitoring_parameter:

# modeled as ad hoc (named) capabilities in VDU node template

# for example:

#capabilities:

# cpu_load: tosca.capabilities.nfv.Metric

# memory_usage: tosca.capabilities.nfv.Metric

host: #Editor note: FFS. How this capabilities should be used in NFV Profile|

type: *tosca.capabilities.Container*

valid_source_types:
[*tosca.nodes.SoftwareComponent*]

occurrences: [0,UNBOUNDED]

endpoint:

occurrences: [0,0]

os:

occurrences: [0,0]

scalable:
#Editor note: FFS. How this capabilities should be used in NFV Profile

type: *tosca.capabilities.Scalable*

binding:

occurrences: [0,UNBOUND]

requirements:

- virtual_storage:

capability: tosca.capabilities.nfv.VirtualStorage

relationship: tosca.relationships.nfv.VDU.AttachedTo

node: tosca.nodes.nfv.VDU.VirtualStorage

occurences: [ 0, UNBOUNDED ]

- local_storage: #For NFV Profile, this requirement is deprecated.

occurrences: [0,0]

artifacts:

- sw_image:

file:

type: tosca.artifacts.nfv.SwImage
Artifact

Note: currently not supported.

Name

Required

Type

Constraints

Description

SwImage

Yes

tosca.artifacts.nfv.SwImage

Describes the software image which is directly realizing this virtual storage

image2

tosca.nodes.nfv.VDU.VirtualStorage

The NFV VirtualStorage node type represents a virtual storage entity which it describes the deployment and operational behavior of a virtual storage resources, as defined by [ETSI NFV IFA011].

[editor note] open issue: should NFV profile use the current storage model as described in YAML 1.1. Pending on Shitao proposal (see NFVIFA(17)000110 discussion paper)

[editor note] new relationship type as suggested in Matt presentation. Slide 8. With specific rules of “valid_target_type”

Shorthand Name

VirtualStorage

Type Qualified Name

tosca: VirtualStorage

Type URI

tosca.nodes.nfv.VDU.VirtualStorage

derived_from

tosca.nodes.Root

tosca.artifacts.nfv.SwImage

Shorthand Name

SwImage

Type Qualified Name

tosca:SwImage

Type URI

tosca.artifacts.nfv.SwImage

derived_from

tosca.artifacts.Deployment.Image

Properties

Name

Required

Type

Constraints

Description

name

yes

string

Name of this software image

version

yes

string

Version of this software image

checksum

yes

string

Checksum of the software image file

container_format

yes

string

The container format describes the container file format in which software image is provided.

disk_format

yes

string

The disk format of a software image is the format of the underlying disk image

min_disk

yes

scalar-unit.size

The minimal disk size requirement for this software image.

min_ram

no

scalar-unit.size

The minimal RAM requirement for this software image.

Size

yes

scalar-unit.size

The size of this software image

sw_image

yes

string

A reference to the actual software image within VNF Package, or url.

operating_system

no

string

Identifies the operating system used in the software image.

supported_virtualization_enviroment

no

list

Identifies the virtualization environments (e.g. hypervisor) compatible with this software image

Definition
tosca.artifacts.nfv.SwImage:

  derived_from: tosca.artifacts.Deployment.Image

  properties or metadata:

    #id:

      # node name

    name:

      type: string

required: true

    version:

      type: string

required: true

    checksum:

      type: string

required: true

    container_format:

      type: string

required: true

    disk_format:

      type: string

required: true

    min_disk:

      type: scalar-unit.size # Number

required: true

    min_ram:

      type: scalar-unit.size # Number

required: false

    size:

      type: scalar-unit.size # Number

required: true

    sw_image:

      type: string

required: true

    operating_system:

      type: string

required: false

    supported_virtualisation_environments:

      type: list

      entry_schema:

        type: string

required: false

Heat

General Guidelines for Heat

This section contains general Heat Orchestration Template guidelines and requirements.

Heat Template Compliance

The Heat Orchestration Template requirements with RFC 2119 keywords MUST and MUST NOT can be validated against a set of Heat Templates via the VNF Validation Program (VVP).

NOTE: Not all requirements are currently testable via VVP.

The VVP validation scripts project contains python validation scripts that will parse Heat Orchestration Templates in a given directory to ensure that they comply with ONAP Heat Orchestration Template requirements.

For instructions on how to use the VVP validation scripts, please see the validation scripts README

YAML Format
Requirement: R-95303 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
validation_mode: static

A VNF’s Heat Orchestration Template MUST be defined using valid YAML.

YAML (YAML Ain’t Markup Language) is a human friendly data serialization standard for all programming languages. See http://www.yaml.org/.

YAML rules include:

  • Tabs are not allowed, use spaces ONLY

  • You must indent your properties and lists with 1 or more spaces

  • All Resource IDs and resource property parameters are case-sensitive. (e.g., “ThIs”, is not the same as “thiS”)

ONAP Heat Orchestration Template Format

As stated above, Heat Orchestration templates must be defined in YAML.

Requirement: R-92635 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: casablanca
validation_mode: static

A VNF’s Heat Orchestration Template MUST be compliant with the OpenStack Template Guide.

The OpenStack Template Guide is defined at https://docs.openstack.org/heat/latest/template_guide/index.html#top.

Heat Orchestration Template Structure

Heat Orchestration template structure follows the following format, as defined by OpenStack at https://docs.openstack.org/developer/heat/template_guide/hot_spec.html.

heat_template_version: <date>

description:
  # a description of the template

parameter_groups:
  # a declaration of input parameter groups and order

parameters:
  # declaration of input parameters

resources:
  # declaration of template resources

outputs:
  # declaration of output parameters

conditions:
  # declaration of conditions
heat_template_version
Requirement: R-27078 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
validation_mode: static

A VNF’s Heat Orchestration template MUST contain the section heat_template_version:.

The section heat_template_version: must be set to a date that is supported by the OpenStack environment.

description
Requirement: R-39402 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
validation_mode: static

A VNF’s Heat Orchestration Template MUST contain the section description:.

parameter_groups

A VNF Heat Orchestration template may contain the section “parameter_groups:”.

parameters
Requirement: R-35414 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt
validation_mode: static

A VNF Heat Orchestration’s template MUST contain the section parameters: with at least one parameter defined.

parameters:

  <param name>:

    type: <string | number | json | comma_delimited_list | boolean>

    label: <human-readable name of the parameter>

    description: <description of the parameter>

    default: <default value for parameter>

    hidden: <true | false>

    constraints:

      <parameter constraints>

    immutable: <true | false>

    tags: <list of parameter categories>

This section allows for specifying input parameters that have to be provided when instantiating the template. Each parameter is specified in a separate nested block with the name of the parameters defined in the first line and additional attributes (e.g., type, label) defined as nested elements.

Requirement: R-90279 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt
validation_mode: static

A VNF Heat Orchestration’s template’s parameter MUST be used

  • in a resource AND/OR

  • in a output parameter (in the outputs section)

with the exception of the parameters for the OS::Nova::Server resource property availability_zone which is defined in R-98450.

Requirement: R-91273 _images/arrow-right-circle.svg
target: VNF
keyword: MAY NOT
updated: casablanca
validation_mode: none

A VNF Heat Orchestration’s template’s parameter for the OS::Nova::Server resource property availability_zone MAY NOT be used in any OS::Nova::Server.

That is, the parameter associated with the property availability_zone maybe declared but not used in a resource.

<param name>

The name of the parameter.

Requirement: R-25877 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
validation_mode: static

A VNF’s Heat Orchestration Template’s parameter name (i.e., <param name>) MUST contain only alphanumeric characters and underscores (‘_’).

type
Requirement: R-36772 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
validation_mode: static

A VNF’s Heat Orchestration Template’s parameter MUST include the attribute type:.

Requirement: R-11441 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

A VNF’s Heat Orchestration Template’s parameter type MUST be one of the following values:

  • string

  • number

  • json

  • comma_delimited_list

  • boolean

label
Requirement: R-32094 _images/arrow-right-circle.svg
target: VNF
keyword: MAY
validation_mode: none

A VNF’s Heat Orchestration Template parameter declaration MAY contain the attribute label:.

description
Requirement: R-44001 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
validation_mode: static

A VNF’s Heat Orchestration Template parameter declaration MUST contain the attribute description.

Note that the parameter attribute description: is an OpenStack optional attribute that provides a description of the parameter. ONAP implementation requires this attribute.

default
Requirement: R-90526 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
validation_mode: static

A VNF Heat Orchestration Template parameter declaration MUST NOT contain the default attribute.

Requirement: R-26124 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: none

If a VNF Heat Orchestration Template parameter has a default value, it MUST be enumerated in the environment file.

Note that the parameter attribute default: is an OpenStack optional attribute that declares the default value of the parameter. ONAP implementation prohibits the use of this attribute.

hidden
Requirement: R-32557 _images/arrow-right-circle.svg
target: VNF
keyword: MAY
validation_mode: none

A VNF’s Heat Orchestration Template parameter declaration MAY contain the attribute hidden:.

The parameter attribute hidden: is an OpenStack optional attribute that defines whether the parameters should be hidden when a user requests information about a stack created from the template. This attribute can be used to hide passwords specified as parameters.

constraints

The parameter attribute constraints: is an OpenStack optional attribute that defines a list of constraints to apply to the parameter.

Requirement: R-88863 _images/arrow-right-circle.svg
target: VNF
keyword: MAY
updated: dublin
validation_mode: none

A VNF’s Heat Orchestration Template’s parameter defined in a non-nested YAML file as type number MAY have a parameter constraint defined.

Requirement: R-40518 _images/arrow-right-circle.svg
target: VNF
keyword: MAY
updated: casablanca

A VNF’s Heat Orchestration Template’s parameter defined in a non-nested YAML file as type string MAY have a parameter constraint defined.

Requirement: R-96227 _images/arrow-right-circle.svg
target: VNF
keyword: MAY
updated: casablanca

A VNF’s Heat Orchestration Template’s parameter defined in a non-nested YAML file as type json MAY have a parameter constraint defined.

Requirement: R-79817 _images/arrow-right-circle.svg
target: VNF
keyword: MAY
updated: casablanca

A VNF’s Heat Orchestration Template’s parameter defined in a non-nested YAML file as type comma_delimited_list MAY have a parameter constraint defined.

Requirement: R-06613 _images/arrow-right-circle.svg
target: VNF
keyword: MAY
updated: casablanca

A VNF’s Heat Orchestration Template’s parameter defined in a non-nested YAML file as type boolean MAY have a parameter constraint defined.

Requirement: R-00011 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD NOT
updated: dublin
validation_mode: static

A VNF’s Heat Orchestration Template’s parameter defined in a nested YAML file SHOULD NOT have a parameter constraint defined.

The constraints block of a parameter definition defines additional validation constraints that apply to the value of the parameter. The parameter values provided in the VNF Heat Orchestration Template are validated against the constraints at instantiation time. The stack creation fails if the parameter value doesn’t comply to the constraints.

The constraints are defined as a list with the following syntax

constraints:
  - <constraint type>: <constraint definition>
    description: <constraint description>

<constraint type> Provides the type of constraint to apply. The list of OpenStack supported constraints can be found at https://docs.openstack.org/heat/latest/template_guide/hot_spec.html .

<constraint definition> provides the actual constraint. The syntax and constraint is dependent of the <constraint type> used.

description: is an optional attribute that provides a description of the constraint. The text is presented to the user when the value the user defines violates the constraint. If omitted, a default validation message is presented to the user.

Below is a brief overview of the range and allowed values constraints. For complete details on constraints, see https://docs.openstack.org/heat/latest/template_guide/hot_spec.html#parameter-constraints

range

range: The range constraint applies to parameters of type: number. It defines a lower and upper limit for the numeric value of the parameter. The syntax of the range constraint is

range: { min: <lower limit>, max: <upper limit> }

It is possible to define a range constraint with only a lower limit or an upper limit.

allowed_values

allowed_values: The allowed_values constraint applies to parameters of type string or type number. It specifies a set of possible values for a parameter. At deployment time, the user-provided value for the respective parameter must match one of the elements of the list. The syntax of the allowed_values constraint is

allowed_values: [ <value>, <value>, ... ]

Alternatively, the following YAML list notation can be used

allowed_values:
  - <value>
  - <value>
  - ...
immutable
Requirement: R-22589 _images/arrow-right-circle.svg
target: VNF
keyword: MAY

A VNF’s Heat Orchestration Template parameter declaration MAY contain the attribute immutable:.

The parameter attribute immutable is an OpenStack optional attribute that defines whether the parameter is updatable. A Heat Orchestration Template stack update fails if immutable is set to true and the parameter value is changed. This attribute immutable defaults to false.

tags
Requirement: R-225891 _images/arrow-right-circle.svg
target: VNF
keyword: MAY
introduced: el alto

A VNF’s Heat Orchestration Template parameter declaration MAY contain the attribute tags:.

resources
Requirement: R-23663 _images/arrow-right-circle.svg
target: VNF
keyword: MAY
introduced: frankfurt

A VNF’s Heat Orchestration template’s base module MAY (or MAY NOT) contain the section resources:.

When a VNF is composed of two or more Heat Orchestration Templates (i.e., a base module and one or more incremental modules), it is valid for the base module to not declare a resource.

Requirement: R-23664 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt
validation_mode: static

A VNF’s Heat Orchestration template’s incremental module and volume module MUST contain the section resources:.

Requirement: R-90152 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
validation_mode: static

A VNF’s Heat Orchestration Template’s resources: section MUST contain the declaration of at least one resource.

Requirement: R-40551 _images/arrow-right-circle.svg
target: VNF
keyword: MAY
updated: casablanca

A VNF’s Heat Orchestration Template’s Nested YAML files MAY (or MAY NOT) contain the section resources:.

Each resource is defined as a separate block in the resources section with the following syntax.

resources:

  <resource ID>:

    type: <resource type>

    properties:

      <property name>: <property value>

    metadata:

      <resource specific metadata>

    depends_on: <resource ID or list of ID>

    update_policy: <update policy>

    deletion_policy: <deletion policy>

    external_id: <external resource ID>

    condition: <condition name or expression or boolean>
resource ID
Requirement: R-75141 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
validation_mode: static

A VNF’s Heat Orchestration Template’s resource name (i.e., <resource ID>) MUST only contain alphanumeric characters and underscores (‘_’).

Requirement: R-16447 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
validation_mode: static

A VNF’s <resource ID> MUST be unique across all Heat Orchestration Templates and all HEAT Orchestration Template Nested YAML files that are used to create the VNF.

Note that a VNF can be composed of one or more Heat Orchestration Templates.

Note that OpenStack requires the <resource ID> to be unique to the Heat Orchestration Template and not unique across all Heat Orchestration Templates the compose the VNF.

type

The resource attribute type is an OpenStack required attribute that defines the resource type, such as OS::Nova::Server or OS::Neutron::Port.

The resource attribute type may specify a VNF HEAT Orchestration Template Nested YAML file.

Requirement: R-53952 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
validation_mode: static

A VNF’s Heat Orchestration Template’s Resource MUST NOT reference a HTTP-based resource definitions.

Requirement: R-71699 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
validation_mode: static

A VNF’s Heat Orchestration Template’s Resource MUST NOT reference a HTTP-based Nested YAML file.

properties

The resource attribute properties is an OpenStack optional attribute that provides a list of resource-specific properties. The property value can be provided in place, or via a function (e.g., Intrinsic functions).

Requirement: R-10834 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
updated: el alto
validation_mode: static

A VNF’s Heat Orchestration Template resource attribute property: MUST NOT use more than two levels of nested get_param intrinsic functions when deriving a property value. SDC does not support nested get_param with recursive lists (i.e., a list inside list). The second get_param in a nested lookup must directly derive its value without further calls to get_param functions.

  • Example of valid nesting:

    • name: {get_param: [ {vm-type}_names, {get_param : index } ] }

  • Examples of invalid nesting. SDC will not support these examples since there is an array inside array.

    • name: {get_param: [ {vm-type}_names, { get_param: [ indexlist, 0 ] } ] }

    • name: {get_param: [ {vm-type}_names, { get_param: [ indexlist1, { get_param: indexlist2 } ] } ] }

metadata

The resource attribute metadata is an OpenStack optional attribute.

Requirement: R-67386 _images/arrow-right-circle.svg
target: VNF
keyword: MAY
introduced: casablanca
validation_mode: static

A VNF’s Heat Orchestration Template’s Resource MAY declare the attribute metadata.

depends_on

The resource attribute depends_on is an OpenStack optional attribute. See Section 9.7 for additional details.

Requirement: R-46968 _images/arrow-right-circle.svg
target: VNF
keyword: MAY

VNF’s Heat Orchestration Template’s Resource MAY declare the attribute depends_on:.

update_policy
Requirement: R-63137 _images/arrow-right-circle.svg
target: VNF
keyword: MAY

VNF’s Heat Orchestration Template’s Resource MAY declare the attribute update_policy:.

deletion_policy
Requirement: R-43740 _images/arrow-right-circle.svg
target: VNF
keyword: MAY
updated: casablanca

VNF’s Heat Orchestration Template’s Resource MAY declare the attribute deletion_policy:.

If specified, the deletion_policy attribute for resources allows values Delete, Retain, and Snapshot. Starting with heat_template_version 2016-10-14, lowercase equivalents are also allowed.

The default policy is to delete the physical resource when deleting a resource from the stack.

external_id
Requirement: R-78569 _images/arrow-right-circle.svg
target: VNF
keyword: MAY
updated: casablanca

VNF’s Heat Orchestration Template’s Resource MAY declare the attribute external_id:.

This attribute allows for specifying the resource_id for an existing external (to the stack) resource. External resources cannot depend on other resources, but we allow other resources to depend on external resource. This attribute is optional. Note: when this is specified, properties will not be used for building the resource and the resource is not managed by Heat. This is not possible to update that attribute. Also, resource won’t be deleted by heat when stack is deleted.

condition

The resource attribute condition is an OpenStack optional attribute.

outputs
Requirement: R-36982 _images/arrow-right-circle.svg
target: VNF
keyword: MAY

A VNF’s Heat Orchestration template MAY contain the outputs: section.

This section allows for specifying output parameters available to users once the template has been instantiated. If the section is specified, it will need to adhere to specific requirements. See Output Parameters and ONAP Output Parameter Names for additional details.

Environment File Format

A VNF’s Heat Orchestration Template’s environment file is a yaml text file. (https://docs.openstack.org/developer/heat/template_guide/environment.html)

Requirement: R-86285 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

A VNF’s Heat Orchestration template MUST have a corresponding environment file.

The use of an environment file in OpenStack is optional. In ONAP, it is mandatory. A Heat Orchestration Template uploaded to ONAP must have a corresponding environment file, even if no parameters are enumerated in the mandatory parameter section.

Requirement: R-03324 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

A VNF’s Heat Orchestration template’s Environment File MUST contain the parameters: section.

Requirement: R-68198 _images/arrow-right-circle.svg
target: VNF
keyword: MAY
updated: casablanca

A VNF’s Heat Orchestration template’s Environment File’s parameters: section MAY (or MAY NOT) enumerate parameters.

ONAP implementation requires the parameters section in the environmental file to be declared. The parameters section contains a list of key/value pairs.

Requirement: R-59930 _images/arrow-right-circle.svg
target: VNF
keyword: MAY

A VNF’s Heat Orchestration template’s Environment File’s MAY contain the parameter_defaults: section.

The parameter_defaults: section contains default parameters that are passed to all template resources.

Requirement: R-46096 _images/arrow-right-circle.svg
target: VNF
keyword: MAY

A VNF’s Heat Orchestration template’s Environment File’s MAY contain the encrypted_parameters: section.

The encrypted_parameters: section contains a list of encrypted parameters.

Requirement: R-24893 _images/arrow-right-circle.svg
target: VNF
keyword: MAY

A VNF’s Heat Orchestration template’s Environment File’s MAY contain the event_sinks: section.

The event_sinks: section contains the list of endpoints that would receive stack events.

Requirement: R-42685 _images/arrow-right-circle.svg
target: VNF
keyword: MAY

A VNF’s Heat Orchestration template’s Environment File’s MAY contain the parameter_merge_strategies: section.

The parameter_merge_strategies: section provides the merge strategies for merging parameters and parameter defaults from the environment file.

Requirement: R-67231 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
validation_mode: static

A VNF’s Heat Orchestration template’s Environment File’s MUST NOT contain the resource_registry: section.

ONAP implementation does not support the Environment File resource_registry section. The resource_registry section allows for the definition of custom resources.

ONAP Heat Orchestration Templates Overview

ONAP supports a modular Heat Orchestration Template design pattern, referred to as VNF Modularity.

ONAP VNF Modularity Overview
Requirement: R-69663 _images/arrow-right-circle.svg
target: VNF
keyword: MAY

A VNF MAY be composed from one or more Heat Orchestration Templates, each of which represents a subset of the overall VNF.

The Heat Orchestration Templates can be thought of a components or modules of the VNF and are referred to as VNF Modules. During orchestration, these modules are deployed incrementally to create the complete VNF.

Requirement: R-33132 _images/arrow-right-circle.svg
target: VNF
keyword: MAY
updated: casablanca
A VNF’s Heat Orchestration Template MAY be
1.) Base Module Heat Orchestration Template (also referred to as a

Base Module),

2.) Incremental Module Heat Orchestration Template (referred to as

an Incremental Module), or

3.) a Cinder Volume Module Heat Orchestration Template (referred to as

Cinder Volume Module).

Requirement: R-37028 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

A VNF MUST be composed of one Base Module

Requirement: R-13196 _images/arrow-right-circle.svg
target: VNF
keyword: MAY

A VNF MAY be composed of zero to many Incremental Modules.

Requirement: R-28980 _images/arrow-right-circle.svg
target: VNF
keyword: MAY

A VNF’s incremental module MAY be used for initial VNF deployment only.

Requirement: R-86926 _images/arrow-right-circle.svg
target: VNF
keyword: MAY

A VNF’s incremental module MAY be used for scale out only.

A VNF’s Incremental Module that is used for scale out is deployed sometime after initial VNF deployment to add capacity.

Requirement: R-91497 _images/arrow-right-circle.svg
target: VNF
keyword: MAY

A VNF’s incremental module MAY be used for both deployment and scale out.

Requirement: R-68122 _images/arrow-right-circle.svg
target: VNF
keyword: MAY

A VNF’s incremental module MAY be deployed more than once, either during initial VNF deployment and/or scale out.

Requirement: R-46119 _images/arrow-right-circle.svg
target: VNF
keyword: MAY
updated: dublin

A VNF’s Heat Orchestration Template’s Resource OS::Cinder::Volume MAY be defined in a Base Module.

Requirement: R-90748 _images/arrow-right-circle.svg
target: VNF
keyword: MAY
updated: dublin

A VNF’s Heat Orchestration Template’s Resource OS::Cinder::Volume MAY be defined in an Incremental Module.

Requirement: R-03251 _images/arrow-right-circle.svg
target: VNF
keyword: MAY
updated: dublin

A VNF’s Heat Orchestration Template’s Resource OS::Cinder::Volume MAY be defined in a Cinder Volume Module.

ONAP also supports the concept of an optional, independently deployed Cinder volume via a separate Heat Orchestration Templates, referred to as a Cinder Volume Module. This allows the volume to persist after a Virtual Machine (VM) (i.e., OS::Nova::Server) is deleted, allowing the volume to be reused on another instance (e.g., during a fail over activity).

Requirement: R-11200 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

A VNF’s Cinder Volume Module, when it exists, MUST be 1:1 with a Base module or Incremental module.

It is strongly recommended that Cinder Volumes be created in a Cinder Volume Module.

Requirement: R-38474 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

A VNF’s Base Module MUST have a corresponding Environment File.

Requirement: R-81725 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

A VNF’s Incremental Module MUST have a corresponding Environment File

Requirement: R-53433 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

A VNF’s Cinder Volume Module MUST have a corresponding environment file

These concepts will be described in more detail throughout the document. This overview is provided to set the stage and help clarify the concepts that will be introduced.

Nested Heat Orchestration Templates Overview

ONAP supports nested Heat Orchestration Templates per OpenStack specifications.

Requirement: R-36582 _images/arrow-right-circle.svg
target: VNF
keyword: MAY

A VNF’s Base Module MAY utilize nested heat.

Requirement: R-56721 _images/arrow-right-circle.svg
target: VNF
keyword: MAY

A VNF’s Incremental Module MAY utilize nested heat.

Requirement: R-30395 _images/arrow-right-circle.svg
target: VNF
keyword: MAY

A VNF’s Cinder Volume Module MAY utilize nested heat.

Nested templates may be suitable for larger VNFs that contain many repeated instances of the same VM type(s). A common usage pattern is to create a nested template for each VM type along with its supporting resources. The Heat Orchestration Template may then reference these nested templates either statically (by repeated definition) or dynamically (via OS::Heat::ResourceGroup).

See Nested Heat Templates for additional details.

ONAP Heat Orchestration Template Filenames

In order to enable ONAP to understand the relationship between Heat files, the following Heat file naming convention must be utilized.

In the examples below, <text> represents any alphanumeric string that must not contain any special characters and must not contain the word “base”.

Requirement: R-87485 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
validation_mode: static

A VNF’s Heat Orchestration Template’s file extension MUST be in the lower case format .yaml or .yml.

Requirement: R-56438 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
validation_mode: static

A VNF’s Heat Orchestration Template’s Nested YAML file extension MUST be in the lower case format .yaml or .yml.

Requirement: R-74304 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
validation_mode: static

A VNF’s Heat Orchestration Template’s Environment file extension MUST be in the lower case format .env.

Requirement: R-99646 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
validation_mode: static

A VNF’s YAML files (i.e, Heat Orchestration Template files and Nested files) MUST have a unique name in the scope of the VNF.

Base Modules
Requirement: R-81339 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: el alto
validation_mode: static

A VNF Heat Orchestration Template’s Base Module file name MUST include case insensitive ‘base’ in the filename and MUST match one of the following four formats:

1.) base_<text>.y[a]ml

2.) <text>_base.y[a]ml

3.) base.y[a]ml

4.) <text>_base_<text>.y[a]ml

where <text> MUST contain only alphanumeric characters and underscores ‘_’ and MUST NOT contain the case insensitive string base or volume.

Requirement: R-91342 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
validation_mode: static

A VNF Heat Orchestration Template’s Base Module’s Environment File MUST be named identical to the VNF Heat Orchestration Template’s Base Module with .y[a]ml replaced with .env.

Incremental Modules
Requirement: R-87247 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: el alto
validation_mode: static

VNF Heat Orchestration Template’s Incremental Module file name MUST contain only alphanumeric characters and underscores ‘_’ and MUST NOT contain the case insensitive string base.

Requirement: R-94509 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
validation_mode: static

A VNF Heat Orchestration Template’s Incremental Module’s Environment File MUST be named identical to the VNF Heat Orchestration Template’s Incremental Module with .y[a]ml replaced with .env.

To clearly identify the incremental module, it is recommended to use the following naming options for modules:

  • module_<text>.y[a]ml

  • <text>_module.y[a]ml

  • module.y[a]ml

  • <text>_module_<text>.y[a]ml

Cinder Volume Modules
Requirement: R-82732 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

A VNF Heat Orchestration Template’s Cinder Volume Module MUST be named identical to the base or incremental module it is supporting with _volume appended.

Requirement: R-589037 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: dublin
updated: el alto
validation_mode: static

A VNF Heat Orchestration Template’s Cinder Volume Module resources: section MUST only be defined using one of the following:

  • one of more OS::Cinder::Volume resources

  • one or more OS::Heat::ResourceGroup resources that call a nested YAML file that contains only OS::Cinder::Volume resources

  • a resource that calls a nested YAML file (static nesting) that contains only OS::Cinder::Volume resources

Requirement: R-31141 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

VNF Heat Orchestration Template’s Cinder Volume Module’s Environment File MUST be named identical to the VNF Heat Orchestration Template’s Cinder Volume Module with .y[a]ml replaced with .env.

Nested Heat file
Requirement: R-76057 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: el alto
validation_mode: static

VNF Heat Orchestration Template’s Nested YAML file name MUST contain only alphanumeric characters and underscores ‘_’ and MUST NOT contain the case insensitive string base.

Requirement: R-70276 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
validation_mode: static

A VNF HEAT’s Orchestration Nested Template’s YAML file name MUST NOT be in the format {vm-type}.y[a]ml where {vm-type} is defined in the Heat Orchestration Template.

Examples include

  • <text>.y[a]ml

  • nest_<text>.y[a]ml

  • <text>_nest.y[a]ml

  • nest.y[a]ml

  • <text>_nest_<text>.y[a]ml

VNF Heat Orchestration Template’s Nested YAML file does not have a corresponding environment files, per OpenStack specifications.

Output Parameters

The output parameters are parameters defined in the output section of a Heat Orchestration Template. The ONAP output parameters are subdivided into three categories:

  1. ONAP Base Module Output Parameters

  2. ONAP Volume Module Output Parameters

  3. ONAP Predefined Output Parameters.

ONAP Base Module Output Parameters

ONAP Base Module Output Parameters are declared in the outputs: section of the VNF’s Heat Orchestration Template’s Base Module. A Base Module Output Parameter is available as an input parameter (i.e., declared in the parameters: section) to all Incremental Modules in the VNF.

A Base Module Output Parameter may be used as an input parameter in any incremental module in the VNF. Note that the parameter is not available to other VNFs.

Requirement: R-52753 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: dublin
validation_mode: none

VNF’s Heat Orchestration Template’s Base Module’s output parameter’s name and type MUST match the VNF’s Heat Orchestration Template’s incremental Module’s name and type.

Requirement: R-22608 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD NOT
updated: dublin
validation_mode: static

When a VNF’s Heat Orchestration Template’s Base Module’s output parameter is declared as an input parameter in an Incremental Module, the parameter attribute constraints: SHOULD NOT be declared.

Additional details on ONAP Base Module Output Parameters are provided in ONAP Output Parameter Names and ONAP VNF Modularity.

ONAP Volume Module Output Parameters
Requirement: R-89913 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: dublin
validation_mode: static

A VNF’s Heat Orchestration Template’s Cinder Volume Module Output Parameter(s) MUST include the UUID(s) of the Cinder Volumes created in template.

A VNF’s Heat Orchestration Template’s Cinder Volume Module Output Parameter(s) are only available for the module (base or incremental) that the volume template is associated with.

Requirement: R-07443 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: dublin
validation_mode: static

A VNF’s Heat Orchestration Templates’ Cinder Volume Module Output Parameter’s name and type MUST match the input parameter name and type in the corresponding Base Module or Incremental Module.

Requirement: R-20547 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD NOT
updated: dublin
validation_mode: static

When an ONAP Volume Module Output Parameter is declared as an input parameter in a base or an incremental module Heat Orchestration Template, parameter constraints SHOULD NOT be declared.

Additional details on ONAP Base Module Output Parameters are provided in ONAP Output Parameter Names and ONAP Heat Cinder Volumes.

ONAP Predefined Output Parameters

ONAP will look for a small set of pre-defined Heat output parameters to capture resource attributes for inventory in ONAP. These output parameters are optional and currently only two parameters are supported. These output parameters are optional and are specified in OAM Management IP Addresses.

Support of heat stack update

ONAP does not support the use of heat stack-update command for scaling (growth/de-growth).

Requirement: R-39349 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
validation_mode: none

A VNF Heat Orchestration Template MUST NOT be designed to utilize the OpenStack heat stack-update command for scaling (growth/de-growth).

Requirement: R-43413 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
validation_mode: none

A VNF MUST utilize a modular Heat Orchestration Template design to support scaling (growth/de-growth).

It is important to note that ONAP only supports heat stack-update for image upgrades.

Scope of a Heat Orchestration Template
Requirement: R-59482 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
validation_mode: none

A VNF’s Heat Orchestration Template MUST NOT be VNF instance specific or cloud site specific.

ONAP provides the instance specific parameter values to the Heat Orchestration Template at orchestration time.

Requirement: R-01896 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
validation_mode: none

A VNF’s Heat Orchestration Template’s parameter values that are constant across all deployments MUST be declared in a Heat Orchestration Template Environment File.

ONAP VNF On-Boarding
Requirement: R-511776 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: dublin
validation_mode: static

When a VNF’s Heat Orchestration Template is ready to be on-boarded to ONAP, all files composing the VNF Heat Orchestration Template MUST be placed in a flat (i.e., non-hierarchical) directory and archived using ZIP. The resulting ZIP file is uploaded into ONAP.

The VNF’s Heat Orchestration Template’s ZIP file must include the base module YAML file (R-37028) and corresponding environment file (R-38474).

The VNF’s Heat Orchestration Template’s ZIP file MAY include

  • One or more incremental module YAML files (R-13196) and corresponding environment files (R-81725).

  • One or more volume module YAML files (R-03251) and corresponding environment files (R-53433).

  • One or more nested YAML files (R-36582, R-56721, R-30395).

  • One or more files that are retrieved via the intrinsic function get_file. The get_file function returns the content of a file into a Heat Orchestration Template. It is generally used as a file inclusion mechanism for files containing scripts or configuration files. (See Section 9.3)

Requirement: R-348813 _images/arrow-right-circle.svg
target: VNF HEAT PACKAGE
keyword: MUST NOT
introduced: dublin
validation_mode: static

The VNF’s Heat Orchestration Template’s ZIP file MUST NOT include a binary image file.

ONAP Heat Networking

ONAP defines two types of networks: External Networks and Internal Networks.

External Networks

An ONAP external network is created by using VID or by invoking SO directly to instantiate the network. External networks are orchestrated separately, independent of VNFs. A network instantiated via VID or by invoking SO directly is managed by ONAP and is inventoried in AAI.

An external network can be created by using one of the following resources:

  • OS::Neutron::Net

  • OS::Neutron::ProviderNet

  • OS::ContrailV2::VirtualNetwork

An external network MAY be used to

  • Connect a VM in a VNF to VMs in another VNF

  • Connect a VM in a VNF to an external gateway or external router

  • Connect a VM in a VNF to other VMs in the same VNF

An external network may be designed to perform

  • All three functions listed above or

  • Perform only two functions listed above or

  • Perform only one function listed above

Requirement: R-16968 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
updated: frankfurt
validation_mode: static

A VNF’s Heat Orchestration Templates MUST NOT include heat resources to create an ONAP external network.

An ONAP external network MUST be instantiated by using VID or by invoking SO directly.

Requirement: R-00606 _images/arrow-right-circle.svg
target: VNF
keyword: MAY
updated: frankfurt

A VNF MAY be connected to zero, one or more than one ONAP external network.

Requirement: R-57424 _images/arrow-right-circle.svg
target: VNF
keyword: MAY
updated: frankfurt
validation_mode: none

A VNF’s port connected to an ONAP external network MAY use the port for the purpose of

  • Connecting a VM in the VNF to VMs in another VNF and/or

  • Connecting a VM in the VNF to an external gateway or external router and/or

  • Connecting a VM in the VNF to other VMs in the same VNF

Requirement: R-99794 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt
validation_mode: none

An ONAP external network MUST have one subnet. An external network MAY have more than one subnet.

ONAP enforces a naming convention for resource IDs and resource property parameters associated with external networks. ONAP Heat Resource ID and Parameter Naming Convention provides additional details.

Internal Networks

An ONAP internal network is created by the VNF’s Heat Orchestration Template. That is, the VNF’s Heat Orchestration Template contains the heat resources to instantiate the network. An ONAP internal network is not inventoried by AAI and can not be managed independently of the VNF.

An ONAP internal network MUST only be used for connecting a VM in the VNF to other VMs in the same VNF.

An ONAP internal network MUST NOT be used for connecting a VM in the VNF to VMs in another VNF or connecting a VM in the VNF to an external gateway and/or external router.

The reason for this is for operational simplicity. An ONAP internal network will be deleted when the VNF that created the network (referred to as VNF A) is deleted. If a different VNF (referred to as VNF B) attaches to the ONAP internal network created by VNF A, then VNF B must be deleted prior VNF A.

In addition, if an ONAP internal network is used to connect two (or more) VNFs, there is no record in AAI inventory. This could lead to additional operational complications.

Requirement: R-87096 _images/arrow-right-circle.svg
target: VNF
keyword: MAY
updated: frankfurt

A VNF MAY contain zero, one or more than one ONAP internal network.

Requirement: R-35666 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt
validation_mode: static

If a VNF has an ONAP internal network, the VNF’s Heat Orchestration Template MUST include the heat resources to create the ONAP internal network.

A VNF’s ONAP internal network is created using Neutron Heat Resources (e.g., OS::Neutron::Net, OS::Neutron::Subnet, OS::Neutron::ProviderNet) and/or Contrail Heat Resources (e.g., OS::ContrailV2::VirtualNetwork, OS::ContrailV2::NetworkIpam).

Requirement: R-52425 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt
validation_mode: none

A VNF’s port connected to an ONAP internal network MUST use the port for the purpose of reaching VMs in the same VNF.

Requirement: R-46461 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
updated: frankfurt
validation_mode: none

A VNF’s port connected to an ONAP internal network MUST NOT use the port for the purpose of reaching VMs in another VNF and/or an external gateway and/or external router.

Requirement: R-16241 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt
validation_mode: static

A VNF’s ONAP internal network MUST have one subnet. A VNF’s ONAP internal network MAY have more than one subnet.

Requirement: R-86972 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD
updated: frankfurt

A VNF SHOULD create the ONAP internal network in the VNF’s Heat Orchestration Template’s Base Module.

Requirement: R-22688 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt
validation_mode: static

When a VNF’s Heat Orchestration Template creates an ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666) and the ONAP internal network needs to be shared between modules within a VNF, the ONAP internal network MUST be created either in the

  • the base module

  • a nested YAML file invoked by the base module

and the base module MUST contain an output parameter that provides either the network UUID or network name.

  • If the network UUID value is used to reference the network, the output parameter name in the base module MUST follow the naming convention int_{network-role}_net_id

  • If the network name in is used to reference the network, the output parameter name in the base template MUST follow the naming convention int_{network-role}_net_name

The {network-role} MUST be the network-role of the ONAP internal network created in the Base Module.

The Base Module Output Parameter MUST be declared in the parameters: section of the Incremental Module(s) where the OS::Neutron::Port resource(s) is attaching to the ONAP internal network.

ONAP does not programmatically enforce a naming convention for parameters for internal network. However, a naming convention is provided that must be followed. ONAP Heat Resource ID and Parameter Naming Convention provides additional details.

ONAP Heat Resource ID and Parameter Naming Convention

This section provides the ONAP naming requirements for:

  1. Resource IDs

  2. Resource Property Parameters

{vm-type}
Requirement: R-01455 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: dublin
validation_mode: static

When a VNF’s Heat Orchestration Template creates a Virtual Machine (i.e., OS::Nova::Server), each “class” of VMs MUST be assigned a VNF unique {vm-type}; where “class” defines VMs that MUST have the following identical characteristics:

1.) OS::Nova::Server resource property flavor value

2.) OS::Nova::Server resource property image value

3.) Cinder Volume attachments

  • Each VM in the “class” MUST have the identical Cinder Volume configuration

4.) Network attachments and IP address requirements

  • Each VM in the “class” MUST have the identical number of ports connecting to the identical networks and requiring the identical IP address configuration.

The {vm-type} will be used in a VNF’s Heat Orchestration Template’s

  • Resource IDs

  • Resource property parameter names

A VNF’s Heat Orchestration Template’s Resource property parameter that is associated with a unique Virtual Machine type MUST include {vm-type} as part of the parameter name with two exceptions:

1.) The Resource OS::Nova::Server property availability_zone parameter MUST NOT be prefixed with a common {vm-type} identifier,

2.) The Resource OS::Nova::Server mandatory and optional metadata parameters

  • vnf_name

  • vnf_id

  • vf_module_id

  • vf_module_name

  • vf_module_index

  • environment_context

  • workload_context

MUST NOT be prefixed with a common {vm-type} identifier.

Requirements for specific resource property parameter names can be found in later sections of this document.

Requirement: R-98407 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
updated: casablanca
validation_mode: static

A VNF’s Heat Orchestration Template’s {vm-type} MUST contain only alphanumeric characters and/or underscores ‘_’ and MUST NOT contain any of the following strings: _int or int_ or _int_.

Requirement: R-48067 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
updated: casablanca
validation_mode: static

A VNF’s Heat Orchestration Template’s {vm-type} MUST NOT be a substring of {network-role}.

It may cause the VNF Validation Program validation-scripts project to produce erroneous error messages.

Requirement: R-32394 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

A VNF’s Heat Orchestration Template’s use of {vm-type} in all Resource property parameter names MUST be the same case.

Requirement: R-46839 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

A VNF’s Heat Orchestration Template’s use of {vm-type} in all Resource IDs MUST be the same case.

Requirement: R-36687 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD
updated: casablanca

A VNF’s Heat Orchestration Template’s {vm-type} case in Resource property parameter names SHOULD match the case of {vm-type} in Resource IDs and vice versa.

{network-role}
Requirement: R-69014 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt
validation_mode: none

When a VNF’s port connects to an ONAP internal network or ONAP external network, a network role, referred to as the {network-role} MUST be assigned to the network for use in the VNF’s Heat Orchestration Template. The {network-role} is used in the VNF’s Heat Orchestration Template’s resource IDs and resource property parameter names.

Requirement: R-05201 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: dublin
validation_mode: none

When a VNF connects to two or more unique networks, each network MUST be assigned a unique {network-role} in the context of the VNF for use in the VNF’s Heat Orchestration Template.

Requirement: R-21330 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt
validation_mode: none

A VNF’s Heat Orchestration Template’s Resource property parameter that is associated with an ONAP external network MUST include the {network-role} as part of the parameter name.

Requirement: R-11168 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt
validation_mode: none

A VNF’s Heat Orchestration Template’s Resource ID that is associated with an ONAP external network MUST include the {network-role} as part of the resource ID.

Requirement: R-84322 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt
validation_mode: none

A VNF’s Heat Orchestration Template’s Resource property parameter that is associated with an ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666) MUST include int_{network-role} as part of the parameter name, where int_ is a hard coded string.

Requirement: R-96983 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt
validation_mode: none

A VNF’s Heat Orchestration Template’s Resource ID that is associated with an ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666) MUST include int_{network-role} as part of the Resource ID, where int_ is a hard coded string.

Requirement: R-26506 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
updated: dublin
validation_mode: static

A VNF’s Heat Orchestration Template’s {network-role} MUST contain only alphanumeric characters and/or underscores ‘_’ and

  • MUST NOT contain any of the following strings: _int or int_ or _int_

  • MUST NOT end in the string: _v6

  • MUST NOT contain the strings _#_, where # is a number

  • MUST NOT end in the string: _#, where # is a number

Requirement: R-00977 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
updated: casablanca
validation_mode: static

A VNF’s Heat Orchestration Template’s {network-role} MUST NOT be a substring of {vm-type}.

For example, if a VNF has a ‘{vm-type}’ of ‘oam’ and a ‘{network-role}’ of ‘oam_protected’ would be a violation of the requirement.

Requirement: R-58424 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: none

A VNF’s Heat Orchestration Template’s use of {network-role} in all Resource property parameter names MUST be the same case.

Requirement: R-21511 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: none

A VNF’s Heat Orchestration Template’s use of {network-role} in all Resource IDs MUST be the same case.

Requirement: R-86588 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD
updated: casablanca

A VNF’s Heat Orchestration Template’s {network-role} case in Resource property parameter names SHOULD match the case of {network-role} in Resource IDs and vice versa.

Note that this document refers to {network-role} which in reality is the {network-role-tag}. The value of the {network-role} / {network-role-tag} is determined by the designer of the VNF’s Heat Orchestration Template and there is no requirement for {network-role} / {network-role-tag} uniqueness across Heat Orchestration Templates for different VNFs.

When an external network is created by ONAP, the network is also assigned a {network-role}. The {network-role} of the network is not required to match the {network-role} of the VNF Heat Orchestration Template.

For example, the VNF Heat Orchestration Template can assign a {network-role} of oam to a network which attaches to an external network with a {network-role} of oam_protected .

When the Heat Orchestration Template is on-boarded into ONAP
  • each {network-role} value in the Heat Orchestration Template is mapped to the {network-role-tag} in the ONAP data structure.

  • each OS::Neutron::Port is associated with the external network it is connecting to, thus creating the VNF Heat Orchestration Template {network-role} / {network-role-tag} to external network {network-role} mapping.

Resource IDs

Requirement R-75141 states a VNF’s Heat Orchestration Template’s resource name (i.e., <resource ID>) MUST only contain alphanumeric characters and underscores (‘_’).*

Requirement R-16447 states a VNF’s <resource ID> MUST be unique across all Heat Orchestration Templates and all HEAT Orchestration Template Nested YAML files that are used to create the VNF.

As stated previously, OpenStack requires the <resource ID> to be unique to the Heat Orchestration Template and not unique across all Heat Orchestration Templates the compose the VNF.

Heat Orchestration Template resources are described in resources.

Requirement: R-54517 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: none

When a VNF’s Heat Orchestration Template’s resource is associated with a single {vm-type}, the Resource ID MUST contain the {vm-type}.

Requirement: R-96482 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt
validation_mode: none

When a VNF’s Heat Orchestration Template’s resource is associated with a single ONAP external network, the Resource ID MUST contain the text {network-role}.

Requirement: R-98138 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt
validation_mode: none

When a VNF’s Heat Orchestration Template’s resource is associated with a single ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666), the Resource ID MUST contain the text int_{network-role}.

Requirement: R-82115 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt
validation_mode: none

When a VNF’s Heat Orchestration Template’s resource is associated with a single {vm-type} and a single ONAP external network, the Resource ID text MUST contain both the {vm-type} and the {network-role}

  • the {vm-type} MUST appear before the {network-role} and MUST be separated by an underscore ‘_’

    • e.g., {vm-type}_{network-role}, {vm-type}_{index}_{network-role}

  • note that an {index} value MAY separate the {vm-type} and the {network-role} and when this occurs underscores MUST separate the three values. (e.g., {vm-type}_{index}_{network-role}).

Requirement: R-82551 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt
validation_mode: none

When a VNF’s Heat Orchestration Template’s resource is associated with a single {vm-type} and a single ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666), the Resource ID MUST contain both the {vm-type} and the int_{network-role} and

  • the {vm-type} MUST appear before the int_{network-role} and MUST be separated by an underscore ‘_’

    • (e.g., {vm-type}_int_{network-role}, {vm-type}_{index}_int_{network-role})

  • note that an {index} value MAY separate the {vm-type} and the int_{network-role} and when this occurs underscores MUST separate the three values. (e.g., {vm-type}_{index}_int_{network-role}).

Requirement: R-67793 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
updated: frankfurt
validation_mode: none

When a VNF’s Heat Orchestration Template’s resource is associated with more than one {vm-type} and/or more than one ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666) and/or ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), the Resource ID MUST NOT contain the {vm-type} and/or {network-role}/int_{network-role}.

Requirement: R-27970 _images/arrow-right-circle.svg
target: VNF
keyword: MAY
updated: frankfurt

When a VNF’s Heat Orchestration Template’s resource is associated with more than one {vm-type} and/or more than one ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666) and/or ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), the Resource ID MAY contain the term shared and/or MAY contain text that identifies the VNF.

Requirement: R-11690 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: dublin
validation_mode: static

When a VNF’s Heat Orchestration Template’s Resource ID contains an {index}, the {index} is a numeric value that MUST start at zero and MUST increment by one.

As stated in R-16447, a VNF’s <resource ID> MUST be unique across all Heat Orchestration Templates and all HEAT Orchestration Template Nested YAML files that are used to create the VNF. While the {index} will start at zero in the VNF, the {index} may not start at zero in a given Heat Orchestration Template or HEAT Orchestration Template Nested YAML file.

OpenStack Heat Resources Resource ID Naming Convention

Some OpenStack Heat Resources Resource IDs have mandatory or suggested naming conventions. They are provided in the following sections.

OS::Cinder::Volume
Requirement: R-87004 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD
updated: dublin

A VNF’s Heat Orchestration Template’s Resource OS::Cinder::Volume Resource ID SHOULD use the naming convention

  • {vm-type}_volume_{index}

where

  • {vm-type} is the vm-type

  • {index} starts at zero and increments by one (as described in R-11690)

OS::Cinder::VolumeAttachment
Requirement: R-86497 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD
updated: dublin

A VNF’s Heat Orchestration Template’s Resource OS::Cinder::VolumeAttachment Resource ID SHOULD use the naming convention

  • {vm-type}_volume_attachment_{index}

where

  • {vm-type} is the vm-type

  • {index} starts at zero and increments by one (as described in R-11690)

OS::Heat::CloudConfig
Requirement: R-04747 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

A VNF’s Heat Orchestration Template’s Resource OS::Heat::CloudConfig Resource ID MUST contain the {vm-type}.

Requirement: R-20319 _images/arrow-right-circle.svg
target: VNF
keyword: MAY
updated: casablanca

A VNF’s Heat Orchestration Template’s Resource OS::Heat::CloudConfig Resource ID MAY use the naming convention

  • {vm-type}_RCC

where

  • {vm-type} is the vm-type

  • RCC signifies that it is the Resource Cloud Config

OS::Heat::MultipartMime
Requirement: R-30804 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

A VNF’s Heat Orchestration Template’s Resource OS::Heat::MultipartMime Resource ID MUST contain the {vm-type}.

Requirement: R-18202 _images/arrow-right-circle.svg
target: VNF
keyword: MAY
updated: casablanca

A VNF’s Heat Orchestration Template’s Resource OS::Heat::MultipartMime Resource ID MAY use the naming convention

  • {vm-type}_RMM

where

  • {vm-type} is the vm-type

  • RMM signifies that it is the Resource Multipart Mime

OS::Heat::ResourceGroup

There is no mandatory naming convention for the resource ‘OS::Heat::ResourceGroup’.

OS::Heat::SoftwareConfig
Requirement: R-08975 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

A VNF’s Heat Orchestration Template’s Resource OS::Heat::SoftwareConfig Resource ID MUST contain the {vm-type}.

Requirement: R-03656 _images/arrow-right-circle.svg
target: VNF
keyword: MAY
updated: casablanca

A VNF’s Heat Orchestration Template’s Resource OS::Heat::SoftwareConfig Resource ID MAY use the naming convention

  • {vm-type}_RSC

where

  • {vm-type} is the vm-type

  • RSC signifies that it is the Resource Software Config

OS::Neutron::Net
Requirement: R-25720 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt
validation_mode: static

A VNF’s Heat Orchestration Template’s Resource OS::Neutron::Net Resource ID MUST use the naming convention

  • int_{network-role}_network

VNF Heat Orchestration Templates can only create ONAP internal networks (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666). There is no {index} after {network-role} because {network-role} MUST be unique in the scope of the VNF’s Heat Orchestration Template.

OS::Neutron::Port
Requirement: R-20453 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt
validation_mode: static

A VNF’s Heat Orchestration Template’s Resource OS::Neutron::Port that is attaching to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), the OS::Neutron::Port Resource ID MUST use the naming convention

  • {vm-type}_{vm-type_index}_{network-role}_port_{port-index}

where

  • {vm-type} is the vm-type

  • {vm-type_index} references the instance of the {vm-type} in the VNF. The {vm-type_index} is a numeric value that MUST start at zero in the VNF and MUST increment by one each time a new instance of a {vm-type} is referenced.

  • {network-role} is the network-role of the ONAP external network that the port is attached to

  • {port_index} references the instance of the port on the {vm-type} attached to {network-role} network. The {port_index} is a numeric value that MUST start at zero on an instance of a {vm-type} and MUST increment by one each time a new port is defined on the instance of the {vm-type} attached to {network-role} network.

Requirement: R-26351 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt
validation_mode: static

A VNF’s Heat Orchestration Template’s Resource OS::Neutron::Port that is attaching to an ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666), the OS::Neutron::Port Resource ID MUST use the naming convention

  • {vm-type}_{vm-type_index}_int_{network-role}_port_{port-index}

where

  • {vm-type} is the vm-type

  • {vm-type_index} references the instance of the {vm-type} in the VNF. The {vm-type_index} is a numeric value that MUST start at zero in the VNF and MUST increment by one each time a new instance of a {vm-type} is referenced.

  • {network-role} is the network-role of the ONAP internal network that the port is attached to

  • {port_index} references the instance of the port on the {vm-type} attached to {network-role} network. The {port_index} is a numeric value that MUST start at zero on an instance of a {vm-type} and MUST increment by one each time a new port is defined on the instance of the {vm-type} attached to {network-role} network.

Requirement: R-27469 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD
updated: frankfurt
validation_mode: none

A VNF’s Heat Orchestration Template’s Resource OS::Neutron::Port that is creating a Reserve Port with an IPv4 address, the OS::Neutron::Port Resource ID SHOULD use the naming convention

  • reserve_port_{vm-type}_{network-role}_floating_ip_{index}

where

  • {vm-type} is the vm-type

  • {network-role} is the network-role of the ONAP external network that the port is attached to

  • {index} is the instance of the IPv4 Reserve Port for the vm-type attached to the network of {network-role}. The {index} starts at zero and increments by one (as described in R-11690).

Requirement: R-68520 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD
updated: frankfurt
validation_mode: none

A VNF’s Heat Orchestration Template’s Resource OS::Neutron::Port that is creating a Reserve Port with an IPv6 address, the OS::Neutron::Port Resource ID SHOULD use the naming convention

  • reserve_port_{vm-type}_{network-role}_floating_v6_ip_{index}

where

  • {vm-type} is the vm-type

  • {network-role} is the network-role of the ONAP external network that the port is attached to

  • {index} is the instance of the IPv6 Reserve Port for the vm-type attached to the network of {network-role}. The {index} starts at zero and increments by one (as described in R-11690).

OS::Neutron::SecurityGroup
Requirement: R-08775 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD
updated: frankfurt

A VNF’s Heat Orchestration Template’s Resource OS::Neutron::SecurityGroup that is applicable to one {vm-type} and more than one network (ONAP internal network and/or ONAP external network), the OS::Neutron::SecurityGroup Resource ID SHOULD use the naming convention

  • {vm-type}_security_group

where

  • {vm-type} is the vm-type

Requirement: R-03595 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD
updated: frankfurt

A VNF’s Heat Orchestration Template’s Resource OS::Neutron::SecurityGroup that is applicable to more than one {vm-type} and one ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), the OS::Neutron::SecurityGroup Resource ID SHOULD use the naming convention

  • {network-role}_security_group

where

  • {network-role} is the network-role of the ONAP external network

Requirement: R-73213 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD
updated: frankfurt

A VNF’s Heat Orchestration Template’s Resource OS::Neutron::SecurityGroup that is applicable to more than one {vm-type} and one ONAP internal network, (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666), the OS::Neutron::SecurityGroup Resource ID SHOULD use the naming convention

  • int_{network-role}_security_group

where

  • {network-role} is the network-role of the ONAP internal network

Requirement: R-17334 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD
updated: frankfurt

A VNF’s Heat Orchestration Template’s Resource OS::Neutron::SecurityGroup that is applicable to one {vm-type} and one ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), the OS::Neutron::SecurityGroup Resource ID SHOULD use the naming convention

  • {vm-type}_{network-role}_security_group

where

  • {vm-type} is the vm-type

  • {network-role} is the network-role of the ONAP external network

Requirement: R-14198 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD
updated: frankfurt

A VNF’s Heat Orchestration Template’s Resource OS::Neutron::SecurityGroup that is applicable to one {vm-type} and one ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666), the OS::Neutron::SecurityGroup Resource ID SHOULD use the naming convention

  • {vm-type}_int_{network-role}_security_group

where

  • {vm-type} is the vm-type

  • {network-role} is the network-role of the ONAP internal network

Requirement: R-30005 _images/arrow-right-circle.svg
target: VNF
keyword: MAY
updated: frankfurt

A VNF’s Heat Orchestration Template’s Resource OS::Neutron::SecurityGroup that is applicable to more than one {vm-type} and more than one network (internal and/or external), the OS::Neutron::SecurityGroup Resource ID MAY use the naming convention

  • shared_security_group

or

  • {vnf-type}_security_group

where

  • {vnf-type} describes the VNF

OS::Neutron::Subnet
Requirement: R-59434 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD
updated: frankfurt

A VNF’s Heat Orchestration Template’s Resource OS::Neutron::Subnet Resource ID SHOULD use the naming convention

  • int_{network-role}_subnet_{index}

where

  • {network-role} is the network-role of the ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666).

  • {index} is the {index} of the subnet of the ONAP internal network. The {index} starts at zero and increments by one (as described in R-11690).

OS::Nova::Keypair
Requirement: R-24997 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD
updated: frankfurt

A VNF’s Heat Orchestration Template’s Resource OS::Nova::Keypair that applies to one {vm-type}, the OS::Nova::Keypair Resource ID SHOULD use the naming convention

  • {vm-type}_keypair_{index}

where

  • {vm-type} is the vm-type of the OS::Nova::Server

  • {index} is the {index} of the keypair. The {index} starts at zero and increments by one (as described in R-11690).

Requirement: R-65516 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD
updated: frankfurt

A VNF’s Heat Orchestration Template’s Resource OS::Nova::Keypair that applies to all Virtual Machines in the VNF, the OS::Nova::Keypair Resource ID SHOULD use the naming convention

  • {vnf-type}_keypair

where

  • {vnf-type} describes the VNF

OS::Nova::Server
Requirement: R-29751 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: dublin
validation_mode: static

A VNF’s Heat Orchestration Template’s Resource OS::Nova::Server Resource ID MUST use the naming convention

  • {vm-type}_server_{index}

where

  • {vm-type} is the vm-type

  • {index} is the index. The {index} MUST starts at zero and increment by one as described in R-11690.

OS::Nova::ServerGroup
Requirement: R-15189 _images/arrow-right-circle.svg
target: VNF
keyword: MAY
updated: casablanca

A VNF’s Heat Orchestration Template’s Resource OS::Nova::ServerGroup Resource ID MAY use the naming convention

  • {vm-type}_RSG

or

  • {vm-type}_Server_Grp

or

  • {vm-type}_ServerGroup

or

  • {vm-type}_servergroup

Contrail Heat Resources Resource ID Naming Convention

Some Contrail Heat Resources Resource IDs have mandatory or suggested naming conventions. They are provided in the following sections.

OS::ContrailV2::InstanceIp
Requirement: R-53310 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt
validation_mode: static

A VNF’s Heat Orchestration Template’s Resource OS::ContrailV2::InstanceIp Resource ID that is configuring an IPv4 Address on a virtual machine interface (i.e., OS::ContrailV2::VirtualMachineInterface) attached to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968) MUST use the naming convention

  • {vm-type}_{vm-type_index}_{network-role}_vmi_{vmi_index}_IP_{index}

where

  • {vm-type} is the vm-type

  • {vm-type_index} references the instance of the {vm-type} in the VNF. The {vm-type_index} is a numeric value that MUST start at zero in the VNF and MUST increment by one each time a new instance of a {vm-type} is referenced.

  • {network-role} is the network-role of the ONAP external network that the virtual machine interface is attached to

  • {vmi_index} references the instance of the virtual machine interface on the {vm-type} attached to {network-role} network. The {vmi_index} is a numeric value that MUST start at zero on an instance of a {vm-type} and MUST increment by one each time a new virtual machine interface is defined on the instance of the {vm-type} attached to {network-role} network.

  • IP signifies that an IPv4 address is being configured

  • {index} references the instance of the IPv4 address configured on the virtual machine interface. The {index} is a numeric value that MUST start at zero on an instance of a virtual machine interface and MUST increment by one each time a new IPv4 address is configured on the virtual machine interface.

Requirement: R-46128 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt
validation_mode: static

A VNF’s Heat Orchestration Template’s Resource OS::ContrailV2::InstanceIp Resource ID that is configuring an IPv6 Address on a virtual machine interface (i.e., OS::ContrailV2::VirtualMachineInterface) attached to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968) MUST use the naming convention

  • {vm-type}_{vm-type_index}_{network-role}_vmi_{vmi_index}_v6_IP_{index}

where

  • {vm-type} is the vm-type

  • {vm-type_index} references the instance of the {vm-type} in the VNF. The {vm-type_index} is a numeric value that MUST start at zero in the VNF and MUST increment by one each time a new instance of a {vm-type} is referenced.

  • {network-role} is the network-role of the ONAP external network that the port is attached to

  • {vmi_index} references the instance of the virtual machine interface on the {vm-type} attached to {network-role} network. The {vmi_index} is a numeric value that MUST start at zero on an instance of a {vm-type} and MUST increment by one each time a new virtual machine interface is defined on the instance of the {vm-type} attached to {network-role} network.

  • v6_IP signifies that an IPv6 address is being configured

  • {index} references the instance of the IPv6 address configured on the virtual machine interface. The {index} is a numeric value that MUST start at zero on an instance of a virtual machine interface and MUST increment by one each time a new IPv6 address is configured on the virtual machine interface.

Requirement: R-62187 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt
validation_mode: static

A VNF’s Heat Orchestration Template’s Resource OS::ContrailV2::InstanceIp Resource ID that is configuring an IPv4 Address on a virtual machine interface (i.e., OS::ContrailV2::VirtualMachineInterface) attached to an ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666) MUST use the naming convention

  • {vm-type}_{vm-type_index}_int_{network-role}_vmi_{vmi_index}_IP_{index}

where

  • {vm-type} is the vm-type

  • {vm-type_index} references the instance of the {vm-type} in the VNF. The {vm-type_index} is a numeric value that MUST start at zero in the VNF and MUST increment by one each time a new instance of a {vm-type} is referenced.

  • {network-role} is the network-role of the ONAP internal network that the port is attached to

  • {vmi_index} references the instance of the virtual machine interface on the {vm-type} attached to {network-role} network. The {vmi_index} is a numeric value that MUST start at zero on an instance of a {vm-type} and MUST increment by one each time a new virtual machine interface is defined on the instance of the {vm-type} attached to {network-role} network.

  • IP signifies that an IPv4 address is being configured

  • {index} references the instance of the IPv4 address configured on the virtual machine interface. The {index} is a numeric value that MUST start at zero on an instance of a virtual machine interface and MUST increment by one each time a new IPv4 address is configured on the virtual machine interface.

Requirement: R-87563 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt
validation_mode: static

A VNF’s Heat Orchestration Template’s Resource OS::ContrailV2::InstanceIp Resource ID that is configuring an IPv6 Address on a virtual machine interface (i.e., OS::ContrailV2::VirtualMachineInterface) attached to an ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666) MUST use the naming convention

  • {vm-type}_{vm-type_index}_int_{network-role}_vmi_{vmi_index}_v6_IP_{index}

where

  • {vm-type} is the vm-type

  • {vm-type_index} references the instance of the {vm-type} in the VNF. The {vm-type_index} is a numeric value that MUST start at zero in the VNF and MUST increment by one each time a new instance of a {vm-type} is referenced.

  • {network-role} is the network-role of the ONAP internal network that the port is attached to

  • {vmi_index} references the instance of the virtual machine interface on the {vm-type} attached to {network-role} network. The {vmi_index} is a numeric value that MUST start at zero on an instance of a {vm-type} and MUST increment by one each time a new virtual machine interface is defined on the instance of the {vm-type} attached to {network-role} network.

  • v6_IP signifies that an IPv6 address is being configured

  • {index} references the instance of the IPv6 address configured on the virtual machine interface. The {index} is a numeric value that MUST start at zero on an instance of a virtual machine interface and MUST increment by one each time a new IPv6 address is configured on the virtual machine interface.

OS::ContrailV2::InterfaceRouteTable
Requirement: R-81214 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

A VNF’s Heat Orchestration Template’s Resource OS::ContrailV2::InterfaceRouteTable Resource ID MUST contain the {network-role}.

Requirement: R-28189 _images/arrow-right-circle.svg
target: VNF
keyword: MAY
updated: casablanca

A VNF’s Heat Orchestration Template’s Resource OS::ContrailV2::InterfaceRouteTable Resource ID MAY use the naming convention

  • {network-role}_RIRT

where

  • {network-role} is the network-role

  • RIRT signifies that it is the Resource Interface Route Table

OS::ContrailV2::NetworkIpam
Requirement: R-30753 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt
validation_mode: static

A VNF’s Heat Orchestration Template’s Resource OS::ContrailV2::NetworkIpam Resource ID MUST contain the {network-role} of the ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666) that the resource is associated with.

Requirement: R-81979 _images/arrow-right-circle.svg
target: VNF
keyword: MAY
updated: casablanca

A VNF’s Heat Orchestration Template’s Resource OS::ContrailV2::NetworkIpam Resource ID MAY use the naming convention

  • {network-role}_RNI

where

  • {network-role} is the network-role

  • RNI signifies that it is the Resource Network IPAM

OS::ContrailV2::PortTuple
Requirement: R-20065 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

A VNF’s Heat Orchestration Template’s Resource OS::ContrailV2::PortTuple Resource ID MUST contain the {vm-type}.

Requirement: R-84457 _images/arrow-right-circle.svg
target: VNF
keyword: MAY
updated: casablanca

A VNF’s Heat Orchestration Template’s Resource OS::ContrailV2::PortTuple Resource ID MAY use the naming convention

  • {vm-type}_RPT

where

  • {vm-type} is the vm-type

  • RPT signifies that it is the Resource Port Tuple

OS::ContrailV2::ServiceHealthCheck
Requirement: R-76014 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

A VNF’s Heat Orchestration Template’s Resource OS::ContrailV2::ServiceHealthCheck Resource ID MUST contain the {vm-type}.

Requirement: R-65618 _images/arrow-right-circle.svg
target: VNF
keyword: MAY
updated: casablanca

A VNF’s Heat Orchestration Template’s Resource OS::ContrailV2::ServiceHealthCheck Resource ID MAY use the naming convention

  • {vm-type}_RSHC_{LEFT|RIGHT}

where

  • {vm-type} is the vm-type

  • RSHC signifies that it is the Resource Service Health Check

  • LEFT is used if the Service Health Check is on the left interface

  • RIGHT is used if the Service Health Check is on the right interface

OS::ContrailV2::ServiceTemplate
Requirement: R-16437 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

A VNF’s Heat Orchestration Template’s Resource OS::ContrailV2::ServiceTemplate Resource ID MUST contain the {vm-type}.

Requirement: R-14447 _images/arrow-right-circle.svg
target: VNF
keyword: MAY
updated: dublin

A VNF’s Heat Orchestration Template’s Resource OS::ContrailV2::ServiceTemplate Resource ID MAY use the naming convention

  • {vm-type}_RST_{index}

where

  • {vm-type} is the vm-type

  • RST signifies that it is the Resource Service Template

  • {index} is the index. The {index} starts at zero and increments by one (as described in R-11690).

OS::ContrailV2::VirtualMachineInterface
Requirement: R-96253 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt
validation_mode: static

A VNF’s Heat Orchestration Template’s Resource OS::ContrailV2::VirtualMachineInterface Resource ID that is attaching to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968) MUST use the naming convention

  • {vm-type}_{vm-type_index}_{network-role}_vmi_{vmi_index}

where

  • {vm-type} is the vm-type

  • {vm-type_index} references the instance of the {vm-type} in the VNF. The {vm-type_index} is a numeric value that MUST start at zero in the VNF and MUST increment by one each time a new instance of a {vm-type} is referenced.

  • {network-role} is the network-role of the ONAP external network that the port (i.e. virtual machine interface) is attached to

  • {vmi_index} references the instance of the virtual machine interface on the {vm-type} attached to {network-role} network. The {vmi_index} is a numeric value that MUST start at zero on an instance of a {vm-type} and MUST increment by one each time a new virtual machine interface is defined on the instance of the {vm-type} attached to {network-role} network.

Requirement: R-50468 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt
validation_mode: static

A VNF’s Heat Orchestration Template’s Resource OS::ContrailV2::VirtualMachineInterface Resource ID that is attaching to an ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666) MUST use the naming convention

  • {vm-type}_{vm-type_index}_int_{network-role}_vmi_{vmi_index}

where

  • {vm-type} is the vm-type

  • {vm-type_index} references the instance of the {vm-type} in the VNF. The {vm-type_index} is a numeric value that MUST start at zero in the VNF and MUST increment by one each time a new instance of a {vm-type} is referenced.

  • {network-role} is the network-role of the ONAP internal network that the port (i.e. virtual machine interface) is attached to

  • {vmi_index} references the instance of the virtual machine interface on the {vm-type} attached to {network-role} network. The {vmi_index} is a numeric value that MUST start at zero on an instance of a {vm-type} and MUST increment by one each time a new virtual machine interface is defined on the instance of the {vm-type} attached to {network-role} network.

OS::ContrailV2::VirtualNetwork
Requirement: R-99110 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt
validation_mode: static

A VNF’s Heat Orchestration Template’s Resource OS::ContrailV2::VirtualNetwork Resource ID MUST use the naming convention

  • int_{network-role}_network

VNF Heat Orchestration Templates can only create ONAP internal networks (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666). There is no {index} after {network-role} because {network-role} MUST be unique in the scope of the VNF’s Heat Orchestration Template.

Resource: OS::Nova::Server - Parameters

The OS::Nova::Server resource manages the running virtual machine (VM) instance within an OpenStack cloud. (See https://docs.openstack.org/developer/heat/template_guide/openstack.html#OS::Nova::Server)

The following four properties of the OS::Nova::Server resource must follow an ONAP specified naming convention.

  1. image

  2. flavor

  3. name

  4. availability_zone

Requirement R-01455 defines how the {vm-type] is defined.

Requirement: R-304011 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: casablanca
updated: el alto
validation_mode: static

A VNF’s Heat Orchestration Template’s OS::Nova::Server resource’s

  • Resource ID (defined in R-29751)

  • property image parameter name (defined in R-58670)

  • property flavor parameter name (defined in R-45188)

  • property name parameter name (defined in R-54171 & R-87817)

  • property networks map property port value which is a OS::Neutron::Port Resource ID (defined in R-20453) referenced using the intrinsic function get_attr

MUST contain the identical {vm-type} and MUST follow the naming conventions defined in R-58670, R-45188, R-54171, R-87817, and R-29751. And the {index} in the OS::Nova::Server Resource ID (defined in R-29751) MUST match the {vm-type_index} defined in the OS::Nova::Server property networks map property port referenced OS::Neutron::Port Resource ID (defined in R-20453).

The table below provides a summary. The sections that follow provides the detailed requirements.

Table 1 OS::Nova::Server Resource Property Parameter Naming Convention

Resource

Property

Parameter Type

Parameter Name

Parameter Value Provided to Heat

OS::Nova::Server

image

string

{vm-type}_image_name

Environment File

OS::Nova::Server

flavor

string

{vm-type}_flavor_name

Environment File

OS::Nova::Server

name

string

{vm-type}_name_{index}

ONAP

OS::Nova::Server

name

CDL

{vm-type}_names

ONAP

OS::Nova::Server

availability_zone

string

availability_zone_{index}

ONAP

Property: image
Requirement: R-901331 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: casablanca
validation_mode: static

The VNF’s Heat Orchestration Template’s Resource OS::Nova::Server property image value MUST be be obtained via a get_param.

Requirement: R-71152 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

The VNF’s Heat Orchestration Template’s Resource OS::Nova::Server property image parameter MUST be declared as type: string.

Requirement: R-58670 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

The VNF’s Heat Orchestration Template’s Resource OS::Nova::Server property image parameter name MUST follow the naming convention {vm-type}_image_name.

Requirement: R-91125 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

The VNF’s Heat Orchestration Template’s Resource OS::Nova::Server property image parameter MUST be enumerated in the Heat Orchestration Template’s Environment File and a value MUST be assigned.

Requirement: R-57282 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

Each VNF’s Heat Orchestration Template’s {vm-type} MUST have a unique parameter name for the OS::Nova::Server property image even if more than one {vm-type} shares the same image.

Example Parameter Definition

parameters:
    {vm-type}_image_name:
        type: string
        description: {vm-type} server image
Property: flavor
Requirement: R-481670 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: casablanca
validation_mode: static

The VNF’s Heat Orchestration Template’s Resource OS::Nova::Server property flavor value MUST be be obtained via a get_param.

Requirement: R-50436 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

The VNF’s Heat Orchestration Template’s Resource OS::Nova::Server property flavor parameter MUST be declared as type: string.

Requirement: R-45188 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

The VNF’s Heat Orchestration Template’s Resource ‘OS::Nova::Server’ property flavor parameter name MUST follow the naming convention {vm-type}_flavor_name.

Requirement: R-69431 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

The VNF’s Heat Orchestration Template’s Resource OS::Nova::Server property flavor parameter MUST be enumerated in the Heat Orchestration Template’s Environment File and a value MUST be assigned.

Requirement: R-40499 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

Each VNF’s Heat Orchestration Template’s {vm-type} MUST have a unique parameter name for the OS::Nova::Server property flavor even if more than one {vm-type} shares the same flavor.

Example Parameter Definition

parameters:
    {vm-type}_flavor_name:
        type: string
        description: {vm-type} flavor
Property: Name
Requirement: R-663631 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: casablanca
validation_mode: static

The VNF’s Heat Orchestration Template’s Resource OS::Nova::Server property name value MUST be be obtained via a get_param.

Requirement: R-51430 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

The VNF’s Heat Orchestration Template’s Resource OS::Nova::Server property name parameter MUST be declared as either type string or type comma_delimited_list.

Requirement: R-54171 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: dublin
validation_mode: static

When the VNF’s Heat Orchestration Template’s Resource OS::Nova::Server property name parameter is defined as a string, the parameter name MUST follow the naming convention

  • {vm-type}_name_{index}

where {index} is a numeric value that MUST start at zero in a VNF’s Heat Orchestration Template and MUST increment by one.

Requirement: R-87817 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

When the VNF’s Heat Orchestration Template’s Resource OS::Nova::Server property name parameter is defined as a comma_delimited_list, the parameter name MUST follow the naming convention {vm-type}_names.

Requirement: R-22838 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
updated: casablanca
validation_mode: static

The VNF’s Heat Orchestration Template’s Resource OS::Nova::Server property name parameter MUST NOT be enumerated in the Heat Orchestration Template’s Environment File.

If a VNF’s Heat Orchestration Template’s contains more than three OS::Nova::Server resources of a given {vm-type}, the comma_delimited_list form of the parameter name (i.e., {vm-type}_names) should be used to minimize the number of unique parameters defined in the template.

Example: Parameter Definition

parameters:

{vm-type}_names:
  type: comma_delimited_list
  description: VM Names for {vm-type} VMs

{vm-type}_name_{index}:
  type: string
  description: VM Name for {vm-type} VM {index}

Example: comma_delimited_list

In this example, the {vm-type} has been defined as “lb” for load balancer.

parameters:

  lb_names:
    type: comma_delimited_list
    description: VM Names for lb VMs

resources:
  lb_server_0:
    type: OS::Nova::Server
    properties:
      name: { get_param: [lb_names, 0] }
      ...

  lb_server_1:
    type: OS::Nova::Server
    properties:
      name: { get_param: [lb_names, 1] }
      ...

Example: fixed-index

In this example, the {vm-type} has been defined as “lb” for load balancer.

parameters:

  lb_name_0:
    type: string
    description: VM Name for lb VM 0

  lb_name_1:
    type: string
    description: VM Name for lb VM 1

resources:

  lb_server_0:
    type: OS::Nova::Server
    properties:
      name: { get_param: lb_name_0 }
      ...

  lb_server_1:
    type: OS::Nova::Server
    properties:
      name: { get_param: lb_name_1 }
      ...
Contrail Issue with Values for OS::Nova::Server Property Name
Requirement: R-44271 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD NOT
updated: casablanca

The VNF’s Heat Orchestration Template’s Resource OS::Nova::Server property name parameter value SHOULD NOT contain special characters since the Contrail GUI has a limitation displaying special characters.

However, if special characters must be used, the only special characters supported are: — " ! $ ‘ () = ~ ^ | @ ` { } [ ] > , . _

Property: availability_zone
Requirement: R-98450 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: el alto
validation_mode: static

A VNF’s Heat Orchestration Template’s base module or incremental module resource OS::Nova::Server property availability_zone parameter MUST follow the naming convention

  • availability_zone_{index}

where {index} is a numeric value that MUST start at zero in a VNF’s Heat Orchestration Templates and MUST increment by one.

Requirement: R-23311 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: el alto
validation_mode: static

The VNF’s Heat Orchestration Template’s base module or incremental module resource OS::Nova::Server property availability_zone parameter MUST be declared as type: string.

The parameter must not be declared as type comma_delimited_list, ONAP does not support it.

Requirement: R-59568 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
updated: casablanca
validation_mode: static

The VNF’s Heat Orchestration Template’s Resource OS::Nova::Server property availability_zone parameter MUST NOT be enumerated in the Heat Orchestration Template’s Environment File.

Requirement: R-256790 _images/arrow-right-circle.svg
target: VNF
keyword: MAY
introduced: el alto
validation_mode: none

A VNF’s Heat Orchestration Template’s Resource OS::Nova::Server property availability_zone parameter name MAY change when past into a nested YAML file.

Example Parameter Definition

parameters:
  availability_zone_{index}:
    type: string
    description: availability zone {index} name

Requirement (R-90279) states that a VNF Heat Orchestration’s template’s parameter MUST be used in a resource with the exception of the parameters for the OS::Nova::Server resource property availability_zone.

Requirement: R-01359 _images/arrow-right-circle.svg
target: VNF
keyword: MAY
updated: casablanca

A VNF’s Heat Orchestration Template that contains an OS::Nova:Server resource MAY define a parameter for the property availability_zone that is not utilized in any OS::Nova::Server resources in the Heat Orchestration Template.

Example

The example below depicts part of a Heat Orchestration Template that uses the four OS::Nova::Server properties discussed in this section.

In the Heat Orchestration Template below, four Virtual Machines (OS::Nova::Server) are created: two dns servers with {vm-type} set to dns and two oam servers with {vm-type} set to oam. Note that the parameter associated with the property name is a comma_delimited_list for dns and a string for oam.

parameters:

  dns_image_name:
    type: string
    description: dns server image

  dns_flavor_name:
    type: string
    description: dns server flavor

  dns_names:
    type: comma_delimited_list
    description: dns server names

  oam_image_name:
    type: string
    description: oam server image

  oam_flavor_name:
    type: string
    description: oam server flavor

  oam_name_0:
    type: string
    description: oam server name 0

  oam_name_1:
    type: string
    description: oam server name 1

  availability_zone_0:
    type: string
    description: availability zone ID or Name

  availability_zone_1:
    type: string
    description: availability zone ID or Name

resources:

  dns_server_0:
    type: OS::Nova::Server
    properties:
      name: { get_param: [ dns_names, 0 ] }
      image: { get_param: dns_image_name }
      flavor: { get_param: dns_flavor_name }
      availability_zone: { get_param: availability_zone_0 }

. . .

    dns_server_1:
      type: OS::Nova::Server
      properties:
        name: { get_param: [ dns_names, 1 ] }
        image: { get_param: dns_image_name }
        flavor: { get_param: dns_flavor_name }
        availability_zone: { get_param: availability_zone_1 }

. . .

    oam_server_0:
      type: OS::Nova::Server
      properties:
        name: { get_param: oam_name_0 }
        image: { get_param: oam_image_name }
        flavor: { get_param: oam_flavor_name }
        availability_zone: { get_param: availability_zone_0 }

. . .

    oam_server_1:
      type: OS::Nova::Server
      properties:
        name: { get_param: oam_name_1 }
        image: { get_param: oam_image_name }
        flavor: { get_param: oam_flavor_name }
        availability_zone: { get_param: availability_zone_1 }

. . .
Boot Options
Requirement: R-99798 _images/arrow-right-circle.svg
target: VNF
keyword: MAY
updated: casablanca

A VNF’s Heat Orchestration Template’s Virtual Machine (i.e., OS::Nova::Server resource) MAY boot from an image or MAY boot from a Cinder Volume.

Requirement: R-83706 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: none

When a VNF’s Heat Orchestration Template’s Virtual Machine (i.e., OS::Nova::Server resource) boots from an image, the OS::Nova::Server resource property image MUST be used.

The requirements associated with the ‘image’ property are detailed in Property: image

Requirement: R-69588 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: none

When a VNF’s Heat Orchestration Template’s Virtual Machine (i.e., OS::Nova::Server Resource) boots from Cinder Volume, the OS::Nova::Server resource property block_device_mapping or block_device_mapping_v2 MUST be used.

There are currently no heat guidelines associated with these two properties: ‘block_device_mapping’ and ‘block_device_mapping_v2’.

Resource: OS::Nova::Server Metadata Parameters

The OS::Nova::Server resource property metadata is an optional OpenStack property. Table 2 summarizes the mandatory and optional metadata supported by ONAP. The sections that follow provides the requirements associated with each metadata parameter.

Table 2 OS::Nova::Server Mandatory and Optional Metadata

Resource

Property

Parameter Name

Parameter Type

Required

Parameter Value Provided to Heat

OS::Nova::Server

metadata

vnf_id

string

MUST

ONAP

OS::Nova::Server

metadata

vf_module_id

string

MUST

ONAP

OS::Nova::Server

metadata

vnf_name

string

MUST

ONAP

OS::Nova::Server

metadata

vf_module_name

string

SHOULD

ONAP

OS::Nova::Server

metadata

vm_role

string

MAY

YAML or Environment File

OS::Nova::Server

metadata

vf_module_index

number

MAY

ONAP

OS::Nova::Server

metadata

workload_context

string

MUST

ONAP

OS::Nova::Server

metadata

environment_context

string

MUST

ONAP

vnf_id

The OS::Nova::Server resource property metadata key/value pair vnf_id is an ONAP generated UUID that identifies the VNF. The value is provided by ONAP to the VNF’s Heat Orchestration Template at orchestration time.

Requirement: R-37437 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

A VNF’s Heat Orchestration Template’s OS::Nova::Server resource property metadata MUST contain the key/value pair vnf_id and the value MUST be obtained via a get_param.

Requirement: R-07507 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

A VNF’s Heat Orchestration Template’s OS::Nova::Server resource property metadata key/value pair vnf_id parameter MUST be declared as vnf_id and the parameter MUST be defined as type: string.

Requirement: R-55218 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
updated: casablanca
validation_mode: static

A VNF’s Heat Orchestration Template’s OS::Nova::Server resource property metadata key/value pair vnf_id parameter vnf_id MUST NOT have parameter constraints defined.

Requirement: R-20856 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
updated: casablanca
validation_mode: static

A VNF’s Heat Orchestration Template’s OS::Nova::Server resource property metadata key/value pair vnf_id parameter vnf_id MUST NOT be enumerated in the Heat Orchestration Template’s environment file.

Example ‘vnf_id’ Parameter Definition

parameters:

  vnf_id:
    type: string
    description: Unique ID for this VNF instance
vf_module_id

The OS::Nova::Server Resource metadata map value parameter vf_module_id is an ONAP generated UUID that identifies the VF Module (e.g., Heat Orchestration Template). The value is provided by ONAP to the VNF’s Heat Orchestration Template at orchestration time.

Requirement: R-71493 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

A VNF’s Heat Orchestration Template’s OS::Nova::Server resource property metadata MUST contain the key/value pair vf_module_id and the value MUST be obtained via a get_param.

Requirement: R-82134 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

A VNF’s Heat Orchestration Template’s OS::Nova::Server resource property metadata key/value pair vf_module_id parameter MUST be declared as vf_module_id and the parameter MUST be defined as type: string.

Requirement: R-98374 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
updated: casablanca
validation_mode: static

A VNF’s Heat Orchestration Template’s OS::Nova::Server resource property metadata key/value pair vf_module_id parameter vf_module_id MUST NOT have parameter constraints defined.

Requirement: R-72871 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
updated: casablanca
validation_mode: static

A VNF’s Heat Orchestration Template’s OS::Nova::Server resource property metadata key/value pair vf_module_id parameter vf_module_id MUST NOT be enumerated in the Heat Orchestration Template’s environment file.

Example ‘vf_module_id’ Parameter Definition

parameters:

  vnf_module_id:
    type: string
    description: Unique ID for this VNF module instance
vnf_name

The OS::Nova::Server Resource metadata map value parameter vnf_name is the ONAP (SDN-C) generated alphanumeric name of the deployed VNF instance. The value is provided by ONAP to the VNF’s Heat Orchestration Template at orchestration time.

Requirement: R-72483 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

A VNF’s Heat Orchestration Template’s OS::Nova::Server resource property metadata MUST contain the key/value pair vnf_name and the value MUST be obtained via a get_param.

Requirement: R-62428 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

A VNF’s Heat Orchestration Template’s OS::Nova::Server resource property metadata key/value pair vnf_name parameter MUST be declared as vnf_name and the parameter MUST be defined as type: string.

Requirement: R-44318 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
updated: casablanca
validation_mode: static

A VNF’s Heat Orchestration Template’s OS::Nova::Server resource property metadata key/value pair vnf_name parameter vnf_name MUST NOT have parameter constraints defined.

Requirement: R-36542 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
updated: casablanca
validation_mode: static

A VNF’s Heat Orchestration Template’s OS::Nova::Server resource property metadata key/value pair vnf_name parameter vnf_name MUST NOT be enumerated in the Heat Orchestration Template’s environment file.

Example ‘vnf_name’ Parameter Definition

parameters:

  vnf_name:
    type: string
    description: Unique name for this VNF instance
vf_module_name

The OS::Nova::Server Resource metadata map value parameter vf_module_name is the deployment name of the heat stack created (e.g., <STACK_NAME>) from the VNF’s Heat Orchestration template in the command Heat stack-create (e.g., Heat stack-create [-f <FILE>] [-e <FILE>] <STACK_NAME>). The vf_module_name (e.g., <STACK_NAME> is specified as part of the orchestration process.

Requirement: R-100400 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD
introduced: dublin

A VNF’s Heat Orchestration Template’s OS::Nova::Server resource property metadata SHOULD contain the key/value pair vf_module_name.

Requirement: R-68023 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: dublin
validation_mode: static

A VNF’s Heat Orchestration Template’s OS::Nova::Server resource property metadata key/value pair vf_module_name value MUST be obtained via a get_param.

Requirement: R-39067 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

A VNF’s Heat Orchestration Template’s OS::Nova::Server resource property metadata key/value pair vf_module_name parameter MUST be declared as vf_module_name and the parameter MUST be defined as type: string.

Requirement: R-15480 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
updated: casablanca
validation_mode: static

A VNF’s Heat Orchestration Template’s OS::Nova::Server resource property metadata key/value pair vf_module_name parameter vf_module_name MUST NOT have parameter constraints defined.

Requirement: R-80374 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
updated: casablanca
validation_mode: static

A VNF’s Heat Orchestration Template’s OS::Nova::Server resource property metadata key/value pair vf_module_name parameter vf_module_name MUST NOT be enumerated in the Heat Orchestration Template’s environment file.

Example ‘vf_module_name’ Parameter Definition

parameters:

  vf_module_name:
    type: string
    description: Unique name for this VNF Module instance
vm_role

The OS::Nova::Server Resource metadata map value parameter vm_role is a metadata tag that describes the role of the Virtual Machine.

Requirement: R-85328 _images/arrow-right-circle.svg
target: VNF
keyword: MAY
updated: casablanca

A VNF’s Heat Orchestration Template’s OS::Nova::Server resource property metadata MAY contain the key/value pair vm_role and the value MUST be obtained either via

  • get_param

  • hard coded in the key/value pair vm_role.

Requirement: R-95430 _images/arrow-right-circle.svg
target: VNF
keyword: MAY
updated: dublin
validation_mode: none

If a VNF’s Heat Orchestration Template’s OS::Nova::Server resource property metadata key/value pair vm_role value is obtained via get_param, the parameter MAY be declared as

  • vm_role and the parameter defined as type: string.

  • vm_roles and the parameter defined as type: comma_delimited_list.

  • {vm-type}_vm_role and the parameter defined as type: string.

Requirement: R-67597 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
updated: casablanca
validation_mode: static

A VNF’s Heat Orchestration Template’s OS::Nova::Server resource property metadata key/value pair vm_role parameter vm_role MUST NOT have parameter constraints defined.

Defining the vm_role as the {vm-type} is a recommended convention

Requirement: R-86476 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

A VNF’s Heat Orchestration Template’s OS::Nova::Server resource property metadata key/value pair vm_role value MUST only contain alphanumeric characters and underscores (i.e., ‘_’).

Example ‘vm_role’ Parameter Definition

parameters:

  vm_role:
    type: string
    description: Unique role for this VM

Example: ‘vm_role’ Definition: Hard Coded in OS::Nova::Resource metadata property

resources:

  dns_server_0
    type: OS::Nova::Server
    properties:
      . . . .
      metadata:
        vm_role: dns

Example ‘vm_role’ Definition: Defined in Environment file and retrieved via ‘get_param’

resources:

  dns_server_0:
    type: OS::Nova::Server
    properties:
      . . . .
      metadata:
        vm_role: { get_param: vm_role }
Example vnf_id, vf_module_id, vnf_name, vf_module_name, vm_role

The example below depicts part of a Heat Orchestration Template that uses the five of the OS::Nova::Server resource metadata map value parameters discussed in this section. The {vm-type} has been defined as lb for load balancer.

parameters:
  lb_name_0
    type: string
    description: VM Name for lb VM 0
  vnf_name:
    type: string
    description: Unique name for this VNF instance
  vnf_id:
    type: string
    description: Unique ID for this VNF instance
  vf_module_name:
    type: string
    description: Unique name for this VNF Module instance
  vf_module_id:
    type: string
    description: Unique ID for this VNF Module instance
  vm_role:
    type: string
    description: Unique role for this VM
resources:
  lb_server_0:
    type: OS::Nova::Server
    properties:
      name: { get_param: lb_name_0 }
      ...
      metadata:
        vnf_name: { get_param: vnf_name }
        vnf_id: { get_param: vnf_id }
        vf_module_name: { get_param: vf_module_name }
        vf_module_id: { get_param: vf_module_id }
        vm_role: lb
vf_module_index
Requirement: R-100410 _images/arrow-right-circle.svg
target: VNF
keyword: MAY
introduced: dublin

A VNF’s Heat Orchestration Template’s OS::Nova::Server resource property metadata MAY contain the key/value pair vf_module_index.

Requirement: R-50816 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: dublin
validation_mode: static

A VNF’s Heat Orchestration Template’s OS::Nova::Server resource property metadata key/value pair vf_module_index value MUST be obtained via a get_param.

Requirement: R-54340 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

A VNF’s Heat Orchestration Template’s OS::Nova::Server resource property metadata key/value pair vf_module_index parameter MUST be declared as vf_module_index and the parameter MUST be defined as type: number.

Requirement: R-09811 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
updated: casablanca
validation_mode: static

A VNF’s Heat Orchestration Template’s OS::Nova::Server resource property metadata key/value pair vf_module_index MUST NOT have parameter constraints defined.

Requirement: R-37039 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
updated: casablanca
validation_mode: static

A VNF’s Heat Orchestration Template’s OS::Nova::Server resource property metadata key/value pair vf_module_index parameter vf_module_index MUST NOT be enumerated in the Heat Orchestration Template’s environment file.

Requirement: R-55306 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
updated: casablanca
validation_mode: static

A VNF’s Heat Orchestration Template’s OS::Nova::Server resource property metadata key/value pair vf_module_index MUST NOT be used in a OS::Cinder::Volume resource and MUST NOT be used in VNF’s Volume template; it is not supported.

The vf_module_index parameter indicates which instance of the module is being deployed into the VNF. This parameter may be used in cases where multiple instances of the same incremental module are being instantiated for scaling purposes. The index can be used in the Heat Orchestration Template for indexing into a comma_delimited_list defined parameter to provide a unique value for each module instance. The parameter list may be defined in the VNF’s Heat Orchestration Template’s environmental file or be provided by SDN-C.

ONAP does not support the vf_module_index to be utilized as an index by all parameters defined as comma_delimited_list. The vf_module_index must not be used for indexing the following resource property parameters:

  • OS::Nova::Server property name parameter (defined as a comma_delimited_list).

  • OS::Neutron::Port property fixed_ips map property ip_address parameter (defined as a comma_delimited_list) when the port is attaching to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968)

The vf_module_index may be used for indexing OS::Neutron::Port property fixed_ips map property ip_address parameter (defined as a comma_delimited_list) when the port is attaching to an ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666). An example is provided below.

Requirement: R-55307 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
introduced: frankfurt
validation_mode: static

A VNF’s Heat Orchestration Template’s parameter vf_module_index MUST NOT be used for indexing an:

  • OS::Nova::Server property name parameter (when defined as a comma_delimited_list).

  • OS::Neutron::Port property fixed_ips map property ip_address parameter (when defined as a comma_delimited_list) when the port is attaching to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968)

  • OS::ContrailV2::InstanceIp property instance_ip_address parameter (when defined as a comma_delimited_list) when the port (i.e, OS::ContrailV2::VirtualMachineInterface) is attaching to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968)

The vf_module_index will start at 0 for the first instance of a module type. Subsequent instances of the same module type will receive the lowest unused index. This means that indexes will be reused if a module is deleted and re-added. As an example, if three copies of a module are deployed with vf_module_index values of 0, 1, and 2 then subsequently the second one is deleted (index 1), and then re-added, index 1 will be reused.

Example

In this example, the {vm-type} has been defined as oam_vm to represent an OAM VM. An incremental heat module is used to deploy the OAM VM. The OAM VM attaches to an ONAP internal network which has a {network-role} of ctrl. A maximum of four OAM VMs can be deployed. The environment file contains the four IP addresses that each successive OAM VM will be assigned. The vf_module_index is used as the index to determine the IP assignment.

Environment File

parameters:
  oam_vm_int_ctrl_ips: 10.10.10.1,10.10.10.2,10.10.10.3,10.10.10.4

YAML File

parameters:
  vf_module_index:
    type: number
    description: Unique index for this VNF Module instance
  oam_vm_name_0:
    type: string
    description: VM Name for lb VM 0
  int_ctrl_net_id:
    type: string
    description: Neutron UUID for the internal control network
  oam_vm_int_ctrl_ips:
    type: comma_delimited_list
    description: Fixed IP assignments for oam VMs on the internal control
                 network
resources:
  oam_vm_server_0:
    type: OS::Nova::Server
    properties:
      name: { get_param: oam_vm_name_0 }
      networks:
        - port: { get_resource: oam_vm_0_int_ctrl_port_0 }
#     . . .
      metadata:
        vf_module_index: { get_param: vf_module_index }
  oam_vm_0_int_ctrl_port_0:
    type: OS::Neutron::Port
    properties:
      network: { get_param: int_ctrl_net_id }
      fixed_ips: [ { "ip_address": {get_param: [ oam_vm_int_ctrl_ips, { get_param: vf_module_index} ]}}]
workload_context
Requirement: R-47061 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD
updated: casablanca

A VNF’s Heat Orchestration Template’s OS::Nova::Server Resource SHOULD contain the metadata map value parameter ‘workload_context’.

Requirement: R-74978 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

A VNF’s Heat Orchestration Template’s OS::Nova::Server resource property metadata key/value pair workload_context parameter MUST be declared as workload_context and the parameter MUST be defined as type: string.

Requirement: R-34055 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
updated: casablanca
validation_mode: static

A VNF’s Heat Orchestration Template’s OS::Nova::Server resource property metadata key/value pair workload_context parameter workload_context MUST NOT have parameter constraints defined.

Requirement: R-02691 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
updated: casablanca
validation_mode: static

A VNF’s Heat Orchestration Template’s OS::Nova::Server resource property metadata key/value pair workload_context parameter workload_context MUST NOT be enumerated in the Heat Orchestration Template’s environment file.

The ‘workload_context’ parameter value will be chosen by the Service Model Distribution context client in VID and will be supplied to the Heat Orchestration Template by ONAP at orchestration time.

Example Parameter Definition

parameters:
  workload_context:
    type: string
    description: Workload Context for this VNF instance

Example OS::Nova::Server with metadata

resources:
  . . .

  {vm-type}_server_{index}:
     type: OS::Nova::Server
     properties:
       name:
       flavor:
       image:
      ...
     metadata:
        vnf_name: { get_param: vnf_name }
        vnf_id: { get_param: vnf_id }
        vf_module_name: { get_param: vf_module_name }
        vf_module_id: { get_param: vf_module_id }
        workload_context: {get_param: workload_context}
environment_context
Requirement: R-88536 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD
updated: casablanca

A VNF’s Heat Orchestration Template’s OS::Nova::Server Resource SHOULD contain the metadata map value parameter ‘environment_context’.

Requirement: R-20308 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

A VNF’s Heat Orchestration Template’s OS::Nova::Server resource property metadata key/value pair environment_context parameter MUST be declared as environment_context and the parameter type MUST be defined as type: string.

Requirement: R-56183 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
updated: casablanca
validation_mode: static

A VNF’s Heat Orchestration Template’s OS::Nova::Server resource property metadata``key/value pair ``environment_context parameter environment_context MUST NOT have parameter constraints defined.

Requirement: R-13194 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
updated: casablanca
validation_mode: static

A VNF’s Heat Orchestration Template’s OS::Nova::Server resource property metadata key/value pair environment_context MUST NOT be enumerated in the Heat Orchestration Template’s environment file.

The ‘environment_context’ parameter value will be defined by the service designer as part of the service model during the SDC on-boarding process and will be supplied to the Heat Orchestration Template by ONAP at orchestration time.

Example Parameter Definition

parameters:
  environment_context:
    type: string
    description: Environment Context for this VNF instance

Example OS::Nova::Server with metadata

resources:
  . . .

  {vm-type}_server_{index}:
     type: OS::Nova::Server
     properties:
       name:
       flavor:
       image:
      ...
     metadata:
        vnf_name: { get_param: vnf_name }
        vnf_id: { get_param: vnf_id }
        vf_module_name: { get_param: vf_module_name }
        vf_module_id: { get_param: vf_module_id }
        workload_context: {get_param: workload_context}
        environment_context: {get_param: environment_context }
Resource: OS::Neutron::Port - Parameters

The resource OS::Neutron::Port is for managing Neutron ports.

(See https://docs.openstack.org/developer/heat/template_guide/openstack.html#OS::Neutron::Port)

Introduction

Four properties of the resource OS::Neutron::Port must follow the ONAP naming convention. The four properties are:

  1. network

  2. fixed_ips, ip_address

  3. fixed_ips, subnet

  1. allowed_address_pairs, ip_address

Below is a generic example. Note that for some parameters comma_delimited_list are supported in addition to String.

resources:

...

<resource ID>:
  type: OS::Neutron::Port
  properties:
    allowed_address_pairs: [{"ip_address": String, "mac_address": String}, {"ip_address": String, "mac_address": String}, ...]
    fixed_ips: [{"ip_address": String, "subnet": String}, {"ip_address": String, "subnet": String}, ...]
    network: String

The values associated with these properties may reference an ONAP external network or ONAP internal network. ONAP external networks and ONAP internal networks are defined in ONAP Heat Networking.

When the OS::Neutron::Port is attaching to an ONAP external network, all property values are parameters that are retrieved via the intrinsic function get_param.

When the OS::Neutron::Port is attaching to an ONAP internal network, a property value maybe retrieved via the intrinsic function get_param, get_resource, or get_attr.

This will be described in the forth coming sections.

Items to Note

A VNF MAY have one or more ports connected to a unique ONAP external network. All VNF ports connected to the unique ONAP external network MUST have cloud assigned IP addresses or MUST have ONAP SDN-C assigned IP addresses.

A VNF MAY have one or more ports connected to a unique ONAP internal network. All VNF ports connected to the unique ONAP internal network MUST have cloud assigned IP addresses or MUST have statically assigned IP addresses.

Requirement: R-45602 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
updated: casablanca
validation_mode: none

If a VNF’s Port is attached to a network (internal or external) and the port’s IP addresses are cloud assigned by OpenStack’s DHCP Service, the OS::Neutron::Port Resource’s

  • property fixed_ips map property ip_address MUST NOT be used

  • property fixed_ips map property subnet MAY be used

Requirement: R-63956 _images/arrow-right-circle.svg
target: VNF
keyword: MAY
updated: frankfurt

If the VNF’s ports connected to a unique ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968) and the port’s IP addresses are ONAP SDN-C assigned IP addresses, the IPv4 addresses MAY be from different subnets and the IPv6 addresses MAY be from different subnets.

Requirement: R-48880 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt
validation_mode: none

If a VNF’s Port is attached to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968) and the port’s IP addresses are assigned by ONAP’s SDN-Controller, the OS::Neutron::Port Resource’s

  • property fixed_ips map property ip_address MUST be used

  • property fixed_ips map property subnet MUST NOT be used

Requirement: R-18001 _images/arrow-right-circle.svg
target: VNF
keyword: MAY
updated: frankfurt

If the VNF’s ports connected to a unique ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666) and the port’s IP addresses are statically assigned IP addresses, the IPv4 addresses MAY be from different subnets and the IPv6 addresses MAY be from different subnets.

Requirement: R-70964 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
updated: frankfurt
validation_mode: none

If a VNF’s Port is attached to an ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666) and the port’s IP addresses are statically assigned by the VNF’s Heat Orchestration Template (i.e., enumerated in the Heat Orchestration Template’s environment file), the OS::Neutron::Port Resource’s

  • property fixed_ips map property ip_address MUST be used

  • property fixed_ips map property subnet MUST NOT be used

Requirement: R-681859 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: dublin
validation_mode: static

A VNF’s Heat Orchestration Template’s OS::Neutron::Port resource’s

  • Resource ID (defined in R-20453)

  • property network parameter name (defined in R-62983 and R-86182)

  • property fixed_ips, map property ip_address parameter name (defined in R-40971, R-04697, R-71577, R-23503, R-78380, R-85235, R-27818, and R-29765)

  • property fixed_ips, map property subnet parameter name (defined in R-62802, R-15287, R-84123, R-76160)

  • property allowed_address_pairs parameter name (defined in R-41492 and R-83418)

MUST contain the identical {network-role}.

Property: network

The Resource OS::Neutron::Port property network determines what network the port is attached to.

Requirement: R-18008 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

The VNF’s Heat Orchestration Template’s Resource OS::Neutron::Port property network parameter MUST be declared as type: string.

Requirement: R-62983 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt
validation_mode: static

When the VNF’s Heat Orchestration Template’s Resource OS::Neutron::Port is attaching to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), the network parameter name MUST

  • follow the naming convention {network-role}_net_id if the Neutron network UUID value is used to reference the network

  • follow the naming convention {network-role}_net_name if the OpenStack network name is used to reference the network.

where {network-role} is the network-role of the ONAP external network and a get_param MUST be used as the intrinsic function.

Requirement: R-86182 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt
validation_mode: static

When the VNF’s Heat Orchestration Template’s Resource OS::Neutron::Port is in an incremental module and is attaching to an ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666), the network parameter name MUST

  • follow the naming convention int_{network-role}_net_id if the network UUID value is used to reference the network

  • follow the naming convention int_{network-role}_net_name if the network name in is used to reference the network.

where {network-role} is the network-role of the ONAP internal network and a get_param MUST be used as the intrinsic function.

In Requirement R-86182, the ONAP internal network is created in the VNF’s Base Module (Heat Orchestration Template) and the parameter name is declared in the Base Module’s outputs section. The output parameter name will be declared as a parameter in the parameters section of the incremental module (See Requirement R-22688).

When the VNF’s Heat Orchestration Template’s resource OS::Neutron::Port is in the base module and is attaching to an ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666), and the ONAP internal network is

  • created in the base module, the network property value can obtain the UUID of the internal network by using the intrinsic function get_resource and referencing the Resource ID of the internal network.

  • created in the base module by invoking a Nested YAML file, the network property value can obtain the UUID of the internal network by using the intrinsic function get_attr and referencing the Resource ID of the internal network.

Requirement: R-29872 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
updated: casablanca
validation_mode: static

The VNF’s Heat Orchestration Template’s Resource OS::Neutron::Port property network parameter MUST NOT be enumerated in the Heat Orchestration Template’s Environment File.

The parameter values for ONAP external networks are provided by ONAP to the VNF’s Heat Orchestration Template at orchestration time.

The parameter values for ONAP internal networks created in the VNF’s Base Module Heat Orchestration Template are provided to the VNF’s Incremental Module Heat Orchestration Template at orchestration time.

Example Parameter Definition of External Networks

parameters:

  {network-role}_net_id:
    type: string
    description: Neutron UUID for the external {network-role} network

  {network-role}_net_name:
    type: string
    description: Neutron name for the external {network-role} network

Example Parameter Definition of Internal Networks in an Incremental Module

parameters:

  int_{network-role}_net_id:
    type: string
    description: Neutron UUID for the internal int_{network-role} network

  int_{network-role}_net_name:
    type: string
    description: Neutron name for the internal int_{network-role} network
Property: fixed_ips, Map Property: ip_address

The resource OS::Neutron::Port property fixed_ips map property ip_address is used to assign one IPv4 or IPv6 addresses to port.

One OS::Neutron::Port resource may assign one or more IPv4 and/or IPv6 addresses.

Requirement: R-34037 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

The VNF’s Heat Orchestration Template’s resource OS::Neutron::Port property fixed_ips map property ip_address parameter MUST be declared as either type string or type comma_delimited_list.

Requirement: R-40971 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt
validation_mode: static

When the VNF’s Heat Orchestration Template’s Resource OS::Neutron::Port is attaching to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), and an IPv4 address is assigned using the property fixed_ips map property ip_address and the parameter type is defined as a string, the parameter name MUST follow the naming convention

  • {vm-type}_{network-role}_ip_{index}

where

  • {vm-type} is the {vm-type} associated with the OS::Nova::Server

  • {network-role} is the {network-role} of the ONAP external network

  • {index} is a numeric value that MUST start at zero in a VNF’s Heat Orchestration Template and MUST increment by one

Requirement: R-39841 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
updated: casablanca
validation_mode: static

The VNF’s Heat Orchestration Template’s Resource OS::Neutron::Port property fixed_ips map property ip_address parameter {vm-type}_{network-role}_ip_{index} MUST NOT be enumerated in the VNF’s Heat Orchestration Template’s Environment File.

ONAP’s SDN-Controller assigns the IP address and ONAP provides the value at orchestration to the Heat Orchestration Template.

Example External Network IPv4 Address string Parameter Definition

parameters:

  {vm-type}_{network-role}_ip_{index}:
    type: string
    description: Fixed IPv4 assignment for {vm-type} VM {index} on the {network-role} network
Requirement: R-04697 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt
validation_mode: static

When the VNF’s Heat Orchestration Template’s Resource OS::Neutron::Port is attaching to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), and an IPv4 address is assigned using the property fixed_ips map property ip_address and the parameter type is defined as a comma_delimited_list, the parameter name MUST follow the naming convention

  • {vm-type}_{network-role}_ips

where

  • {vm-type} is the {vm-type} associated with the OS::Nova::Server

  • {network-role} is the {network-role} of the ONAP external network

Requirement: R-98905 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
updated: casablanca
validation_mode: static

The VNF’s Heat Orchestration Template’s Resource OS::Neutron::Port property fixed_ips map property ip_address parameter {vm-type}_{network-role}_ips MUST NOT be enumerated in the VNF’s Heat Orchestration Template’s Environment File.

ONAP’s SDN-Controller assigns the IP address and ONAP provides the value at orchestration to the Heat Orchestration Template.

Example External Network IPv4 Address comma_delimited_list Parameter Definition

parameters:

  {vm-type}_{network-role}_ips:
    type: comma_delimited_list
    description: Fixed IPv4 assignments for {vm-type} VMs on the {network-role} network
Requirement: R-71577 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt
validation_mode: static

When the VNF’s Heat Orchestration Template’s Resource OS::Neutron::Port is attaching to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), and an IPv6 address is assigned using the property fixed_ips map property ip_address and the parameter type is defined as a string, the parameter name MUST follow the naming convention

  • {vm-type}_{network-role}_v6_ip_{index}

where

  • {vm-type} is the {vm-type} associated with the OS::Nova::Server

  • {network-role} is the {network-role} of the ONAP external network

  • {index} is a numeric value that MUST start at zero in a VNF’s Heat Orchestration Template and MUST increment by one

Requirement: R-87123 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
updated: casablanca
validation_mode: static

The VNF’s Heat Orchestration Template’s Resource OS::Neutron::Port property fixed_ips map property ip_address parameter {vm-type}_{network-role}_v6_ip_{index} MUST NOT be enumerated in the VNF’s Heat Orchestration Template’s Environment File.

ONAP’s SDN-Controller assigns the IP address and ONAP provides the value at orchestration to the Heat Orchestration Template.

Example External Network IPv6 Address string Parameter Definition

parameters:

  {vm-type}_{network-role}_v6_ip_{index}:
    type: string
    description: Fixed IPv6 assignment for {vm-type} VM {index} on the {network-role} network
Requirement: R-23503 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt
validation_mode: static

When the VNF’s Heat Orchestration Template’s Resource OS::Neutron::Port is attaching to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), and an IPv6 address is assigned using the property fixed_ips map property ip_address and the parameter type is defined as a comma_delimited_list, the parameter name MUST follow the naming convention

  • {vm-type}_{network-role}_v6_ips

where

  • {vm-type} is the {vm-type} associated with the OS::Nova::Server

  • {network-role} is the {network-role} of the ONAP external network

Requirement: R-93030 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
updated: casablanca
validation_mode: static

The VNF’s Heat Orchestration Template’s Resource OS::Neutron::Port property fixed_ips map property ip_address parameter {vm-type}_{network-role}_v6_ips MUST NOT be enumerated in the VNF’s Heat Orchestration Template’s Environment File.

ONAP’s SDN-Controller assigns the IP address and ONAP provides the value at orchestration to the Heat Orchestration Template.

Example External Network IPv6 Address comma_delimited_list Parameter Definition

parameters:

  {vm-type}_{network-role}_v6_ips:
    type: comma_delimited_list
    description: Fixed IPv6 assignments for {vm-type} VMs on the {network-role} network
Requirement: R-78380 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt
validation_mode: static

When the VNF’s Heat Orchestration Template’s Resource OS::Neutron::Port is attaching to an ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666), and an IPv4 address is assigned using the property fixed_ips map property ip_address and the parameter type is defined as a string, the parameter name MUST follow the naming convention

  • {vm-type}_int_{network-role}_ip_{index}

where

  • {vm-type} is the {vm-type} associated with the OS::Nova::Server

  • {network-role} is the {network-role} of the ONAP internal network

  • {index} is a numeric value that MUST start at zero in a VNF’s Heat Orchestration Template and MUST increment by one

Requirement: R-28795 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

The VNF’s Heat Orchestration Template’s Resource OS::Neutron::Port property fixed_ips map property ip_address parameter {vm-type}_int_{network-role}_ip_{index} MUST be enumerated in the VNF’s Heat Orchestration Template’s Environment File.

The IP address is local to the VNF’s internal network and is (re)used in every VNF spin up, thus the constant value is declared in the VNF’s Heat Orchestration Template’s Environment File.

Example Internal Network IPv4 Address string Parameter Definition

parameters:

  {vm-type}_int_{network-role}_ip_{index}:
    type: string
    description: Fixed IPv4 assignment for {vm-type} VM {index} on the int_{network-role} network
Requirement: R-85235 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt
validation_mode: static

When the VNF’s Heat Orchestration Template’s Resource OS::Neutron::Port is attaching to an ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666), and an IPv4 address is assigned using the property fixed_ips map property ip_address and the parameter type is defined as a comma_delimited_list, the parameter name MUST follow the naming convention

  • {vm-type}_int_{network-role}_ips

where

  • {vm-type} is the {vm-type} associated with the OS::Nova::Server

  • {network-role} is the {network-role} of the ONAP internal network

Requirement: R-90206 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

The VNF’s Heat Orchestration Template’s Resource OS::Neutron::Port property fixed_ips map property ip_address parameter {vm-type}_int_{network-role}_int_ips MUST be enumerated in the VNF’s Heat Orchestration Template’s Environment File.

The IP address is local to the VNF’s internal network and is (re)used in every VNF spin up, thus the constant value is declared in the VNF’s Heat Orchestration Template’s Environment File.

parameters:

  {vm-type}_int_{network-role}_ips:
    type: comma_delimited_list
    description: Fixed IPv4 assignments for {vm-type} VMs on the int_{network-role} network
Requirement: R-27818 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt
validation_mode: static

When the VNF’s Heat Orchestration Template’s Resource OS::Neutron::Port is attaching to an ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666), and an IPv6 address is assigned using the property fixed_ips map property ip_address and the parameter type is defined as a string, the parameter name MUST follow the naming convention

  • {vm-type}_int_{network-role}_v6_ip_{index}

where

  • {vm-type} is the {vm-type} associated with the OS::Nova::Server

  • {network-role} is the {network-role} of the ONAP internal network

  • {index} is a numeric value that MUST start at zero in a VNF’s Heat Orchestration Template and MUST increment by one

Requirement: R-97201 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

The VNF’s Heat Orchestration Template’s Resource OS::Neutron::Port property fixed_ips map property ip_address parameter {vm-type}_int_{network-role}_v6_ip_{index} MUST be enumerated in the VNF’s Heat Orchestration Template’s Environment File.

The IP address is local to the VNF’s internal network and is (re)used in every VNF spin up, thus the constant value is declared in the VNF’s Heat Orchestration Template’s Environment File.

Example Internal Network IPv6 Address string Parameter Definition

parameters:

  {vm-type}_int_{network-role}_v6_ip_{index}:
    type: string
    description: Fixed IPv6 assignment for {vm-type} VM {index} on the int_{network-role} network
Requirement: R-29765 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt
validation_mode: static

When the VNF’s Heat Orchestration Template’s Resource OS::Neutron::Port is attaching to an ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666), and an IPv6 address is assigned using the property fixed_ips map property ip_address and the parameter type is defined as a comma_delimited_list, the parameter name MUST follow the naming convention

  • {vm-type}_int_{network-role}_v6_ips

where

  • {vm-type} is the {vm-type} associated with the OS::Nova::Server

  • {network-role} is the {network-role} of the ONAP internal network

Example Internal Network IPv6 Address comma_delimited_list Parameter Definition

parameters:

  {vm-type}_int_{network-role}_v6_ips:
    type: comma_delimited_list
    description: Fixed IPv6 assignments for {vm-type} VMs on the int_{network-role} network
Requirement: R-98569 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

The VNF’s Heat Orchestration Template’s Resource OS::Neutron::Port property fixed_ips map property ip_address parameter {vm-type}_int_{network-role}_v6_ips MUST be enumerated in the VNF’s Heat Orchestration Template’s Environment File.

The IP address is local to the VNF’s internal network and is (re)used in every VNF spin up, thus the constant value is declared in the VNF’s Heat Orchestration Template’s Environment File.

parameters:

  {vm-type}_int_{network-role}_v6_ips:
    type: comma_delimited_list
    description: Fixed IPv6 assignments for {vm-type} VMs on the int_{network-role} network
Requirement: R-62590 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
updated: frankfurt
validation_mode: static

The VNF’s Heat Orchestration Template’s Resource OS::Neutron::Port property fixed_ips map property ip_address parameter associated with an ONAP external network, i.e.,

  • {vm-type}_{network-role}_ip_{index}

  • {vm-type}_{network-role}_v6_ip_{index}

  • {vm-type}_{network-role}_ips

  • {vm-type}_{network-role}_v6_ips

MUST NOT be enumerated in the Heat Orchestration Template’s Environment File. ONAP provides the IP address assignments at orchestration time.

Requirement: R-93496 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt
validation_mode: static

The VNF’s Heat Orchestration Template’s Resource OS::Neutron::Port property fixed_ips map property ip_address parameter associated with an ONAP internal network, i.e.,

  • {vm-type}_int_{network-role}_ip_{index}

  • {vm-type}_int_{network-role}_v6_ip_{index}

  • {vm-type}_int_{network-role}_ips

  • {vm-type}_int_{network-role}_v6_ips

MUST be enumerated in the Heat Orchestration Template’s Environment File and IP addresses MUST be assigned.

Summary Table
Table 4 OS::Neutron::Port Property fixed_ips map property ip_address Parameter Naming Convention

Resource

Property

Map Property

Network Type

IP Address

Parameter Type

Parameter Name

Environment File

OS::Neutron::Port

fixed_ips

ip_address

ONAP external

IPv4

string

{vm-type}_{network-role}_ip_{index}

NO

OS::Neutron::Port

fixed_ips

ip_address

ONAP external

IPv4

comma_delimited_list

{vm-type}_{network-role}_ips

NO

OS::Neutron::Port

fixed_ips

ip_address

ONAP external

IPv6

string

{vm-type}_{network-role}_v6_ip_{index}

NO

OS::Neutron::Port

fixed_ips

ip_address

ONAP external

IPv6

comma_delimited_list

{vm-type}_{network-role}_v6_ips

NO

OS::Neutron::Port

fixed_ips

ip_address

ONAP internal

IPv4

string

{vm-type}_int_{network-role}_ip_{index}

YES

OS::Neutron::Port

fixed_ips

ip_address

ONAP internal

IPv4

comma_delimited_list

{vm-type}_int_{network-role}_ips

YES

OS::Neutron::Port

fixed_ips

ip_address

ONAP internal

IPv6

string

{vm-type}_int_{network-role}_v6_ip_{index}

YES

OS::Neutron::Port

fixed_ips

ip_address

ONAP internal

IPv6

comma_delimited_list

{vm-type}_int_{network-role}_v6_ips

YES

Examples

Example: comma_delimited_list parameters for IPv4 and IPv6 Address Assignments to an ONAP external network

In this example, the {network-role} has been defined as oam to represent an oam network and the {vm-type} has been defined as db for database.

parameters:
  oam_net_id:
    type: string
    description: Neutron UUID for a oam network
  db_oam_ips:
    type: comma_delimited_list
    description: Fixed IPv4 assignments for db VMs on the oam network
  db_oam_v6_ips:
    type: comma_delimited_list
    description: Fixed IPv6 assignments for db VMs on the oam network
resources:
  db_0_oam_port_0:
    type: OS::Neutron::Port
    properties:
      network: { get_param: oam_net_id }
      fixed_ips: [ { "ip_address": {get_param: [ db_oam_ips, 0 ]}}, {
      "ip_address": {get_param: [ db_oam_v6_ips, 0 ]}}]
  db_1_oam_port_0:
    type: OS::Neutron::Port
    properties:
      network: { get_param: oam_net_id }
      fixed_ips:
        - "ip_address": {get_param: [ db_oam_ips, 1 ]}
        - "ip_address": {get_param: [ db_oam_v6_ips, 1 ]}

Example: string parameters for IPv4 and IPv6 Address Assignments to an ONAP external network

In this example, the {network-role} has been defined as oam to represent an oam network and the {vm-type} has been defined as db for database.

parameters:
  oam_net_id:
    type: string
    description: Neutron UUID for an OAM network
  db_oam_ip_0:
    type: string
    description: Fixed IPv4 assignment for db VM 0 on the OAM network
  db_oam_ip_1:
    type: string
    description: Fixed IPv4 assignment for db VM 1 on the OAM network
  db_oam_v6_ip_0:
    type: string
    description: Fixed IPv6 assignment for db VM 0 on the OAM network
  db_oam_v6_ip_1:
    type: string
    description: Fixed IPv6 assignment for db VM 1 on the OAM network
resources:
  db_0_oam_port_0:
    type: OS::Neutron::Port
    properties:
      network: { get_param: oam_net_id }
      fixed_ips: [ { "ip_address": {get_param: db_oam_ip_0}}, { "ip_address": {get_param: db_oam_v6_ip_0 }}]
  db_1_oam_port_0:
    type: OS::Neutron::Port
    properties:
      network: { get_param: oam_net_id }
      fixed_ips:
        - "ip_address": {get_param: db_oam_ip_1}
        - "ip_address": {get_param: db_oam_v6_ip_1}

Example: comma_delimited_list parameters for IPv4 and IPv6 Address Assignments to an ONAP internal network*

In this example, the {network-role} has been defined as ctrl to represent an ctrl network internal to the vnf. The {vm-type} has been defined as db for database.

parameters:
  int_ctrl_net_id:
    type: string
    description: Neutron UUID for the ctrl internal network
  db_int_ctrl_ips:
    type: comma_delimited_list
    description: Fixed IPv4 assignments for db VMs on the ctrl internal
    network
  db_int_ctrl_v6_ips:
    type: comma_delimited_list
    description: Fixed IPv6 assignments for db VMs on the ctrl internal
    network
resources:
  db_0_int_ctrl_port_0:
    type: OS::Neutron::Port
    properties:
      network: { get_param: int_ctrl_net_id }
      fixed_ips: [ { "ip_address": {get_param: [ db_int_ctrl_ips, 0 ]}}, {
      "ip_address": {get_param: [ db_int_ctrl_v6_ips, 0 ]}}]
  db_1_int_ctrl_port_0:
    type: OS::Neutron::Port
    properties:
      network: { get_param: int_ctrl_net_id }
      fixed_ips:
      - "ip_address": {get_param: [ db_int_ctrl_ips, 1 ]}
      - "ip_address": {get_param: [ db_int_ctrl_v6_ips, 1 ]}

Example: string parameters for IPv4 and IPv6 Address Assignments to an ONAP internal network

In this example, the int_{network-role} has been defined as int_ctrl to represent a control network internal to the vnf. The {vm-type} has been defined as db for database.

parameters:
  int_ctrl_net_id:
    type: string
    description: Neutron UUID for an OAM internal network
  db_int_ctrl_ip_0:
    type: string
    description: Fixed IPv4 assignment for db VM on the oam_int network
  db_int_ctrl_ip_1:
    type: string
    description: Fixed IPv4 assignment for db VM 1 on the oam_int network
  db_int_ctrl_v6_ip_0:
    type: string
    description: Fixed IPv6 assignment for db VM 0 on the oam_int network
  db_int_ctrl_v6_ip_1:
    type: string
    description: Fixed IPv6 assignment for db VM 1 on the oam_int network
resources:
  db_0_int_ctrl_port_0:
    type: OS::Neutron::Port
    properties:
      network: { get_param: int_oam_int_net_id }
      fixed_ips: [ { "ip_address": {get_param: db_oam_int_ip_0}}, {
      "ip_address": {get_param: db_oam_int_v6_ip_0 }}]
  db_1_int_ctrl_port_0:
    type: OS::Neutron::Port
    properties:
      network: { get_param: int_oam_int_net_id }
      fixed_ips:
        - "ip_address": {get_param: db_oam_int_ip_1}
        - "ip_address": {get_param: db_oam_int_v6_ip_1}
Property: fixed_ips, Map Property: subnet

The resource OS::Neutron::Port property fixed_ips map property subnet is used when a port is requesting an IP assignment via OpenStack’s DHCP Service (i.e., cloud assigned).

The IP address assignment will be made from the specified subnet.

Specifying the subnet is not required; it is optional.

If the network (ONAP external or ONAP internal) that the port is attaching to only contains one subnet, specifying the subnet is superfluous. The IP address will be assigned from the one existing subnet.

If the network (ONAP external or ONAP internal) that the port is attaching to contains two or more subnets, specifying the subnet in the fixed_ips map property subnet determines which subnet the IP address will be assigned from.

If the network (ONAP external or ONAP internal) that the port is attaching to contains two or more subnets, and the subnet is not is not specified, OpenStack will randomly determine which subnet the IP address will be assigned from.

The property fixed_ips is used to assign IPs to a port. The Map Property subnet specifies the subnet the IP is assigned from.

Requirement: R-38236 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

The VNF’s Heat Orchestration Template’s resource OS::Neutron::Port property fixed_ips map property subnet parameter MUST be declared type string.

Requirement: R-62802 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt
validation_mode: static

When the VNF’s Heat Orchestration Template’s resource OS::Neutron::Port is attaching to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), and an IPv4 address is being cloud assigned by OpenStack’s DHCP Service and the ONAP external network IPv4 subnet is to be specified using the property fixed_ips map property subnet, the parameter MUST follow the naming convention

  • {network-role}_subnet_id

where

  • {network-role} is the network role of the ONAP external network.

Note that ONAP only supports cloud assigned IP addresses from one IPv4 subnet of a given network.

Requirement: R-83677 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
updated: casablanca
validation_mode: static

The VNF’s Heat Orchestration Template’s Resource OS::Neutron::Port property fixed_ips map property subnet parameter {network-role}_subnet_id MUST NOT be enumerated in the VNF’s Heat Orchestration Template’s Environment File.

ONAP’s SDN-Controller provides the network’s subnet’s UUID value at orchestration to the Heat Orchestration Template.

Example Parameter Definition

parameters:

  {network-role}_subnet_id:
    type: string
    description: Neutron IPv4 subnet UUID for the {network-role} network
Requirement: R-15287 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt
validation_mode: static

When the VNF’s Heat Orchestration Template’s resource OS::Neutron::Port is attaching to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), and an IPv6 address is being cloud assigned by OpenStack’s DHCP Service and the ONAP external network IPv6 subnet is to be specified using the property fixed_ips map property subnet, the parameter MUST follow the naming convention

  • {network-role}_v6_subnet_id

where

  • {network-role} is the network role of the ONAP external network.

Note that ONAP only supports cloud assigned IP addresses from one IPv6 subnet of a given network.

Requirement: R-80829 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
updated: casablanca
validation_mode: static

The VNF’s Heat Orchestration Template’s Resource OS::Neutron::Port property fixed_ips map property subnet parameter {network-role}_v6_subnet_id MUST NOT be enumerated in the VNF’s Heat Orchestration Template’s Environment File.

Example: One Cloud Assigned IPv4 Address (DHCP) assigned to an ONAP external network that has two or more IPv4 subnets

In this example, the {network-role} has been defined as oam to represent an oam network and the {vm-type} has been defined as lb for load balancer. The cloud assigned IP address uses the OpenStack DHCP service to assign IP addresses.

parameters:
  oam_net_id:
    type: string
    description: Neutron UUID for the oam network
  oam_subnet_id:
    type: string
    description: Neutron IPv4 subnet UUID for the oam network
resources:
  lb_0_oam_port_0:
    type: OS::Neutron::Port
      parameters:
        network: { get_param: oam_net_id }
        fixed_ips:
          - subnet: { get_param: oam_subnet_id }

Example: One Cloud Assigned IPv4 address and one Cloud Assigned IPv6 address assigned to an ONAP external network that has at least one IPv4 subnet and one IPv6 subnet

In this example, the {network-role} has been defined as oam to represent an oam network and the {vm-type} has been defined as lb for load balancer.

parameters:
  oam_net_id:
    type: string
    description: Neutron UUID for the oam network
  oam_subnet_id:
    type: string
    description: Neutron IPv4 subnet UUID for the oam network
  oam_v6_subnet_id:
    type: string
    description: Neutron IPv6 subnet UUID for the oam network
resources:
  lb_0_oam_port_0:
    type: OS::Neutron::Port
    properties:
      network: { get_param: oam_net_id }
      fixed_ips:
        - subnet: { get_param: oam_subnet_id }
        - subnet: { get_param: oam_v6_subnet_id }
Requirement: R-84123 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt
validation_mode: static

When

  • the VNF’s Heat Orchestration Template’s resource OS::Neutron::Port in an Incremental Module is attaching to an ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666) that is created in the Base Module, AND

  • an IPv4 address is being cloud assigned by OpenStack’s DHCP Service AND

  • the internal network IPv4 subnet is to be specified using the property fixed_ips map property subnet,

the parameter MUST follow the naming convention

  • int_{network-role}_subnet_id

where

  • {network-role} is the network role of the ONAP internal network

Note that the parameter MUST be defined as an output parameter in the base module.

Requirement: R-69634 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
updated: casablanca
validation_mode: static

The VNF’s Heat Orchestration Template’s Resource OS::Neutron::Port property fixed_ips map property subnet parameter int_{network-role}_subnet_id MUST NOT be enumerated in the VNF’s Heat Orchestration Template’s Environment File.

The assumption is that the ONAP internal networks are created in the base module. The Neutron subnet network ID will be passed as an output parameter (e.g., ONAP Base Module Output Parameter) to the incremental modules. In the incremental modules, the output parameter name will be defined as input parameter.

Example Parameter Definition

parameters:

  int_{network-role}_subnet_id:
    type: string
    description: Neutron IPv4 subnet UUID for the int_{network-role} network
Requirement: R-76160 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt
validation_mode: static

When

  • the VNF’s Heat Orchestration Template’s resource OS::Neutron::Port in an Incremental Module is attaching to an ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666) that is created in the Base Module, AND

  • an IPv6 address is being cloud assigned by OpenStack’s DHCP Service AND

  • the ONAP internal network IPv6 subnet is to be specified using the property fixed_ips map property subnet,

the parameter MUST follow the naming convention

  • int_{network-role}_v6_subnet_id

where {network-role} is the network role of the ONAP internal network.

Note that the parameter MUST be defined as an output parameter in the base module.

Requirement: R-22288 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
updated: casablanca
validation_mode: static

The VNF’s Heat Orchestration Template’s Resource OS::Neutron::Port property fixed_ips map property subnet parameter int_{network-role}_v6_subnet_id MUST NOT be enumerated in the VNF’s Heat Orchestration Template’s Environment File.

Example Parameter Definition

parameters:

  int_{network-role}_v6_subnet_id:
    type: string
    description: Neutron subnet UUID for the int_{network-role} network
Property: allowed_address_pairs, Map Property: ip_address

The property allowed_address_pairs in the resource OS::Neutron::Port allows the user to specify a mac_address and/or ip_address that will pass through a port regardless of subnet. This enables the use of protocols, such as VRRP, which allow for a Virtual IP (VIP) address to be shared among two or more ports, with one designated as the master and the others as backups. In case the master fails, the Virtual IP address is mapped to a backup’s IP address and the backup becomes the master.

Note that the IP address assigned to the allowed_address_pairs property will be referred to as a Virtual IP or VIP or VIP address.

The management of the VIP addresses (i.e. transferring ownership between active and standby VMs) is the responsibility of the VNF application.

If a VNF requires a Virtual IP address, a VNF’s Heat Orchestration Template’s resource OS::Neutron::Port property allowed_address_pairs map property ip_address parameter must be used.

The allowed_address_pairs is an optional property. It is not required.

The ONAP data model only supports the assignment of

  • One IPv4 Virtual IP address and/or

  • One IPv6 Virtual IP address

for a set of ports associated with a {vm-type} and {network-role}.

The ONAP data model that supports VIPs includes the

  • SDC TOSCA model

  • SDN-C MD-SAL structure

  • AAI VNF-C object

However, it is possible to assign additional VIP addresses to a port. These additional VIP addresses will not be represented in the SDC TOSCA model and AAI VNF-C object and will be represented differently in the MD-SAL structure.

All VIP addresses will be inventoried in the A&AI vserver object. This assumes the mechanism to populate allowed_address_pair IP addresses in the AAI vserver object has been implemented.

In order for the VIP address to be supported by the ONAP data model, the parameter associated with the OS::Neutron::Port property allowed_address_pairs map property ip_address must follow an explicit naming convention. As expected, the naming convention only supports one IPv4 VIP address and one IPv6 VIP address.

It is recommended that the first IPv4 VIP address and first IPv6 VIP address assigned follow the explicit naming convention. If additional VIP addresses are required, the naming convention is at the discretion of the user. However, OS::Neutron::Port resource-level metadata (not property-level) must be included in the resource definition.

The detailed requirements follow in the sections below.

VIP Assignment, ONAP External Networks
Requirement: R-83412 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
updated: frankfurt
validation_mode: static

If a VNF’s Heat Orchestration Template’s resource OS::Neutron::Port is attaching to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), the property allowed_address_pairs map property ip_address parameter(s) MUST NOT be enumerated in the VNF’s Heat Orchestration Template’s Environment File.

Requirement: R-41492 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt
validation_mode: static

When the VNF’s Heat Orchestration Template’s resource OS::Neutron::Port is attaching to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), and the IPv4 VIP is required to be supported by the ONAP data model, the property allowed_address_pairs map property ip_address parameter name MUST follow the naming convention

  • {vm-type}_{network-role}_floating_ip

where

  • {vm-type} is the {vm-type} associated with the OS::Nova::Server

  • {network-role} is the {network-role} of the ONAP external network

And the parameter MUST be declared as type string.

As noted in the introduction to this section, the ONAP data model can only support one IPv4 VIP address.

Example Parameter Definition

parameters:

  {vm-type}_{network-role}_floating_ip:
    type: string
    description: IPv4 VIP for {vm-type} VMs on the {network-role} network
Requirement: R-35735 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt
validation_mode: static

When the VNF’s Heat Orchestration Template’s resource OS::Neutron::Port is attaching to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), and the IPv6 VIP is required to be supported by the ONAP data model, the property allowed_address_pairs map property ip_address parameter name MUST follow the naming convention

  • {vm-type}_{network-role}_floating_v6_ip

where

  • {vm-type} is the {vm-type} associated with the OS::Nova::Server

  • {network-role} is the {network-role} of the ONAP external network

And the parameter MUST be declared as type string.

As noted in the introduction to this section, the ONAP data model can only support one IPv6 VIP address.

Example Parameter Definition

parameters:

  {vm-type}_{network-role}_floating_v6_ip:
    type: string
    description: IPv6 VIP for {vm-type} VMs on the {network-role} network
Requirement: R-41493 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: dublin
updated: frankfurt
validation_mode: static

When the VNF’s Heat Orchestration Template’s resource OS::Neutron::Port is attaching to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), and the IPv4 VIP address and/or IPv6 VIP address is not supported by the ONAP data model, the property allowed_address_pairs map property ip_address

  • Parameter name MAY use any naming convention. That is, there is no ONAP mandatory parameter naming convention.

  • Parameter MAY be declared as type string or type

comma_delimited_list.

And the OS::Neutron::Port resource MUST contain resource-level metadata (not property-level).

And the metadata format MUST must contain the key value aap_exempt with a list of all allowed_address_pairs map property ip_address parameters not supported by the ONAP data model.

Example

In the example below, the OS::Neutron::Port property allowed_address_pairs map property ip_address has two parameters, param1 and param2, that are not supported by the ONAP data model.

db_0_oam_port_0:
  type: OS::Neutron::Port
  properties:
    network: { get_param: oam_net_id }
    fixed_ips: [ { "ip_address": {get_param: db_oam_ip_0 }}]
    allowed_address_pairs: [ { "ip_address": {get_param: param1 }}, { "ip_address": {get_param: param2 }}]
  metadata:
    aap_exempt:
      - param1
      - param2

Example

In the example below, the OS::Neutron::Port property allowed_address_pairs map property ip_address has two parameters, db_oam_ip_0, which is supported by the ONAP data model, and param1, which is not supported by the ONAP data model.

db_0_oam_port_0:
  type: OS::Neutron::Port
  properties:
    network: { get_param: oam_net_id }
    fixed_ips: [ { "ip_address": {get_param: db_oam_ip_0 }}]
    allowed_address_pairs: [ { "ip_address": {get_param: db_oam_floating_ip }}, { "ip_address": {get_param: param1 }} ]
  metadata:
    aap_exempt:
      - param1

Note that the parameters associated with the resource OS::Neutron::Port property allowed_address_pairs map property ip_address are not intended to represent an OpenStack “Floating IP”, for which OpenStack manages a pool of public IP addresses that are mapped to specific VM ports. In that case, the individual VMs are not even aware of the public IPs, and all assignment of public IPs to VMs is via OpenStack commands. ONAP does not support Neutron-style Floating IPs. That is, ONAP does not support the resources OS::Neutron::FloatingIP and OS::Neutron::FloatingIPAssociation.

Requirement: R-05257 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
updated: casablanca
validation_mode: static

A VNF’s Heat Orchestration Template’s MUST NOT contain the Resource OS::Neutron::FloatingIP.

Requirement: R-76449 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
updated: casablanca
validation_mode: static

A VNF’s Heat Orchestration Template’s MUST NOT contain the Resource OS::Neutron::FloatingIPAssociation.

The Floating IP functions as a NAT. They are allocated within OpenStack, and always “terminate” within the OpenStack infrastructure. When OpenStack receives packets on a Floating IP, the packets will be forwarded to the Port that has been mapped to the Floating IP, using the private address of the port. The VM never sees or knows about the OpenStack Floating IP. The process to use is:

  • User allocates a floating IP from the OpenStack pool.

  • User ‘attaches’ that floating IP to one of the VM ports.

If there is a high-availability VNF that wants to “float” the IP to a different VM, it requires a Neutron command to request OpenStack to ‘attach’ the floating IP to a different VM port. The pool of such addresses is managed by OpenStack infrastructure. Users cannot create new ones, they can only choose from those in the pool. The pool is typically global (i.e. any user/tenant can grab them).

Allowed address pairs are for more typical Linux-level “virtual IPs”. They are additional IP addresses that are advertised by some port on the VM, in addition to the primary private IP address. Typically in a high-availability VNF, an additional IP is assigned and will float between VMs (e.g., via some health-check app that will plumb the IP on one or other VM). In order for this to work, the actual packets must be addressed to that IP address (and the allowed_ip_address list will let it pass through to the VM). This generally requires provider network access (i.e. direct access to a data center network for the VMs), such that these IPs can pass through all of the virtual routers. Contrail also provides the enhanced networking that allows routing of such additional IPs.

Floating IPs are not used in ONAP due to the NAT-ting nature of the IPs, the inability to reserve such IPs for specific use, the need to manage them via OpenStack commands (i.e. a HA VNF would require direct access to OpenStack to ‘float’ such an IP from one VM to another).

Example:

In this example, the {network-role} has been defined as oam to represent an oam network and the {vm-type} has been defined as db for database.

parameters:
  oam_net_id:
    type: string
    description: Neutron UUID for the oam network
  db_oam_ips:
    type: comma_delimited_list
    description: Fixed IPs for db VMs on the oam network
  db_oam_floating_ip:
    type: string
    description: VIP IP for db VMs on the oam network
resources:
  db_0_oam_port_0:
    type: OS::Neutron::Port
    properties:
      network: { get_param: oam_net_id }
      fixed_ips: [ { "ip_address": {get_param: [db_oam_ips, 0] }}]
      allowed_address_pairs: [ { "ip_address": {get_param: db_oam_floating_ip}}]
  db_1_oam_port_0:
    type: OS::Neutron::Port
      properties:
        network: { get_param: oam_net_id }
        fixed_ips: [ { "ip_address": {get_param: [db_oam_ips, 1] }}]
        allowed_address_pairs: [ { "ip_address": {get_param: db_oam_floating_ip}}]
VIP Assignment, ONAP Internal Networks
Requirement: R-717227 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: dublin
updated: frankfurt
validation_mode: static

When the VNF’s Heat Orchestration Template’s Resource OS::Neutron::Port is attaching to an ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666), and an IPv4 Virtual IP (VIP) address is assigned using the property allowed_address_pairs map property ip_address, the parameter name MUST follow the naming convention

  • {vm-type}_int_{network-role}_floating_ip

where

  • {vm-type} is the {vm-type} associated with the OS::Nova::Server

  • {network-role} is the {network-role} of the ONAP internal network

And the parameter MUST be declared as type: string and MUST be enumerated in the environment file.

OR

the parameter name MUST follow the naming convention

  • {vm-type}_int_{network-role}_floating_ips

where

  • {vm-type} is the {vm-type} associated with the OS::Nova::Server

  • {network-role} is the {network-role} of the ONAP internal network

And the parameter MUST be declared as type: comma_delimited_list and MUST be enumerated in the environment file.

Requirement: R-805572 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: dublin
updated: frankfurt
validation_mode: static

When the VNF’s Heat Orchestration Template’s Resource OS::Neutron::Port is attaching to an ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666), and an IPv6 Virtual IP (VIP) address is assigned using the property allowed_address_pairs map property ip_address, the parameter name MUST follow the naming convention

  • {vm-type}_int_{network-role}_floating_v6_ip

where

  • {vm-type} is the {vm-type} associated with the OS::Nova::Server

  • {network-role} is the {network-role} of the ONAP internal network

And the parameter MUST be declared as type: string and MUST be enumerated in the environment file

OR

the parameter name MUST follow the naming convention

  • {vm-type}_int_{network-role}_floating_v6_ips

where

  • {vm-type} is the {vm-type} associated with the OS::Nova::Server

  • {network-role} is the {network-role} of the ONAP internal network

And the parameter MUST be declared as type: comma_delimited_list and MUST be enumerated in the environment file.

Reserve Port Concept

A “Reserve Port” is an OS::Neutron::Port that fixed_ips, ip_address property is assigned one or more IP addresses that are used as Virtual IP (VIP) addresses (i.e., allowed_address_pairs) on other ports.

A “Reserve Port” is never attached to a Virtual Machine (OS::Nova::Server). The reserve port ensures that the intended allowed_address_pair IP address is not inadvertently assigned as a fixed_ips to a OS::Neutron::Port that is attached OS::Nova::Server and thus causing routing issues.

A VNF may have one or more “Reserve Ports”. A reserve port maybe created in the base module or an incremental module. If created in the base module, parameters may be defined in the outputs: section of the base template so the IP address assigned to the reserve port maybe assigned to the allowed_address_pair property of an OS::Neutron::Port in one or more incremental modules.

The parameter name of the IP address used in the “Reserve Port” depends on the allowed_address_pair “option” utilized by the VNF.

When creating a Reserve Port, if only one allowed_address_pair is configured on a port, then the parameter name depends upon the IP addresses type (IPv4 or IPv6) and network type (ONAP internal or ONAP external). The valid parameter names are:

  • {vm-type}_{network-role}_floating_ip

  • {vm-type}_{network-role}_floating_v6_ip

  • {vm-type}_int_{network-role}_floating_ip

  • {vm-type}_int_{network-role}_floating_v6_ip

When creating a Reserve Port, if more than one (e.g., multiple) allowed_address_pair is configured on a port, then the parameter name depends upon the IP addresses type (IPv4 or IPv6) and network type (internal or external) and the option being used. The valid parameter names are:

  • {vm-type}_{network-role}_ip_{index}

  • {vm-type}_{network-role}_ips

  • {vm-type}_{network-role}_v6_ip_{index}

  • {vm-type}_{network-role}_v6_ips

  • {vm-type}_{network-role}_vip_{index}

  • {vm-type}_{network-role}_vips

  • {vm-type}_{network-role}_v6_vip_{index}

  • {vm-type}_{network-role}_v6_vips

  • {vm-type}_{network-role}_{vip-type}_vip

  • {vm-type}_{network-role}_v6_{vip-type}_vip

  • {vm-type}_{network-role}_{vip-type}_vips

  • {vm-type}_{network-role}_v6_{vip-type}_vips

Example IPv4 Reserve Port Definition: one allowed_address_pair configured on a port

Reserve_Port_{vm-type}_{network-role}_floating_ip_{index}:
  type: OS::Neutron::Port
  properties:
    network: { get_param: {network-role}_net_id }
    fixed_ips:
      - ip_address : { get_param: {vm-type}_{network-role}_floating_ip }

Example IPv6 Reserve Port Definition: one allowed_address_pair configured on a port

Reserve_Port_{vm-type}_{network-role}_floating_v6_ip_{index}:
  type: OS::Neutron::Port
  properties:
    network: { get_param: {network-role}_net_id }
    fixed_ips:
      - ip_address : { get_param: {vm-type}_{network-role}_floating_v6_ip }

Note that the use of a Reserve Port may prevent the VIP address from being inventoried in the AAI VNF-C object.

Resource Property “name”

The parameter naming convention of the property name for the resource OS::Nova::Server has been defined in Resource: OS::Nova::Server Metadata Parameters.

This section provides specifies how the property name for non OS::Nova::Server resources must be defined when the property is used. Not all resources require the property name (e.g., it is optional) and some resources do not support the property.

Requirement: R-85734 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: dublin
validation_mode: static

If a VNF’s Heat Orchestration Template contains the property name for a non OS::Nova::Server resource, the intrinsic function str_replace MUST be used in conjunction with the ONAP supplied metadata parameter vnf_name to generate a unique value. Additional data MAY be used in the str_replace construct to generate a unique value.

This approach prevents the enumeration of a unique value for the property name in a per instance environment file.

In most cases the use of the metadata value vnf_name will create a unique property name. If this does not create a unique value, additional dynamic or constant data can be added to the str_replace construct.

For example, the Heat Orchestration Template pseudo parameter OS::stack_name can be used in the str_replace construct.

For resources created in a nested heat file invoked by an OS::Heat::ResourceGroup, the index can be used to construct a unique value.

Requirement: R-99812 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
updated: casablanca
validation_mode: static

A value for VNF’s Heat Orchestration Template’s property name for a non OS::Nova::Server resource MUST NOT be declared in the VNF’s Heat Orchestration Template’s Environment File.

Example: Property ‘name’ for resource ‘OS::Neutron::SecurityGroup’

resources:
  DNS_SECURITY_GROUP:
    type: OS::Neutron::SecurityGroup
    properties:
      description: vDNS security group
      name:
        str_replace:
          template: VNF_NAME_sec_grp_DNS
          params:
            VNF_NAME: {get_param: vnf_name}
      rules: [. . . . .]

Example: Property ‘name’ for resource ‘OS::Cinder::Volume’

resources:
  dns_volume_0:
    type: OS::Cinder::Volume
    properties:
      description: Cinder Volume
      name:
        str_replace:
          template: VNF_NAME_STACK_NAME_dns_volume
          params:
            VNF_NAME: {get_param: vnf_name}
            STACK_NAME: { get_param: 'OS::stack_name' }
. . . .

Example: Property ‘name’ for resource ‘OS::Cinder::Volume’ invoked by a ‘OS::Heat::ResourceGroup’

resources:
  dns_volume_0:
    type: OS::Cinder::Volume
    properties:
      description: Cinder Volume
      name:
        str_replace:
            template: VNF_NAME_STACK_NAME_dns_volume_INDEX
            params:
                VNF_NAME: { get_param: vnf_name }
                STACK_NAME: { get_param: 'OS::stack_name' }
                INDEX: { get_param: index }
. . . .
Contrail Issue with Values for the Property Name
Requirement: R-84517 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD
updated: casablanca

The Contrail GUI has a limitation displaying special characters. The issue is documented in https://bugs.launchpad.net/juniperopenstack/+bug/1590710. It is recommended that special SHOULD characters be avoided. However, if special characters must be used, note that for the following resources:

  • Virtual Machine

  • Virtual Network

  • Port

  • Security Group

  • Policies

  • IPAM Creation

the only special characters supported are - " ! $‘ ( ) = ~ ^ | @ ` { } [ ] > , . _”

ONAP Output Parameter Names

ONAP defines three types of Output Parameters as detailed in Output Parameters.

ONAP Base Module Output Parameters:

ONAP Base Module Output Parameters do not have an explicit naming convention.

Requirement: R-97726 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: none

A VNF’s Heat Orchestration Template’s Base Module Output Parameter names MUST contain {vm-type} and/or {network-role} when appropriate.

ONAP Volume Template Output Parameters:
Requirement: R-88524 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: none

A VNF’s Heat Orchestration Template’s Volume Template Output Parameter names MUST contain {vm-type} when appropriate.

Predefined Output Parameters

ONAP currently defines one predefined output parameter the OAM Management IP Addresses.

OAM Management IP Addresses

A VNF may have a management interface for application controllers to interact with and configure the VNF. Typically, this will be via a specific VM that performs a VNF administration function. The IP address of this interface must be captured and inventoried by ONAP. The IP address might be a VIP if the VNF contains an HA pair of management VMs, or may be a single IP address assigned to one VM.

Requirement: R-47874 _images/arrow-right-circle.svg
target: VNF
keyword: MAY
updated: casablanca
A VNF MAY have
  • Only an IPv4 OAM Management IP Address

  • Only an IPv6 OAM Management IP Address

  • Both a IPv4 and IPv6 OAM Management IP Addresses

Requirement: R-18683 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

If a VNF has one IPv4 OAM Management IP Address and the IP Address needs to be inventoried in ONAP’s A&AI database, an output parameter MUST be declared in only one of the VNF’s Heat Orchestration Templates and the parameter MUST be named oam_management_v4_address.

Requirement: R-94669 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

If a VNF has one IPv6 OAM Management IP Address and the IP Address needs to be inventoried in ONAP’s A&AI database, an output parameter MUST be declared in only one of the VNF’s Heat Orchestration Templates and the parameter MUST be named oam_management_v6_address.

The OAM Management IP Address maybe assigned either via
  • ONAP SDN-C

  • DHCP

Requirement: R-56287 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: none

If the VNF’s OAM Management IP Address is assigned by ONAP SDN-C and assigned in the VNF’s Heat Orchestration Template’s via a heat resource OS::Neutron::Port property fixed_ips map property ip_adress parameter (e.g., {vm-type}_{network-role}_ip_{index}, {vm-type}_{network-role}_v6_ip_{index}) and the OAM IP Address is required to be inventoried in ONAP A&AI, then the parameter MUST be echoed in an output statement.

outputs:
    oam_management_v4_address:
      value: {get_param: {vm-type}_{network-role}_ip_{index} }
    oam_management_v6_address:
      value: {get_param: {vm-type}_{network-role}_v6_ip_{index} }

Example: ONAP SDN-C Assigned IP Address echoed as oam_management_v4_address

parameters:
  admin_oam_ip_0:
    type: string
    description: Fixed IPv4 assignment for admin VM 0 on the OAM network
. . .
resources:
  admin_0_oam_port_0:
    type: OS::Neutron::Port
    properties:
      name:
        str_replace:
          template: VNF_NAME_admin_oam_port_0
          params:
            VNF_NAME: {get_param: vnf_name}
      network: { get_param: oam_net_id }
      fixed_ips: [{ "ip_address": { get_param: admin_oam_ip_0 }}]
      security_groups: [{ get_param: security_group }]
  admin_server_0:
    type: OS::Nova::Server
    properties:
      name: { get_param: admin_names }
      image: { get_param: admin_image_name }
      flavor: { get_param: admin_flavor_name }
      availability_zone: { get_param: availability_zone_0 }
    networks:
      - port: { get_resource: admin_0_oam_net_port_0 }
    metadata:
      vnf_id: { get_param: vnf_id }
      vf_module_id: { get_param: vf_module_id }
      vnf_name: {get_param: vnf_name }
outputs:
    oam_management_v4_address:
      value: {get_param: admin_oam_ip_0 }
Requirement: R-48987 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: none

If the VNF’s OAM Management IP Address is cloud assigned and and the OAM IP Address is required to be inventoried in ONAP A&AI, then the parameter MUST be obtained by the resource OS::Neutron::Port attribute ip_address.

outputs:
    oam_management_v4_address:
      value: {get_attr: [ {OS::Neutron Port Resource ID}, fixed_ips, 0, ip_address] }

Example: Cloud Assigned IP Address output as oam_management_v4_address

parameters:
. . .
resources:
  admin_0_oam_port_0:
    type: OS::Neutron::Port
    properties:
      name:
        str_replace:
          template: VNF_NAME_admin_oam_0_port
          params:
            VNF_NAME: {get_param: vnf_name}
      network: { get_param: oam_net_id }
      security_groups: [{ get_param: security_group }]
  admin_server_0:
    type: OS::Nova::Server
    properties:
      name: { get_param: admin_name_0 }
      image: { get_param: admin_image_name }
      flavor: { get_param: admin_flavor_name }
      availability_zone: { get_param: availability_zone_0 }
      networks:
        - port: { get_resource: admin_0_oam_port_0 }
      metadata:
        vnf_id: { get_param: vnf_id }
        vf_module_id: { get_param: vf_module_id }
        vnf_name: {get_param: vnf_name }
outputs:
  oam_management_v4_address:
    value: {get_attr: [admin_0_oam_port_0, fixed_ips, 0, ip_address] }
Contrail Resource Parameters

ONAP requires the parameter names of certain Contrail Resources to follow specific naming conventions. This section provides these requirements.

Contrail Network Parameters

Contrail based resources may require references to a Contrail network using the network FQDN.

ONAP External Networks
Requirement: R-02164 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt
validation_mode: static

When a VNF’s Heat Orchestration Template’s Contrail resource OS::ContrailV2::InstanceIp and/or OS::ContrailV2::VirtualMachineInterface contains the property virtual_network_refs that references an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), the property value MUST be obtained by a get_param and the property parameter

  • MUST follow the format {network-role}_net_fqdn

  • MUST be declared as type string

Requirement: R-92193 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
updated: frankfurt
validation_mode: static

A VNF’s Heat Orchestration Template’s Contrail resource OS::ContrailV2::InstanceIp and/or OS::ContrailV2::VirtualMachineInterface property virtual_network_refs parameter {network-role}_net_fqdn MUST NOT be enumerated in the VNF’s Heat Orchestration Template’s Environment File.

Example: Parameter declaration

parameters:
  {network-role}_net_fqdn:
    type: string
    description: Contrail FQDN for the {network-role} network

Example: Contrail Resource OS::ContrailV2::VirtualMachineInterface Reference to a Network FQDN.

In this example, the {network-role} has been defined as oam to represent an oam network and the {vm-type} has been defined as fw for firewall. The Contrail resource OS::ContrailV2::VirtualMachineInterface property virtual_network_refs references a contrail network FQDN.

fw_0_oam_vmi_0:
  type: OS::ContrailV2::VirtualMachineInterface
  properties:
    name:
      str_replace:
        template: VM_NAME_virtual_machine_interface_1
        params:
          VM_NAME: { get_param: fw_name_0 }
    virtual_machine_interface_properties:
      virtual_machine_interface_properties_service_interface_type: {
      get_param: oam_protected_interface_type }
    virtual_network_refs:
      - get_param: oam_net_fqdn
    security_group_refs:
      - get_param: fw_sec_grp_id
Interface Route Table Prefixes for Contrail InterfaceRoute Table
Requirement: R-28222 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

If a VNF’s Heat Orchestration Template OS::ContrailV2::InterfaceRouteTable resource interface_route_table_routes property interface_route_table_routes_route map property parameter name MUST follow the format

  • {vm-type}_{network-role}_route_prefixes

Requirement: R-19756 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

If a VNF’s Heat Orchestration Template OS::ContrailV2::InterfaceRouteTable resource interface_route_table_routes property interface_route_table_routes_route map property parameter {vm-type}_{network-role}_route_prefixes MUST be defined as type json.

Requirement: R-76682 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
updated: casablanca
validation_mode: static

If a VNF’s Heat Orchestration Template OS::ContrailV2::InterfaceRouteTable resource interface_route_table_routes property interface_route_table_routes_route map property parameter {vm-type}_{network-role}_route_prefixes MUST NOT be enumerated in the VNF’s Heat Orchestration Template’s Environment File.

The parameter {vm-type}_{network-role}_route_prefixes supports IP addresses in the format:

  1. Host IP Address (e.g., 10.10.10.10)

  2. CIDR Notation format (e.g., 10.0.0.0/28)

Example Parameter Definition

parameters:
  {vm-type}_{network-role}_route_prefixes:
    type: json
    description: JSON list of Contrail Interface Route Table route prefixes

Example:

parameters:
  vnf_name:
    type: string
    description: Unique name for this VF instance
  fw_oam_route_prefixes:
    type: json
    description: prefix for the ServiceInstance InterfaceRouteTable
  int_fw_dns_trusted_interface_type:
    type: string
    description: service_interface_type for ServiceInstance

resources:
  <resource name>:
    type: OS::ContrailV2::InterfaceRouteTable
    depends_on: [resource name of OS::ContrailV2::ServiceInstance]
    properties:
      name:
        str_replace:
          template: VNF_NAME_interface_route_table
          params:
            VNF_NAME: { get_param: vnf_name }
      interface_route_table_routes:
        interface_route_table_routes_route: { get_param: fw_oam_route_prefixes }
      service_instance_refs:
        - get_resource: <resource name of OS::ContrailV2::ServiceInstance>
      service_instance_refs_data:
        - service_instance_refs_data_interface_type: { get_param: oam_interface_type }
Resource OS::ContrailV2::InstanceIp

The Contrail resource OS::ContrailV2::InstanceIp has two properties that parameters MUST follow an explicit naming convention. The properties are instance_ip_address and subnet_uuid.

Example OS::ContrailV2::InstanceIp Resource

<resource ID>:
  type: OS::ContrailV2::InstanceIp
  properties:
    name: { get_param: name }
    fq_name: { get_param: fq_name }
    display_name: { get_param: display_name }
    secondary_ip_tracking_ip:
      {
        secondary_ip_tracking_ip_ip_prefix: { get_param: secondary_ip_tracking_ip_ip_prefix },
        secondary_ip_tracking_ip_ip_prefix_len: { get_param: secondary_ip_tracking_ip_ip_prefix_len },
      }
    instance_ip_address: { get_param: instance_ip_address }
    instance_ip_mode: { get_param: instance_ip_mode }
    subnet_uuid: { get_param: subnet_uuid }
    instance_ip_family: { get_param: instance_ip_family }
    annotations:
      {
        annotations_key_value_pair:
          [{
            annotations_key_value_pair_key: { get_param: annotations_key_value_pair_key },
            annotations_key_value_pair_value: { get_param: annotations_key_value_pair_value },
          }],
      }
    instance_ip_local_ip: { get_param: instance_ip_local_ip }
    instance_ip_secondary: { get_param: instance_ip_secondary }
    physical_router_refs: [{ get_param: physical_router_refs }]
    virtual_machine_interface_refs: [{ get_param: virtual_machine_interface_refs }]
    virtual_network_refs: [{ get_param: virtual_network_refs }]
Resource OS::ContrailV2::InstanceIp Property instance_ip_address

A VNF’s Heat Orchestration Templates resource OS::ContrailV2::InstanceIp property instance_ip_address parameter MUST follow the same requirements that apply to the resource OS::Neutron property fixed_ips map property ip_address parameter.

Requirement: R-100000 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: dublin
validation_mode: static

The VNF’s Heat Orchestration Template’s resource OS::ContrailV2::InstanceIp property instance_ip_address parameter MUST be declared as either type string or type comma_delimited_list.

Requirement: R-100010 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: dublin
updated: frankfurt
validation_mode: static

When the VNF’s Heat Orchestration Template’s Resource OS::ContrailV2::InstanceIp is assigning an IP address to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), and an IPv4 address is assigned using the property instance_ip_address and the parameter type is defined as a string, the parameter name MUST follow the naming convention

  • {vm-type}_{network-role}_ip_{index}

where

  • {vm-type} is the {vm-type} associated with the OS::Nova::Server

  • {network-role} is the {network-role} of the ONAP external network

  • {index} is a numeric value that MUST start at zero in a VNF’s Heat Orchestration Template and MUST increment by one

Requirement: R-100020 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
introduced: dublin
validation_mode: static

The VNF’s Heat Orchestration Template’s Resource OS::ContrailV2::InstanceIp property instance_ip_address parameter {vm-type}_{network-role}_ip_{index} MUST NOT be enumerated in the VNF’s Heat Orchestration Template’s Environment File.

ONAP’s SDN-Controller assigns the IP Address and ONAP provides the value at orchestration to the Heat Orchestration Template.

Example ONAP External Network IPv4 Address string Parameter Definition

parameters:

  {vm-type}_{network-role}_ip_{index}:
    type: string
    description: Fixed IPv4 assignment for {vm-type} VM {index} on the {network-role} network
Requirement: R-100030 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: dublin
updated: frankfurt
validation_mode: static

When the VNF’s Heat Orchestration Template’s Resource OS::ContrailV2::InstanceIp is assigning an IP address to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), and an IPv4 address is assigned using the property instance_ip_address and the parameter type is defined as a comma_delimited_list, the parameter name MUST follow the naming convention

  • {vm-type}_{network-role}_ips

where

  • {vm-type} is the {vm-type} associated with the OS::Nova::Server

  • {network-role} is the {network-role} of the ONAP external network

Requirement: R-100040 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
introduced: dublin
validation_mode: static

The VNF’s Heat Orchestration Template’s Resource OS::ContrailV2::InstanceIp property instance_ip_address parameter {vm-type}_{network-role}_ips MUST NOT be enumerated in the VNF’s Heat Orchestration Template’s Environment File.

ONAP’s SDN-Controller assigns the IP Address and ONAP provides the value at orchestration to the Heat Orchestration Template.

Example External Network IPv4 Address comma_delimited_list Parameter Definition

parameters:

  {vm-type}_{network-role}_ips:
    type: comma_delimited_list
    description: Fixed IPv4 assignments for {vm-type} VMs on the {network-role} network
Requirement: R-100050 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: dublin
updated: frankfurt
validation_mode: static

When the VNF’s Heat Orchestration Template’s Resource OS::ContrailV2::InstanceIp is assigning an IP address to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), and an IPv6 address is assigned using the property instance_ip_address and the parameter type is defined as a string, the parameter name MUST follow the naming convention

  • {vm-type}_{network-role}_v6_ip_{index}

where

  • {vm-type} is the {vm-type} associated with the OS::Nova::Server

  • {network-role} is the {network-role} of the ONAP external network

  • {index} is a numeric value that MUST start at zero in a VNF’s Heat Orchestration Template and MUST increment by one

Requirement: R-100060 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
introduced: dublin
validation_mode: static

The VNF’s Heat Orchestration Template’s Resource OS::ContrailV2::InstanceIp property instance_ip_address parameter {vm-type}_{network-role}_v6_ip_{index} MUST NOT be enumerated in the VNF’s Heat Orchestration Template’s Environment File.

ONAP’s SDN-Controller assigns the IP Address and ONAP provides the value at orchestration to the Heat Orchestration Template.

Example ONAP External Network IPv6 Address string Parameter Definition

parameters:

  {vm-type}_{network-role}_v6_ip_{index}:
    type: string
    description: Fixed IPv6 assignment for {vm-type} VM {index} on the {network-role} network
Requirement: R-100070 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: dublin
updated: frankfurt
validation_mode: static

When the VNF’s Heat Orchestration Template’s Resource OS::ContrailV2::InstanceIp is assigning an IP address to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), and an IPv6 address is assigned using the property instance_ip_address and the parameter type is defined as a comma_delimited_list, the parameter name MUST follow the naming convention

  • {vm-type}_{network-role}_v6_ips

where

  • {vm-type} is the {vm-type} associated with the OS::Nova::Server

  • {network-role} is the {network-role} of the ONAP external network

Requirement: R-100080 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
introduced: dublin
validation_mode: static

The VNF’s Heat Orchestration Template’s Resource OS::ContrailV2::InstanceIp property instance_ip_address parameter {vm-type}_{network-role}_v6_ips MUST NOT be enumerated in the VNF’s Heat Orchestration Template’s Environment File.

ONAP’s SDN-Controller assigns the IP Address and ONAP provides the value at orchestration to the Heat Orchestration Template.

Example ONAP External Network IPv6 Address comma_delimited_list Parameter Definition

parameters:

  {vm-type}_{network-role}_v6_ips:
    type: comma_delimited_list
    description: Fixed IPv6 assignments for {vm-type} VMs on the {network-role} network
Requirement: R-100090 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: dublin
updated: frankfurt
validation_mode: static

When the VNF’s Heat Orchestration Template’s Resource OS::ContrailV2::InstanceIp is assigning an IP address to an ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666), and an IPv4 address is assigned using the property instance_ip_address and the parameter type is defined as a string, the parameter name MUST follow the naming convention

  • {vm-type}_int_{network-role}_ip_{index}

where

  • {vm-type} is the {vm-type} associated with the OS::Nova::Server

  • {network-role} is the {network-role} of the ONAP internal network

  • {index} is a numeric value that MUST start at zero in a VNF’s Heat Orchestration Template and MUST increment by one

Requirement: R-100100 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: dublin
validation_mode: static

The VNF’s Heat Orchestration Template’s Resource OS::ContrailV2::InstanceIp property instance_ip_address parameter {vm-type}_int_{network-role}_ip_{index} MUST be enumerated in the VNF’s Heat Orchestration Template’s Environment File.

The IP address is local to the VNF’s ONAP internal network and is (re)used in every VNF spin up, thus the constant value is declared in the VNF’s Heat Orchestration Template’s Environment File.

Example ONAP Internal Network IPv4 Address string Parameter Definition

parameters:

  {vm-type}_int_{network-role}_ip_{index}:
    type: string
    description: Fixed IPv4 assignment for {vm-type} VM {index} on the int_{network-role} network
Requirement: R-100110 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: dublin
updated: frankfurt
validation_mode: static

When the VNF’s Heat Orchestration Template’s Resource OS::ContrailV2::InstanceIp is assigning an IP address to an ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666), and an IPv4 address is assigned using the property instance_ip_address and the parameter type is defined as a comma_delimited_list, the parameter name MUST follow the naming convention

  • {vm-type}_int_{network-role}_ips

where

  • {vm-type} is the {vm-type} associated with the OS::Nova::Server

  • {network-role} is the {network-role} of the ONAP internal network

Requirement: R-100120 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: dublin
validation_mode: static

The VNF’s Heat Orchestration Template’s Resource OS::ContrailV2::InstanceIp property instance_ip_address parameter {vm-type}_int_{network-role}_int_ips MUST be enumerated in the VNF’s Heat Orchestration Template’s Environment File.

The IP address is local to the VNF’s ONAP internal network and is (re)used in every VNF spin up, thus the constant value is declared in the VNF’s Heat Orchestration Template’s Environment File.

Example ONAP Internal Network IPv4 Address comma_delimited_list Parameter Definition

parameters:

  {vm-type}_int_{network-role}_ips:
    type: comma_delimited_list
    description: Fixed IPv4 assignments for {vm-type} VMs on the int_{network-role} network
Requirement: R-100130 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: dublin
updated: frankfurt
validation_mode: static

When the VNF’s Heat Orchestration Template’s Resource OS::ContrailV2::InstanceIp is assigning an IP address to an ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666), and an IPv6 address is assigned using the property instance_ip_address and the parameter type is defined as a string, the parameter name MUST follow the naming convention

  • {vm-type}_int_{network-role}_v6_ip_{index}

where

  • {vm-type} is the {vm-type} associated with the OS::Nova::Server

  • {network-role} is the {network-role} of the ONAP internal network

  • {index} is a numeric value that MUST start at zero in a VNF’s Heat Orchestration Template and MUST increment by one

Requirement: R-100140 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: dublin
validation_mode: static

The VNF’s Heat Orchestration Template’s Resource OS::ContrailV2::InstanceIp property instance_ip_address parameter {vm-type}_int_{network-role}_v6_ip_{index} MUST be enumerated in the VNF’s Heat Orchestration Template’s Environment File.

The IP address is local to the VNF’s ONAP internal network and is (re)used in every VNF spin up, thus the constant value is declared in the VNF’s Heat Orchestration Template’s Environment File.

Example ONAP Internal Network IPv6 Address string Parameter Definition

parameters:

  {vm-type}_int_{network-role}_v6_ip_{index}:
    type: string
    description: Fixed IPv6 assignment for {vm-type} VM {index} on the int_{network-role} network
Requirement: R-100150 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: dublin
updated: frankfurt
validation_mode: static

When the VNF’s Heat Orchestration Template’s Resource OS::ContrailV2::InstanceIp is assigning an IP address to an ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666), and an IPv6 address is assigned using the property instance_ip_address and the parameter type is defined as a comma_delimited_list, the parameter name MUST follow the naming convention

  • {vm-type}_int_{network-role}_v6_ips

where

  • {vm-type} is the {vm-type} associated with the OS::Nova::Server

  • {network-role} is the {network-role} of the ONAP internal network

Requirement: R-100160 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: dublin
validation_mode: static

The VNF’s Heat Orchestration Template’s Resource OS::ContrailV2::InstanceIp property instance_ip_address map property ip_address parameter {vm-type}_int_{network-role}_v6_ips MUST be enumerated in the VNF’s Heat Orchestration Template’s Environment File.

The IP address is local to the VNF’s ONAP internal network and is (re)used in every VNF spin up, thus the constant value is declared in the VNF’s Heat Orchestration Template’s Environment File.

Example ONAP Internal Network IPv6 Address comma_delimited_list Parameter Definition

parameters:

  {vm-type}_int_{network-role}_v6_ips:
    type: comma_delimited_list
    description: Fixed IPv6 assignments for {vm-type} VMs on the int_{network-role} network
Requirement: R-100170 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
introduced: dublin
updated: frankfurt
validation_mode: static

The VNF’s Heat Orchestration Template’s Resource OS::ContrailV2::InstanceIp property instance_ip_address parameter associated with an ONAP external network, i.e.,

  • {vm-type}_{network-role}_ip_{index}

  • {vm-type}_{network-role}_v6_ip_{index}

  • {vm-type}_{network-role}_ips

  • {vm-type}_{network-role}_v6_ips

MUST NOT be enumerated in the Heat Orchestration Template’s Environment File. ONAP provides the IP address assignments at orchestration time.

Requirement: R-100180 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: dublin
updated: frankfurt
validation_mode: static

The VNF’s Heat Orchestration Template’s Resource OS::ContrailV2::InstanceIp property instance_ip_address parameter associated with an ONAP internal network, i.e.,

  • {vm-type}_int_{network-role}_ip_{index}

  • {vm-type}_int_{network-role}_v6_ip_{index}

  • {vm-type}_int_{network-role}_ips

  • {vm-type}_int_{network-role}_v6_ips

MUST be enumerated in the Heat Orchestration Template’s Environment File and IP addresses MUST be assigned.

Example: Contrail Resource OS::ContrailV2::InstanceIp, Property instance_ip_address

The property instance_ip_address uses the same parameter naming convention as the property fixed_ips and Map Property ip_address in OS::Neutron::Port. The resource is assigning an ONAP SDN-C Assigned IP Address. The {network-role} has been defined as oam_protected to represent an oam protected network and the {vm-type} has been defined as fw for firewall.

fw_0_oam_protected_vmi_0_IP_0:
  type: OS::ContrailV2::InstanceIp
  depends_on:
    - fw_0_oam_protected_vmi_0
  properties:
    virtual_machine_interface_refs:
      - get_resource: fw_0_oam_protected_vmi_0
    virtual_network_refs:
      - get_param: oam_protected_net_fqdn
    instance_ip_address: { get_param: [fw_oam_protected_ips, get_param: index ] }
Resource OS::ContrailV2::InstanceIp Property subnet_uuid

A VNF’s Heat Orchestration Templates resource OS::ContrailV2::InstanceIp property subnet_uuid parameter MUST follow the same requirements that apply to the resource OS::Neutron property fixed_ips map property subnet parameter.

The resource OS::ContrailV2::InstanceIp property subnet_uuid parameter is used when a port is requesting an IP assignment via OpenStack’s DHCP Service (i.e., cloud assigned).

The IP address assignment will be made from the specified subnet.

Specifying the subnet is not required; it is optional.

If the network (external or internal) that the port is attaching to only contains one subnet, specifying the subnet is superfluous. The IP address will be assigned from the one existing subnet.

If the network (external or internal) that the port is attaching to contains two or more subnets, specifying the subnet in the instance_ip_address property determines which subnet the IP address will be assigned from.

If the network (external or internal) that the port is attaching to contains two or more subnets, and the subnet is not is not specified, OpenStack will randomly determine which subnet the IP address will be assigned from.

The property instance_ip_address is used to assign IPs to a port. The property subnet_uuid specifies the subnet the IP is assigned from.

Requirement: R-100190 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: dublin
validation_mode: static

The VNF’s Heat Orchestration Template’s resource OS::ContrailV2::InstanceIp property subnet_uuid parameter MUST be declared type string.

Requirement: R-100200 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: dublin
updated: frankfurt
validation_mode: static

When the VNF’s Heat Orchestration Template’s resource OS::ContrailV2::InstanceIp is assigning an IP address to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), and an IPv4 address is being cloud assigned by OpenStack’s DHCP Service and the ONAP external network IPv4 subnet is to be specified using the property subnet_uuid, the parameter MUST follow the naming convention

  • {network-role}_subnet_id

where

  • {network-role} is the network role of the ONAP external network.

Note that ONAP only supports cloud assigned IP addresses from one IPv4 subnet of a given network.

Requirement: R-100210 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
introduced: dublin
validation_mode: static

The VNF’s Heat Orchestration Template’s Resource OS::ContrailV2::InstanceIp property subnet_uuid parameter {network-role}_subnet_id MUST NOT be enumerated in the VNF’s Heat Orchestration Template’s Environment File.

ONAP’s SDN-Controller provides the network’s subnet’s UUID value at orchestration to the Heat Orchestration Template.

Example Parameter Definition

parameters:

  {network-role}_subnet_id:
    type: string
    description: Neutron IPv4 subnet UUID for the {network-role} network
Requirement: R-100220 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: dublin
updated: frankfurt
validation_mode: static

When the VNF’s Heat Orchestration Template’s resource OS::ContrailV2::InstanceIp is assigning an IP address to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), and an IPv6 address is being cloud assigned by OpenStack’s DHCP Service and the ONAP external network IPv6 subnet is to be specified using the property subnet_uuid, the parameter MUST follow the naming convention

  • {network-role}_v6_subnet_id

where

  • {network-role} is the network role of the ONAP external network.

Note that ONAP only supports cloud assigned IP addresses from one IPv6 subnet of a given network.

Requirement: R-100230 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
introduced: dublin
validation_mode: static

The VNF’s Heat Orchestration Template’s Resource OS::ContrailV2::InstanceIp property subnet_uuid parameter {network-role}_v6_subnet_id MUST NOT be enumerated in the VNF’s Heat Orchestration Template’s Environment File.

ONAP’s SDN-Controller provides the network’s subnet’s UUID value at orchestration to the Heat Orchestration Template.

Example Parameter Definition

parameters:

  {network-role}_v6_subnet_id:
    type: string
    description: Neutron IPv6 subnet UUID for the {network-role} network
Requirement: R-100240 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: dublin
updated: frankfurt
validation_mode: static

When

  • the VNF’s Heat Orchestration Template’s resource OS::ContrailV2::InstanceIp in an Incremental Module is assigning an IP address to an ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666) that is created in the Base Module, AND

  • an IPv4 address is being cloud assigned by OpenStack’s DHCP Service AND

  • the ONAP internal network IPv4 subnet is to be specified using the property subnet_uuid,

the parameter MUST follow the naming convention

  • int_{network-role}_subnet_id

where

  • {network-role} is the network role of the ONAP internal network

Note that the parameter MUST be defined as an output parameter in the base module.

Requirement: R-100250 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
introduced: dublin
validation_mode: static

The VNF’s Heat Orchestration Template’s Resource OS::ContrailV2::InstanceIp property subnet_uuid parameter int_{network-role}_subnet_id MUST NOT be enumerated in the VNF’s Heat Orchestration Template’s Environment File.

The assumption is that ONAP internal networks are created in the base module. The subnet network ID will be passed as an output parameter (e.g., ONAP Base Module Output Parameter) to the incremental modules. In the incremental modules, the output parameter name will be defined as input parameter.

Example Parameter Definition

parameters:

  int_{network-role}_subnet_id:
    type: string
    description: Neutron IPv4 subnet UUID for the int_{network-role} network
Requirement: R-100260 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: dublin
updated: frankfurt
validation_mode: static

When

  • the VNF’s Heat Orchestration Template’s resource OS::ContrailV2::InstanceIp in an Incremental Module is attaching to an ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666) that is created in the Base Module, AND

  • an IPv6 address is being cloud assigned by OpenStack’s DHCP Service AND

  • the ONAP internal network IPv6 subnet is to be specified using the property subnet_uuid,

the parameter MUST follow the naming convention

  • int_{network-role}_v6_subnet_id

where {network-role} is the network role of the ONAP internal network.

Note that the parameter MUST be defined as an output parameter in the base module.

Requirement: R-100270 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
introduced: dublin
validation_mode: static

The VNF’s Heat Orchestration Template’s Resource OS::ContrailV2::InstanceIp property subnet_uuid parameter int_{network-role}_v6_subnet_id MUST NOT be enumerated in the VNF’s Heat Orchestration Template’s Environment File.

Example Parameter Definition

parameters:

  int_{network-role}_v6_subnet_id:
    type: string
    description: Neutron subnet UUID for the int_{network-role} network

Example: Contrail Resource OS::ContrailV2::InstanceIp, Property subnet_uuid

The property instance_ip_address uses the same parameter naming convention as the property fixed_ips and Map Property subnet in OS::Neutron::Port. The resource is assigning a cloud assigned IP Address. The {network-role} has been defined as “oam_protected” to represent an oam protected network and the {vm-type} has been defined as “fw” for firewall.

fw_0_oam_protected_vmi_0_IP_0:
  type: OS::ContrailV2::InstanceIp
  depends_on:
  - fw_0_oam_protected_vmi_0
  properties:
    virtual_machine_interface_refs:
      - get_resource: fw_0_oam_protected_vmi_0
    virtual_network_refs:
      - get_param: oam_protected_net_fqdn
    subnet_uuid: { get_param: oam_protected_subnet_id }
OS::ContrailV2::VirtualMachineInterface Property virtual_machine_interface_allowed_address_pairs

A VNF’s Heat Orchestration Templates resource OS::ContrailV2::VirtualMachineInterface map property,

virtual_machine_interface_allowed_address_pairs,

virtual_machine_interface_allowed_address_pairs_allowed_address_pair,

virtual_machine_interface_allowed_address_pairs_allowed_address_pair_ip,

virtual_machine_interface_allowed_address_pairs_allowed_address_pair_ip_ip_prefix

parameter MUST follow the same requirements that apply to the resource OS::Neutron::Port property allowed_address_pairs, map property ip_address parameter.

ONAP External Networks
Requirement: R-100280 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
introduced: dublin
updated: frankfurt
validation_mode: static

If a VNF’s Heat Orchestration Template’s resource OS::ContrailV2::VirtualMachineInterface is attaching to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), the map property

virtual_machine_interface_allowed_address_pairs,

virtual_machine_interface_allowed_address_pairs_allowed_address_pair,

virtual_machine_interface_allowed_address_pairs_allowed_address_pair_ip,

virtual_machine_interface_allowed_address_pairs_allowed_address_pair_ip_ip_prefix

parameter MUST NOT be enumerated in the VNF’s Heat Orchestration Template’s Environment File.

Requirement: R-100310 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: dublin
updated: frankfurt
validation_mode: static

When the VNF’s Heat Orchestration Template’s resource OS::ContrailV2::VirtualMachineInterface is attaching to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), and an IPv4 Virtual IP (VIP) is required to be supported by the ONAP data model, the map property

virtual_machine_interface_allowed_address_pairs,

virtual_machine_interface_allowed_address_pairs_allowed_address_pair,

virtual_machine_interface_allowed_address_pairs_allowed_address_pair_ip,

virtual_machine_interface_allowed_address_pairs_allowed_address_pair_ip_ip_prefix

parameter name MUST follow the naming convention

  • {vm-type}_{network-role}_floating_ip

where

  • {vm-type} is the {vm-type} associated with the OS::Nova::Server

  • {network-role} is the {network-role} of the ONAP external network

And the parameter MUST be declared as type string.

The ONAP data model can only support one IPv4 VIP address.

Example Parameter Definition

parameters:

  {vm-type}_{network-role}_floating_ip:
    type: string
    description: IPv4 VIP for {vm-type} VMs on the {network-role} network
Requirement: R-100330 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: dublin
updated: frankfurt
validation_mode: static

When the VNF’s Heat Orchestration Template’s resource OS::ContrailV2::VirtualMachineInterface is attaching to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), and an IPv6 Virtual IP (VIP) is required to be supported by the ONAP data model, the map property

virtual_machine_interface_allowed_address_pairs,

virtual_machine_interface_allowed_address_pairs_allowed_address_pair,

virtual_machine_interface_allowed_address_pairs_allowed_address_pair_ip,

virtual_machine_interface_allowed_address_pairs_allowed_address_pair_ip_ip_prefix

parameter name MUST follow the naming convention

  • {vm-type}_{network-role}_floating_v6_ip

where

  • {vm-type} is the {vm-type} associated with the OS::Nova::Server

  • {network-role} is the {network-role} of the ONAP external network

And the parameter MUST be declared as type string.

The ONAP data model can only support one IPv6 VIP address.

Example Parameter Definition

parameters:

  {vm-type}_{network-role}_floating_v6_ip:
    type: string
    description: IPv6 VIP for {vm-type} VMs on the {network-role} network
Requirement: R-100350 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: dublin
updated: frankfurt
validation_mode: static

When the VNF’s Heat Orchestration Template’s resource OS::ContrailV2::VirtualMachineInterface is attaching to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), and the IPv4 VIP address and/or IPv6 VIP address is not supported by the ONAP data model, the map property

virtual_machine_interface_allowed_address_pairs,

virtual_machine_interface_allowed_address_pairs_allowed_address_pair,

virtual_machine_interface_allowed_address_pairs_allowed_address_pair_ip,

virtual_machine_interface_allowed_address_pairs_allowed_address_pair_ip_ip_prefix

  • Parameter name MAY use any naming convention. That is, there is no ONAP mandatory parameter naming convention.

  • Parameter MAY be declared as type string or type comma_delimited_list.

And the OS::ContrailV2::VirtualMachineInterface resource MUST contain resource-level metadata (not property-level).

And the metadata format MUST must contain the key value aap_exempt with a list of all map property

virtual_machine_interface_allowed_address_pairs,

virtual_machine_interface_allowed_address_pairs_allowed_address_pair,

virtual_machine_interface_allowed_address_pairs_allowed_address_pair_ip,

virtual_machine_interface_allowed_address_pairs_allowed_address_pair_ip_ip_prefix

parameters not supported by the ONAP data model.

ONAP Internal Networks
Requirement: R-100360 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: dublin
updated: frankfurt
validation_mode: static

When the VNF’s Heat Orchestration Template’s Resource OS::ContrailV2::VirtualMachineInterface is attaching to an ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666), and an IPv4 Virtual IP (VIP) address is assigned using the map property, virtual_machine_interface_allowed_address_pairs, virtual_machine_interface_allowed_address_pairs_allowed_address_pair, virtual_machine_interface_allowed_address_pairs_allowed_address_pair_ip, virtual_machine_interface_allowed_address_pairs_allowed_address_pair_ip_ip_prefix , the parameter name MUST follow the naming convention

  • {vm-type}_int_{network-role}_floating_ip

where

  • {vm-type} is the {vm-type} associated with the OS::Nova::Server

  • {network-role} is the {network-role} of the ONAP internal network

And the parameter MUST be declared as type: string and MUST be enumerated in the environment file.

OR

the parameter name MUST follow the naming convention

  • {vm-type}_int_{network-role}_floating_ips

where

  • {vm-type} is the {vm-type} associated with the OS::Nova::Server

  • {network-role} is the {network-role} of the ONAP internal network

And the parameter MUST be declared as type: comma_delimited_list and MUST be enumerated in the environment file.

Requirement: R-100370 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: dublin
updated: frankfurt
validation_mode: static

When the VNF’s Heat Orchestration Template’s Resource OS::ContrailV2::VirtualMachineInterface is attaching to an ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666), and an IPv6 Virtual IP (VIP) address is assigned using the map property, virtual_machine_interface_allowed_address_pairs, virtual_machine_interface_allowed_address_pairs_allowed_address_pair, virtual_machine_interface_allowed_address_pairs_allowed_address_pair_ip, virtual_machine_interface_allowed_address_pairs_allowed_address_pair_ip_ip_prefix , the parameter name MUST follow the naming convention

  • {vm-type}_int_{network-role}_floating_v6_ip

where

  • {vm-type} is the {vm-type} associated with the OS::Nova::Server

  • {network-role} is the {network-role} of the ONAP internal network

And the parameter MUST be declared as type: string and MUST be enumerated in the environment file

OR

the parameter name MUST follow the naming convention

  • {vm-type}_int_{network-role}_floating_v6_ips

where

  • {vm-type} is the {vm-type} associated with the OS::Nova::Server

  • {network-role} is the {network-role} of the ONAP internal network

And the parameter MUST be declared as type: comma_delimited_list and MUST be enumerated in the environment file.

Example

Example OS::ContrailV2::VirtualMachineInterface

<resource ID>:
  type: OS::ContrailV2::VirtualMachineInterface
  properties:
    name: { get_param: name }
    fq_name: { get_param: fq_name }
    ecmp_hashing_include_fields:
      {
        ecmp_hashing_include_fields_hashing_configured: { get_param: ecmp_hashing_include_fields_hashing_configured },
        ecmp_hashing_include_fields_source_ip: { get_param: ecmp_hashing_include_fields_source_ip },
        ecmp_hashing_include_fields_destination_ip: { get_param: ecmp_hashing_include_fields_destination_ip },
        ecmp_hashing_include_fields_ip_protocol: { get_param: ecmp_hashing_include_fields_ip_protocol },
        ecmp_hashing_include_fields_source_port: { get_param: ecmp_hashing_include_fields_source_port },
        ecmp_hashing_include_fields_destination_port: { get_param: ecmp_hashing_include_fields_destination_port },
      }
    virtual_machine_interface_host_routes:
      {
        virtual_machine_interface_host_routes_route:
          [{
            virtual_machine_interface_host_routes_route_prefix: { get_param: virtual_machine_interface_host_routes_route_prefix },
            virtual_machine_interface_host_routes_route_next_hop: { get_param: virtual_machine_interface_host_routes_route_next_hop },
            virtual_machine_interface_host_routes_route_next_hop_type: { get_param: virtual_machine_interface_host_routes_route_next_hop_type },
            virtual_machine_interface_host_routes_route_community_attributes:
              {
                virtual_machine_interface_host_routes_route_community_attributes_community_attribute: [{ get_param: virtual_machine_interface_host_routes_route_community_attributes_community_attribute }],
              },
          }],
      }
    virtual_machine_interface_mac_addresses:
      {
        virtual_machine_interface_mac_addresses_mac_address: [{ get_param: virtual_machine_interface_mac_addresses_mac_address }],
      }
    virtual_machine_interface_dhcp_option_list:
      {
        virtual_machine_interface_dhcp_option_list_dhcp_option:
          [{
            virtual_machine_interface_dhcp_option_list_dhcp_option_dhcp_option_name: { get_param: virtual_machine_interface_dhcp_option_list_dhcp_option_dhcp_option_name },
            virtual_machine_interface_dhcp_option_list_dhcp_option_dhcp_option_value: { get_param: virtual_machine_interface_dhcp_option_list_dhcp_option_dhcp_option_value },
            virtual_machine_interface_dhcp_option_list_dhcp_option_dhcp_option_value_bytes: { get_param: virtual_machine_interface_dhcp_option_list_dhcp_option_dhcp_option_value_bytes },
          }],
      }
    virtual_machine_interface_bindings:
      {
        virtual_machine_interface_bindings_key_value_pair:
          [{
            virtual_machine_interface_bindings_key_value_pair_key: { get_param: virtual_machine_interface_bindings_key_value_pair_key },
            virtual_machine_interface_bindings_key_value_pair_value: { get_param: virtual_machine_interface_bindings_key_value_pair_value },
          }],
      }
    virtual_machine_interface_disable_policy: { get_param: virtual_machine_interface_disable_policy }
    virtual_machine_interface_allowed_address_pairs:
      {
        virtual_machine_interface_allowed_address_pairs_allowed_address_pair:
          [{
            virtual_machine_interface_allowed_address_pairs_allowed_address_pair_ip:
              {
                virtual_machine_interface_allowed_address_pairs_allowed_address_pair_ip_ip_prefix: { get_param: virtual_machine_interface_allowed_address_pairs_allowed_address_pair_ip_ip_prefix },
                virtual_machine_interface_allowed_address_pairs_allowed_address_pair_ip_ip_prefix_len: { get_param: virtual_machine_interface_allowed_address_pairs_allowed_address_pair_ip_ip_prefix_len },
              },
            virtual_machine_interface_allowed_address_pairs_allowed_address_pair_mac: { get_param: virtual_machine_interface_allowed_address_pairs_allowed_address_pair_mac },
            virtual_machine_interface_allowed_address_pairs_allowed_address_pair_address_mode: { get_param: virtual_machine_interface_allowed_address_pairs_allowed_address_pair_address_mode },
          }],
      }
    annotations:
      {
        annotations_key_value_pair:
          [{
            annotations_key_value_pair_key: { get_param: annotations_key_value_pair_key },
            annotations_key_value_pair_value: { get_param: annotations_key_value_pair_value },
          }],
      }
    virtual_machine_interface_fat_flow_protocols:
      {
        virtual_machine_interface_fat_flow_protocols_fat_flow_protocol:
          [{
            virtual_machine_interface_fat_flow_protocols_fat_flow_protocol_protocol: { get_param: virtual_machine_interface_fat_flow_protocols_fat_flow_protocol_protocol },
            virtual_machine_interface_fat_flow_protocols_fat_flow_protocol_port: { get_param: virtual_machine_interface_fat_flow_protocols_fat_flow_protocol_port },
          }],
      }
    virtual_machine_interface_device_owner: { get_param: virtual_machine_interface_device_owner }
    port_security_enabled: { get_param: port_security_enabled }
    virtual_machine_interface_properties:
      {
        virtual_machine_interface_properties_service_interface_type: { get_param: virtual_machine_interface_properties_service_interface_type },
        virtual_machine_interface_properties_interface_mirror:
          {
            virtual_machine_interface_properties_interface_mirror_traffic_direction: { get_param: virtual_machine_interface_properties_interface_mirror_traffic_direction },
            virtual_machine_interface_properties_interface_mirror_mirror_to:
              {
                virtual_machine_interface_properties_interface_mirror_mirror_to_analyzer_name: { get_param: virtual_machine_interface_properties_interface_mirror_mirror_to_analyzer_name },
                virtual_machine_interface_properties_interface_mirror_mirror_to_encapsulation: { get_param: virtual_machine_interface_properties_interface_mirror_mirror_to_encapsulation },
                virtual_machine_interface_properties_interface_mirror_mirror_to_analyzer_ip_address: { get_param: virtual_machine_interface_properties_interface_mirror_mirror_to_analyzer_ip_address },
                virtual_machine_interface_properties_interface_mirror_mirror_to_analyzer_mac_address: { get_param: virtual_machine_interface_properties_interface_mirror_mirror_to_analyzer_mac_address },
                virtual_machine_interface_properties_interface_mirror_mirror_to_routing_instance: { get_param: virtual_machine_interface_properties_interface_mirror_mirror_to_routing_instance },
                virtual_machine_interface_properties_interface_mirror_mirror_to_udp_port: { get_param: virtual_machine_interface_properties_interface_mirror_mirror_to_udp_port },
                virtual_machine_interface_properties_interface_mirror_mirror_to_juniper_header: { get_param: virtual_machine_interface_properties_interface_mirror_mirror_to_juniper_header },
                virtual_machine_interface_properties_interface_mirror_mirror_to_nh_mode: { get_param: virtual_machine_interface_properties_interface_mirror_mirror_to_nh_mode },
                virtual_machine_interface_properties_interface_mirror_mirror_to_static_nh_header:
                  {
                    virtual_machine_interface_properties_interface_mirror_mirror_to_static_nh_header_vtep_dst_ip_address: { get_param: virtual_machine_interface_properties_interface_mirror_mirror_to_static_nh_header_vtep_dst_ip_address },
                    virtual_machine_interface_properties_interface_mirror_mirror_to_static_nh_header_vtep_dst_mac_address: { get_param: virtual_machine_interface_properties_interface_mirror_mirror_to_static_nh_header_vtep_dst_mac_address },
                    virtual_machine_interface_properties_interface_mirror_mirror_to_static_nh_header_vni: { get_param: virtual_machine_interface_properties_interface_mirror_mirror_to_static_nh_header_vni },
                  },
              },
          },
        virtual_machine_interface_properties_local_preference: { get_param: virtual_machine_interface_properties_local_preference },
        virtual_machine_interface_properties_sub_interface_vlan_tag: { get_param: virtual_machine_interface_properties_sub_interface_vlan_tag },
      }
    display_name: { get_param: display_name }
    service_health_check_refs: [{ get_param: service_health_check_refs }]
    routing_instance_refs: [{ get_param: routing_instance_refs }]
    routing_instance_refs_data:
      [{
        routing_instance_refs_data_direction: { get_param: routing_instance_refs_data_direction },
        routing_instance_refs_data_vlan_tag: { get_param: routing_instance_refs_data_vlan_tag },
        routing_instance_refs_data_src_mac: { get_param: routing_instance_refs_data_src_mac },
        routing_instance_refs_data_dst_mac: { get_param: routing_instance_refs_data_dst_mac },
        routing_instance_refs_data_mpls_label: { get_param: routing_instance_refs_data_mpls_label },
        routing_instance_refs_data_service_chain_address: { get_param: routing_instance_refs_data_service_chain_address },
        routing_instance_refs_data_ipv6_service_chain_address: { get_param: routing_instance_refs_data_ipv6_service_chain_address },
        routing_instance_refs_data_protocol: { get_param: routing_instance_refs_data_protocol },
      }]
    security_group_refs: [{ get_param: security_group_refs }]
    physical_interface_refs: [{ get_param: physical_interface_refs }]
    port_tuple_refs: [{ get_param: port_tuple_refs }]
    interface_route_table_refs: [{ get_param: interface_route_table_refs }]
    virtual_machine_interface_refs: [{ get_param: virtual_machine_interface_refs }]
    virtual_network_refs: [{ get_param: virtual_network_refs }]
    virtual_machine_refs: [{ get_param: virtual_machine_refs }]
    qos_config_refs: [{ get_param: qos_config_refs }]
    virtual_machine: { get_param: virtual_machine }
    project: { get_param: project }
Suggested Naming Convention for Common Parameters

Many VNFs use the parameters in the table below are used in user_data. The table below provides a suggested naming convention for these common parameters.

Netmask
Table 8: Suggested Naming Convention for Common Parameters: Netmask

Parameter Name

Parameter Type

Notes

{network-role}_subnet_<index>_netmask

string

int_<network-role>_subnet_<index>_netmask

string

{network-role}_v6_subnet_<index>_netmask

string

int_{network-role}_v6_subnet_<index>_netmask

string

CIDR
Table 9: Suggested Naming Convention for Common Parameters: CIDR

Parameter Name

Parameter Type

Notes

<network-role>_subnet_<index>_cidr

string

int_<network-role>_subnet_<index>_cidr

string

<network-role>_v6_subnet_<index>_cidr

string

int_<network-role>_v6_subnet_<index>_cidr

string

Default Gateway
Table 10: Suggested Naming Convention for Common Parameters: Default Gateway

Parameter Name

Parameter Type

Notes

{network-role}_subnet_<index>_default_gateway

string

{network-role}_v6_subnet_<index>_default_gateway

string

DCAE Collector IP Address
Table 11: Suggested Naming Convention for Common Parameters: DCAE Collector Address

Parameter Name

Parameter Type

Notes

dcae_collector_ip_<index>

string

dcae_collector_v6_ip_<index>

string

NTP Server IP Address
Table 12: Suggested Naming Convention for Common Parameters: NTP Server IP Address

Parameter Name

Parameter Type

Notes

ntp_ip_<index>

string

ntp_v6_ip_<index>

string

DNS
Table 13: Suggested Naming Convention for Common Parameters: DCAE Collector Address

Parameter Name

Parameter Type

Notes

dns_{network-role}_ip_<index>

string

dns_{network-role}_v6_ip_<index>

string

Security Group
Table 14: Suggested Naming Convention for Common Parameters: Security Group

Parameter Name

Parameter Type

Notes

{vm-type}_security_group

string

Security Group applicable to one {vm-type} and more than one network (internal and/or external)

{network-role}_security_group

string

Security Group applicable to more than one {vm-type} and one external network

int_{network-role}_security_group

string

Security Group applicable to more than one {vm-type} and one internal network

{vm-type}_{network-role}_security_group

string

Security Group applicable to one {vm-type} and one external network

{vm-type}_int_{network-role}_security_group

string

Security Group applicable to one {vm-type} and one internal network

shared_security_group

string

Security Group applicable to more than one {vm-type} and more than one network (internal and/or external)

ONAP Heat VNF Modularity

ONAP supports a modular Heat Orchestration Template design pattern, referred to as VNF Modularity. With this approach, a single VNF MAY be composed from one or more Heat Orchestration Templates, each of which represents a subset of the overall VNF. These component parts are referred to as VNF Modules. During orchestration, these modules are deployed incrementally to create the complete VNF.

As stated in (R-33132), a VNF’s Heat Orchestration Template MAY be
  1. Base Module Heat Orchestration Template (also referred to as a Base Module),

  2. Incremental Module Heat Orchestration Template (referred to as an Incremental Module), or

  3. a Cinder Volume Module Heat Orchestration Template (referred to as Cinder Volume Module).

At orchestration time, the VNF’s Base Module MUST be deployed first, prior to any incremental modules.

As stated in (R-28980), (R-86926), and (R-91497), a VNF’s incremental module MAY be used for

  • initial VNF deployment only

  • scale out only

  • both deployment and scale out

As stated in (R-68122), a VNF’s incremental module MAY be deployed more than once, either during initial VNF deployment and/or scale out

As stated in (R-37028) and (R-13196), a VNF MUST be composed of one Base Module and MAY be composed of zero to many Incremental Modules.

ONAP also supports the concept of an optional, independently deployed Cinder volume via a separate Heat Orchestration Templates, referred to as a Cinder Volume Module. This allows the volume to persist after a VM (i.e., OS::Nova::Server) is deleted, allowing the volume to be reused on another instance (e.g., during a fail over activity).

The scope of a Cinder volume module, when it exists, must be 1:1 with a Base module or Incremental Module.

A VNF module (base, incremental, cinder) MAY support nested templates.

Requirement: R-610010 _images/arrow-right-circle.svg
target: VNF
keyword: MAY
introduced: el alto
validation_mode: none

A VNF’s Heat Orchestration Template’s Base Module MAY declare zero, one, or more than one OS::Nova::Server resource. A OS::Nova::Server MAY be created in the base module or a nested yaml file invoked by the base module.

Requirement: R-610020 _images/arrow-right-circle.svg
target: VNF
keyword: MAY
introduced: el alto
validation_mode: none

If a VNF’s Heat Orchestration Template’s Base Module contains two or more OS::Nova::Server resources (created in the base module itself and/or in a nested yaml file invoked by the base module), the OS::Nova::Server resources MAY define the same {vm-type} (as defined in R-01455) or MAY define different {vm-type}.

Note that

  • there is no constraint on the number of unique {vm-type} defined in the base module.

  • there is no constraint on the number of OS::Nova::Server resources that define the same {vm-type} in the base module.

  • if an OS::Nova::Server is created in a nested yaml file invoked by the base module, the nested yaml file MUST NOT contain more than one OS::Nova::Server resource (as defined in R-17528).

Requirement: R-610030 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: guilin
validation_mode: static

A VNF’s Heat Orchestration Template’s Incremental Module MUST declare

  • one or more OS::Nova::Server resources OR

  • one or more OS::Cinder::Volume resources.

An OS::Nova::Server MAY be created in the incremental module or a nested yaml file invoked by the incremental module.

An OS::Cinder::Volume MAY be created in the incremental module or a nested yaml file invoked by the incremental module.

Requirement: R-610040 _images/arrow-right-circle.svg
target: VNF
keyword: MAY
introduced: el alto
validation_mode: none

If a VNF’s Heat Orchestration Template’s Incremental Module contains two or more OS::Nova::Server resources, the OS::Nova::Server resources MAY define the same {vm-type} (as defined in R-01455) or MAY define different {vm-type}.

Note that

  • there is no constraint on the number of unique {vm-type} defined in the incremental module.

  • there is no constraint on the number of OS::Nova::Server resources that define the same {vm-type} in the incremental module.

  • if an OS::Nova::Server is created in a nested yaml file invoked by the incremental module, the nested yaml file MUST NOT contain more than one OS::Nova::Server resource (as defined in R-17528).

Requirement: R-610050 _images/arrow-right-circle.svg
target: VNF
keyword: MAY
introduced: el alto
validation_mode: none

The same {vm-type} for a VNF’s Heat Orchestration Template’s OS::Nova::Server resource (as defined in R-01455) MAY exist in the VNF’s Heat Orchestration Template’s Base Module (or invoked nested yaml file) and/or one or more of the VNF’s Heat Orchestration Template’s Incremental Modules (or invoked nested yaml file).

A shared Heat Resource is a resource that MAY be used by other Heat Resources either in the Base Module or an Incremental Module.

Requirement: R-61001 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: dublin
validation_mode: none

A shared Heat Orchestration Template resource is a resource that MUST be defined in the base module and will be referenced by one or more resources in one or more incremental modules.

The UUID of the shared resource (created in the base module) MUST be exposed by declaring a parameter in the outputs section of the base module.

For ONAP to provided the UUID value of the shared resource to the incremental module, the parameter name defined in the outputs section of the base module MUST be defined as a parameter in the parameters section of the incremental module.

ONAP will capture the output parameter name and value in the base module and provide the value to the corresponding parameter(s) in the incremental module(s).

When the shared resource needs to be referenced by a resource in an incremental module, the UUID of the shared resource must be exposed by declaring an ONAP Base Module Output Parameter.

Note that a Cinder volume is not a shared resource. A volume template must correspond 1:1 with a base module or incremental module.

An example of a shared resource is the resource OS::Neutron::SecurityGroup. Security groups are sets of IP filter rules that are applied to a VNF’s networking. The resource OS::Neutron::Port has a property security_groups which provides the security groups associated with port. The value of parameter(s) associated with this property must be the UUIDs of the resource(s) OS::Neutron::SecurityGroup.

Note: A Cinder volume is not considered a shared resource. A volume template must correspond 1:1 with a base template or add-on module template.

Suggested Patterns for Modular VNFs

There are numerous variations of VNF modularity. Below are two suggested usage patterns.

Option 1: Incremental Modules per VNFC type

  1. Base module contains only the shared resources.

  2. Group all VMs (e.g., VNFCs) of a given type (i.e. {vm-type}) into its own incremental module. That is, the VNF has an incremental module for each {vm-type}.

  3. For a given {vm-type} incremental module, the VNF may have

    1. One incremental module used for both initial turn up and re-used for scaling. This approach is used when the number of VMs instantiated will be the same for initial deployment and scaling.

    2. Two incremental modules, where one is used for initial turn up and one is used for scaling. This approach is used when the number of VMs instantiated will be different for initial deployment and scaling.

Option 2: Base VNF with Incremental Growth Modules

  1. Base module contains a complete initial VNF instance

  2. Incremental modules for incremental scaling units

    1. May contain VMs of multiple types in logical scaling combinations

    2. May be separated by VM type for multi-dimensional scaling

With no growth units, Option 2 is equivalent to the “One Heat Template per VNF” model.

Note that modularization of VNFs is not required. A single Heat Orchestration Template (a base module) may still define a complete VNF, which might be appropriate for smaller VNFs that do not have any scaling options.

Modularity Rules

There are some rules to follow when building modular VNF templates:

  1. All VNFs must have one Base VNF Module (template) that must be the first one deployed. The base template:

    1. Must include all shared resources (e.g., private networks, server groups, security groups)

    2. Must expose all shared resources (by UUID) as “outputs” in its associated Heat template (i.e., ONAP Base Module Output Parameters)

    3. May include initial set of VMs

    4. May be operational as a stand-alone “minimum” configuration of the VNF

  2. VNFs may have one or more incremental modules which:

    1. Defines additional resources that can be added to an existing VNF

    2. Must be complete Heat templates

      1. i.e. not snippets to be incorporated into some larger template

    3. Should define logical growth-units or sub-components of an overall VNF

    4. On creation, receives appropriate Base Module outputs as parameters

      1. Provides access to all shared resources (by UUID)

      2. VNFs may have one or more incremental modules which must not be dependent on other Add-On VNF Modules

    5. Multiple instances of an incremental Module may be added to the same VNF (e.g., incrementally grow a VNF by a fixed “add-on” growth units)

  3. Each VNF Module (base or incremental) may have (optional) an associated Cinder Volume Module (see Cinder Volumes)

    1. Volume modules must correspond 1:1 with a base module or incremental module

    2. A Cinder volume may be embedded within the base module or incremental module if persistence is not required

  4. Shared resource UUIDs are passed between the base module and incremental modules via Heat Outputs Parameters (i.e., Base Module Output Parameters)

    1. The output parameter name in the base must match the parameter name in the add-on module

VNF Modularity Examples

Example: Base Module creates SecurityGroup

A VNF has a base module, named base.yaml, that defines a OS::Neutron::SecurityGroup. The security group will be referenced by an OS::Neutron::Port resource in an incremental module, named INCREMENTAL_MODULE.yaml. The base module defines a parameter in the outputs:section named dns_sec_grp_id. dns_sec_grp_id is defined as a parameter in the incremental module. ONAP captures the UUID value of dns_sec_grp_id from the base module output statement and provides the value to the incremental module.

Note that the example below is not a complete Heat Orchestration Template. The {network-role} has been defined as oam to represent an oam network and the {vm-type} has been defined as dns.

base_MODULE.yaml

parameters:
. . .
resources:
  DNS_SECURITY_GROUP:
    type: OS::Neutron::SecurityGroup
    properties:
      description: vDNS security group
      name:
      str_replace:
        template: VNF_NAME_sec_grp_DNS
        params:
          VMF_NAME: {get_param: vnf_name}
      rules: [. . . . .
      ]
. . .
outputs:
  dns_sec_grp_id:
    description: UUID of DNS Resource SecurityGroup
    value: { get_resource: DNS_SECURITY_GROUP }

INCREMENTAL_MODULE.yaml

parameters:
  dns_sec_grp_id:
    type: string
    description: security group UUID
. . .

resources:
  dns_0_oam_0_port:
    type: OS::Neutron::Port
      properties:
        name:
          str_replace:
            template: VNF_NAME_dns_oam_port
            params:
              VNF_NAME: {get_param: vnf_name}
        network: { get_param: oam_net_name }
        fixed_ips: [{ "ip_address": { get_param: dns_oam_ip_0 }}]
        security_groups: [{ get_param: dns_sec_grp_id }]

Examples: Base Module creates an internal network

A VNF has a base module, named base_module.yaml, that creates an internal network. An incremental module, named incremental_module.yaml, will create a VM that will connect to the internal network. The base module defines a parameter in the out section named int_oam_net_id. int_oam_net_id is defined as a parameter in the incremental module. ONAP captures the UUID value of int_oam_net_id from the base module output statement and provides the value to the incremental module.

Note that the example below is not a complete Heat Orchestration Template. The {network-role} has been defined as oam to represent an oam network and the {vm-type} has been defined as lb for load balancer.

base.yaml

heat_template_version: 2013-05-23

resources:
  int_oam_network:
    type: OS::Neutron::Net
    properties:
      name: { }
. . .

outputs:
  int_oam_net_id:
  value: {get_resource: int_oam_network }

incremental.yaml

heat_template_version: 2013-05-23

parameters:
  int_oam_net_id:
    type: string
    description: ID of shared private network from Base template
  lb_name_0:
    type: string
    description: name for the add-on VM instance

resources:
  lb_server_0:
    type: OS::Nova::Server
    properties:
      name: {get_param: lb_name_0}
      networks:
        - port: { get_resource: get_resource: lb_0_int_oam_port_0  }
. . .
  lb_0_int_oam_port_0:
    type: OS::Neutron::Port
      properties:
      network: { get_param: int_oam_net_id }
...

ONAP Heat Cinder Volumes

Cinder Volumes are created with the heat resource OS::Cinder::Volume.

As stated in (R-46119), (R-90748), (R-03251), a VNF’s Heat Orchestration Template’s Resource OS::Cinder::Volume MAY be defined in a Base Module, Incremental Module, or Cinder Volume Module.

ONAP supports the independent deployment of a Cinder volume via separate Heat Orchestration Templates, the Cinder Volume module. This allows the volume to persist after VNF deletion so that they can be reused on another instance (e.g., during a failover activity).

A Base Module or Incremental Module may have a corresponding volume module. Use of separate volume modules is optional. A Cinder volume may be embedded within the Base Module or Incremental Module if persistence is not required.

If a VNF Base Module or Incremental Module has an independent volume module, the scope of volume templates must be 1:1 with Base module or Incremental module. A single volume module must create only the volumes required by a single Incremental module or Base module.

As stated in (R-11200), a VNF’s Cinder Volume Module, when it exists, MUST be 1:1 with a Base module or Incremental module. That is, A single volume module must create only the volumes required by a single Incremental module or Base module.

As stated in (R-30395), a VNF’s Cinder Volume Module MAY utilize nested heat.

As stated in (R-89913), a VNF’s Heat Orchestration Template’s Cinder Volume Module Output Parameter(s) MUST include the UUID(s) of the Cinder Volumes created in template, while others MAY be included.

As stated in (R-07443), a VNF’s Heat Orchestration Templates’ Cinder Volume Module Output Parameter’s name and type MUST match the input parameter name and type in the corresponding Base Module or Incremental Module.

A volume template must define outputs for each Cinder volume resource universally unique identifier (UUID) (i.e. ONAP Volume Template Output Parameters.

  • The VNF Incremental Module or Base Module must define input parameters that match each Volume output parameter (i.e., ONAP Volume Template Output Parameters).

    • ONAP will supply the volume template outputs automatically to the bases/incremental template input parameters.

  • Volume modules may utilize nested Heat templates.

Requirement: R-270358 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: casablanca
validation_mode: static

A VNF’s Heat Orchestration Template’s Cinder Volume Template MUST contain either

  • An OS::Cinder::Volume resource

  • An OS::Heat::ResourceGroup resource that references a Nested YAML file that contains an OS::Cinder::Volume resource

  • A resource that defines the property type as a Nested YAML file (i.e., static nesting) and the Nested YAML contains an OS::Cinder::Volume resource

Optional Property availability_zone
Requirement: R-25190 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD NOT
updated: casablanca

A VNF’s Heat Orchestration Template’s Resource OS::Cinder::Volume SHOULD NOT declare the property availability_zone.

If the property is used, the value MUST be enumerated in the environment file and must be set to nova, which is the default. There are no requirements on the parameter naming convention with the exception that the naming convention MUST NOT be the same as the OS::Nova::Server property availability_zone (i.e., availability_zone_{index}).

Optional Property volume_type

OpenStack supports multiple volume types. If the OS::Cinder::Volume optional property volume_type is not specified, the OpenStack default volume type is used. If a specific volume type is required, the property is used and the value MUST be enumerated in the environment file. There are no requirements on the parameter naming convention.

Cinder Volume Examples

Examples: Volume Template

A VNF has a Cinder volume module, named incremental_volume.yaml, that creates an independent Cinder volume for a VM in the module incremental.yaml. The incremental_volume.yaml defines a parameter in the output section, dns_volume_id_0 which is the UUID of the cinder volume. dns_volume_id_0 is defined as a parameter in incremental.yaml. ONAP captures the UUID value of dns_volume_id_0 from the volume module output statement and provides the value to the incremental module.

Note that the example below is not a complete Heat Orchestration Template. The {vm-type} has been defined as “dns”.

incremental_volume.yaml

parameters:
  vnf_name:
    type: string
  dns_volume_size_0:
    type: number
...

resources:
  dns_volume_0:
    type: OS::Cinder::Volume
    properties:
      name:
        str_replace:
          template: VNF_NAME_volume_0
          params:
            VNF_NAME: { get_param: vnf_name }
      size: {get_param: dns_volume_size_0}
...
outputs:
  dns_volume_id_0:
    value: {get_resource: dns_volume_0}
...

incremental.yaml

parameters:
  dns_server_0:
    type: string
  dns_volume_id_0:
    type: string
...

resources:
  dns_server_0:
    type: OS::Nova::Server
    properties:
      name: {get_param: dns_name_0}
      networks:
...
  dns_volume_attach_0:
    type: OS::Cinder::VolumeAttachment
    properties:
      instance_uuid: { get_resource: dns_server_0 }
      volume_id: { get_param: dns_volume_id_0 }

ONAP Heat Support of Environment Files

Requirement: R-599443 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: dublin
validation_mode: static

A parameter enumerated in a VNF’s Heat Orchestration Template’s environment file MUST be declared in the corresponding VNF’s Heat Orchestration Template’s YAML file’s parameters: section.

Note that this is an ONAP requirement. This is not required by OpenStack.

ONAP Heat Heat Template Constructs

Nested Heat Templates

ONAP supports nested Heat templates per the OpenStack specifications. Nested templates may be suitable for larger VNFs that contain many repeated instances of the same VM type(s). A common usage pattern is to create a nested template for each {vm-type} along with its supporting resources. The VNF module may then reference these component templates either statically by repeated definition or dynamically by using the resource OS::Heat::ResourceGroup.

Nested Heat Template Requirements

ONAP supports nested Heat Orchestration Templates.

As stated in Requirements (R-36582), (R-56721), and (R-30395), a Base Module, Incremental Module, and Cinder Volume Module may use nested heat.

Requirement: R-00228 _images/arrow-right-circle.svg
target: VNF
keyword: MAY
updated: casablanca

A VNF’s Heat Orchestration Template MAY reference the nested heat statically by repeated definition.

Requirement: R-01101 _images/arrow-right-circle.svg
target: VNF
keyword: MAY
updated: casablanca

A VNF’s Heat Orchestration Template MAY reference the nested heat dynamically using the resource OS::Heat::ResourceGroup.

A VNF’s Heat Orchestration Template must reference a Nested YAML file by name. The use of resource_registry in the VNF’s Heat Orchestration Templates Environment File must not be used (as stated in R-67231).

As stated in requirement R-99646, a VNF’s YAML files (i.e, Heat Orchestration Template files and Nested files) MUST have a unique name in the scope of the VNF.

Requirement: R-60011 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

A VNF’s Heat Orchestration Template MUST have no more than two levels of nesting.

Two levels of nesting is defined as follows: A base module, incremental module, or cinder volume module references a nested heat file either statically or by using the resource OS::Heat::ResourceGroup. The referenced YAML heat file is the first level of nested heat. If first level nested YAML file references a nested heat file, that file is the second level of nested heat.

Requirement: R-17528 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
updated: frankfurt
validation_mode: static

A VNF’s Heat Orchestration Template’s first level Nested YAML file MUST NOT contain more than one OS::Nova::Server resource. A VNF’s Heat Orchestration Template’s second level Nested YAML file MUST NOT contain any heat resources.

Requirement: R-708564 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
introduced: dublin
validation_mode: static

If a VNF’s Heat Orchestration Template’s resource invokes a nested YAML file, either statically or dynamically (via OS::Heat::ResourceGroup), the names of the parameters associated with the following resource properties MUST NOT change.

  • OS::Nova::Server property flavor

  • OS::Nova::Server property image

  • OS::Nova::Server property name

  • OS::Nova::Server property metadata key value vnf_id

  • OS::Nova::Server property metadata key value vf_module_id

  • OS::Nova::Server property metadata key value vnf_name

  • OS::Nova::Server property metadata key value vf_module_name

  • OS::Nova::Server property metadata key value vm_role

  • OS::Nova::Server property metadata key value vf_module_index

  • OS::Nova::Server property metadata key value workload_context

  • OS::Nova::Server property metadata key value environment_context

  • OS::Neutron::Port property fixed_ips, map property ip_address

  • OS::Neutron::Port property fixed_ips, map property subnet

  • OS::Neutron::Port property allowed_address_pairs, map property ip_address

  • OS::Neutron::Port property network

  • OS::ContrailV2::VirtualMachineInterface property virtual_network_refs

  • OS::ContrailV2::VirtualMachineInterface property virtual_machine_interface_allowed_address_pairs, map property virtual_machine_interface_allowed_address_pairs_allowed_address_pair, virtual_machine_interface_allowed_address_pairs_allowed_address_pair_ip , virtual_machine_interface_allowed_address_pairs_allowed_address_pair_ip_ip_prefix

  • OS::ContrailV2::InstanceIP property instance_ip_address

  • OS::ContrailV2::InstanceIP property subnet_uuid

Note that the parameters associated with properties not listed in R-708564 may change when past into a nested YAML file. For example, OS::Nova::Server property availability_zone.

Requirement R-708564 was introduced with Generic Resource API (GR-API). GR-API creates the new VNFC Object. SDN-C matches the {vm-type} in the OS::Nova::Server resource in the nested YAML file to the corresponding nfc_naming_code. If the {vm-type} name changes when the parameter names are passed into the nested YAML file, SDN-C will not be able to match the {vm-type} to the nfc_naming_code, breaking the assignment logic and ONAP assigns a default value (i.e., “DEFAULT”). Instantiation will succeed with the incorrect VNFC Object (i.e, contains the DEFAULT value). However, the default VNFC object will cause issues for other ONAP applications/features.

Requirement: R-11041 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

All parameters defined in a VNFs Nested YAML file MUST be passed in as properties of the resource calling the nested yaml file.

Requirement: R-90022 _images/arrow-right-circle.svg
target: VNF
keyword: MAY
updated: casablanca

A VNF’s Nested YAML file MAY be invoked more than once by a VNF’s Heat Orchestration Template.

Requirement: R-04344 _images/arrow-right-circle.svg
target: VNF
keyword: MAY
updated: casablanca

A VNF’s Nested YAML file MAY be invoked by more than one of a VNF’s Heat Orchestration Templates (when the VNF is composed of two or more Heat Orchestration Templates).

Note that as stated in requirement R-00011, a VNF’s Heat Orchestration Template’s Nested YAML file’s parameter’s SHOULD NOT have a parameter constraint defined.

If a VNF’s Heat Orchestration Template’s nested YAML file is required to expose a resource property to the invoking Heat OrchestrationTemplate, an outputs: statement must be used in the nested YAML file. The invoking template references the property by using the intrinsic function get_attr that targets the resource invoking the nested YAML file and references the parameter defined in the outputs section.

Nested Heat Template Example: Static

incremental.yaml

resources:
  dns_server_0:
    type: nested.yaml
    properties:
      dns_image_name: { get_param: dns_image_name }
      dns_flavor_name: { get_param: dns_flavor_name }
      availability_zone_0: { get_param: availability_zone_0 }
      DNS_shared_sec_grp_id: { get_param: DNS_shared_sec_grp_id }
      oam_protected_net_id: { get_param: oam_protected_net_id }
      dns_oam_ip_0: { get_param: dns_oam_ip_0 }
      dns_name_0: { get_param: dns_name_0 }
      vnf_name: { get_param: vnf_name }
      vnf_id: { get_param: vnf_id }
      vf_module_id: {get_param: vf_module_id}

nested.yaml

dns_0_oam_protected_port_0:
  type: OS::Neutron::Port
  properties:
    name:
      str_replace:
        template: VNF_NAME_dns_oam_port
        params:
          VNF_NAME: {get_param: vnf_name}
    network: { get_param: oam_protected_net_id }
    fixed_ips: [{ "ip_address": { get_param: dns_oam_ip_0 }}]
    security_groups: [{ get_param: DNS_shared_sec_grp_id }]
dns_server_0:
  type: OS::Nova::Server
  properties:
    name: { get_param: dns_names }
    image: { get_param: dns_image_name }
    flavor: { get_param: dns_flavor_name }
    availability_zone: { get_param: availability_zone_0 }
    networks:
    - port: { get_resource: ns_0_oam_protected_port_0 }
    metadata:
      vnf_id: { get_param: vnf_id }
      vf_module_id: { get_param: vf_module_id }
      vnf_name {get_param: vnf_name }
Use of Heat ResourceGroup

The OS::Heat::ResourceGroup is a useful Heat element for creating multiple instances of a given resource or collection of resources. Typically, it is used with a nested Heat template to create, for example, a set of identical OS::Nova::Server resources plus their related OS::Neutron::Port resources via a single resource in a master template.

OS::Heat::ResourceGroup may be used to simplify the structure of a Heat template that creates multiple instances of the same VM type.

However, there are important caveats to be aware of:

OS::Heat::ResourceGroup does not deal with structured parameters (comma-delimited-list and json) as one might typically expect. In particular, when using a list-based parameter, where each list element corresponds to one instance of the ResourceGroup, it is not possible to use the intrinsic “loop variable” %index% in the OS::Heat::ResourceGroup definition.

For instance, the following is not valid Heat for OS::Heat::ResourceGroup:

type: OS::Heat::ResourceGroup
properties:
    . . .
    resource_def:
      type: my_nested_vm_template.yaml
      properties:
        name: {get_param: [vm_name_list, "%index%"]}

Although this appears to use the nth entry of the vm_name_list list for the nth element of the OS::Heat::ResourceGroup, it will in fact result in a Heat exception. When parameters are provided as a list (one for each element of a OS::Heat::ResourceGroup), you must pass the complete parameter to the nested template along with the current index as separate parameters.

Below is an example of an acceptable Heat Syntax for a ResourceGroup:

type: OS::Heat::ResourceGroup
properties:
  . . .
  resource_def:
    type: my_nested_vm_template.yaml
    properties:
      names: {get_param: vm_name_list}
      index: "%index%"

You can then reference within the nested template as:

{ get_param: [names, {get_param: index} ] }

OS::Heat::ResourceGroup Property count
Requirement: R-50011 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

A VNF’s Heat Orchestration Template’s OS::Heat::ResourceGroup property count MUST be enumerated in the VNF’s Heat Orchestration Template’s Environment File and MUST be assigned a value.

This is required for ONAP to build the TOSCA model for the VNF.

type: OS::Heat::ResourceGroup
properties:
  count: { get_param: count }
  index_var: index
  resource_def:
    type: my_nested_vm_template.yaml
    properties:
      names: {get_param: vm_name_list}
      index: index
Availability Zone and ResourceGroups

The resource OS::Heat::ResourceGroup and the OS::Nova::Server property availability_zone parameter has been an “issue” with a few VNFs since ONAP only supports the availability_zone parameter as a string and not as a comma_delimited_list. This makes it difficult to use a OS::Heat::ResourceGroup to create OS::Nova::Server in more than one availability zone.

There are numerous solutions to this issue. Below are two suggested usage patterns.

Option 1: create a comma delimited list in the OS::Heat::ResourceGroup. In the resource OS::Heat::ResourceGroup, create a comma_delimited_list property availability_zones by concatenating the string availability_zone parameters.

<resource name>:
  type: OS::Heat::ResourceGroup
  properties:
    count: { get_param: node_count }
    index_var: index
    resource_def:
      type: nested.yaml
      properties:
        index: index
        availability_zones: [ { get_param: availability_zone_0 }, { get_param: availability_zone_1 } ]

In the nested heat

parameters:
  availability_zones:
    type: comma_delimited_list
    description:

resources:
  servers:
    type: OS::Nova::Server
    properties:
      name: { get_param: [ dns_names, get_param: index ] }
      image: { get_param: dns_image_name }
      flavor: { get_param: dns_flavor_name }
      availability_zone: { get_param: [ availability_zones, get_param: index ] }

Option 2: Create a CDL by passing the availability zone parameter into a nested heat template. An example is provided below.

base.yaml

availability_zone_list:
   type: az_list_generate.yaml
   properties:
     availability_zone_0: { get_param: availability_zone_0 }
     availability_zone_1: { get_param: availability_zone_1 }

  create_virtual_machines:
    type: OS::Heat::ResourceGroup
    properties:
      count: { get_param: count }
      index_var: $INDEX
      resource_def:
        type: nest_file.yaml
        properties:
          index: $INDEX
          availability_zone_0 : { get_attr: [availability_zone_list, general_zones ] }
          . . .

az_list_generate.yaml

parameters:
  availability_zone_0:
    type: string
    description: availability zone 0

  availability_zone_1:
    type: string
    description: availability zone 1

outputs:

  general_zones:
    value: [
      { get_param: availability_zone_0 },
      { get_param: availability_zone_1 },
      { get_param: availability_zone_0 },
      { get_param: availability_zone_1 },
      { get_param: availability_zone_0 },
      { get_param: availability_zone_1 }
]
Nested Heat Template Example: OS::Heat::ResourceGroup

In this example, ocgapp_volume.yml creates volumes using a OS::Heat::ResourceGroup that uses nested heat by calling ocgapp_nested_volume.yml. ocgapp_volume.yml has an outputs: parameter ocgapp_volume_ids which is declared a input parameter of type: json in ocgapp_volume.yml.

This is an example of requirement (R-07443), where a VNF’s Heat Orchestration Templates’ Cinder Volume Module Output Parameter’s name and type MUST match the input parameter name and type in the corresponding Base Module or Incremental Module unless the Output Parameter is of the type comma_delimited_list, then the corresponding input parameter MUST be declared as type json.

ocgapp_volume.yml

heat_template_version: 2014-10-16

description: Template for the volumes

parameters:
  vnf_name:
    type: string
    label: OCG VNF Name
    description: OCG VNF Name
  ocgapp_volume_size_0:
    type: number
    label: Cinder volume 1 size
    description: the size of the Cinder volume
    constraints:
    - range: { min: 100, max: 400 }
  ocgapp_volume_type_0:
    type: string
    label: app vm 1 volume type
    description: the name of the target volume backend for the first OCG APP
  volume_count:
    type: number
    label: volume count
    description: number of volumes needed

resources:
  ocgapp_volume_resource_group:
    type: OS::Heat::ResourceGroup
    properties:
      count: {get_param: volume_count}
      index_var: index
      resource_def:
        type: ocgapp_nested_volume.yml
        properties:
          index: index
          size: {get_param: ocgapp_volume_size_0}
          volume_type: {get_param: ocgapp_volume_type_0}
          vnf_name: {get_param: vnf_name}

outputs:
  ocgapp_volume_ids:
  description: ocgapp volume ids
  value: {get_attr: [ocgapp_volume_resource_group, ocgapp_volume_id_0]}

ocgapp_nested_volume.yml

heat_template_version: 2014-10-16

description: nested heat

parameters:
  index:
    type: number
    label: Volume Index
    description: number of volumes to spin up
  size:
    type: number
    label: Volume Size
    description: size of the cinder volumes
  volume_type:
    type: string
    label: Volume Type
    description: type of cinder volumes
  vnf_name:
    type: string
    label: VNF Name
    description: vnf name

resources:
  ocgapp_volume_0:
    type: OS::Cinder::Volume
    properties:
      size: {get_param: size}
      volume_type: {get_param: volume_type}
      name:
        str_replace:
          template: VF_NAME_STACK_NAME_INDEX
          params:
            VF_NAME: { get_param: vnf_name }
            STACK_NAME: { get_param: 'OS::stack_name' }
            INDEX: {get_param: index}

outputs:
  ocgapp_volume_id_0:
  description: the ocgapp volume uuid
  value: {get_resource: ocgapp_volume_0}

Below is a screen shot of parameter ocgapp_volume_ids from the OpenStack Horizon GUI showing the output.

_images/heat_picture3.png

The heat template below is a partial heat template,

ocgapp.yml

heat_template_version: 2014-10-16

#file version 1.0
description: OCG Apps template

parameters:
  ocgapp_volume_ids:
    type: json
    description: Unique IDs for volumes

resources:
  ocgapp_server_0:
    type: OS::Nova::Server
    properties:
  . . . .
  ocgapp_server_1:
    type: OS::Nova::Server
    properties:
  . . . .
  ocgapp_volume_attachment_0:
    type: OS::Cinder::VolumeAttachment
    properties:
      volume_id: {get_param: [ocgapp_volume_ids, 0]}
      instance_uuid: {get_resource: ocgapp_server_0}
  ocgapp_volume_attachment_1:
    type: OS::Cinder::VolumeAttachment
    properties:
      volume_id: {get_param: [ocgapp_volume_ids, 1]}
      instance_uuid: {get_resource: ocgapp_server_1}
External References

Heat templates must not reference any HTTP-based resource definitions, any HTTP-based nested configurations, or any HTTP-based environment files.

  • During orchestration, ONAP must not retrieve any such resources from external/untrusted/unknown sources.

  • VNF images must not contain external references in user-data or other configuration/operational scripts that are specified via Heat or encoded into the VNF image itself.

Note: HTTP-based references are acceptable if the HTTP-based reference is accessing information utilizing the VM private/internal network.

Note that Namespaces in XML (defined at http://www.w3.org/TR/2009/REC-xml-names-20091208/) are allowed if the Heat Orchestration Template is describing and storing software configuration information. An XML namespace is identified by a URI reference. A Uniform Resource Identifier (URI) is a string of characters which identifies an Internet Resource. The most common URI is the Uniform Resource Locator (URL) which identifies an Internet domain address. Another, not so common type of URI is the Universal Resource Name (URN). The namespace URI is not used by XML the parser to look up information. The purpose of using an URI is to give the namespace a unique name.

Heat Files Support (get_file)

A VNF’s Heat Orchestration Template may contain the inclusion of text files containing scripts or configuration files. The get_file intrinsic function returns the content of a file into a Heat Orchestration Template.

The support for the get_file intrinsic function in ONAP is subject to the following limitations:

Requirement: R-76718 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

If a VNF’s Heat Orchestration Template uses the intrinsic function get_file, the get_file target MUST be referenced in the Heat Orchestration Template by file name.

The get_file target files are on-boarded to SDC in the same zip file that contains the VNF’s complete Heat Orchestration Template. See requirement R-511776.

Requirement: R-41888 _images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
updated: casablanca
validation_mode: static

A VNF’s Heat Orchestration Template intrinsic function get_file MUST NOT utilize URL-based file retrieval.

Requirement: R-05050 _images/arrow-right-circle.svg
target: VNF
keyword: MAY
updated: casablanca

A VNF’s Heat Orchestration Templates intrinsic function get_file <content key> MAY be used:

  • more than once in a VNF’s Heat Orchestration Template

  • in two or more of a VNF’s Heat Orchestration Templates

  • in a VNF’s Heat Orchestration Templates nested YAML file

Key Pairs

When Nova Servers are created via Heat templates, they may be passed a “keypair” which provides an ssh key to the ‘root’ login on the newly created VM. This is often done so that an initial root key/password does not need to be hard-coded into the image.

Key pairs are unusual in OpenStack, because they are the one resource that is owned by an OpenStack User as opposed to being owned by an OpenStack Tenant. As a result, they are usable only by the User that created the keypair. This causes a problem when a Heat template attempts to reference a keypair by name, because it assumes that the keypair was previously created by a specific ONAP user ID.

When a keypair is assigned to a server, the SSH public-key is provisioned on the VMs at instantiation time. They keypair itself is not referenced further by the VM (i.e. if the keypair is updated with a new public key, it would only apply to subsequent VMs created with that keypair).

Due to this behavior, the recommended usage of keypairs is in a more generic manner which does not require the pre-requisite creation of a keypair. The Heat should be structured in such a way as to:

  • Pass a public key as a parameter value instead of a keypair name

  • Create a new keypair within the VNF Heat templates (in the base module) based on an existing public key for use within that VNF

By following this approach, the end result is the same as pre-creating the keypair using the public key – i.e., that public key will be provisioned in the new VM. However, this recommended approach also makes sure that a known public key is supplied (instead of having OpenStack generate a public/private pair to be saved and tracked outside of ONAP). It also removes any access/ownership issues over the created keypair.

The public keys may be enumerated as a VNF Orchestration Constant in the environment file (since it is public, it is not a secret key), or passed at run-time as instance-specific parameters. ONAP will never automatically assign a public/private key pair.

Requirement: R-100380 _images/arrow-right-circle.svg
target: VNF
keyword: SHOULD
introduced: dublin
validation_mode: none

If a VNF requires the use of an SSH key created by OpenStack, the VNF Heat Orchestration Template SHOULD create the OS::Nova::Keypair in the base module, and expose the public key as an output value.

This allows re-use of the key by ONAP when triggering scale out, recovery, or other day 1 operations.

Example (create keypair with an existing ssh public-key for {vm-type} of lb (for load balancer)):

parameters:
  vnf_name:
    type: string
  lb_ssh_public_key:
    type: string

resources:
  lb_keypair_0:
    type: OS::Nova::Keypair
    properties:
      name:
        str_replace:
          template: VNF_NAME_key_pair
          params:
            VNF_NAME: { get_param: vnf_name }
      public_key: {get_param: lb_ssh_public_key}
      save_private_key: false
Security Groups

OpenStack allows a tenant to create Security groups and define rules within the security groups.

Security groups, with their rules, may either be created in the Heat Orchestration Template or they can be pre-created in OpenStack and referenced within the Heat template via parameter(s). There can be a different approach for security groups assigned to ports on internal (intra-VNF) networks or external networks (inter-VNF). Furthermore, there can be a common security group across all VMs for a specific network or it can vary by VM (i.e., {vm-type}) and network type (i.e., {network-role}).

Anti-Affinity and Affinity Rules

Anti-affinity or affinity rules are supported using normal OpenStack OS::Nova::ServerGroup resources. Separate ServerGroups are typically created for each VM type to prevent them from residing on the same host, but they can be applied to multiple VM types to extend the affinity/anti-affinity across related VM types as well.

Example:

In this example, the {network-role} has been defined as oam to represent an oam network and the {vm-type} have been defined as lb for load balancer and db for database.

resources:
  db_server_group:
    type: OS::Nova::ServerGroup
    properties:
      name:
        str_replace:
          params:
            $vnf_name: {get_param: vnf_name}
          template: $vnf_name-server_group1
      policies:
      - anti-affinity
  lb_server_group:
    type: OS::Nova::ServerGroup
    properties:
      name:
        str_replace:
          params:
            $vnf_name: {get_param: vnf_name}
          template: $vnf_name-server_group2
      policies:
      - affinity
  db_server_0:
    type: OS::Nova::Server
    properties:
      ...
      scheduler_hints:
      group: {get_resource: db_server_group}
  db_server_1:
    type: OS::Nova::Server
    properties:
      ...
      scheduler_hints:
      group: {get_resource: db_server_group}
  lb_server_0:
    type: OS::Nova::Server
    properties:
      ...
      scheduler_hints:
      group: {get_resource: lb_server_group}
Resource Data Synchronization

For cases where synchronization is required in the orchestration of Heat resources, two approaches are recommended:

  • Standard Heat depends_on property for resources

    • Assures that one resource completes before the dependent resource is orchestrated.

    • Definition of completeness to OpenStack may not be sufficient (e.g., a VM is considered complete by OpenStack when it is ready to be booted, not when the application is up and running).

  • Use of Heat Notifications

    • Create OS::Heat::WaitCondition and OS::Heat::WaitConditionHandle resources.

    • Pre-requisite resources issue wc_notify commands in user_data.

    • Dependent resource define depends_on in the OS::Heat::WaitCondition resource.

Example: “depends_on” case

In this example, the {network-role} has been defined as oam to represent an oam network and the {vm-type} has been defined as oam to represent an oam server.

resources:
  oam_server_01:
    type: OS::Nova::Server
    properties:
      name: {get_param: [oam_names, 0]}
      image: {get_param: oam_image_name}
      flavor: {get_param: oam_flavor_name}
      availability_zone: {get_param: availability_zone_0}
      networks:
      - port: {get_resource: oam01_port_0}
      - port: {get_resource: oam01_port_1}
      user_data:
      scheduler_hints: {group: {get_resource: oam_servergroup}}
      user_data_format: RAW
  oam_01_port_0:
    type: OS::Neutron::Port
    properties:
      network: {get_resource: oam_net_name}
      fixed_ips: [{"ip_address": {get_param: [oam_oam_net_ips, 1]}}]
      security_groups: [{get_resource: oam_security_group}]
  oam_01_port_1:
    type: OS::Neutron::Port
    properties:
      network: {get_param: oam_net_name}
      fixed_ips: [{"ip_address": {get_param: [oam_oam_net_ips, 2]}}]
      security_groups: [{get_resource: oam_security_group}]
  oam_volume_attachment_0:
    type: OS::Cinder::VolumeAttachment
    depends_on: oam_server_01
    properties:
      volume_id: {get_param: oam_vol_1}
      mountpoint: /dev/vdb
      instance_uuid: {get_resource: oam_server_01}

ONAP Heat High Availability

VNF/VM parameters may include availability zone IDs for VNFs that require high availability.

The Heat must comply with the following requirements to specific availability zone IDs:

  • The Heat template should spread Nova resources across the availability zones as desired

ONAP Heat Post Orchestration & VNF Configuration

Heat templates should contain a minimum amount of post-orchestration configuration data. For instance, do not embed complex user-data scripts in the template with large numbers of configuration parameters to the Heat template.

  • VNFs may provide configuration APIs for use after VNF creation. Such APIs will be invoked via application and/or SDN controllers.

Note: It is important to follow this convention to the extent possible even in the short-term as of the long-term direction.

VNFM Driver Development Steps

Refer to the ONAP documentation for VNF Provider instructions on integrating vendor-specific VNFM adaptors with VF-C. The VNF driver development steps are highlighted below.

1. Use the VNF SDK tools to design the VNF with TOSCA models to output the VNF TOSCA package. Using the VNF SDK tools, the VNF package can be validated and tested.

2. The VNF Provider supplies a vendor-specific VNFM driver in ONAP, which is a microservice providing a translation interface from VF-C to the vendor-specific VNFM. The interface definitions of vendor-specific VNFM adaptors are supplied by the VNF Providers themselves.

Creating Vendor-Specific VNFM Adaptor Microservices

VNFs can be managed by vendor-specific VNFMs. To add a vendor-specific VNFM to ONAP, a vendor-specific VNFM adaptor is added to ONAP implementing the interface of the vendor-specific VNFM.

A vendor-specific VNFM adaptor is a microservice with a unique name and an appointed port. When started up, the vendor-specific VNFM adaptor microservice is automatically registered to the Microservices Bus (MSB). The following RESTful example describes the scenario of registering a vendor-specific VNFM adaptor to MSB:

POST /api/microservices/v1/services
{
    "serviceName": "catalog",
    "version": "v1",
    "url": "/api/catalog/v1",
    "protocol": "REST",
    "visualRange": "1",
    "nodes": [
    {
        "ip": "10.74.56.36",
        "port": "8988",
        "ttl": 0
    }
    ]
}

Infrastructure Requirements

This release of the requirements is targeted for those implementations that consist of Network Clouds: Vanilla OpenStack (based on Ocata) and commercial Clouds for example: OpenStack (including Titanium - Mitaka from Wind River and VIO - Ocata from VMware). Future versions of ONAP are envisioned to include other targeted cloud infrastructure implementations, for example, on-premise private cloud, public cloud, or hybrid cloud implementations, and related network backends, e.g. Microsoft Azure et al.

ONAP Management Requirements

Service Design

This section, Service Design, has been left intentionally blank. It is out-of-scope for the VNF Requirements project for this release and no numbered requirements are expected. Content may be added in future updates of this document.

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

Requirement: R-66070 _images/arrow-right-circle.svg
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.

Requirement: R-69565 _images/arrow-right-circle.svg
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.

Requirement: R-00156 _images/arrow-right-circle.svg
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).

Requirement: R-00068 _images/arrow-right-circle.svg
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.

Requirement: R-12678 _images/arrow-right-circle.svg
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.

Requirement: R-84366 _images/arrow-right-circle.svg
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.

Requirement: R-36280 _images/arrow-right-circle.svg
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.

Requirement: R-98617 _images/arrow-right-circle.svg
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.

Requirement: R-22346 _images/arrow-right-circle.svg
target: VNF or PNF PROVIDER
keyword: MUST
introduced: casablanca
updated: guilin
validation_mode: static

The VNF or PNF Provider MUST provide VES Event Registration for all VES events provided by that VNF or PNF.

Requirement: R-384337 _images/arrow-right-circle.svg
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.

Requirement: R-025941 _images/arrow-right-circle.svg
target: VNF or PNF PROVIDER
keyword: MUST
updated: frankfurt
impacts: DCAE,Documentation,Integration,SDC
validation_mode: static

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

Requirement: R-816745 _images/arrow-right-circle.svg
target: VNF or PNF PROVIDER
keyword: MUST
introduced: dublin
updated: frankfurt
impacts: DCAE,Documentation,Integration,SDC
validation_mode: static

THe VNF or PNF PROVIDER MUST provide PM Meta Data (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

Requirement: R-89571 _images/arrow-right-circle.svg
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
Requirement: R-30278 _images/arrow-right-circle.svg
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
Requirement: R-13390 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

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

Requirement: R-18525 _images/arrow-right-circle.svg
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
Requirement: R-75608 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

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

Requirement: R-16777 _images/arrow-right-circle.svg
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.

Requirement: R-46567 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

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

Requirement: R-16065 _images/arrow-right-circle.svg
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

Requirement: R-22888 _images/arrow-right-circle.svg
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.

Requirement: R-01556 _images/arrow-right-circle.svg
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.

Requirement: R-16875 _images/arrow-right-circle.svg
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.

Requirement: R-35960 _images/arrow-right-circle.svg
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.

Requirement: R-42018 _images/arrow-right-circle.svg
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 ) and for the overall VNF or PNF.

Requirement: R-01478 _images/arrow-right-circle.svg
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.

Requirement: R-73560 _images/arrow-right-circle.svg
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.

Requirement: R-90632 _images/arrow-right-circle.svg
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.

Requirement: R-86235 _images/arrow-right-circle.svg
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.

Requirement: R-33904 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

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

Requirement: R-53598 _images/arrow-right-circle.svg
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.

Requirement: R-69877 _images/arrow-right-circle.svg
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.

Requirement: R-22680 _images/arrow-right-circle.svg
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.

Requirement: R-33694 _images/arrow-right-circle.svg
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.

Requirement: R-56815 _images/arrow-right-circle.svg
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).

Requirement: R-48596 _images/arrow-right-circle.svg
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

Requirement: R-35851 _images/arrow-right-circle.svg
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.

Requirement: R-97102 _images/arrow-right-circle.svg
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.

Requirement: R-20204 _images/arrow-right-circle.svg
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.

Requirement: R-44896 _images/arrow-right-circle.svg
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.

Requirement: R-55802 _images/arrow-right-circle.svg
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.

Requirement: R-26881 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: dublin

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

Requirement: R-96634 _images/arrow-right-circle.svg
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

Requirement: R-43958 _images/arrow-right-circle.svg
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.

Requirement: R-04298 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: dublin

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

Requirement: R-58775 _images/arrow-right-circle.svg
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.

Requirement: R-85653 _images/arrow-right-circle.svg
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.

Requirement: R-40827 _images/arrow-right-circle.svg
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.

Requirement: R-44569 _images/arrow-right-circle.svg
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.

Requirement: R-13613 _images/arrow-right-circle.svg
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.

Requirement: R-27511 _images/arrow-right-circle.svg
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.

Requirement: R-85991 _images/arrow-right-circle.svg
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.

Requirement: R-47849 _images/arrow-right-circle.svg
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, 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.

Configuration Management

The protocol used to communicate with VNF or PNF for life cycle management (LCM) operations are NETCONF, Ansible, Chef, and REST. A VNF or PNF shall support at least one of communication protocols as specified in the requirement R-305645.

Requirement: R-305645 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
introduced: frankfurt

The VNF or PNF MUST support configuration management including life cycle management (LCM) using at least one of the following protocols a)NETCONF/YANG, b)Ansible and c)Chef.

Since Frankfurt release, SO building blocks can use either APPC client or CDS client for life cycle management (LCM) operations. The associated API is either APPC/SDN-C LCM API or CDS self-service API. A VNF or PNF must support LCM operations that using either of two APIs. The selection of which API to use for LCM operations for a given PNF/VNF type is defined in design time by the service designer.

The requirements for supporting of SDN-C/APPC LCM API for LCM operations are documented in section 7.3.1.

Controller Interactions With VNF or PNF

This section is not applicable to LCM operations using CDS self-service API.

APPC/SDN-C expose a northbound API to clients (such as SO) in order for the clients to initiate an activity (aka command) on a VNF or PNF. APPC/SDN-C interact with VNFs or PNFs 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 or PNF. 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 or PNF’s, unless The commands below are expected to be supported on all VNF or PNF’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 APPC/SDN-C itself or depend upon network cloud components for implementation (thus, these actions do not put any special requirement on the VNF or PNF provider).

The commands allow for parametric data to be passed from APPC/SDN-C to the VNF or PNF 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 APPC/SDN-C client is requesting that a post-instantiation configuration be applied to the target VNF or PNF. After the Configure action is completed, the VNF or PNF instance should be ready for service. Note that customer specific configurations may need to be applied using the ConfigModify action. This command requires exclusive access rights of the VNF or PNF.

ConfigModify: The APPC client is requesting a configuration update to a subset of the total configuration parameters of an VNF or PNF or to apply customer specific configurations. The configuration update is typically done while the VNF or PNF is in service and should not disrupt traffic. This command requires exclusive access rights of the VNF or PNF.

ConfigBackup: The APPC client is requesting a backup of the configuration parameters where the parameters are stored on the VNF or PNF. 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 or PNF is not in service (i.e., in a maintenance state). When the ConfigBackup command is executed, the current VNF or PNF configuration parameters are saved in storage that is preserved (if there is an existing set of backed up parameters, they are overwritten). This command requires exclusive access rights of the VNF or PNF.

ConfigRestore: The APPC client is requesting a restore action of the configuration parameters to the VNF or PNF 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 or PNF needs to be rolled back to the prior configuration. When the ConfigRestore command is executed, the VNF or PNF configuration parameters which were backed to persistent preserved storage are applied to the VNF or PNF (replacing existing parameters). The ConfigRestore is typically done while the VNF or PNF is not in service (i.e., in a maintenance state). This command requires exclusive access rights of the VNF or PNF.

ConfigScaleOut: The APPC/SDN-C 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 to support manual Scale Out and will be extended to support Auto ScaleOut in Casablanca release. This command requires exclusive access rights of the VNF.

Audit: The APPC client is requesting that the current (last known configuration update) is audited against the running configuration on the VNF (Openstack).

Requirement: R-20741 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

The VNF or PNF MUST support APPC/SDN-C Configure command.

Requirement: R-19366 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

The VNF or PNF MUST support APPC ConfigModify command.

Requirement: R-32981 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

The VNF or PNF MUST support APPC ConfigBackup command.

Requirement: R-48247 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

The VNF or PNF MUST support APPC ConfigRestore command.

Requirement: R-94084 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

The VNF or PNF MUST support APPC/SDN-C ConfigScaleOut command.

Requirement: R-56385 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

The VNF or PNF MUST support APPC Audit command.

Notes On Command Support Using APPC/SDN-C Southbound Protocols

APPC/SDN-C are designed to support a standard set of protocols in order to communicate with the VNF or PNF instance. The supported protocols are NETCONF, Ansible, Chef, and REST.

NETCONF and REST require the VNF or PNF 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 APPC/SDN-C (northbound) and the VNF or PNF 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

APPC/SDN-C and their Adapters utilize device YANG model and NETCONF APIs to make the required changes in the VNF or PNF state and configuration. The VNF or PNF providers must provide the Device YANG model and NETCONF server supporting NETCONF APIs to comply with target ONAP and industry standards.

VNF or PNF Configuration via NETCONF Requirements
Configuration Management
Requirement: R-88026 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

The VNF or PNF MUST include a NETCONF server enabling runtime configuration and lifecycle management capabilities.

Requirement: R-95950 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

The VNF or PNF MUST provide a NETCONF interface fully defined by supplied YANG models for the embedded NETCONF server.

NETCONF Server Requirements
Requirement: R-73468 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: honolulu

The VNF 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 if VNF is heat based.

Requirement: R-90007 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

The VNF or PNF MUST implement the protocol operation: close-session() - Gracefully close the current session.

Requirement: R-70496 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: honolulu

The VNF or PNF MUST implement the protocol operation: commit(confirmed, confirm-timeout) - Commit candidate configuration data store to the running configuration if “:candidate” is supported.

Requirement: R-18733 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: honolulu

The VNF or PNF MUST implement the protocol operation: discard-changes() - Revert the candidate configuration data store to the running configuration if “:candidate” is supported.

Requirement: R-44281 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

The VNF or PNF MUST implement the protocol operation: edit-config(target, default-operation, test-option, error-option, config) - Edit the target configuration data store by merging, replacing, creating, or deleting new config elements.

Requirement: R-60106 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

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

Requirement: R-29488 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

The VNF or PNF MUST implement the protocol operation: get-config(source, filter - Retrieve a (filtered subset of a) configuration from the configuration data store source.

Requirement: R-11235 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

The VNF or PNF MUST implement the protocol operation: kill-session(session- Force the termination of session.

Requirement: R-02597 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

The VNF or PNF MUST implement the protocol operation: lock(target) - Lock the configuration data store target.

Requirement: R-96554 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

The VNF or PNF MUST implement the protocol operation: unlock(target) - Unlock the configuration data store target.

Requirement: R-29324 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: SHOULD
updated: dublin

The VNF or PNF SHOULD implement the protocol operation: copy-config(target, source) - Copy the content of the configuration data store source to the configuration data store target.

Requirement: R-88031 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: SHOULD
updated: dublin

The VNF or PNF SHOULD implement the protocol operation: delete-config(target) - Delete the named configuration data store target.

Requirement: R-97529 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: SHOULD
updated: dublin

The VNF or PNF SHOULD implement the protocol operation: get-schema(identifier, version, format) - Retrieve the YANG schema.

Requirement: R-62468 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

The VNF or PNF MUST allow all configuration data to be edited through a NETCONF <edit-config> operation. Proprietary NETCONF RPCs that make configuration changes are not sufficient.

Requirement: R-01382 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

The VNF or PNF MUST allow the entire configuration of the VNF or PNF to be retrieved via NETCONF’s <get-config> and <edit-config>, independently of whether it was configured via NETCONF or other mechanisms.

Requirement: R-28756 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MAY
updated: honolulu

The VNF or PNF MAY 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 <running> configuration at the same time.

Requirement: R-83873 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

The VNF or PNF MUST support :rollback-on-error value for the <error-option> parameter to the <edit-config> 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 <edit-config> request.

Requirement: R-68990 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MAY
updated: honolulu

The VNF or PNF MAY support the :startup capability. It will allow the running configuration to be copied to this special database. It can also be locked and unlocked.

Requirement: R-68200 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MAY
updated: honolulu

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

Requirement: R-20353 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: honolulu

The VNF or PNF MUST implement at least one of :candidate and :writable-running capabilities. When both :candidate and :writable-running are provided then two locks should be supported.

Requirement: R-11499 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MAY
updated: honolulu

The VNF or PNF MAY fully support the XPath 1.0 specification for filtered retrieval of configuration and other database contents. The ‘type’ attribute within the <filter> parameter for <get> and <get-config> 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.

Requirement: R-83790 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MAY
updated: honolulu

The VNF or PNF MAY implement the :validate capability.

Requirement: R-49145 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

The VNF or PNF MUST implement :confirmed-commit If :candidate is supported.

Requirement: R-58358 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MAY
updated: honolulu

The VNF or PNF MAY implement the :with-defaults capability [RFC6243].

Requirement: R-59610 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

The VNF or PNF MUST implement the data model discovery and download as defined in [RFC6022].

Requirement: R-93443 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

The VNF or PNF MUST define all data models in YANG 1.0 [RFC6020] or YANG 1.1 [RFC7950]. A combination of YANG 1.0 and YANG 1.1 modules is allowed subject to the rules in [RFC7950] section 12. The mapping to NETCONF shall follow the rules defined in this RFC.

Requirement: R-26115 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

The VNF or PNF MUST follow the data model update rules defined in [RFC6020] section 10 for YANG 1.0 modules, and [RFC7950] section 11 for YANG 1.1 modules. All deviations from the aforementioned update rules shall be handled by a built-in automatic upgrade mechanism.

Requirement: R-29495 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

The VNF or PNF MUST support locking if a common object is being manipulated by two simultaneous NETCONF configuration operations on the same VNF or PNF 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).

Requirement: R-53015 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

The VNF or PNF MUST apply locking based on the sequence of NETCONF operations, with the first configuration operation locking out all others until completed.

Requirement: R-41829 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: honolulu

The VNF or PNF MUST be able to specify the granularity of the lock via a restricted or full XPath expression if “:partial-lock” is supported.

Requirement: R-66793 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

The VNF or PNF MUST guarantee the VNF or PNF 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 VNF or PNF without locking either configuration method out).

Requirement: R-54190 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

The VNF or PNF MUST release locks to prevent permanent lock-outs when/if a session applying the lock is terminated (e.g., SSH session is terminated).

Requirement: R-03465 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: honolulu

The VNF or PNF MUST release locks to prevent permanent lock-outs when the corresponding <partial-unlock> operation succeeds if “:partial-lock” is supported.

Requirement: R-63935 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

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

Requirement: R-10173 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

The VNF or PNF MUST allow another NETCONF session to be able to initiate the release of the lock by killing the session owning the lock, using the <kill-session> operation to guard against hung NETCONF sessions.

Requirement: R-07545 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

The VNF or PNF MUST support all operations, administration and management (OAM) functions available from the supplier for VNFs or PNFs using the supplied YANG code and associated NETCONF servers.

Requirement: R-60656 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

The VNF or PNF MUST support sub tree filtering.

Requirement: R-80898 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

TThe VNF or PNF MUST support heartbeat via a <get> with null filter.

Requirement: R-25238 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: honolulu

The VNF or PNF PACKAGE MUST validated YANG code using the open source pyang 1 program using the following commands:

$ pyang --verbose --strict <YANG-file-name(s)> $ echo $!

The VNF or PNF MUST have the echo command return a zero value otherwise the validation has failed.

Requirement: R-26508 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

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

Requirement: R-10353 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

The VNF or PNF MUST conform its YANG model to RFC 6244, “An Architecture for Network Management Using NETCONF and YANG”.

Requirement: R-53317 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: SHOULD
updated: honolulu

The VNF or PNF SHOULD conform its YANG model to RFC 8407, “Guidelines for Authors and Reviewers of YANG Data Model specification”.

Requirement: R-33955 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: SHOULD
updated: dublin

The VNF or PNF SHOULD conform its YANG model to RFC 6991, “Common YANG Data Types”.

Requirement: R-22946 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: SHOULD
updated: honolulu

The VNF or PNF SHOULD conform its YANG model to RFC 8341, “NETCONF Access Control Model”.

Requirement: R-10129 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: SHOULD
updated: dublin

The VNF or PNF SHOULD conform its YANG model to RFC 7223, “A YANG Data Model for Interface Management”.

Requirement: R-12271 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: SHOULD
updated: dublin

The VNF or PNF SHOULD conform its YANG model to RFC 7223, “IANA Interface Type YANG Module”.

Requirement: R-49036 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: SHOULD
updated: dublin

The VNF or PNF SHOULD conform its YANG model to RFC 7277, “A YANG Data Model for IP Management”.

Requirement: R-87564 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: SHOULD
updated: dublin

The VNF or PNF SHOULD conform its YANG model to RFC 7317, “A YANG Data Model for System Management”.

Requirement: R-24269 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: SHOULD
updated: dublin

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

Requirement: R-33946 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

The VNF or PNF MUST conform to the NETCONF RFC 4741, “NETCONF Configuration Protocol”.

Requirement: R-04158 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

The VNF or PNF MUST conform to the NETCONF RFC 4742, “Using the NETCONF Configuration Protocol over Secure Shell (SSH)”.

Requirement: R-01334 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MAY
updated: honolulu

The VNF or PNF MAY conform to the NETCONF RFC 5717, “Partial Lock Remote Procedure Call”.

Requirement: R-78282 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

The VNF or PNF MUST conform to the NETCONF RFC 6242, “Using the Network Configuration Protocol over Secure Shell”.

Requirement: R-997907 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: SHOULD
introduced: dublin

The VNF or PNF SHOULD support TLS as secure transport for the NETCONF protocol according to [RFC7589].

LCM Operations via NETCONF
Requirement: R-246519 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MAY
introduced: frankfurt

As alternative to Ansible, Chef or REST, a VNF or PNF MAY support YANG models allowing execution of standard controller LCM operations including HealthCheck. Note: To support vendor YANG models for LCM operations, the controller is responsible for performing VNF/PNF specific translation of north-bound API requests into one or more south-bound NETCONF requests.

VNF or PNF REST APIs

HealthCheck command must be supported using a RESTful interface (defined in this section) or with NETCONF/YANG (defined in section NETCONF Standards and Capabilities) or with a Chef cookbook/Ansible playbook (defined in sections Chef Standards and Capabilities and Ansible Standards and Capabilities).

See section 7.3.1.4 for the definition of Full Healthcheck and Partial Healthchecks.

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

REST APIs
Requirement: R-31809 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

The VNF or PNF MUST support the HealthCheck RPC. The HealthCheck RPC executes a VNF or PNF Provider-defined VNF or PNF HealthCheck over the scope of the entire VNF or PNF (e.g., if there are multiple VNFCs, then run a health check, as appropriate, for all VNFCs). It returns a 200 OK if the test completes. A JSON object is returned indicating state (healthy, unhealthy), scope identifier, time-stamp and one or more blocks containing info and fault information. If the VNF or PNF 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:

{
  "identifier":"VNF",
  "state":"healthy",
  "time":"2018-11-28 22:39:00.809466"
},

{
  "identifier":"VNF",
  "state":"unhealthy",
  "info":"There are stopped processes or VNF is not ready, may be quiesced or frozen.",
  "fault":"VNF mtn23comx8000v not ready for service.",
  "time":"2018-11-30 05:47:48.655959"
}

Chef Standards and Capabilities

ATTENTION: Chef is supported by ONAP, but it is not currently used by any of the official ONAP use cases and is not part of standard release testing like REST, Ansible, and Netconf. For this reason, the other options are generally favored over Chef at this time.

ONAP will support configuration of VNFs or PNFs 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 or PNF 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 or PNF via the Chef-client.

ONAP will utilize the open source Chef Server, invoke the documented Chef REST APIs to manage the VNF or PNF and requires the use of open source Chef-Client and Push Jobs Client on the VNF or PNF (https://downloads.chef.io/).

VNF or PNF Configuration via Chef Requirements
Chef Client Requirements
Requirement: R-79224 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

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

Requirement: R-72184 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

The VNF or PNF MUST have routable FQDNs for all the endpoints (VMs) of a VNF or PNF that contain chef-clients which are used to register with the Chef Server. As part of invoking VNF or PNF actions, ONAP will trigger push jobs against FQDNs of endpoints for a VNF or PNF, if required.

Requirement: R-47068 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MAY
updated: dublin

The VNF or PNF MAY expose a single endpoint that is responsible for all functionality.

Requirement: R-67114 _images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: dublin

The VNF or PNF MUST be installed with Chef-Client >= 12.0 and Chef push jobs client >= 2.0.

Chef Roles/Requirements
Requirement: R-27310 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

The VNF or PNF Package MUST include all relevant Chef artifacts (roles/cookbooks/recipes) required to execute VNF or PNF actions requested by ONAP for loading on appropriate Chef Server.

Requirement: R-26567 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

The VNF or PNF Package MUST include a run list of roles/cookbooks/recipes, for each supported VNF or PNF action, that will perform the desired VNF or PNF action in its entirety as specified by ONAP (see Section 7.c, APPC/SDN-C APIs and Behavior, for list of VNF or PNF actions and requirements), when triggered by a chef-client run list in JSON file.

Requirement: R-98911 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST NOT
updated: dublin

The VNF or PNF MUST NOT use any instance specific parameters for the VNF or PNF in roles/cookbooks/recipes invoked for a VNF or PNF action.

Requirement: R-37929 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

The VNF or PNF MUST accept all necessary instance specific data from the environment or node object attributes for the VNF or PNF in roles/cookbooks/recipes invoked for a VNF or PNF action.

Requirement: R-62170 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

The VNF or PNF MUST over-ride any default values for configurable parameters that can be set by ONAP in the roles, cookbooks and recipes.

Requirement: R-78116 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

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

Requirement: R-44013 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

The VNF or PNF 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 VNF or PNF action requires the output of a chef-client run be made available (e.g., get running configuration).

Requirement: R-30654 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

The VNF or PNF 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 VNF or PNF (e.g., configure).

Requirement: R-65755 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: SHOULD
updated: dublin

The VNF or PNF SHOULD support callback URLs to return information to ONAP upon completion of the chef-client run for any chef-client run associated with a VNF or PNF 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.

Requirement: R-15885 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

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

  1. When ONAP receives a request for an action for a Chef Managed VNF or PNF, it retrieves the corresponding template (based on action and VNF or PNF) 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:

{
 "command": "chef-client"
 "run_timeout": 300
 "nodes": ["node1.vnf_a.onap.com", "node2.vnf_a.onap.com"]
   "env": {
            "RequestId":"8279-abcd-aksdj-19231"
            "CallbackUrl":"<callback>"
          }
}
  1. 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.

  2. 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 or PNFs via Ansible subject to the requirements and guidelines defined in this section.

Ansible allows agentless management of VNFs or PNFs/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 or PNFs that support Ansible.

VNF or PNF Configuration via Ansible Requirements
Ansible Client Requirements
Requirement: R-32217 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

The VNF or PNF MUST have routable management IP addresses or FQDNs that are reachable via the Ansible Server for the endpoints (VMs) of a VNF or PNF that playbooks will target. ONAP will initiate requests to the Ansible Server for invocation of playbooks against these end points 3.

Requirement: R-54373 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: guilin

The VNF or PNF Provider MUST provide Ansible playbooks that are compatible with the Operator’s deployed versions of Ansible and Python. As the Ansible runtime itself is not deployed as part of ONAP, the ONAP project cannot dictate the specific versions supported.

Requirement: R-35401 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

The VNF or PNF MUST support SSH and allow SSH access by the Ansible server to the endpoint VM(s) and comply with the Network Cloud Service Provider guidelines for authentication and access.

Requirement: R-82018 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: guilin

The VNF or PNF MUST load the Ansible Server SSH public key onto VNF or PNF VM(s) /root/.ssh/authorized_keys as part of instantiation. Alternative, is for Ansible Server SSH public key to be loaded onto VNF or PNF under /home/<Mechanized user ID>/.ssh/authorized_keys as part of instantiation, when a Mechanized user ID is created during instantiation, and Configure and all playbooks are designed to use a mechanized user ID only for authentication (never using root authentication during Configure playbook run). This will allow the Ansible Server to authenticate to perform post-instantiation configuration without manual intervention and without requiring specific VNF or PNF login IDs and passwords.

CAUTION: For VNFs or PNFs 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.

Requirement: R-92866 _images/arrow-right-circle.svg
target: VNF or PNF PROVIDER
keyword: MUST
updated: dublin

The VNF or PNF Provider 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 creating Mechanized user ID(s) used by the Ansible Server(s) on VNF VM(s) and uploading and installing new SSH keys used by the mechanized use ID(s).

Requirement: R-97345 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
introduced: casablanca
updated: dublin

The VNF or PNF MUST permit authentication, using root account, only right after instantiation and until post-instantiation configuration is completed.

Requirement: R-97451 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
introduced: casablanca
updated: dublin

The VNF or PNF MUST provide the ability to remove root access once post-instantiation configuration (Configure) is completed.

Requirement: R-91745 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

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

Requirement: R-73459 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
introduced: casablanca
updated: dublin

The VNF or PNF MUST provide the ability to include a “from=” clause in SSH public keys associated with mechanized user IDs created for an Ansible Server cluster to use for VNF or PNF VM authentication.

Requirement: R-45197 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
introduced: casablanca
updated: dublin

The VNF or PNF MUST define the “from=” clause to provide the list of IP addresses of the Ansible Servers in the Cluster, separated by coma, to restrict use of the SSH key pair to elements that are part of the Ansible Cluster owner of the issued and assigned mechanized user ID.

Requirement: R-94567 _images/arrow-right-circle.svg
target: VNF or PNF PROVIDER
keyword: MUST
introduced: casablanca
updated: guilin

The VNF or PNF Provider’s Ansible playbooks MUST be designed to run using an inventory hosts file in a supported format with only IP addresses or IP addresses and VM/VNF or PNF names.

Requirement: R-67124 _images/arrow-right-circle.svg
target: VNF or PNF PROVIDER
keyword: MUST
introduced: casablanca
updated: guilin

The VNF or PNF Provider’s Ansible playbooks MUST be designed to run using an inventory hosts file in a supported format; with group names matching VNFC 3-character string adding “vip” for groups with virtual IP addresses shared by multiple VMs as seen in examples provided in Appendix.

Requirement: R-24482 _images/arrow-right-circle.svg
target: VNF or PNF PROVIDER
keyword: MUST
introduced: casablanca
updated: guilin

The VNF or PNF Provider’s Ansible playbooks MUST be designed to run using an inventory hosts file in a supported format; with site group that shall be used to add site specific configurations to the target VNF or PNF VM(s) as needed.

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.

Requirement: R-49396 _images/arrow-right-circle.svg
target: VNF or PNF PROVIDER
keyword: MUST
updated: guilin

The VNF or PNF Provider’s Ansible playbooks MUST support each APPC/SDN-C VNF or PNF 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.

Requirement: R-33280 _images/arrow-right-circle.svg
target: VNF or PNF PROVIDER
keyword: MUST NOT
updated: guilin

The VNF or PNF Provider’s Ansible playbooks MUST NOT contain instance specific values that can not be provided by a parameter to the playbook.

Requirement: R-195620 _images/arrow-right-circle.svg
target: VNF or PNF PROVIDER
keyword: SHOULD
introduced: guilin

The VNF or PNF Provider’s Ansible playbooks SHOULD compare the version(s) of Ansible that the VNF Provider developed and tested against to the ansible_version.full value during playbook execution, and issue a WARNING message if the operator version is not one of the tested versions.

Requirement: R-918136 _images/arrow-right-circle.svg
target: VNF or PNF PROVIDER
keyword: MUST NOT
introduced: guilin

The VNF or PNF Provider’s Ansible playbooks MUST NOT fail due to a mismatched version check as specified in R-918136. The warning message should be issued, and the playbook execution should continue as normal.

Requirement: R-444446 _images/arrow-right-circle.svg
target: VNF or PNF PROVIDER
keyword: SHOULD
introduced: guilin

The VNF or PNF Provider’s Ansible playbooks SHOULD issue log messages in the same format as Ansible’s default messages: [<Log Level>]: <message>

Example:

[WARNING]: Ansible version 2.9.3 does not match a known, tested version: 2.8.1, 2.8.2

Requirement: R-48698 _images/arrow-right-circle.svg
target: VNF or PNF PROVIDER
keyword: MUST
updated: guilin

The VNF or PNF Provider’s Ansible playbooks MUST utilize information from key value pairs that will be provided by the Ansible Server as extra-vars during invocation to execute the desired VNF or PNF action. The “extra-vars” attribute-value pairs are passed to the Ansible Server by an APPC/SDN-C as part of the Rest API request. 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. Any files containing instance specific info (attribute-value pairs), not obtainable from any ONAP inventory databases or other sources, referenced and used as input by playbooks, shall be provisioned (and distributed) in advance of use, e.g., VNF or PNF instantiation. Recommendation is to avoid these instance specific, manually created in advance of instantiation, files.

The Ansible Server will determine if a playbook invoked to execute an VNF or PNF 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.

Requirement: R-43253 _images/arrow-right-circle.svg
target: VNF or PNF PROVIDER
keyword: MUST
updated: guilin

The VNF or PNF Provider’s Ansible playbooks MUST be 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).

Requirement: R-50252 _images/arrow-right-circle.svg
target: VNF or PNF PROVIDER
keyword: MUST
updated: guilin

The VNF or PNF Provider’s Ansible playbooks MUST write to a response file in JSON format that will be retrieved and made available by the Ansible Server if, as part of a VNF or PNF action (e.g., audit), a playbook is required to return any VNF or PNF information/response. The text files must be written in the main playbook home directory, in JSON format. The JSON file must be created for the VNF or PNF with the name ‘<VNF or PNF name>_results.txt’. All playbook output results, for all VNF VMS or PNF Server/Blades, to be provided as a response to the request, must be written to this response file.

Requirement: R-51442 _images/arrow-right-circle.svg
target: VNF or PNF PROVIDER
keyword: SHOULD
updated: guilin

The VNF or PNF Provider’s Ansible playbooks SHOULD be designed to automatically ‘rollback’ to the original state in case of any errors for actions that change state of the VNF or PNF (e.g., configure).

Note: In case rollback at the playbook level is not supported or possible, the VNF or PNF provider shall provide alternative rollback mechanism (e.g., for a small VNF or PNF the rollback mechanism may rely on workflow to terminate and re-instantiate VNF VMs and then re-run playbook(s)). Backing up updated files is also recommended to support rollback when soft rollback is feasible.

Requirement: R-58301 _images/arrow-right-circle.svg
target: VNF or PNF PROVIDER
keyword: SHOULD NOT
updated: dublin

The VNF or PNF Provider’s Ansible playbooks SHOULD NOT 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 Playbook related artifacts.

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 APPC/SDN-C. There are policies, as part of Control Loop models, that send remediation action requests to an APPC/SDN-C; these are triggered as a response to an event or correlated events published to Event Bus.

Requirement: R-02651 _images/arrow-right-circle.svg
target: VNF or PNF PROVIDER
keyword: SHOULD
updated: guilin

The VNF or PNF Provider’s Ansible playbooks SHOULD use available backup capabilities 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.

Requirement: R-43353 _images/arrow-right-circle.svg
target: VNF or PNF PROVIDER
keyword: MUST
updated: guilin

The VNF or PNF Provider’s Ansible playbooks MUST return control only after all tasks performed by playbook 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 response only after VNF or PNF application is fully stopped, all processes/services stopped.

StartApplication Playbook – StartApplication Playbook shall return control and a completion status only after all VNF or PNF 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 or PNF is 100% healthy, ready to take requests and provide services, with all VNF or PNF 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 or PNF 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 create one response file (per VNF or PNF) in JSON format, named after the VNF or PNF instance, followed by “_results.txt” (<VNF or PNF instance name>_results.txt) to be provided as a response to the requestor, indicating health-check was executed and completed successfully, example: vfdb9904v_results.txt, with the following contents:

{
 "identifier": "VNF",
 "state": "healthy",
 "time": "2018-03-16:1139"
}

Example:

$ cat vfdb9904v_results.txt
{
 "identifier": "VNF",
 "state": "healthy",
 "time": "2018-03-16:1139"
}

NOTE: See section 7.3.1.4 for comments on support of partial health checks.

FAILURE – A health check playbook shall return a non-zero return code in case VNF or PNF is not 100% healthy because one or more VNF or PNF 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 or PNF that need attention even if they do not impact services provided by the VNF or PNF.

A failed health-check playbook shall also create one file (per VNF or PNF), in JSON format, named after the VNF or PNF instance name, followed by “_results.txt” to indicate health-check was executed and found issues in the health of the VNF or PNF. This is to differentiate from failure to run health-check playbook or playbook tasks to verify the health of the VNF or PNF, example: vfdb9904v_results.txt, with the following contents:

{
 "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:

$ 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 or PNF REST APIs for additional details on HealthCheck.

Some VNFs or PNFs may support and desire to run partial health checks and receive a successful response when partial health check completes without errors. The parameter name used by HealthCheck playbook to request non-default partial health check is healthcheck_type. Example of health check types could be healthcheck_type=GuestOS, healthcheck_type=noDB, healthcheck_type=noConnections, healthcheck_type=IgnoreAlarms, etc.. This attribute-value pair may be passed by Orchestrator or Workflow or other (northbound) APPC/SDN-C clients to APPC/SDN-C as part of the request.

By default, when no argument/parameter is passed, healthcheck playbook performs a full VNF or PNF health check.

Requirement: R-24189 _images/arrow-right-circle.svg
target: VNF or PNF PROVIDER
keyword: MUST
introduced: casablanca
updated: guilin

The VNF or PNF Provider MUST deliver a new set of Ansible playbooks that includes all updated and unchanged playbooks for any new revision to an existing set of playbooks.

Requirement: R-49911 _images/arrow-right-circle.svg
target: VNF or PNF PROVIDER
keyword: MUST
introduced: casablanca
updated: guilin

The VNF or PNF Provider MUST assign a new point release to the updated Ansible playbook set. The functionality of a new playbook set must be tested before it is deployed to the production.

Requirement: R-42333 _images/arrow-right-circle.svg
target: VNF or PNF PROVIDER
keyword: MUST
introduced: frankfurt
updated: guilin

The VNF or PNF Provider’s Ansible playbooks that target a subset of VMs (or servers/blades) part of a VNF (or PNF) instance MUST be designed to use the VNF or PNF inventory host file and to use a parameter named target_vm_list to provide the subset of VMs in the VNF instance specifically targeted by the playbook.

NOTE: Example of such playbooks would be playbooks used to configure VMs added to a VNF instance as part of a scale-out/up or scale-in/down operation. Such playbook is expected to also need to perform configuration/reconfiguration tasks part of the base VNF instance build.

Requirement: R-39003 _images/arrow-right-circle.svg
target: VNF or PNF PROVIDER
keyword: MUST
introduced: frankfurt
updated: guilin

The VNF or PNF Provider’s Ansible playbooks MUST store passwords and other attributes that must remain secret in JSON, YAML or INI files that can be encrypted/decrypted using Ansible Vault capabilities.

Requirement: R-46823 _images/arrow-right-circle.svg
target: VNF or PNF PROVIDER
keyword: MUST
introduced: frankfurt

The VNF or PNF Provider’s Ansible playbooks MUST store passwords and other attributes that must remain secret in JSON, YAML or INI with differentiated names when passwords and secrets vary from environment to environment. Example, name must include <Mechanized user ID>_…json or <Mechanized user ID>_…xml when labs and production use different passwords and/or secrets. The <Mechanized user ID> is discovered from the environment /etc/ansible/ansible.cfg where the playbook runs.

Requirement: R-83092 _images/arrow-right-circle.svg
target: VNF or PNF PROVIDER
keyword: MUST
introduced: frankfurt
updated: guilin

The VNF or PNF Provider’s Ansible playbooks MUST load passwords and other attributes that must remain secret from JSON, YAML or INI files that can be encrypted/decrypted using Ansible Vault capabilities.

Requirement: R-09209 _images/arrow-right-circle.svg
target: VNF or PNF PROVIDER
keyword: MUST
introduced: frankfurt
updated: guilin

The VNF or PNF Provider’s Ansible playbooks MUST store any playbook configuration data that requires encryption (passwords, secrets, etc.) in a JSON (.json), YAML (.yaml|.yml) or INI (.ini) file, which will be placed in <VNF type>/<Version>/ansible/vars directory.

Requirement: R-56988 _images/arrow-right-circle.svg
target: VNF or PNF PROVIDER
keyword: MUST
introduced: frankfurt

The VNF or PNF Provider’s Ansible playbooks MUST load any configuration data that requires encryption (passwords, secrets, etc.) in a JSON (.json), YAML (.yaml|.yml) or INI (.ini) file, from the <VNF type>/<Version>/ansible/vars directory.

Requirement: R-20988 _images/arrow-right-circle.svg
target: VNF or PNF PROVIDER
keyword: MUST
introduced: frankfurt
updated: guilin

The VNF or PNF Provider’s Ansible playbooks MUST not log or display passwords and other attributes that must remain secret when running playbook in debug mode.

NOTE: Use no_log: True

Requirement: R-53245 _images/arrow-right-circle.svg
target: VNF or PNF PROVIDER
keyword: MUST NOT
introduced: frankfurt
updated: guilin

The VNF or PNF Provider’s Ansible playbooks MUST NOT require passwords or secrets to be passed in clear text in the command line or Rest API request to run the playbook.

Requirement: R-78640 _images/arrow-right-circle.svg
target: VNF or PNF PROVIDER
keyword: SHOULD
introduced: frankfurt
updated: guilin

The VNF or PNF Provider’s Ansible playbooks SHOULD provide a single YAML or JSON file with all the passwords and secrets to reduce the number of files to be decrypted/encrypted before on-boarding into the central repository.

Requirement: R-88786 _images/arrow-right-circle.svg
target: VNF or PNF PROVIDER
keyword: SHOULD
introduced: frankfurt
updated: guilin

The VNF or PNF Provider’s Ansible playbooks SHOULD place the passwords and secrets to be edited at the top of the single YAML or JSON file with all the secrets, and the (default) ones that are to remain unchanged ‘ towards the bottom, with commentary separating them.

Requirement: R-88002 _images/arrow-right-circle.svg
target: VNF or PNF PROVIDER
keyword: MUST
introduced: frankfurt

The VNF or PNF Provider MUST use a pre-agreed upon password to encrypt the Ansible Vault file, or provide the vault password used to encrypt the file to the customer, in a secure manner, to allow the customer to decrypt/encrypt (rekey) Ansible Vault files before they are checked into the central repository for distribution.

Ansible API Usage

This section outlines the workflow that APPC/SDN-C invokes when it receives an action request against an Ansible managed VNF or PNF.

  1. When APPC/SDN-C receives a request for an action for an Ansible managed VNF or PNF, it retrieves the corresponding template (based on action and VNF or PNF Type) from its database and sets necessary values (such as an Id, NodeList, and EnvParameters) from either information either in the request or data obtained from other sources, inventory database, is an example of such sources. This is referred to as the payload that is sent as a JSON object to the Ansible server as part of the Rest API request.

  2. The APPC/SDN-C sends a request to the Ansible server to execute the action.

  3. The APPC/SDN-C, after sending a request to the Ansible server, polls it to get results(success or failure). The APPC/SDN-C has a timeout value which is contained in the action request template. Different actions can set different timeout values (default setting is 600 seconds). If the result is not available when the timeout is reached, the APPC/SDN-C stops polling and returns a timeout error to the requester. The Ansible Server continues to process the request.

Support of APPC/SDN-C 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. APPC/SDN-C APIs and NETCONF Commands

Command

NETCONF Support

Chef Support

Ansible

General Comments

For each RPC, the appropriate RPC operation is listed.

VNF or PNF Vendor must provide any necessary roles, cookbooks, recipes to retrieve the running configuration from a VNF or PNF and place it in the respective Node Objects ‘PushJobOutput’ attribute of all nodes in NodeList when triggered by a chef-client run.

The JSON file for this VNF or PNF action is required to set “PushJobFlag” to “True” and “GetOutputFlag” to “True”. The “Node” JSON dictionary must have the run list populated with the necessary sequence of roles, cookbooks, recipes.

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

VNF Vendor must provide an Ansible playbook to retrieve the running configuration from a VNF and place the output on the Ansible server in a manner aligned with playbook requirements listed in this document.

The PlaybookName must be provided in the JSON file.

NodeList must list IP addresses or DNS supported FQDNs of the VNF instance on which to execute playbook.

Audit

The <get-config> is used to return the running configuration.

Supported via a cookbook that returns the running configuration.

Supported via a playbook that returns the running configuration.

Configure, ModifyConfig

The <edit-config> operation loads all or part of a specified data set to the specified target database. If there is no <candidate/> database, then the target is the <running/> database. A <commit> follows.

Supported via a cookbook that updates the VNF or PNF configuration.

Supported via a playbook that updates the VNF configuration.

Other Configuration Commands

This command has no existing NETCONF RPC action.

Supported via a cookbook that performs the action.

Supported via a playbook that performs the action.

Lifecycle Management Commands

This command has no existing NETCONF RPC action.

Supported via a cookbook that performs the action.

Supported via a playbook that performs the action.

Health Check

This command has no existing NETCONF RPC action.

Supported via a cookbook that performs a HealthCheck and returns the results.

Supported via a playbook that performs 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 or PNF 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.

Monitoring & Management

In ONAP, DCAE is responsible of collecting, receiving, and analyzing NF monitoring data. This data serves the basis for tracking the health, performance, and operational status of the NF. DCAE provides a number of predefined interfaces based upon accepted, open standards to support monitoring data ingestion. Some of these interfaces collect data by polling or pulling data from the NF using standard protocols. Other DCAE interfaces receive monitoring data (such as VES events) that are pushed from the NFs.

A NF that produces monitoring data and uses protocols that are compatible with ONAP’s predefined monitoring ingestion capabilities can easily be integrated with ONAP through simple configuration rather than custom development.

This chapter will define the expected requirements for a NF to easily integrate with an instance of ONAP.

Monitoring and Fault Protocol Selection

This section provides the proper guidance on how a NF should determine the protocol and data format for providing a specific types of telemetry data to ONAP.

Requirement: R-82909 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
introduced: guilin

The VNF or PNF MUST report faults and alarms using either Virtual Function Event Streaming (VES) or SNMP. (NOTE: See relevant sections for more detailed requirements)

Requirement: R-554966 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
introduced: guilin

The VNF or PNF MUST report performance metrics using Virtual Function Event Streaming (VES) or Bulk Performance Measurement.

Requirement: R-69111 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
introduced: guilin

The VNF or PNF MUST report application logs using either Virtual Function Event Streaming (VES) or Syslog in compliance with RFC 5424 .

Requirement: R-209104 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: SHOULD
introduced: guilin

The VNF or PNF producing VES syslog events SHOULD restrict these events to those that convey significant errors or warnings needed to support the operation or troubleshooting of the VNF or PNF. It is expected the volume of such events would be lower (e.g. less than 2000 per day) than more detailed events produced in the course of normal operations.

Requirement: R-332680 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: SHOULD
introduced: casablanca
updated: guilin
impacts: dcae
validation_mode: in_service

The VNF or PNF producing VES events SHOULD deliver syslog messages that meet the criteria in R-209104 to the VES Event Listener using the syslog VES domain.

Requirement: R-935717 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
introduced: guilin

The VNF or PNF MUST report heartbeats using Virtual Function Event Streaming (VES).

Requirement: R-697654 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MAY
introduced: casablanca
updated: guilin
impacts: DCAE
validation_mode: in_service

The VNF or PNF MAY leverage ONAP’s High Volume VNF Event Streaming (HV-VES) when there is a need to deliver large volumes of real-time performance management metrics. See HV-VES collector service details for more information.

Requirement: R-857511 _images/arrow-right-circle.svg
target: VNF or PNF PROVIDER
keyword: MUST
introduced: guilin
impacts: DCAE
validation_mode: none

VNF or PNF Provider MUST have agreement with the Service Provider before utilizing the HV-VES option for monitoring as this option does not fully integrate with the ONAP’s DCAE event processing capabilities.

Requirement: R-908291 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MAY
introduced: casablanca
updated: guilin
impacts: dcae, dmaap
validation_mode: in_service

The VNF or PNF MAY leverage a bulk VNF or PNF telemetry transmission mechanism in instances where other transmission methods are not practical or advisable.

NOTE: For additional information and use cases for the Bulk Telemetry Transmission Mechanism, please refer to the Bulk Performance Measurement requirements and the 5G - Bulk PM ONAP Development Wiki page.

Requirement: R-63105 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MAY
introduced: guilin
impacts: dcae

The VNF or PNF MAY produce telemetry data using the RESTConf Collector, but this requires additional coordination with the operator to appropriately map the data internally to a VES-like structure used within ONAP. If this option is needed, then the VNF or PNF Provider must coordinate with with the Operator for the data to be successfully collected and processed by DCAE.

SNMP Monitoring Requirements

Requirement: R-261501 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
introduced: guilin

If the VNF or PNF is using SNMP, then the VNF or PNF Provider MUST provide a Management Information Base (MIB) file that uniquely identifies and describes all SNMP events exposed by the network function.

Requirement: R-233922 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: SHOULD
introduced: guilin

If the VNF or PNF is using SNMP, then the VNF or PNF Provider SHOULD provide examples of all SNMP alarms.

Virtual Function Event Streaming (VES) Client Requirements

The VES protocol enables NFs to transmit telemetry data in a non-proprietary, extensible format to ONAP using the HTTP protocol. This chapter will define the requirements for a NF to deliver events to ONAP’s VES event listeners in a manner that conforms with the appropriate VES Event Listener specifications, and ensures the NF can be configured to maximize the reliability of telemetry data delivery.

Event Definition and Registration
Requirement: R-520802 _images/arrow-right-circle.svg
target: VNF or PNF PROVIDER
keyword: MUST
introduced: casablanca
updated: guilin
impacts: dcae
validation_mode: static

If the VNF or PNF is using VES, then the VNF or PNF Provider MUST provide a YAML file formatted in adherence with the VES Event Registration specification that defines the following information for each event produced by the VNF:

  • eventName

  • Required fields

  • Optional fields

  • Any special handling to be performed for that event

Requirement: R-120182 _images/arrow-right-circle.svg
target: VNF or PNF PROVIDER
keyword: MUST
introduced: casablanca
updated: guilin
impacts: dcae
validation_mode: static

A VNF or PNF Provider utilizing VES MUST indicate specific conditions that may arise, and recommend actions that may be taken at specific thresholds, or if specific conditions repeat within a specified time interval, using the semantics and syntax described by the VES Event Registration specification.

NOTE: The Service Provider may override VNF or PNF provider Event Registrations using the ONAP SDC Design Studio to finalizes Service Provider engineering rules for the processing of the VNF or PNF events. These changes may modify any of the following:

  • Threshold levels

  • Specified actions related to conditions

Requirement: R-123044 _images/arrow-right-circle.svg
target: VNF or PNF PROVIDER
keyword: MAY
introduced: casablanca
updated: dublin
impacts: dcae
validation_mode: in_service

The VNF or PNF Provider MAY require that specific events, identified by their eventName, require that certain fields, which are optional in the common event format, must be present when they are published.

Event Formatting and Usage
Requirement: R-570134 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
introduced: casablanca
updated: guilin
impacts: dcae
validation_mode: in_service

The VES events produced by the VNF or PNF MUST be compliant with the common event formats defined in one of the following specifications:

The latest version (7.2) should be preferred. Earlier versions are provided for backwards compatibility.

Requirement: R-528866 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
introduced: casablanca
updated: guilin
impacts: dcae
validation_mode: in_service

The VES events produced by the VNF or PNF MUST conform to the schema and other formatting requirements specified in the relevant VES Event Listener specification.

Requirement: R-283988 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST NOT
introduced: casablanca
updated: guilin
impacts: dcae
validation_mode: in_service

A VNF or PNF producing VES events MUST NOT send information through extensible structures if the event specification has explicitly defined fields for that information.

Requirement: R-470963 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: SHOULD
introduced: casablanca
updated: guilin
impacts: dcae
validation_mode: in_service

A VNF or PNF producing VES events SHOULD leverage camel case to separate words and acronyms used as keys that will be sent through extensible fields. When an acronym is used as the key, then only the first letter shall be capitalized.

Requirement: R-408813 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
introduced: casablanca
updated: guilin
impacts: dcae
validation_mode: none

A VNF or PNF producing VES events MUST pass all information it is able to collect even if the information field is identified as optional. However, if the data cannot be collected, then optional fields can be omitted.

Requirement: R-408814 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
introduced: guilin
impacts: dcae
validation_mode: none

The VNF or a PNF producing VES stndDefined domain events to report standards-organization defined events to ONAP, MUST set the event.stndDefinedNamespace property. By default, ONAP ships with support for the following:

  • 3GPP-Provisioning

  • 3GPP-Heartbeat

  • 3GPP-FaultSupervision

  • 3GPP-PerformanceAssurance

Another namespace, outside of the list provided, needs to registered in ONAP in coordination with the operator before it can be used.

Requirement: R-408815 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
introduced: guilin
impacts: dcae
validation_mode: none

If the VNF or PNF producing VES stndDefined domain events provides the event.stndDefinedFields.schemaReference then it MUST set its value to the publicUrl value in DCAE’s VES Collector etc/externalRepo/schema-map.json that describes the data being sent in event.stndDefinedFields.data.

Requirement: R-408816 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
introduced: guilin
impacts: dcae
validation_mode: none

If the VNF or PNF producing VES stndDefined domain events provides the event.stndDefinedFields.schemaReference then it MUST only pass events that conform to schema references previously registered with DCAE otherwise the event will be rejected. By default, ONAP ships with support for schemas found in DCAE’s VES Collector etc/externalRepo/schema-map.json.

Requirement: R-408817 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
introduced: guilin
impacts: dcae
validation_mode: none

The VNF or PNF Provider producing stndDefined events MUST coordinate with the operator, willing to validate stndDefined events, to configure DCAE to accept any new event schema prior to sending those events or the events will be rejected.

Requirement: R-408818 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
introduced: guilin
impacts: dcae
validation_mode: none

If the VNF or PNF producing VES stndDefined domain events provides the event.stndDefinedFields.schemaReference then it MUST set the event.stndDefined.schemaReference property to an exact structure, from supported schemaReference, describing the notification within an openAPI specification, using JSON Pointer as URI fragment e.g. “https://forge.3gpp.org/…/faultMnS.yaml#/components/schemas/notifyNewAlarm

Configuration Requirements

This section defines the types the configuration options and defaults a NF producing VES events should provide to ensure the NF can be configured properly for the Service Provider’s ONAP environment and ensure reliable delivery of VES events.

There are several methods available to provide configuration settings to a network function. This document does not specify the exact manner in which the configuration elements described below must be required. The configuration can be provided during instantiation (e.g. preload), provided by an ONAP controller action, or provided manually.

Requirement: R-460012 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
introduced: guilin

The VNF or PNF producing VES events MUST allow the configuration of the attributes defined in Table 1 and utilize the provided default value (where applicable) when the configuration value is not provided by the Service Provider.

Requirement: R-940591 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: SHOULD
introduced: guilin

A VNF or PNF producing VES events SHOULD use the recommended parameter name for the configurable value from Table 1.

Table 1: VES Configurable Values

Parameter

Description

Default

Parameter Name (VES 7.2+)

VES Listener Endpoint

FQDN or IP of the Event Listener

n/a

ves_listener_endpoint

Heartbeat Interval

Frequency in seconds the NF must send a heartbeat to the event listener

60

ves_heartbeat_interval_seconds

Timeout Value

Duration in seconds the NF should wait for ACK from the event listener before timeout

5

ves_timeout_seconds

Measurement Interval

Window size in seconds to use for aggregated measurements

300

ves_measurement_interval_seconds

HTTP Username

Required if NF supports HTTP Basic Authentication with the VES Event Listener

n/a

ves_http_username

HTTP Password

Required if NF supports HTTP Basic Authentication with the VES Event Listener

n/a

ves_http_password

VES Listener Endpoint and DNS Resolution

In a high availability deployment of a VES Event Listener, a round-robin DNS or dynamic DNS may be used to either load balance or provide fault tolerance of the Event Listener. Adherence to the following requirements ensure the VNF or PNF interacts properly with this deployment configuration.

Requirement: R-70492 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
introduced: guilin

The VNF or PNF MUST support DNS resolution of the VES Listener Endpoint if a Fully Qualified Domain Name (FQDN) is provided.

Requirement: R-130645 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
introduced: guilin

The VNF or PNF MUST respect the Time To Live provided by the DNS for the VES Event Listener FQDN.

Event Delivery Requirements
Requirement: R-06924 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: guilin

The VNF or PNF producing VES events MUST deliver VES events as it becomes available or according to the configured measurement interval.

Requirement: R-655209 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
introduced: guilin

The VNF or PNF producing VES events MUST respect the configured VES Timeout Value when delivering VES events, and abort any call where the VES Event Listener does not successfully acknowledge the delivery of event(s) within the Timeout Value. These failed transactions should be buffered and retried in accordance with the Buffering and Redelivery Requirements.

Requirement: R-176945 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: SHOULD NOT
introduced: guilin

The VNF or PNF producing VES events SHOULD NOT send syslog events to the VES Event Listener during debug mode, but rather store syslog events locally for access or possible file transfer.

Buffering and Redelivery

To maximize the reliable delivery of VES events when the VES Listener becomes unavailable or unhealthy, the NF must adhere to these requirements.

Requirement: R-658596 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
introduced: guilin

A VNF or PNF producing VES events MUST buffer events that meet the following criteria if the VES Event Listener is unreachable or the request encounters a timeout.

  • Faults with eventSeverity of MINOR, MAJOR, NORMAL, or CRITICAL

  • Syslog with syslogSev of Emergency, Alert, Critical, Error, or Warning

  • All measurement events

Requirement: R-636251 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
introduced: guilin

A VNF or PNF producing VES events MUST size the event buffer referenced in R-658596 such that it can buffer a minimum of 1 hours of events under nominal load.

Requirement: R-498679 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MAY
introduced: guilin

A VNF or PNF producing VES events MAY discard buffered events older than a maximum retention period, not less than 1 hour, even if the event was never successfully delivered to the event listener. While discarding based on this retention period is supported for backwards compatibility, it is recommended to retain events until the maximum buffer size is reached per R-346137 as that will maximize the number of events delivered.

Requirement: R-346137 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
introduced: guilin

A VNF or PNF producing VES events that is buffering events per R-658596 MUST store in-scope events even when the maximum capacity of the buffer (defined in R-636251) has been reached. To make room for new events in this situation, hte oldest event in the buffer shall be removed as necessary. (i.e. First In First Out)

Requirement: R-379523 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
introduced: guilin

A VNF or PNF producing VES events that is buffering events due to an unavailable VES Event Listener MUST redeliver all buffered events according to the following rules when the VNF or PNF detects the VES Event Listener has become available:

  • Deliver all previously buffered events before sending new events

  • Deliver buffered events in the order they were received

Requirement: R-818859 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
introduced: guilin

The VNF or PNF producing VES events MUST not allow an unavailable or timing out VES Event Listener to impact the performance, stability, or correct execution of network function.

Requirement: R-103464 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MAY
introduced: guilin

A VNF or PNF producing VES events that is buffering events due to an unavailable VES Event Listener MAY leverage to publishEventBatch operation to redeliver buffered events. Please note this can only be used when all buffered events belong to the same domain due to the restrictions in place for the operation.

Security
Requirement: R-68165 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
updated: dublin

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

Requirement: R-33878 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
introduced: el alto
updated: guilin

The VNF or PNF MUST utilize one of the authentication methods prescribed by the relevant VES Event Listener specification.

Bulk Performance Measurement

Requirement: R-841740 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: SHOULD
introduced: casablanca
updated: dublin
impacts: dcae, dmaap

The VNF or PNF SHOULD support FileReady VES event for event-driven bulk transfer of monitoring data.

Requirement: R-440220 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: SHOULD
introduced: casablanca
updated: dublin
impacts: dcae, dmaap

The VNF or PNF SHOULD support File transferring protocol, such as FTPES or SFTP, when supporting the event-driven bulk transfer of monitoring data.

Requirement: R-75943 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: SHOULD
introduced: casablanca
updated: guilin
impacts: dcae, dmaap

The VNF or PNF SHOULD support the data schema defined in 3GPP TS 32.435 or 3GPP TS 28.532, when supporting the event-driven bulk transfer of monitoring data.

Requirement: R-807129 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: SHOULD
introduced: dublin
impacts: dcae, dmaap

The VNF or PNF SHOULD report the files in FileReady for as long as they are available at VNF or PNF.

Note: Recommended period is at least 24 hours.

PNF Plug and Play

PNF Plug and Play

The following are the requirements related to PNF Plug and Play.

Requirement: R-56718 _images/arrow-right-circle.svg
target: PNF
keyword: MAY
introduced: casablanca

The PNF Vendor MAY provide software version(s) to be supported by PNF for SDC Design Studio PNF Model. This is set in the PNF Model property software_versions.

Requirement: R-106240 _images/arrow-right-circle.svg
target: PNF
keyword: MUST
introduced: casablanca
updated: guilin

A PNF MUST support the pnfRegistration VES event which is required to integrate with ONAP’s PNF Plug and Play capabilities.

Requirement: R-258352 _images/arrow-right-circle.svg
target: PNF
keyword: MUST
introduced: casablanca

The PNF MUST support & accept the provisioning of an ONAP contact IP address (in IPv4 or IPv6 format).

Note: For example, it a possibility is that an external EMS would configure & provision the ONAP contact IP address to the PNF (in either IPv4 or IPv6 format). For the PNF Plug and Play Use Case, this IP address is the service provider’s “point of entry” to the DCAE VES Listener.

Note: different service provider’s network architecture may also require special setup to allow an external PNF to contact the ONAP installation. For example, in the AT&T network, a maintenance tunnel is used to access ONAP.

Requirement: R-793716 _images/arrow-right-circle.svg
target: PNF
keyword: MUST
introduced: casablanca

The PNF MUST have “ONAP Aware” software which is capable of performing PNF PnP registration with ONAP. The “ONAP Aware” software is capable of performing the PNF PnP Registration with ONAP MUST either be loaded separately or integrated into the PNF software upon physical delivery and installation of the PNF.

Note: It is up to the specific vendor to design the software management functions.

Requirement: R-952314 _images/arrow-right-circle.svg
target: PNF
keyword: MUST
introduced: casablanca

If the PNF set up a TLS connection and mutual (two-way) authentication is being used, then the PNF MUST provide its own X.509v3 Certificate to the DCAE VES Collector for authentication.

Note: This allows TLS authentication by DCAE VES Collector.

Note: The PNF got its X.509 certificate through Enrollment with an operator certificate authority or a X.509 vendor certificate from the vendor factory CA.

Note: In R3 three authentication options are supported:

  1. HTTP with Username & Password and no TLS.

  2. HTTP with Username & Password & TLS with two-way certificate authentication.

  3. HTTP with Username & Password & TLS with server-side certificate authentication.

Requirement: R-809261 _images/arrow-right-circle.svg
target: PNF
keyword: MUST
introduced: casablanca

The PNF MUST use a IP address to contact ONAP.

Note: it is expected that an ONAP operator can ascertain the ONAP IP address or the security gateway to reach ONAP on the VID or ONAP portal GUI.

Note: The ONAP contact IP address has been previously configured and provisioned prior to this step.

Note: The ONAP IP address could be provisioned or resolved through FQDN & DNS.

Requirement: R-763774 _images/arrow-right-circle.svg
target: VNF or PNF
keyword: MUST
introduced: casablanca
updated: el alto

The VNF or PNF MUST support a HTTPS connection to the DCAE VES Event Listener.

Requirement: R-686466 _images/arrow-right-circle.svg
target: PNF
keyword: MUST
introduced: casablanca

The PNF MUST support sending a pnfRegistration VES event.

Requirement: R-980039 _images/arrow-right-circle.svg
target: PNF
keyword: MUST
introduced: casablanca

The PNF MUST send the pnfRegistration VES event periodically.

Requirement: R-981585 _images/arrow-right-circle.svg
target: PNF
keyword: MUST
introduced: casablanca

The pnfRegistration VES event periodicity MUST be configurable.

Note: The PNF uses the service configuration request as a semaphore to stop sending the pnfRegistration sent. See the requirement PNP-5360 requirement.

Requirement: R-284934 _images/arrow-right-circle.svg
target: PNF
keyword: MAY
introduced: casablanca

If the PNF encounters an error authenticating, reaching the ONAP DCAE VES Event listener or recieves an error response from sending the pnfRegistration VES Event, it MAY log the error, and notify the operator.

Note: the design of how errors are logged, retrieved and reported will be a vendor-specific architecture. Reporting faults and errors is also a vendor specific design. It is expected that the PNF shall have a means to log an error and notify a user when a fault condition occurs in trying to contact ONAP, authenticate or send a pnfRegistration event.

Requirement: R-256347 _images/arrow-right-circle.svg
target: PNF
keyword: MUST
introduced: casablanca
updated: dublin

The PNF MUST support one of the protocols for a Service Configuration message exchange between the PNF and PNF Controller (in ONAP): a) Netconf/YANG, b) Chef, or c) Ansible.

Note: The PNF Controller may be VF-C, APP-C or SDN-C based on the PNF and PNF domain.

Requirement: R-707977 _images/arrow-right-circle.svg
target: PNF
keyword: MUST
introduced: casablanca

When the PNF receives a Service configuration from ONAP, the PNF MUST cease sending the pnfRegistration VES Event.

Requirement: R-17624 _images/arrow-right-circle.svg
target: PNF
keyword: MAY
introduced: casablanca

The PNF MAY support the optional parameters for Service Configuration Parameters.

Note: These are detailed in the Stage 5 PnP

Note: These parameters are optional, and not all PNFs will support any or all of these parameters, it is up to the vendor and service provider to ascertain which ones are supported up to an including all of the ones that have been defined. Note: It is expected that there will be a growing list of supported configuration parameters in future releases of ONAP.

Requirement: R-378131 _images/arrow-right-circle.svg
target: PNF
keyword: MAY
introduced: casablanca

(Error Case) - If an error is encountered by the PNF during a Service Configuration exchange with ONAP, the PNF MAY log the error and notify an operator.

Requirement: R-638216 _images/arrow-right-circle.svg
target: PNF
keyword: MUST
introduced: casablanca

(Error Case) - The PNF MUST support a configurable timer to stop the periodicity sending of the pnfRegistration VES event. If this timer expires during a Service Configuration exchange between the PNF and ONAP, it MAY log a time-out error and notify an operator.

Note: It is expected that each vendor will enforce and define a PNF service configuration timeout period. This is because the PNF cannot wait indefinitely as there may also be a technician on-site trying to complete installation & commissioning. The management of the VES event exchange is also a requirement on the PNF to be developed by the PNF vendor.

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 VNF or PNF 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/…”

Appendix

Chef JSON Key Value Description

The following provides the key value pairs that must be contained in the JSON file supporting Chef action.

Table A1. Chef JSON File key value description

Field Name

Description

Type

Comment

Environment

A JSON dictionary representing a Chef Environment object. If the VNF action requires loading or modifying Chef environment attributes associated with the VNF, all the relevant information must be provided in this JSON dictionary in a structure that conforms to a Chef Environment Object.

Optional

Depends on VNF action.

Node

A JSON dictionary representing a Chef Node Object.

The Node JSON dictionary must include the run list to be triggered for the desired VNF action by the push job. It should also include any attributes that need to be configured on the Node Object as part of the VNF action.

Mandatory

NodeList

Array of FQDNs that correspond to the endpoints (VMs) of a VNF registered with the Chef Server that need to trigger a chef-client run as part of the desired VNF action.

Mandatory

PushJobFlag

This field indicates whether the VNF action requires a push Job. Push job object will be created by ONAP if required.

Mandatory

If set to “True”, ONAP will request a push job. Ignored otherwise.

CallbackCapable

This field indicates if the chef-client run invoked by push job corresponding to the VNF action is capable of posting results on a callback URL.

Optional

If Chef cookbook is callback capable, VNF owner is required to set it to “True”. Ignored otherwise.

GetOutputFlag

Flag which indicates whether ONAP should retrieve output generated in a chef-client run from Node object attribute node[‘PushJobOutput’] for this VNF action (e.g., in Audit).

Mandatory

ONAP will retrieve output from NodeObject attributes [‘PushJobOutput’] for all nodes in NodeList if set to “True”. Ignored otherwise.

Chef Template example:

"Environment":{
     "name": "HAR",
     "description": "VNF Chef environment for HAR",
     "json_class": "Chef::Environment",
     "chef_type": "environment",
     "default_attributes": { },
     "override_attributes": {
           "Retry_Time":"50",
           "MemCache": "1024",
           "Database_IP":"10.10.1.5"
     },
}
}
"Node": {
     "name" : "signal.network.com "
     "chef_type": "node",
     "json_class": "Chef::Node",
     "attributes": {
           "IPAddress1": "192.168.1.2",
           "IPAddress2":"135.16.162.5",
           "MyRole":"BE"
     },
     "override": {},
     "default": {},
     "normal":{},
     "automatic":{},
     "chef_environment" : "_default"
     "run_list": [ "configure_signal" ]
     },
     "NodeList":["node1.vnf_a.onap.com", "node2.vnf_a.onap.com"],
     "PushJobFlag": "True"
     "CallbackCapable":True
     "GetOutputFlag" : "False"
}

The example JSON file provided by the VNF provider for each VNF action will be turned into a template by ONAP, that can be updated with instance specific values at run-time.

Some points worth noting regarding the JSON fields:

  1. The JSON file must be created for each action for each VNF.

  2. If a VNF action involves multiple endpoints (VMs) of a VNF, ONAP will replicate the “Node” JSON dictionary in the template and post it to each FQDN (i.e., endpoint) in the NodeList after setting the “name” field in the Node object to be the respective FQDN 1. Hence, it is required that all end points (VMs) of a VNF involved in a VNF action support the same set of Node Object attributes.

The following table describes the JSON dictionary to post in Callback.

Table A2. JSON Dictionary to Post in Callback

Key

Description

Type

Comment

RequestId

A unique string associated with the original request by ONAP. This key-value pair will be provided by ONAP in the environment of the push job request and must be returned as part of the POST message.

Mandatory

StatusCode

An integer that must be set to 200 if chef-client run on the node finished successfully 500 otherwise.

Mandatory

StatusMessage

A string which must be set to ‘SUCCESS’ if StatusCode was 200

Appropriate error message otherwise.

Mandatory

Name

A string which corresponds to the name of the node where push job is run. It is required that the value be retrieved from the node object attributes (where it is always defined).

Mandatory

PushJobOutput

Any output from the chef-client run that needs to be returned to ONAP.

Optional

Depends on VNF action. If empty, it must not be included.

1

The “name” field is a mandatory field in a valid Chef Node Object JSON dictionary.

Ansible JSON Key Value Description

The following provides the key value pairs that must be contained in the JSON file supporting APPC/SDN-C Ansible action.

Table B1. Ansible JSON File key value description

TOSCA Definition

Field Name

Description

Type

Comment

PlaybookName

xNF provider must list name of the playbook relative path used to execute the xNF action.

Mandatory

Currently following Ansible standard naming, where main playbook is always named site.yml, and directory name where this main playbook resides, is named after the command/action playbook performs, in lower case, example, configure.

Action

Name of xNF action.

Optional

EnvParameters

A JSON dictionary which should list key attribute-value pairs to be passed to the Ansible playbook. These values usually are instance specific parameters that a playbook needs to execute an action targeting the xNF instance.

Optional

Attribute-value pairs vary from xNF action-to-action. Targeted xNF instance name is commonly a required attribute.

Attribute names (variable names) passed to Ansible shall follow Ansible valid variable names: “Variable names should be letters, numbers, and underscores. Variables should always start with a letter.”

NodeList

xNF inventory xNFC names with respective IP/VIP addresses, in xNFC groups, xNF instance local/site name, and other info required to build inventory hosts file playbook must be executed against.

Optional

If NodeList is not provided, inventory hosts file must be pre-loaded (xNF) in the Ansible Server in advance of request targeting instance otherwise request fails with inventory hosts file not found.

FileParameters

A JSON dictionary where keys are filenames and values are contents of files. The Ansible Server will utilize this feature to generate files with keys as filenames and values as content. This attribute can be used to generate files that a playbook may require as part of execution.

Optional

Depends on the xNF action and playbook design.

Timeout

Time (in seconds) that a playbook is expected to take to finish execution for the xNF. If playbook execution time exceeds this value, Ansible Server will terminate the playbook process.

Optional

InventoryNames

Default “None”, no names, inventory hosts file contains no names, just (OA&M) IP addresses. When set to “VM” or “VNFC” Ansible Server Rest API adds VM names or VNFC names, respectively, to the inventory hosts file besides IP addresses (or FQDNs). Names and IP addresses are provided by APPC/SDN-C in xNF NodeList.

Optional

This parameter is used by Ansible Server Rest API to build inventory hosts file matching what is required by xNF Type.

CAUTION: All templates, for a given xNF Type, shall use the same InventoryNames setting for all commands/playbooks, “None” (Default), “VM” or “VNFC”.

Ansible JSON file example:

{
  "Action":"Configure",
  "PlaybookName": "<VNFCode>/<Version>/ansible/configure/site.yml",
  "NodeList": [
    {
      "vnfc_type": "oam",
      "ne_id_vip": "vfdb9904vm001oam001",
      "floating_ip_address_vip": "1xx.2yy.zzz.109",
      "site": "wp0ny",
      "vm_info": [
        {
          "ne_id": "vfdb9904vm001oam001",
          "fixed_ip_address": "1xx.2yy.zzz.109"
        },
        {
          "ne_id": "vfdb9904vm002oam001",
          "fixed_ip_address": "1xx.2yy.zzz.110"
        }
      ]
    },
    {
      "vnfc_type": "rdb",
      "site": "wp0ny",
      "vm_info": [
        {
          "ne_id": "vfdb9904vm003rdb001",
          "fixed_ip_address": "1xx.2yy.zzz.105"
        },
        {
          "ne_id": "vfdb9904vm004rdb001",
          "fixed_ip_address": "1xx.2yy.zzz.106"
        }
      ]
    }
  ],
  "Timeout": 60,
  "InventoryNames": "None",
  "EnvParameters": {"vnf_instance": "$vnf-instance", "Retry": 3, "Wait": 5, "ConfigFile":"config.txt", "healthcheck_type": "$healthcheck_type",  "target_vm_list": ["$ne-id1","..."] },
  "FileParameters": {"config.txt":"db_ip=10.1.1.1, sip_timer=10000"}
}

In the above example, the Ansible Server Rest API code will:

  1. Process the “FileParameters” dictionary and generate a file named ‘config.txt’ with contents set to the value of the ‘config.txt’ key.

  2. Execute the playbook named ‘<VNFCode>/<Version>/ansible/configure/site.yml’ on nodes with listed IP addresses (or FQDNs) respectively while providing the following key value pairs to the playbook: Retry=3, Wait=5, ConfigFile=config.txt

  3. If execution time of the playbook exceeds 60 secs (across all hosts), it will be terminated.

  4. Inventory hosts file to be build with only IP addresses (or FQDNs), IP addresses and VM names, or IP addresses and VNFC names depending on InventoryNames setting in the template(s) passed to Ansible Server as part of the Rest API request. In a later section with Ansible examples, examples of supported inventory hosts file formats are shared.

VNF License Information Guidelines

This section has been removed as it did not accurately reflect the ONAP Licensing Model. Please refer to the ONAP License Management Information Model for the latest information.

TOSCA model

Table D1. ONAP Resource DM TOSCA/YAML constructs

Standard TOSCA/YAML definitions agreed by VNF SDK Modeling team to be used by VNF vendors to create a standard VNF descriptor.

All definitions are summarized in the table below based on the agreed ONAP Resource DM TOSCA/YAML constructs for Beijing. Their syntax is specified in ETSI GS NFV-SOL001 stable draft for VNF-D.

Requirement Number

Resource IM Info Elements

TOSCA Constructs as per SOL001

R-02454

VNFD.vnfSoftwareVersion

SwImageDesc.Version

For VDU.Compute - tosca.artifacts.nfv.SwImage

For Virtual Storage - tosca.artifacts.Deployment.Image

R-03070

vnfExtCpd’s with virtual NetworkInterfaceRequirements (vNIC)

tosca.nodes.nfv.VnfExtCp with a property tosca.datatypes.nfv.VirtualNetworkInterfaceRequirements

R-09467

VDU.Compute descriptor

tosca.nodes.nfv.Vdu.Compute

R-16065

VDU.Compute. Configurable Properties

tosca.datatypes.nfv.Vnfc ConfigurableProperties

R-30654

VNFD.lifeCycleManagement Script - IFA011 LifeCycleManagementScript

Interface construct tosca.interfaces.nfv.vnf.lifecycle.Nfv with a list of standard LCM operations

R-35851

CPD: VduCp, VnfExtCp, VnfVirtualLinkDesc, QoS Monitoring info element - TBD

tosca.nodes.nfv.VduCp, tosca.nodes.nfv.VnfVirtualLink, tosca.nodes.nfv.VnfExtCp

R-41215

VNFD/VDU Profile and scaling aspect

tosca.datatypes.nfv.VduProfile and tosca.datatypes.nfv.ScalingAspect

R-66070

VNFD meta data

tosca.datatypes.nfv. VnfInfoModifiableAttributes - metadata?

R-96634

VNFD.configurableProperties describing scaling characteristics. VNFD.autoscale defines the rules for scaling based on specific VNF indications

tosca.datatypes.nfv.VnfConfigurableProperties, tosca.datatypes.nfv.ScaleInfo

?

VDU Virtual Storage

tosca.nodes.nfv.Vdu.VirtualStorage

R-01478

R-01556

Monitoring Info Element (TBD) - SOL001 per VNF/VDU/VLink memory-consumption, CPU-utilization, bandwidth-consumption, VNFC downtime, etc.

tosca.capabilities.nfv.Metric - type for monitoring

monitoring_parameter of above type per VNF/VDU/VLink

Table D2. TOSCA CSAR structure

This section defines the requirements around the CSAR structure.

The table below describes the numbered requirements for CSAR structure as agreed with SDC. The format of the CSAR is specified in SOL004.

Requirement Number

Description

CSAR artifact directory

R-26881

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

ROOT\Artifacts\VNF_Image.bin

R-30654

VNFD.lifeCycleManagementScript that includes a list of events and corresponding management scripts performed for the VNF - SOL001

ROOT\Artifacts\Informational\Install.csh

R-35851

All VNF topology related definitions in yaml files VNFD/Main Service template at the ROOT

ROOT\Definitions\VNFC.yaml

ROOT\MainService\Template.yaml

R-40827

CSAR License directory - SOL004

ROOT\Licenses\License_term.txt

R-77707

CSAR Manifest file - SOL004

ROOT\MainServiceTemplate.mf

Ansible Playbook Examples

The following sections contain examples of Ansible playbooks which follow the guidelines.

To see specific documentation for the Ansible Adapter please refer to: APPC Ansible Adapter

Guidelines for Playbooks to properly integrate with APPC/SDN-C

NOTE: To support concurrent requests to multiple playbooks, targeting VNF instances of same or different type, VNF files dynamically created by playbooks with VNF specific default values are kept or created in separate directories.

VNF inventory hosts file names include the VNF instance name and are now created under base inventory directory to preserve properties of (global) inventory/group_vars files with variables, example, site specific attributes for DNS, NTP, etc.

Example of an Ansible command (after pwd) to run playbook again vfdb9904v VNF instance:

$ pwd
/storage/vfdb/V16.1/ansible/configure
$ ansible-playbook -i ../inventory/vfdb9904vhosts site.yml --extra-vars "vnf_instance=vfdb9904v"

NOTE: To preserve Ansible inventory/group_vars capability, that makes
group_vars contents global variables available to all playbooks, when they
reside in the inventory directory, guidelines were updated to name the
VNF inventory hosts file as (a flat file) <VNFName>hosts, stored in the
inventory directory, not a subdirectory under inventory.

Example of corresponding APPC/SDN-C API Call from ONAP – Ansible Server Specifications:

Using a curl request simulating a Rest API POST requesting execution of configure Playbook (using playbook relative path):

curl -u APIUser:APIPassword -H "Content-type:application/json" -X POST
-d '{"Id": "8412", "PlaybookName": "vfdb/V5.x.x/ansible/configure/site.yml",
"Timeout":"600", "EnvParameters": { "vnf_instance": "vfdb9904v" }}'
http://ansible.server.com:5000/Dispatch

Rest API GET request to obtain response/results for prior request (same ID as POST request above):

curl -u APIUser:APIPassword -H 'Content-type: application/json' -X GET
'http://ansible.server.com:5000/Dispatch/?Id=8412&Type=GetResult'

Comments:

  • An ID number is assigned to each request. This ID number is used to track request down to completion and provide status to APPC/SDN-C upon request for status.

  • Playbook Name relative path provided in the request as PlaybookName.

  • Ansible Server Rest API is aware of playbook’s root directory which may vary from instance to instance or Ansible Server cluster to cluster.

Ansible Playbooks will use the VNF instance name (passed using –extra-vars “vnf_instance=vfdb9904v”) to identify other default values to run the playbook(s) against the target VNF instance. Same example as above:

$ ansible-playbook -i ../inventory/vfdb9904vhosts site.yml --extra-vars "vnf_instance=vfdb9904v"

Each Ansible Server or cluster is assigned its own identification to be used to authenticate to VNF VMs using Ansible Server or cluster specific set of SSH keys that may be rotated regularly. Here a hosts file, without any SSH key credentials, to run ansible-playbook command, listed in example above (NOTE: IP addresses were scrubbed):

$ more ../inventory/vfdb9904vhosts
[host]
localhost ansible_connection=local

[oamvip]
1xx.2yy.zzz.108

[oam]
1xx.2yy.zzz.109
1xx.2yy.zzz.110

[rdb]
1xx.2yy.zzz.105
1xx.2yy.zzz.106

[wp0ny:children]
oam
rdb
oamvip

Virtual IP addresses that can be used by multiple VMs, usually, used by the active VM of an active-standby pair, are placed under a group named after the VNFC (VM) type, plus “vip” string, example of such a group name “oamvip”. An inventory hosts file site also contains a (group) with all groups as children (see last four lines in above example), to load site specific variables like NTP, DNS IP addresses, and other site specific variables, making them global variables to be used by playbooks, namely, configure playbook.

NOTE: APPC/SDN-C requests to run Playbooks/Cookbooks target a specific VNF instance, but could be limited to one VM or one type of VM by the request parameters. Actions that may impact a site (LCP), a service, or an entire platform must be orchestrated by MSO in order to execute requests via APPC/SDN-C which then invoke VNF level playbooks. Playbooks that impact more than a single VNF instance are not the current focus of these guidelines.

Creating group_vars sub-directories in the same directory that contains the command/action main playbook, while following Ansible standards, to auto load these variables as global variables is supported as are the majority of Ansible standard capabilities.

Certain VNF Type global variables, for example site specific variables, were moved under inventory/group_vars files in the Beijing release. This way those variables and respective values are available to all playbooks without being explicitly referenced through an include vars statement. Also creating templates that are VNF Type specific moving away from static files that are VNF instance specific.

Any remaining VNF instance specific variables that cannot be obtained from inventory (A&AI) or other sources, that still need to be created or edited manually, in advance of VNF instantiation, shall be created under ansible/vars directory. Recommendation is to use JSON or YAML files, explicitly referenced by the playbooks, for this purpose, example: <VNF_instance_name>.json.

Example of playbook task explicitly referencing a VNF instance specific json file and loading the contents as global variables:

$ cat site.yml
---

...

- name: get json vars
  hosts: localhost
  gather_facts: False
  tasks:
    - name: json attributes and values
      include_vars: "../vars/{{ vnf_instance }}.json"

- name: show variables
  hosts: localhost
  gather_facts: False
  roles:
    - debug
...

# Just another example using YAML file
- name: load vars in a file
 hosts: rdb
...
 vars_files:
   - ../vars/{{ vnf_instance }}.yml

$ ls -1 ../vars
vfdb9904v.json
vfdb9905v.json
vfdb9906v.json
vfdb9904v.yml
vfdb9905v.yml
vfdb9906v.yml

Parameters like VNF names, VNFC names, OA&M IP addresses are extracted from the inventory database (A&AI) by APPC/SDN-C and then passed down to Ansible Server in a NodeList attribute, as part of APPC/SDN-C request through REST API. The Ansible Server Rest API uses the NodeList contents and InventoryNames parameter to build the inventory hosts file for the request, according to VNF playbook design needs, with or without VM or VNFC names. For parameterized playbooks, attribute-value pairs passed down by APPC/SDN-C to Ansible Server, always takes precedence over template or VNF instance specific defaults stored in defaults file(s) as they are made part of the ansible-playbook run command’s "—extra-vars" list.

Example:

$ pwd
/storage/vfdb/latest/ansible
Again, originated from previously re-factored playbooks now being phased out:

$ more vars/vfdb9904v/default_args.yml

vm_config_oam1_vnfc_name: vfdb9904vm001oam001
vm_config_oam1_hostname: vfdb9904vm001
vm_config_oam1_provider_ip_address: 1xx.2yy.zzz.109

vm_config_oam2_vnfc_name: vfdb9904vm002oam001
vm_config_oam2_hostname: vfdb9904vm002
vm_config_oam2_provider_ip_address: 1xx.2yy.zzz.110

vm_config_rdb1_vnfc_name: vfdb9904vm003rdb001
vm_config_rdb1_hostname: vfdb9904vm003
vm_config_rdb1_provider_ip_address: 1xx.2yy.zzz.105

vm_config_rdb2_vnfc_name: vfdb9904vm004rdb001
vm_config_rdb2_hostname: vfdb9904vm004
vm_config_rdb2_provider_ip_address: 1xx.2yy.zzz.106

vm_config_rdb3_vnfc_name: vfdb9904vm005rdb001
vm_config_rdb3_hostname: vfdb9904vm005
vm_config_rdb3_provider_ip_address: 1xx.2yy.zzz.xxx

vm_config_rdb4_vnfc_name: vfdb9904vm006rdb001
vm_config_rdb4_hostname: vfdb9904vm006
vm_config_rdb4_provider_ip_address: 1xx.2yy.zzz.yyy

One of the first tasks on the Ansible Playbooks is to combine the VNF type generic templates, stored on the Ansible Server with playbooks, with the overriding parameters passed down from APPC/SDN-C, to create the VNF instance specific set of attribute-value pairs to be used for the run, in INI format.

Here is an excerpt from such a file that should look somewhat similar to ENV files:

$ more tmp/vfdb9904v/all.yml

deployment_prefix: vfdb9904v
...
timezone: Etc/UTC
...
template_version: '2014-10-16'
stack_name: vfdb9904v
c3dbtype: OAM
stackName: vfdb9904v
juno_base: true
...

# logins list contains ‘login name’, ‘login group’, ‘login password’

logins:
- { name: 'm99999', group: 'm99999', password: 'abcdefgha' }
- { name: 'gsuser', group: 'gsuser', password: ' abcdefgha' }
- { name: 'peruser', group: 'peruser', password: ' abcdefgha' }
- { name: 'dbuser', group: 'dbuser', password: ' abcdefgha' }

NOTE: Arguments passed by APPC/SDN-C to Ansible Server to run a playbook take precedence over any defaults stored in Ansible Server.

Ansible Playbooks – Notes On Artifacts Required to Run Playbooks

Inventory hosts file: should be VNF instance specific.

Default variables: should be VNF instance specific.

Playbooks and paths to referenced files: Playbooks shall not use absolute paths in include or import entries (variables or playbooks) or other types of references.

For this to work properly, when running playbooks, the directory where the main playbook resides shall be the current directory.

Playbook imports, when used, shall use paths relative to the main playbook directory.

Root directory named ansible - Any files provided with playbooks, included, imported, or referenced by playbooks, shall reside under the ansible playbooks (root) directory, containing all playbook subdirectories, or below that ansible root directory, in other subdirectories to support on-boarding and portability of VNF collection of playbooks and related artifacts.

Designing for a shared environment, concurrently running playbooks, targeting multiple VNF instances – inventory hosts file:

To avoid inventory hosts file overwrites or collisions between multiple concurrently running VNF instance requests, chosen approach is for each VNF instance hosts file, to be stored under the Ansible Server Playbooks root directory (ansible), under the inventory subdirectory, on an inventory hosts file named after the VNF instance, as follows:

ansible/inventory/<VNF_instance_name>hosts

Example of inventory hosts file path, relative to ansible playbooks (ansible) root directory (playbooks_dir):

ansible/inventory/vnfx0001vhosts

Designing for a shared environment, concurrently running multiple playbooks, targeting multiple VNF instances – default argument variables for specific VNF instances:

VNF instance specific files referenced/included by playbooks, containing default values, example, default_args.yml, shall be stored under a directory with VNF instance name on the path (backwards compatibility) or contain VNF instance name as part of the name.

Example:

ansible/vars/<VNF_instance_name>/default_args.yml

Example of include statement:

include_vars: ../vars/{{ vnf_instance }}/default_args.yml

Example – all in vars directory:

ansible/vars/<VNF_instance_name>default_args.yml

Example of include statement without vars subdirectory:

include_vars: ../vars/{{ vnf_instance }}default_args.yml

Above example has originated from previously re-factored playbooks now being phased out. Direction is to move away from having to create VNF instance specific files with VNF instance default variables to the extent possible. Moving to extract these values from inventory databases and provide them to Ansible Server as part of APPC/SDN-C request, may be used in a transition from having everything stored in the Ansible Server to APPC/SDN-C extracting and providing VNF instance specific attribute-value pairs to the Ansible Server as part of the request.

Files containing attribute name value pairs (variable name and default values), referenced/included by playbooks – created dynamically by playbooks:

To avoid overwrites or collisions of multiple concurrently running VNF instance requests, files created dynamically by playbooks, based on VNF generic templates, combined with default values and arguments passed down by APPC/SDN-C (as part of the request), shall be stored under a directory with VNF instance name on the path.

Example:

tmp/<VNF_instance_name>/all.yml

Files containing site specific (Openstack location non-instance specific) attribute name value pairs, like NTP server and DNS server’s IP addresses and other parameters, referenced/included by playbooks, not VNF specific – Could/should be stored under inventory/group_vars directory, in a subdirectory named after the string used to identify the site (nyc1, lax2,…).

Examples:

ansible/inventory/group_vars/<Site>

ansible/inventory/group_vars/wp0ny

ansible/inventory/group_vars/la0ca

Ansible Server Design - Directory Structure

To help understanding the contents of this section, here are few basic definitions:

VNF type a.k.a VNF Function Code - Based on current naming convention, each Virtual Network Function is assigned a 4 character string (example vfdb), these are 4 characters in the VNF instance name, followed by (4) numbers, ending in a “v”. The naming convention has evolved to include geographical location. VNF instance name in some cases corresponds to the stack name for the VNF when VNF instance is built based on a single module, single stack. Example of VNF instance name: vfdb9904v. All VNF performing this function, running the same software, coming from the same VNF provider will have the same 4 characters in the VNF instance name, in this example, vfdb.

NOTE: New naming convention includes a prefix indicating geographical location where VNF is instantiated.

VNF type, determined through these 4 characters, is also known as VNF Function Code. All VNF Function Codes can be found in A&AI as well as other Network Design Documents.

Version – VNF software version is the release of the software running on the VNF for which the playbooks were developed. VNF configuration steps may change from release to release and this <Version> in the path will allow the Ansible Server to host playbooks associated with each software release. And run the playbooks that match the software release running on each VNF instance. APPC/SDN-C now support playbook versioning passed as a variable to APP-C to allow multiple actively, in use, playbook versions to be picked to match VNF release/version.

Playbook Function - A name associated with a life cycle management task(s) performed by the playbook(s) stored in this directory. It should clearly identify the type of action(s) performed by the main playbook and possibly other playbooks stored in this same directory. Ideally, playbook function would match APPC/SDN-C corresponding command or function that is performed by the main playbook in this directory. Following Ansible naming standards, main playbook, is named site.yml. There can be other playbooks on the same directory that use a subset of the roles used by the main playbook site.yml. Examples of Playbook Function directory names(matching APPC/SDN-C command name in lowercase):

  • configure – Contains post-instantiation (bulk) configuration playbook(s), roles,…

  • healthcheck – Contains VNF health check playbook(s), roles,…

  • stopapplication – Contains VNF application stop (stopApplication) playbook(s), roles,…

  • startapplication – Contains VNF application start (startApplication) playbook(s), roles,…

  • restartapplication – Contains VNF application restart (restartApplication) playbook(s), roles,…

  • configbackup – Contains VNF configuration backup (ConfigBackup) playbook(s), roles,…

  • configrestore – Contains VNF configuration restore (ConfigBackup) playbook(s), roles,…

  • configmodify – Contains VNF configuration modification (ConfigModify) playbook(s), roles,…

  • configscaleout – Contains VNF scale-out configuration/reconfiguration (ConfigBackup) playbook(s), roles,…

  • quiescetraffic – Contains VNF traffic graceful drain/quiesce (QuiesceTraffic) playbook(s), roles,…

  • resumetraffic – Contains VNF resume/restore traffic (ResumeTraffic) playbook(s), roles,…

  • upgradeprecheck – Contains VNF current (old) SW version check (UpgradePreCheck) playbook(s), roles,…

  • upgradebackup – Contains VNF backup prior to SW upgrade (UpgradeBackup) playbook(s), roles,…

  • upgradesoftware – Contains VNF SW upgrade (UpgradeSoftware) playbook(s), roles,…

  • upgradepostcheck – Contains VNF upgraded (new) SW version check (UpgradePostCheck) playbook(s), roles,…

  • upgradebackout – Contains VNF (SoftwareUpgrade) back out (UpgradeBackout) playbook(s), roles,…

  • license – Contains a playbook to manage licenses, add, upgrade, delete, renew, etc.

  • starttraffic – Contains a playbook used for traffic management (start)

  • stoptraffic – Contains a playbook used for traffic management (stop)

  • distributetraffic – Contains a playbook used for traffic management (distribute/redistribute)

  • statustraffic – Contains a playbook used to check status of traffic (started, stopped, etc.)

  • preconfigcheck – Contains post-instantiation pre-configuration check playbook(s) that makes no configuration changes to the VNF instance, just verifies all conditions are met to successfully run preconfig and/or configure playbooks

  • preconfig – Contains post-instantiation pre-configuration playbook(s), that is to run before running the configure playbook

  • postconfig – Contains post-instantiation post-configuration playbook(s), that is to run after running the configure playbook, example, to integrate VNFs of different types

  • provision – Contains a playbook to run on demand, as needed, load or update provisioning data onto VNF instances

Other playbook actions were added and are supported, example of playbooks supported to run before and after Openstack nova commands:

  • prerebuild & postrebuild

  • premigrate & postmigrate

  • preevacuate & postevacuate

Other playbook actions in use not yet supported by APP-C:

  • postrestart – Contains a playbook used to perform tasks after restarting VNF application or VNF instance or a single VM

  • restartpods – Contains a playbook used to perform tasks to restart application containers

  • user_management – Contains a playbook used to manage user accounts on demand (add, update, delete) as part of VNF instance life cycle management

  • preinstantiate – Contains pre-instantiation playbook(s) to perform preparation tasks in advance of instantiation of a VNF instance

Directory structure to allow hosting multiple version sets of playbooks, for the same VNF type, to be hosted in the runtime environment on the Ansible Servers. Generic directory structure:

Ansible Playbooks – Function directory and main playbook:

<VNF type>/<Version>/ansible/<Playbook Function>/site.yml

Example – Post-instantiation (bulk) configuration – APPC/SDN-C Function - Configure:

<VNF type>/<Version>/ansible/configure/site.yml

Example – Post-instantiation (bulk) configuration – APPC/SDN-C Function – Configure – VNF software version 16.1:

vfdb/V16.1/ansible/configure/site.yml

Example – Health-check - APPC/SDN-C Function - HealthCheck:

<VNF type>/<Version>/ansible/healthcheck/site.yml

OR (Function directory name is not required to match APPC/SDN-C function name exactly)

<VNF type>/<Version>/ansible/check/site.yml

Ansible Directories for other artifacts – VNF inventory hosts file - Required:

<VNF type>/<Version>/ansible/inventory/<VNF instance name>hosts

NOTE: Default groups, in inventory hosts file, will be created based on VNFC type (represented by 3 characters) in VNFC name. Example: “oam”, “rdb”, “dbs”, “man”, “iox”, “app”,…

Ansible Directories for other artifacts – VNF instance specific default arguments – Optional:

<VNF type>/<Version>/ansible/vars/<VNF instance name>.json (Preferred)

OR

<VNF type>/<Version>/ansible/vars/<VNF instance name>.yml
(INI format accepted/supported by Ansible)

NOTE: Requirement remains while manual actions to create or edit VNF or PNF instance specific files are supported all files manually created or edited should be placed in this one directory (ansible/vars).

Ansible Directory for site specific attribute-value pairs (in INI format) - VNF Site files::

<VNF type>/<Version>/ansible/inventory/group_vars/<Site name>

Ansible Directories for other artifacts – VNF (special) other files – Optional – Example – License file:

<VNF type>/<Version>/ansible/<Other directory(s)>

CAUTION: On referenced files used/required by playbooks.

  • To avoid missing files, during on-boarding or uploading of Ansible Playbooks and related artifacts, all permanent files (not generated by playbooks as part of execution), required to run any playbook, shall reside under the ansible root directory or below on other subdirectories.

  • Any references to files, on includes or other playbook entries, shall use relative paths.

  • This is the ansible (root) directory referenced on this note (Ansible Server mount point not included):

<VNF type>/<Version>/ansible/

VNF type directories use A&AI inventory VNF function code. Ansible Playbooks will be stored on a (Cinder) Volume mounted on the Ansible Servers as /storage that is used as a local cache for playbooks and other related artifacts cloned or pulled (updates) from central (git) repository.

Example:

/storage/vfdb/V16.1/ansible – Root directory for database VNF Ansible Playbooks for release 16.1

CAUTION: To support this directory structure as the repository to store Ansible Playbooks run by APPC/SDN-C, APPC/SDN-C API in the Ansible Server side needs to be configured to run playbooks from this directory.

Ansible Server HTTP will be configured to support APPC/SDN-C REST API requests to run playbooks as needed, against specific VNF instances, or specific VM(s) as specified in the request. When a playbook action is expected to target a subset of VMs in a VNF instance, VNF instance inventory hosts file is expected to be used, and an extra-vars parameter, named target_vm_list with the list of VMs to be targeted by the playbook, is expected to be provided to run specific actions targeting the VM subset. The attribute target_vm_list may point to a single name or single IP address or a list of names or IP addresses in between double-quotes with names or IPs seprated by comma, example, target_vm_list=”name1,name2”.

APPC/SDN-C REST API to Ansible Server is documented separately and can be found under ONAP (onap.org).

Ansible Inventory Hosts File – Supported Formats

Supported inventory hosts file examples, built from this NodeList model, extracted from A&AI by APPC/SDN-C and passed to the Ansible Server via Rest API as part of request:

{
  "NodeList": [
      {
          "vnfc_type": "oam",
          "ne_id_vip": "vfdb9904vm001oam001",
          "floating_ip_address_vip": "1xx.2yy.zzz.109",
          "site": "wp0ny",
          "vm_info": [
               {
                   "ne_id": "vfdb9904vm001oam001",
                   "fixed_ip_address": "1xx.2yy.zzz.109"
               },
               {
                   "ne_id": "vfdb9904vm002oam001",
                   "fixed_ip_address": "1xx.2yy.zzz.110"
               }
          ]
      },
      {
          " vnfc_type": "rdb",
          "site": "wp0ny",
          "vm_info": [
               {
                   "ne_id": "vfdb9904vm003rdb001",
                   "fixed_ip_address": "1xx.2yy.zzz.105"
               },
               {
                   "ne_id": "vfdb9904vm004rdb001",
                   "fixed_ip_address": "1xx.2yy.zzz.106"
               }
          ]
      }
  ]
}

With no names, only IP addresses, template “InventoryNames”: “None” (Default)

$ more ../inventory/vfdb9904vhosts
[host]
localhost ansible_connection=local

[oamvip]
1xx.2yy.zzz.108

[oam]
1xx.2yy.zzz.109
1xx.2yy.zzz.110

[rdb]
1xx.2yy.zzz.105
1xx.2yy.zzz.106

[wp0ny:children]
oam
rdb
oamvip

With VM names and IP addresses, template inventory names setting “InventoryNames”: “VM”

$ more ../inventory/vfdb9904vhosts
[host]
localhost ansible_connection=local

[oamvip]
vfdb9904vm001vip ansible_host=1xx.2yy.zzz.108

[oam]
vfdb9904vm001 ansible_host=1xx.2yy.zzz.109
vfdb9904vm002 ansible_host=1xx.2yy.zzz.110

[rdb]
vfdb9904vm003 ansible_host=1xx.2yy.zzz.105
vfdb9904vm004 ansible_host=1xx.2yy.zzz.106

[wp0ny:children]
oam
rdb
oamvip

With VNFC names and IP addresses, template inventory names setting “InventoryNames”: “VNFC”

$ more ../inventory/vfdb9904vhosts
[host]
localhost ansible_connection=local

[oamvip]
vfdb9904vm001oam001vip ansible_host=1xx.2yy.zzz.108

[oam]
vfdb9904vm001oam001 ansible_host=1xx.2yy.zzz.109
vfdb9904vm002oam001 ansible_host=1xx.2yy.zzz.110

[rdb]
vfdb9904vm003rdb001 ansible_host=1xx.2yy.zzz.105
vfdb9904vm004rdb001 ansible_host=1xx.2yy.zzz.106

[wp0ny:children]
oam
rdb
oamvip

Ansible Server – On-boarding Ansible Playbooks

Once playbooks are developed following these guidelines, playbooks need to be on-boarded onto Development Ansible Server(s), and placed under (git) code control. Once a (git) repository is created for the set of playbooks, playbooks are then pushed to the central repository. Using mechanized identification that leverages SSH key based authentication, a mechanism is in place to regularly clone or pull updates from central repository to runtime Ansible Server Clusters, to perform an automated controlled distribution of playbooks and related artifacts to clustered runtime Ansible Servers.

These are the basic steps to on-board playbooks manually onto the Ansible Server.

  1. Upload CSAR, zip, or tar file containing VNF playbooks and related artifacts to Development Ansible Server with connectivity to central repository.

  2. Unzip packaged playbooks or manually create full directory (using –p option below) to store Ansible Playbooks and other artifacts under /storage (or other configured) file system.

    Includes VNF type using VNF function code 4 characters under /storage.

    Includes VNF “Version” directory as part of the path to store playbooks for this VNF version.

    Include generic ansible root directory. Creating full directory path as an example:

$ mkdir –p /storage/vfdb/V16.1/ansible
  1. When manually creating directory structure make this directory (VNF ansible root directory) current directory for next few steps:

cd /storage/vfdb/V16.1/ansible/
  1. Extract Ansible Playbooks and other Ansible artifacts associated with the playbooks onto the ansible directory. Command depends on the type of file uploaded, examples would be:

tar xvf ..
unzip ... # Usually, unzip creates the entire directory structure
  1. Create VNF inventory hosts file with all VMs and OA&M IP addresses, and VM or VNFC names as required for the VNF type, grouped by VM/VNFC type. Add site with all groups as children. Inventory hosts file are required for all VNF instances, to be configured and managed through Ansible. Inventory hosts file example:

$ mkdir inventory

$ touch inventory/vfdb9904vhosts

$ cat inventory/vfdb9904vhosts

[host]
localhost ansible_connection=local

[oamvip]
1xx.2yy.zzz.108

[oam]
1xx.2yy.zzz.109
1xx.2yy.zzz.110

[rdb]
1xx.2yy.zzz.105
1xx.2yy.zzz.106

[wp0ny:children]
oam
rdb
oamvip

Virtual IP addresses that can be used by multiple VMs, usually, used by the active VM of an active-standby pair, are placed under a group named after the VNFC (VM) type, plus “vip” string, example of such a group name “oamvip”.

  1. (Optional) Create directory to hold default arguments for VNF instance, and respective file(s), when required by VNF type, example:

$ mkdir –p vars/vfdb9904v.json
$
$ cat vfdb9904v.json
...
{
  "json_var1": "vfdb9904v_test_var1",
  "json_var2": "vfdb9904v_test_var2",
  "json_var3": "vfdb9904v_test_var3"
}
...

NOTE: Please note names in this file shall use underscore “_” not dots “.” or dashes “-“.

  1. Perform some basic playbook validation running with “–check” option, running dummy playbooks or other.

  2. Make <VNF version> directory current directory to add playbooks and other artifacts under (git) code control:

cd /storage/vfdb/V16.1

NOTE: After creating the repository for the playbooks in the central repository a list of (git) commands is provided to add playbooks under (git) code control and push them to the newly created repository. Each Ansible Server or cluster of Ansible Servers will have its own credentials to authenticate to VNF VMs. Ansible Server SSH public key(s) have to be loaded onto VNF VMs during instantiation or another way before Ansible Server can access VNF VMs and run playbooks. Heat templates used to instantiate VNFs to be configured by these Ansible Servers running playbooks shall include the same SSH public key and load them onto VNF VM(s) as part of instantiation. Same Ansible Server Cluster SSH public keys are to be added to repositories to provide each authorized cluster access, to clone and pull updates, to each VNF collection of playbooks, from central repository.

Other non-vendor specific playbook tasks, required by customer, need to be incorporated in overall post-instantiation configuration playbook. Alternative is for company developed playbooks to be pushed to a repository, distributed and executed, after VNF vendor provided playbooks are run.

A couple of playbooks used for proof-of-concept testing as examples:

UpgradePreCheck:

$ pwd
/storage/comx/V5.3.1.3/ansible/upgradeprecheck

$ more site.yml
---

- import_playbook: ../common/create_vars.yml
- import_playbook: ../common/create_hosts.yml

- name: upgrade software pre check
  hosts: oam,dbs,cpm
  gather_facts: no
  become: true
  become_method: sudo
  become_user: root
  max_fail_percentage: 0
  any_errors_fatal: True
  roles:
    - precheck
  tags: precheck

$ more roles/precheck/tasks/main.yml
---

- include_vars: /tmp/{{ vnf_instance }}/all.yml

- name: get software version installed on vnf
  shell: grep "^SW_VERSION =" /vendor/software/config/param_common.cfg | grep -c "{{ existing_software_version }}"
  register: version_line
  ignore_errors: yes

- name: send msg when matches expected version
  debug:  msg="*** OK *** VNF software release matches (old) release to be upgraded."
   verbosity=1
  when: version_line.stdout.find('1') != -1

# send warning message and failure when release is not a match
- fail:
    msg="*** WARNING *** VNF software release does not match expected (pre-upgrade) release."
  when: (version_line | failed) or version_line.stdout.find('1') == -1

UpgradePostCheck:

$ pwd
/storage/comx/V5.3.1.3/ansible/upgradepostcheck

$ more site.yml
---

- import_playbook: ../common/create_vars.yml
- import_playbook: ../common/create_hosts.yml

- name: upgrade software post check
  hosts: oam,dbs,cpm
  gather_facts: no
  become: true
  become_method: sudo
  become_user: root
  max_fail_percentage: 0
  any_errors_fatal: True
  roles:
    - postcheck
  tags: postcheck

$ more roles/postcheck/tasks/main.yml
---

- include_vars: /tmp/{{ vnf_instance }}/all.yml

- name: get post upgrade software version installed on vnf
  shell: grep "^SW_VERSION =" /vendor/software/config/param_common.cfg | grep -c "{{ new_software_version }}"
  register: version_line
  ignore_errors: yes

- name: send msg when matches expected version
  debug:  msg="*** OK *** VNF software release matches new release."
    verbosity=1
  when: version_line.stdout.find('1') != -1

# send warning message and failure when release is not a match
- fail:
    msg="*** WARNING *** VNF software release does not match expected new (post-upgrade) release."
  when: (version_line | failed) or version_line.stdout.find('1') == -1

Ansible Server – Playbook Example to Discover Ansible Server Mechanized User ID

Example of playbook role discovering runtime Ansible Server mechanized user ID and setting it up on target VNF VM(s) with issued and assigned SSH public key with “from=” clause stored onto xxxxx_id_rsa.frompub file:

$ cat roles/setup_ansible_mechid/tasks/main.yml
---

- name: set mechid
  set_fact:
    ansible_mechid: "{{lookup('ini', 'remote_user section=defaults file=/etc/ansible/ansible.cfg') }}"

- name: set mechid uid
  set_fact:
    ansible_mechuid: "{{lookup('ini', 'remote_user section=defaults file=/etc/ansible/ansible.cfg')[1:] }}"

- debug: msg="mechid {{ ansible_mechid }} ansible_mechuid {{ ansible_mechuid }}"
    verbosity=1

# Create ansible server Mech ID group
- group:
    name: "{{ ansible_mechid }}"
    state: present

# add ansible server mech id user
- user:
    name: "{{ ansible_mechid }}"
    group: "{{ ansible_mechid }}"
    state: present
    comment: "Ansible Server Mech ID"
    expires: 99999
    groups: 0
    uid: "{{ ansible_mechuid }}"

- name: create ansible mech id .ssh directory
  file: path=/home/{{ ansible_mechid }}/.ssh owner={{ ansible_mechid }} group={{ ansible_mechid }} mode=0700 state=directory

- name: touch ansible mech id authorized_keys file
  file: path=/home/{{ ansible_mechid }}/.ssh/authorized_keys owner={{ ansible_mechid }} group={{ ansible_mechid }} mode=0600 state=touch

- name: get path to mechid id_rsa.pub
  set_fact:
    public_key: "{{lookup('ini', 'private_key_file section=defaults file=/etc/ansible/ansible.cfg') }}.frompub"
#   public_key: "{{lookup('ini', 'private_key_file section=defaults file=/etc/ansible/ansible.cfg') }}.pub"

- name: setup authorized_keys file
  authorized_key:
    user: "{{ ansible_mechid }}"
    state: present
    key: "{{ lookup('file', '{{ public_key}}') }}"
…

Service: VES Event Registration 3.2.1

Legal Disclaimer

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.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.

Document

VES Event Registration

Revision

3.2.1

Revision Date

January 28th, 2020

Author

Rich Erickson

Contributors:

Shau-Ann Chang – AT&T

Min Chen – AT&T

Marge Hills – Nokia

Linda Horn – Nokia

Alok Gupta – AT&T

Zu Qiang – Ericsson

Paul Sulewski – Nokia

Introduction

This document specifies a YAML format for the registration of VES Events. The YAML format enables both human designers and applications to parse and understand the fields that will be sent by event sources in conjunction with specific types of events, which are identified by their eventNames.

The semantics of the YAML format are easily extensible to accommodate processing needs that may arise in the future. Among the types of information specified in the YAML are field optionality, restrictions on field values, and event handling recommendations and requirements.

This document should be read in conjunction with the VES Event Listener service specification, which defines the Common Event Format and introduces the concept of specific types of events, identified by eventNames.

Audience

This document is intended to support the following groups:

  • VNF Vendors

  • Service Provider (e.g., AT&T) Teams responsible for deploying VNFs within their infrastructure

VNF vendors will provide a YAML file to the Service Provider that describes the events that their VNFs generate. Using the semantics and syntax supported by YAML, vendors will indicate specific conditions that may arise, and recommend actions that should be taken at specific thresholds, or if specific conditions repeat within a specified time interval.

Based on the vendor’s recommendations, the Service Provider may create another YAML, which finalizes their engineering rules for the processing of the vendor’s events. The Service Provider may alter the threshold levels recommended by the vendor, and may modify and more clearly specify actions that should be taken when specified conditions arise. The Service Provided-created version of the YAML will be distributed to Service Provider applications at design time.

Goal

The goal of the YAML is to completely describe the processing of VNF events in a way that can be compiled or interpreted by applications across a Service Provider’s infrastructure.

Relation to the Common Event Format

The Common Event Format described in the VES Event Listener service specification defines the structure of VES events including optional fields that may be provided.

Specific eventNames registered by the YAML (e.g., an InvalidLicense fault), may require that certain fields, which are optional in the Common Event Format, be present when events with that eventName are published. For example, a fault eventName which communicates an InvalidLicense condition, may be registered to require that the configured licenseKey be provided as a name-value pair in the Common Event Format’s additionalFields structure, within the faultFields block. Anytime an InvalidLicense fault event is detected, designers, applications and microservices across the Service Provider’s infrastructure can count on that name-value pair being present.

The YAML registration may also restrict ranges or enumerations defined in the Common Event Format. For example, eventSeverity is an enumerated string within the Common Event Format with several values ranging from NORMAL to CRITICAL. The YAML registration for a particular eventName may require that it always be sent with eventSeverity set to a single value (e.g., MINOR), or to a subset of the possible enumerated values allowed by the Common Event Format (e.g., MINOR or NORMAL).

Relation to Service Design and Creation

Event registration for a VNF (or other event source) is provided to the Service Provider’s Service Creation and Design Environment (e.g., SDC) as a set of two YAML files consisting of the vendor recommendation YAML and (optionally) the final Service Provider YAML. These YAML files describe all the eventNames that that VNF (or other event source) generates.

Once their events are registered, the Service Creation and Design Environment can then list the registered eventNames (e.g., as a drop down list), for each VNF or other event source (e.g., a service), and enable designers to study the YAML registrations for specific eventNames. YAML registrations are both human readable and machine readable.

The final Service Provider YAML is a type of Service Design and Creation artifact, which can be distributed to Service Provider applications at design time: notably, to applications involved in the collection and processing of VNF events. It can be parsed by those applications so they can support the receipt and processing of VNF events, without the need for any manual, VNF-specific development.

YAML Files

YAML Specification Conformance

YAML files should conform to version 1.2 of the YAML specification available at: http://yaml.org/spec/1.2/spec.html.

Filename

YAML file names should conform to the following naming convention:

{SDCModel}_{SDCModelType}_{v#}.yml

The ‘#’ should be replaced with the current numbered version of the file.

‘SDC’ is a reference to the Service Provider’s Service Design and Creation environment. The SDCModelType is an enumeration with several values of which the following three are potentially relevant:

  • Service

  • Vnf

  • VfModule

The SDCModel is the modelName of the specific modelType whose events are being registered (e.g., the name of the specific VNF or service as it appears in the the Service Design and Creation Environment).

For example:

  • vMRF_Vnf_v1.yml

  • vMRF_Service_v1.yml

  • vIsbcSsc_VfModule_v1.yml

File Structure

Each eventType is registered as a distinct YAML document.

YAML files consist of a series of YAML documents delimited by --- denoting the the start of a document, and – optionally – ... denoting the end of a document. For example:

---
# Event Registration for eventName 'name1'
# details omitted
...
---
# Event Registration for eventName 'name2'
# details omitted
...
---
# Event Registration for eventName 'name3'
# details omitted
...

YAML Syntax and Semantics

YAML registration documents show each relevant VES Common Event Model object and field (i.e., each element) for the eventName being registered, including any extensible fields (e.g., specific name-value pairs).

Qualifiers

Each object or field name in the eventName being registered is followed by a ‘qualifier’, which consists of a colon and two curly braces, for example:

objectOrFieldName: { }

The curly braces contain meta-information about that object or field name (also known as the ‘element’), such as whether it is required to be present, what values it may have, what handling it should trigger, etc…

Semantics have been defined for the following types of meta-information within the curly braces:

Action

The action keyword may be applied to field values or to the event as a whole. The action keyword specifies a set of actions that should be taken if a specified trigger occurs. For example, the action keyword may specify that a threshold crossing alert (i.e., tca) be generated, and/or that a specific microservice handler be invoked, and/or that a specific named-condition be asserted. In the Rules section of the YAML file, tca’s and microservices may be defined on individual named-conditions or on logical combinations of named-conditions.

The action keyword is followed by five values in square brackets. The first two values communicate the trigger, and the last three values communicate the actions to be taken if that trigger occurs:

  1. The first value conveys the trigger level. If the field on which the action is defined reaches or passes through that level, then the trigger fires. If a specific level is not important to the recommended action, the ‘any’ keyword may be used as the first value. (Note: ‘any’ is often used when an action is defined on the ‘event’ structure as a whole).

  2. The second value indicates the direction of traversal of the level specified in the first value. The second value may be up, down, at or ‘any’. ‘any’ is used if the direction of traversal is not important. at implies that it traversed (or exactly attained) the trigger level but it doesn’t matter if the traversal was in the up direction or down direction. Note: If up, down or at are used, the implication is that the microservices processing the events within the service provider are maintaining state (e.g., to know that a measurement field traversed a trigger level in an up direction, the microservice would have to know that the field was previously below the trigger level). When initially implementing support for YAML actions, a service provider may choose to use and interpret these keywords in a simpler way to eliminate the need to handle state. Specifically, they may choose to define and interpret all up guidance to mean ‘at the indicated trigger level or greater’, and they may choose to define and interpret all down guidance to mean ‘at the indicated trigger level or lower’.

  3. The third value optionally names the condition that has been attained when the triggers fires (e.g., invalidLicence or capacityExhaustion). Named-conditions should be expressed in upper camel case with no underscores, hyphens or spaces. In the Rules section of the YAML file, named-conditions may be used to specify tca’s that should be generated and/or microservices that should be invoked. If it is not important to name a condition, then the keyword null may be used as the third value.

  4. The fourth value recommends a specific microservice (e.g., rebootVm or rebuildVnf) supported by the Service Provider, be invoked if the trigger is attained. Design time processing of the YAML by the service provider can use these directives to automatically establish policies and configure flows that need to be in place to support the recommended runtime behavior.

    • If a vendor wants to recommend an action, it can either work with the service provider to identify and specify microservices that the service provider support, or, the vendor may simply indicate and recommend a generic microservice function by prefixing RECO- in front of the microservice name, which should be expressed in upper camel case with no underscores, hyphens or spaces.

    • The fourth value may also be set to null.

  5. The fifth value third value indicates a specific threshold crossing alert (i.e., tca) that should be generated if the trigger occurs. This field may be omitted or provided as null.

    • Tca’s should be indicated by their eventNames.

    • When a tca is specified, a YAML registration for that tca eventName should be added to the event registrations within the YAML file.

Examples:

event: {
 action: [
   any, any, null, rebootVm
 ]
}

# whenever the above event occurs, the VM should be rebooted

fieldname: {
 action: [ 80, up, null, null, tcaUpEventName ],
 action: [ 60, down, overcapacity, null ]
}

# when the value of fieldname crosses 80 in an up direction,
# tcaUpEventName should be published; if the fieldname crosses 60
# in a down direction an 'overCapacity' named-condition is asserted.
AggregationRole

The aggregationRole keyword is applied to the value keyword in a field of a name-value pair.

The field aggregationRole may be set to one of the following:

  • cumulativeCounter

  • gauge

  • index

  • reference

index identifies a field as an index or a key for aggregation.

reference fields have values that typically do not change over consecutive collection intervals.

gauge values may fluctuate from one collection interval to the next, i.e., increase or decrease.

cumulativeCounter values keep incrementing regardless of collection interval boundaries until they overflow, i.e., until they exceed a maximum value specified by design. Typically, delta calculation is needed based on two cumulativeCounter values over two consecutive collection intervals.

If needed, the aggregationRole setting tells the receiving event processor how to aggregate the extensible keyValuePair data. Data aggregation may use a combination of index and reference data fields as aggregation keys while applying aggregation formulas, such as summation or average on the gauge fields.

Example 1:

  • Interpretation of the below: If additionalMeasurements is supplied, it must have key name1 and name1’s value should be interpreted as an index:

additionalMeasurements: {
  presence: optional, array: [
    {
      name: {presence: required},
      arrayOfFields: {
        presence: required, array: [
          {
            name: {presence: required, value: name1},
             value: {presence: required, aggregationRole: index}
          }
        ]
      }
    }
  ]
}

Example 2:

  • Let’s say a VNF wants to send the following TunnelTraffic fields through a VES arrayOfFields structure (specifically through additionalMeasurements in the VES measurementField block):

Tunnel Name

Tunnel Type

Total Output Bytes

Total Output Packets

Total Output Errors

ST6WA21CRS:TUNNEL-TE40018

PRIMARY

2457205

21505

0

ST6WA21CRS:TUNNEL-TE1029

PRIMARY

46677

220

0

ST6WA21CRS:TUNNEL-TE1028

PRIMARY

80346

577

0

  • Tunnel Name is an index, Tunnel Type is reference data and the other three columns are counters

  • The first three columns would be sent through VES as follows:

additionalMeasurements: {
  presence: required, array: [
    {
      name: { presence: required, value: TunnelTraffic},
      arrayOfFields: {
        presence: required, array: [
          {
            name: { presence: required, value: TunnelName},
            value: { presence: required, aggregationRole: index},
          },
          {
            name: { presence: required, value: TunnelType},
            value: { presence: required, aggregationRole: reference}
          },
          {
            name: { presence: required, value: TotalOutputBytes},
            value: { presence: required, aggregationRole: gauge, castTo:number }
          }
        ]
      }
    }
  ]
}
Array

The array keyword indicates that the element is an array; array: is following by square brackets which contain the elements of the array. Note that unlike JSON itself, the YAML registration will explicitly declare the array elements and will not communicate them anonymously.

Examples:

element: {
  array: [
    firstArrayElement: { },
    secondArrayElement: { }
  ]
}
CastTo

The castTo keyword is applied to value keywords. It tells the receiving event processor to cast (or interpret) the supplied value from its standard VES datatype (typically a string) to some other datatype. If not supplied the implication is the standard VES datatype applies.

A value may be castTo one and only one of the following data types:

  • boolean

  • integer

  • number (note: this supports decimal values as well as integral values)

  • string

Example:

fieldname: { value: [ x, y, z ], castTo: number }
# only values 'x','y', or 'z' allowed

# each must be cast to a number

additionalMeasurements: {
  presence: optional, array: [
    {
      name: { presence: required},
      arrayOfFields: {
        presence: required, array: [
          {
            name: { presence: required, value: name1},
            value: { presence: required, castTo: number}
          }
        ]
      }
    }
  ]
}

For another example, see the second example under AggregationRole.

Comment

The comment keyword enables event registrations to communicate additional information, in the form of a quoted string, to designers consuming the event registration. Such additional information might convey meaning, instructions or potential effects associated with particular fields or with the event as a whole.

Examples:

fieldname: {
  range: [ 1, unbounded ],
  default: 5,
  comment: "needs further diagnosis; call the TAC"
}
fieldname: {
  value: [ red, white, blue ],
  default: blue,
  comment: "red indicates degraded quality of service"
}
event: {
  presence: required,
  comment: "this event only occurs in conditions when the
  ipq has stopped operating; manual reset may be required",
  structure: { . . . }
}
Default

The default keyword specifies a default field value. Note: the default value must be within the range or enumeration of acceptable values.

Examples:

fieldname: { range: [ 1, unbounded ], default: 5 }
fieldname: { value: [ red, white, blue ], default: blue }
HeartbeatAction

The heartbeatAction keyword is provided on the event objectName for heartbeat events only. It provides design time guidance to the service provider’s heartbeat processing applications (i.e., their watchdog timers). The syntax and semantics of the heartbeatAction keyword are similar to the action keyword except the trigger is specified by the first field only instead of the first two fields. When the heartbeatAction keyword is indicated, the first field is an integer indicating the number of successively missed heartbeat events. Should that trigger occur, the remaining fields have the same order, meaning and optionality as those described for the action keyword.

Examples:

event: { heartbeatAction: [ 3, vnfDown, RECO-rebootVnf, tcaEventName] }

# whenever the above event occurs, a vnfDown condition is asserted
# and the vnf should be rebooted, plus the indicated tca should be
# generated.
keyValuePairString

The keyValuePairString keyword describes the key-value pairs to be communicated through a string (e.g., in the VES Syslog Fields syslogSData or additionalFields strings). This keyword takes three parameters:

  • The first parameter specifies the character used to delimit (i.e., to separate) the key-value pairs. If a space is used as a delimiter, it should be communicated within single quotes as ‘ ‘; otherwise, the delimiter character should be provided without any quotes.

  • The second parameter specifies the characters used to separate the keys and values. If a space is used as a separator, it should be communicated within single quotes as ‘ ‘; otherwise, the separator character should be provided without any quotes.

  • The third parameter is a “sub-keyword” (i.e., it is used only within keyValuePairString) called keyValuePairs: [ ]. Within the square brackets, a list of keyValuePair keywords can be provided as follows:

    • Each keyValuePair is a structure (used only within keyValuePairs) which has a key and a value. Each keyValuePair, key and value may be decorated with any of the other keywords specified in this specification (e.g., with presence, value, range and other keywords).

Examples:

  • The following specifies an additionalFields string which is stuffed with ‘key=value’ pairs delimited by the pipe (’|’) symbol as in (“key1=value1|key2=value2|key3=value3…”).

additionalFields: {
  presence: required, keyValuePairString: {
    \|, =, keyValuePairs: [
      keyValuePair: {
        presence: required, structure: {
          key: { presence: required, value: someKeyName},
          value: { presence: required, range: [0, 100]}
        }
      },
      keyValuePair: {
        presence: optional, structure: {
          key: { presence: required, value: someOtherKeyName},
          value: { presence: required, value [red, white, blue]}
        }
      }
    ]
  }
}
Presence

The presence keyword may be defined as ‘required’ or ‘optional’. If not provided, the element is assumed to be ‘optional’.

Examples:

element: { presence: required } # element must be present
element: { presence: optional } # element is optional
element: { value: blue }
# by omitting a presence definition, the element is assumed to be optional
Range

The range keyword applies to fields (i.e., simpleTypes); indicates the value of the field is a number within a specified range of values from low to high (inclusive of the indicated values).``range:`` is followed by two parameters in square brackets:

  • the first parameter conveys the minimum value

  • the second parameter conveys the maximum value or ‘unbounded’

The keyword ‘unbounded’ is supported to convey an unbounded upper limit. Note that the range cannot override any restrictions defined in the VES Common Event Format.

Examples:

fieldname: { range: [ 1, unbounded ] }
fieldname: { range: [ 0, 3.14 ] }
Structure

The structure keyword indicates that the element is a complexType (i.e., an object) and is followed by curly braces containing that object.

Example:

objectName: {
  structure: {
    element1: { },
    element2: { },
    anotherObject: {
      structure: {
        element3: { },
        element4: { }
      }
    }
  }
}
Units

The units qualifier may be applied to values provided in VES Common Event Format extensible field structures. The ‘units’ qualifier communicates the units (e.g., megabytes, seconds, Hz) that the value is expressed in. Note: the ‘units’ should not contain any space characters (e.g., use ‘numberOfPorts’ or ‘number_of_ports’ but not ‘number of ports’).

Example:

field: {
  structure: {
    name: { value: pilotNumberPoolSize },
    value: { units: megabytes } # the value will be expressed in megabytes
  }
}
Value

The value keyword applies to fields (i.e., simpleTypes); indicates a single value or an enumeration of possible values. If not provided, it is assumed the value will be determined at runtime. Note that the declared value cannot be inconsistent with restrictions defined in the VES Common Event Format (e.g., it cannot add an enumerated value to an enumeration defined in the Common Event Format, but it can subset the defined enumerations in the Common Event Format).

Values that are strings containing spaces should always be indicated in single quotes.

Examples:

fieldname: { value: x } # the value is 'x'
fieldname: { value: [ x, y, z ] }
# the value is either 'x', 'y', or 'z'
fieldname: { presence: required }
# the value will be provided at runtime
fieldname: { value: 'error state' }
# the value is the string within the single quotes
Rules
Rules Document

After all events have been defined, the YAML file may conclude with a final YAML document delimited by ‘- - -’ and ‘…’, which defines rules based on the named ‘conditions’ asserted in action qualifiers in the preceding event definitions. For example:

---

# Event Registration for eventName 'name1'

event: {
  presence: required,
  action: [any, any, A, null],
  structure: {# details omitted}
}
...
---

# Event Registration for eventName 'name2'
event: {
  presence: required,
  structure: {
    commonEventHeader: {
      presence: required,
      structure: {# details omitted}
    },
    measurements: {
      presence: required,
      structure: {
        cpuUsageArray: {
          presence: required,
          array: {
            cpuUsage: {
              presence: required,
              structure: {
                cpuIdentifier: {
                  presence: required
                },
                percentUsage: {
                  presence: required,
                  action: [90, up, B, null]
                }
              }
            }
          }
        }, # details omitted
      }
    }
  }
}
...
---

# Rules

rules: [
  # defined based on conditions 'A' and 'B' - details omitted
]

...
Rules Syntax and Semantics

The YAML rules document begins with the keyword rules followed by a colon and square brackets. Each rule is then defined within the square brackets. Commas are used to separate rules.

Each rule is expressed as follows:

rule: {
  trigger: *logical expression in terms of conditions*,
  microservices: [ *microservice1, microservice2, microservice3…* ],
  alerts: [tcaE*ventName1, tcaEventName2, tcaEventName3…* ]
}

Notes:

  • All referenced tcaEventNames should be defined within the YAML.

  • For information about microservices, see section 3.1.1 bullet number 4.

  • At least one microservice or alert should be specified, and both microservices and alerts may be specified.

Simple Triggers

The trigger is based on the named conditions asserted in the action qualifiers within the event definitions earlier in the YAML file. The following logical operators are supported:

  • &: which is a logical AND

  • ||, which is a logical OR

In addition parentheses may be used to group expressions.

Example logical expression:

(A & B) || (C & D)

Where A, B, C and D are named conditions expressed earlier in the YAML file.

Example rules definition:

rules: [
  rule: {
    trigger: A,
    alerts: [tcaEventName1],
    microservices: [rebootVm]
  },
  rule: {
    trigger: B || (C & D),
    microservices: [scaleOut]
  }
]

Note: when microservices are defined in terms of multiple event conditions, the designer should take care to consider whether the target of the microservice is clear (e.g., which VNF or VM instance to perform the action on). Future versions of this document may provide more clarity.

Time Based Qualifiers

Time based rules may be established by following any named condition with a colon and curly braces. The time based rule is placed in the curly braces as follows:

trigger: B:{3 times in 300 seconds}

This means that if condition B occurs 3 (or more) times in 300 seconds (e.g., 5 minutes), the trigger fires.

More complex triggers can be created as follows:

trigger: B:{3 times in 300 seconds} | | (C & D:{2 times in 600 seconds}),

This means that the trigger fires if condition B occurs 3 (or more) times in 5 minutes, OR, if condition D occurs 2 (or more) times in 10 minutes AND condition C is in effect.

PM Dictionary

The Performance Management (PM) Dictionary is used by analytics applications to interpret and process perf3gpp measurement information from network functions, including measurement name, measurement family, measured object class, description, collection method, value ranges, unit of measure, triggering conditions and other information. The ultimate goal is for analytics applications to dynamically process new and updated measurements based on information in the PM Dictionary.

The PM dictionary is supplied by NF vendors in a single YAML file composed of two parts:

  • PM Dictionary Schema: specifies meta-information about performance measurements from that NF. The meta-information is conveyed using standard meta-information keywords and may be extended to include vendor-specific meta-information keywords. The PM Dictionary Schema may also convey a range of vendor-specific values for some of the keywords. There is one PM Dictionary Schema provided per YAML file. It must be the first YAML document in the PM Dictionary YAML file, if the file contains multiple documents.

  • PM Dictionary Measurements: defines specific measurements sent by vendor NFs (each of which is compliant with the PM Dictionary Schema provided in the same YAML file). Each PM Dictionary Measurement is specified in a separate YAML document and is composed of two parts; pmHeader and pmFields. The pmHeader values MUST be the same for all PM Dictionary Measurements in a single PM Dictionary YAML file.

PM Dictionary Schema Keywords

The following is a list of standard PM Dictionary Schema Keywords:

pmHeader Keywords:

Keyword

Description

M/O

Example

nfType

NF type to whom this PM Dictionary applies. nfType is vendor defined and should match the nfName-vendor string used in the fileReady or perf3gpp eventName

M

gnb-Nokia

pmDefSchemaVsn

Version of the PM Dictionary Schema used for this PM Dictionary. Schema versions are specified in the VES Event Registration Specifications. The latest PM Dictionary Schema Version 2.0 ( described in this document)

M

2.0

pmDefVsn

Version of the PM Dictionary. Version is vendor defined.

M

5G19_1906_002

pmFields Keywords:

Keyword

Description

M/O

Example

iMeasInfoId

Vendor defined integer identifier for measInfoId for efficiency in GPB.

O

2024

iMeasType

Vendor defined integer identifier for measType for efficiency in GPB.

O

2

measAdditionalFields

Hashmap of vendor specific PM Dictionary fields

O

vendorField1

measChangeType

For the measLastChange ,indicates the type of change made for this measurement. Valid values are added, modified or deleted. Deleted measurements may be kept in the PM Dictionary for one release or more or permanently for historical purposes, if desired.

M

added

measCollectionMethod

Collection Method for the measurement. 3GPP-defined collection methods are CC, SI, DER and Gauge. Collection Methods for 3GPP-defined 4G measurements are specified in 3GPP TS 32.425 item b). Collection Methods for 3GPP-defined 5G measurements are specified in 3GPP TS 28.552 item c). The measCollectionMethod values supported by a vendor are specified in the PM Dictionary YAML using the “value” attribute and may include vendor-defined collection methods not specified by 3GPP; for example Average.

M

SI

measCondition

Text description of the condition that causes the measurement to be updated. Conditions for 3GPP-defined 4G measurements are specified in 3GPP TS 32.425 item c). Conditions for 3GPP-defined 5G measurements are specified in 3GPP TS 28.552 item c). Vendors are free to augment or modify the 3GPP-provided conditions to more accurately describe their measurements as needed.

M

This measurement is obtained by sampling at a pre-defined interval, the number of users in RRC connected mode for each NR cell and then taking the arithmetic mean.

measDescription

Text description of the purpose of the measurement, what information does the measurement provide. Descriptions for 3GPP-defined 4G measurements are specified in 3GPP TS 32.425 item a). Descriptions for 3GPP-defined 5G measurements are specified in 3GPP TS 28.552 item a). Vendors are free to augment or modify the 3GPP-provided descriptions to more accurately describe their measurements as needed.

M

This measurement provides the mean number of users in RRC connected mode during each granularity period.

measFamily

Abbreviation for a family of measurements , in 3GPP format where specified, else vendor defined. Family name abbreviations for 3GPP-defined 4G measurements are specified in 3GPP TS 32.425 Section 3.1. Family name abbreviations for 3GPP-defined 5G measurements are specified in 3GPP TS 28.552 Section 3.4.

O

RRC

measInfoId

Name for a group of related measurements, in 3GPP format where specified, else vendor defined. Family names for 3GPP-defined 4G measurements are specified in 3GPP TS 32.425 Section 3.1. Family names for 3GPP-defined 5G measurements are specified in 3GPP TS 28.552 Section 3.4.

O

Radio Resource Control

measLastChange

PM Dictionary version the last time this measurement was changed, added or deleted.

M

5G18A_1807_003

measObjClass

Measurement Object Class. Object classes for 3GPP-defined 4G measurements are specified in 3GPP TS 32.425 item f). Object classes for 3GPP-defined 5G measurements are specified in 3GPP TS 28.552 item f). The measObjClass values supported by a vendor are specified in the PM Dictionary YAML using the “value” attribute and may include vendor-defined objects not specified by 3GPP; for example IPSEC.

M

NRCellCU

measResultRange

Range for the measurement result. The range is specified as a comma separated list of discrete values or a range of values specified as minimum value-maximum value with no spaces. Result ranges for 3GPP-defined 4G measurements are specified in 3GPP TS 32.425 item d) if applicable. Result ranges for 3GPP-defined 5G measurements are specified in 3GPP TS 28.552 item d) if applicable.

O

measResultType

Data type of the measurement result. Result data types for 3GPP-defined 4G measurements are specified in 3GPP TS 32.425 item d). Result data types for 3GPP-defined 5G measurements are specified in 3GPP TS 28.552 item d). The measResultType values supported by a vendor are specified in the PM Dictionary YAML using the “value” attribute and may include vendor-defined data types not specified by 3GPP; for example boolean.

M

measResultUnits

Unit of measure for the result; e.g. milliseconds, bytes, kilobytes, packets, number. Unit of measure for 3GPP-defined 4G measurements are specified in 3GPP TS 32.425 item d) if applicable. Unit of measure for 3GPP-defined 5G measurements are specified in 3GPP TS 28.552 item d) if applicable. The measResultsUnits values supported by a vendor are specified in the PM Dictionary YAML using the “value” attribute and may include vendor-defined units of measure not specified by 3GPP; for example ethernet frames.

O

measType

Measurement name used in PM file, in 3GPP format where specified ,else vendor defined. Names for 3GPP-defined 4G measurements are specified in 3GPP TS 32.425 item e). Names for 3GPP-defined 5G measurements are specified in 3GPP TS 28.552 item e). Vendor defined names are preceded with VS.

M

RRC.ConnMean

sMeasInfoId

Vendor defined string identifier for measInfoId; could be the same as measInfoId or shortened version like measFamily for efficiency in GPB.

O

RRC

sMeasType

Vendor defined string identifier for measType; could be the same as measType or it could be a shortened version for efficiency in GPB.

O

RRC.ConnMean

PM Dictionary Schema Example

The following is a sample PM Dictionary Schema:

---
# PM Dictionary schema specifying and describing the meta information
# used to define perf3gpp measurements in the PM Dictionary

pmMetaData: { presence: required, structure: {
  pmHeader: {
    presence: required,
    structure: {
        nfType: {
            presence: required,
            comment: "NF type; should match the nfName-vendor string used in
                      the fileReady or perf3gpp eventName"
        },
        pmDefSchemaVsn: {
            presence: required,
            value: 2.0,
            comment: "PM Dictionary Schema Version from the VES Event
                      Registration specification"
        },
        pmDefVsn: {
            presence: required,
            comment: "vendor-defined PM Dictionary version"
        }
    }
  },
  pmFields: {
    presence: required,
    structure: {
        iMeasInfoId: {
            presence: required,
            comment: "vendor-defined integer measurement group identifier"
        },
        iMeasType: {
            presence: required,
            comment: "vendor-defined integer identifier for the measType;
                      must be combined with measInfoId to identify a
                      specific measurement."
            },
        measChangeType: {
            presence: required,
            value: [added, modified, deleted],
            comment: "indicates the type of change that occurred during
                      measLastChange"
        },
        measCollectionMethod: {
            presence: required,
            value: [CC, SI, DER, Gauge, Average],
            comment: "the measurement collection method; CC, SI, DER and
                      Gauge are as defined in 3GPP; average contains the
                      average value of the measurement during the
                      granularity period"
        },
        measCondition: {
            presence: required,
            comment: "description of the condition causing the measurement"
        },
        measDescription: {
            presence: required,
            comment: "description of the measurement information
                      and purpose"
        },
        measFamily: {
            presence: required,
            comment: "abbreviation for a family of measurements, in
                      3GPP format, or vendor defined"
        },
        measInfoId: {
            presence: required,
            comment: "name for a group of related measurements in
                      3GPP format or vendor defined"
        },
        measLastChange: {
            presence: required,
            comment: "version of the PM Dictionary the last time this
                      measurement was added, modified or deleted"
        },
        measObjClass: {
            presence: required,
            value: [NGBTS, NGCELL, IPNO, IPSEC, ETHIF],
            comment: "measurement object class"
        },
        measResultRange: {
            presence: optional,
            comment: "range of the measurement result; only necessary when
                      the range is smaller than the full range of the
                      data type"
        },
        measResultType: {
            presence: required,
            value: [float, uint32, uint64],
            comment: "data type of the measurement result"
        },
        measResultUnits: {
            presence: required,
            value: [seconds, minutes, nanoseconds, microseconds, dB,
                    number, kilobytes, bytes, ethernetFrames,
                    packets, users],
            comment: "units of measure for the measurement result"
        },
        measType: {
            presence: required,
            comment: "measurement name in 3GPP or vendor-specific format;
                      vendor specific names are preceded with VS"
        },
        measAdditionalFields: {
        presence: required,
        comment: "vendor-specific PM Dictionary fields",
        structure: {
            vendorField1: {
                presence: required,
                value: [X, Y, Z],
                comment: "vendor field 1 description"
            },
            vendorField2: {
                presence: optional,
                value: [A, B],
                comment: "vendor field 2 description."
            }
        }
    }
  }
}
...

Note: The measAdditionalFields can be different for different vendors and NF Types. The PM Dictionary Schema specifies what measAdditionalFields are provided for this particular NF type.

PM Dictionary Measurement Example

The following are PM Dictionary measurement examples in both bracketed and indent-style YAML formats

# PM Dictionary perf3gpp measurements for the gnb-Nokia NF (bracket style yaml)
---
pmMetaData: {
  pmHeader: {
      nfType: gnb-Nokia,
      pmDefSchemaVsn: 2.0,
      pmDefVsn: 5G19_1906_002
  },
  pmFields: {
      iMeasInfoId: 2204,
      iMeasType: 1,

      measCollectionMethod: CC,
      measCondition: "This measurement is updated when X2AP: SgNB Modification Required message is sent to MeNB
                      with the SCG Change Indication set as PSCellChange.",
      measDescription: "This counter indicates the number of intra gNB intra frequency PSCell change attempts.",
      measFamily: NINFC,
      measInfoId: "NR Intra Frequency PSCell Change",
      measLastChange: 5G18A_1807_003,
      measObjClass: NGCELL,
      measResultRange: 0-4096,
      measResultType: integer,
      measResultUnits: number,
      measType: VS.NINFC.IntraFrPscelChAttempt,
      measAdditionalFields: {
        vendorField1: X,
        vendorField2: B
      }
    }
}
...
---
pmMetaData: {
  pmHeader: {
      nfType: gnb-Nokia,
      pmDefSchemaVsn: 2.0,
      pmDefVsn: 5G19_1906_002
  },
  pmFields: {
      iMeasInfoId: 2204,
      iMeasType: 2,
      measCollectionMethod: CC,
      measCondition: "This measurement is updated when the TDCoverall timer has elapsed before gNB receives the X2AP: SgNB Modification Confirm message.",
      measDescription: "This measurement the number of intra gNB intra frequency PSCell change failures due to TDCoverall timer expiry.",
      measFamily: NINFC,
      measInfoId: "NR Intra Frequency PSCell Change",
      measLastChange: 5G18A_1807_003,
      measObjClass: NGCELL,
      measResultRange: 0-4096,
      measResultType: integer,
      measResultUnits: number,
      measType: VS.NINFC.IntraFrPscelChFailTdcExp,
      measAdditionalFields: {
        vendorField1: Y
      }
    }
}
...
---
pmMetaData: {
  pmHeader: {
      nfType: gnb-Nokia,
      pmDefSchemaVsn: 2.0,
      pmDefVsn: 5G19_1906_002
  },
  pmFields: {
      iMeasInfoId: 2206,
      iMeasType: 1,
      measCondition: "This measurement is updated when MeNB replies to X2AP: SgNB Modification Required message with the X2AP: SgNB Modification Refuse message.",
      measCollectionMethod: CC,
      measDescription: "This counter indicates the number of intra gNB intra frequency PSCell change failures due to MeNB refusal.",
      measFamily: NINFC
      measInfoId: "NR Intra Frequency PSCell Change",
      measLastChange: 5G19_1906_002,
      measObjClass: NGCELL,
      measResultRange: 0-4096,
      measResultType: integer,
      measResultUnits: number,
      measType: VS.NINFC.IntraFrPscelChFailMenbRef,
      measAdditionalFields: {
        vendorField1: Z,
        vendorField2: A
      }
  }
}
...
# PM Dictionary perf3gpp measurements for the gnb-Nokia NF (indented style yaml)
---
pmDictionary:
  pmHeader:
    nfType: gnb-Nokia
    pmDefSchemaVsn: 2.0
    pmDefVsn: 5G19_1906_002
  pmFields:
      iMeasInfoId: 2204
      iMeasType: 1
      measCollectionMethod: CC
      measCondition: "This measurement is updated when X2AP: SgNB Modification Required message is sent to MeNB with the SCG Change Indication set as PSCellChange."
      measDescription: "This counter indicates the number of intra gNB intra frequency PSCell change attempts."
      measFamily: NINFC
      measInfoId: "NR Intra Frequency PSCell Change"
      measLastChange: 5G18A_1807_003
      measObjClass: NGCELL
      measResultRange: 0-4096
      measResultType: integer
      measResultUnits: number
      measType: VS.NINFC.IntraFrPscelChAttempt
      measAdditionalFields:
        vendorField1: X
        vendorField2: B
...
---
pmMetaData:
  pmHeader:
    nfType: gnb-Nokia
    pmDefSchemaVsn: 2.0
    pmDefVsn: 5G19_1906_002
  pmFields:
      iMeasInfoId: 2204
      iMeasType: 2
      measCollectionMethod: CC
      measCondition: "This measurement is updated when the TDCoverall timer has elapsed before gNB receives the X2AP: SgNB Modification Confirm message."
      measDescription: "This measurement the number of intra gNB intra frequency PSCell change failures due to TDCoverall timer expiry."
      measFamily: NINFC
      measInfoId: "NR Intra Frequency PSCell Change"
      measLastChange: 5G18A_1807_003
      measObjClass: NGCELL
      measResultRange: 0-4096
      measResultType: integer
      measResultUnits: number
      measType: VS.NINFC.IntraFrPscelChFailTdcExp
      measAdditionalFields:
        vendorField1: Y
...
---
pmMetaData:
  pmHeader:
    nfType: gnb-Nokia
    pmDefSchemaVsn: 2.0
    pmDefVsn: 5G19_1906_002
  pmFields:
      iMeasInfoId: 2206
      iMeasType: 1
      measCollectionMethod: CC
      measCondition: "This measurement is updated when MeNB replies to X2AP: SgNB Modification Required message with the X2AP: SgNB Modification Refuse message."
      measDescription: "This counter indicates the number of intra gNB intra frequency PSCell change failures due to MeNB refusal."
      measFamily: NINFC
      measInfoId: "NR Intra Frequency PSCell Change"
      measLastChange: 5G19_1906_002
      measObjClass: NGCELL
      measResultRange: 0-4096
      measResultType: integer
      measResultUnits: number
      measType: VS.NINFC.IntraFrPscelChFailMenbRef
      measAdditionalFields:
        vendorField1: Z
        vendorField2: A
...
FM Meta Data

FM Meta Data enables vendors to provide meta information about FM events using a set of standard keywords. FM Meta Data is conveyed in the YAML event registration using the YAML Comment qualifier.

The FM Meta Data section is optional. FM Meta Data includes Alarm Meta Data and Fault Meta Data:

  • Alarm Meta Data, if provided, shall be placed in the YAML comments qualifier at the top of the event registration for the alarm.

  • Fault Meta Data, if provided, shall be placed in the YAML comments qualifier of faultFields.alarmAdditionalInformation within each alarm.

FM Meta Data keywords must be provided in ‘hash format’ as Keyword: Value. Values containing whitespace must be enclosed in single quotes. Successive keywords must be separated by commas. These conventions will make machine processing of FM Meta Data Keywords easier to perform.

Alarm Meta Data Keywords

The following is a list of standard Alarm Meta Data Keywords. Note: the keywords are in CAPS so they can be easily found within the YAML comments. R / O refers to recommended / optional.

Keyword

R/O

Description

ALARM ID

O

Gives a unique numerical Identifier for the alarm.

ALARM NAME

R

Gives a short, concise meaningful name of the alarm in camel format with no spaces, for example baseStationSynchronizationProblem. Note: Alarm Name meta data must match the name used in alarmCondition in the faultFields of the VES Fault Event to provide the cross reference between the Fault Event and its associated FM Meta Data.

ALARM DESCRIPTION

R

Provides a descriptive meaning of the alarm condition. This is intended to be read by an operator to give an idea of what happened.

ALARM EFFECT

R

Provides a description of the consequences when this alarm condition occurs. This is intended to be read by an operator to give a sense of the effects, consequences, and other impacted areas of the system.

ADDITIONAL TEXT

O

This field Contains further information on the alarm in free form text.See ITU-T Recommendation X.733 clause 8.1.2.13.

ASSOCIATED FAULTS

O

Indicates the associated faults that triggered this alarm. List of Fault IDs associated with the alarm which can be cross indexed against a vendor provided fault information.

CLEARING TYPE

R

Indicates whether the alarm is automatically or manually cleared. Valid values are Automatic or Manual.

EVENT TYPE

O

Indicates the type of alarm. Event Types are found in 3GPP TS 32.111 Annex A. The types are: Communications Alarm, Processing Error Alarm, Environmental Alarm, Quality of Service Alarm, Equipment Alarm, Integrity Violation, Operational Violation, Physical Violation, Security Service or Mechanism Violation, or Time Domain Violation. Note that eventCategory in the faultFields of the VES Fault Event may contain the event type.

MANAGED OBJECT CLASSES

R

Indicates the list of possible managed object classes (MOCs) associated with this alarm. Note that eventSourceType in the faultFields of the VES Fault Event contains the specific MOC against which the particular alarm occurrence was raised.

PROBABLE CAUSE

O

Provides the probable cause qualifier for the alarm. Probable causes are found in 3GPP TS 32.111 Annex B, drawn from ITU-T M.3100 and from ITU-T Recommendation X.721, X.733, and X.736.

PROPOSED REPAIR ACTIONS

R

Indicates proposed repair actions. May be used to provide recovery instructions to the operator in free form text.

Fault Meta Data Keywords

The following is a list of standard Fault Meta Data Keywords. Note: the keywords are in CAPS so they can be easily found within the YAML comments. R / O refers to recommended / optional.

Keyword

R/O

Description

FAULT ID

O

Gives a unique numerical Identifier for the fault.

FAULT NAME

O

Gives a short name for the fault.

FAULT DESCRIPTION

O

Provides a descriptive meaning of the fault condition. This is intended to be read by an operator to give an idea of what happened.

FAULT EFFECT

O

Provides a description of the consequences when this fault occurs. This is intended to be read by an operator to give a sense of the effects, consequences , and other impacted areas of the system.

PROPOSED REPAIR ACTIONS

O

Indicates proposed repair actions. May be used to provide recovery instructions to the operator in free form text.

ADDITIONAL TEXT

O

Contains further information on the fault in free form text. See ITU-T Recommendation X.733 clause 8.1.2.13.

FM Meta Data Example

The following is a snippet of a fault event registration showing use of the FM Meta Data keywords. Note: it is recommended the information be conveyed in a human readable form similar to the example below:

event: {
  presence: required,
  action: {any, any, baseStationSynchronizationProblem,RECO-ContactNokiaTechnicalSupport},
  comment: "
    ALARM NAME: baseStationSynchronizationProblem,
    ALARM ID: 7108,
    ALARM DESCRIPTION: 'A fault has occurred in the base station
      synchronization. For example: the base station reference clock signal is
      lost or is unstable or inaccurate.',
    ALARM EFFECT: 'The effect of the fault on the functioning of the network element depends on the fault id raised. See FAULT EFFECT below.',
    MANAGED OBJECT CLASSES: NRBTS,
    EVENT TYPE: 'Equipment Alarm',
    PROBABLE CAUSE: 'Timing Problem',
    PROPOSED REPAIR ACTIONS: 'See PROPOSED REPAIR ACTIONS for the underlying fault under alarmAdditionalInformation.',
    ASSOCIATED FAULTS: 9, 1818,
    CLEARING TYPE: Automatic
  ",
  structure: {
    commonEventHeader: {
      presence: required, structure: {
        version: {presence: required, value: 3.0},
        domain: {presence: required, value: fault},
        eventName: {presence: required, value: Fault_gnb-Nokia_baseStationSynchronizationProblem},
        eventId: {presence: required},
        sourceName: {presence: required},
        reportingEntityName: {presence: required},
        priority: {presence: required},
        startEpochMicrosec: {presence: required},
        lastEpochMicrosec: {presence: required},
        timeZoneOffset: {presence: required},
        sequence: {presence: required}
      }
    },
    faultFields: {
      presence: required, structure: {
        faultFieldsVersion: {presence: required, value: 3.0},
        eventCategory: {presence: optional, comment: "Equipment Alarm"},
        alarmCondition: {presence: required, value: 'baseStationSynchronizationProblem'},
        eventSourceType: {presence: required},
        alarminterfaceA: {presence: required},
        specificProblem: {presence: required},
        eventSeverity: {presence: required, value: [MINOR, NORMAL]},
        nfStatus: {default: Active},
        alarmAdditionalInformation: {
          presence: required, array: [
            keyValuePair: {
              presence: required,
              structure: {
                key: {presence: required, value: faultId},
                value: {presence: required}
              },
              comment: "
                FAULT ID: 9,
                FAULT NAME: 'BTS time not corrected',
                FAULT DESCRIPTION: 'The reference frequency that the BTS master clock
                  receives has changed by about 200 ppb or more (which equals the change
                  magnitude of 204 DAC steps or more (with 12bit DAC)) during the
                  measurement period, compared to the BTS master clock frequency.
                  Causes can be:
                    1. The reference frequency …..
                    2. The reference frequency fluctuates …',
                FAULT EFFECT: 'This fault does not immediately affect the operations of the BTS, but it is a notification …',
                PROPOSED REPAIR ACTION: 'access the ….follow the instructions below:
                  1. In case of a fault in the transmission network synchronization, 
                  2. If the basic accuracy of the signal used for synch is correct…
                  3. In case of a BTS equipment fault, the location might be:
                  4. After the fault situation has been cleared, ….',
                FAULT ID: 1818,
                FAULT NAME: 'BTS master clock tuning failure',
                FAULT DESCRIPTON: 'Master clock frequency is tuned to within 5% of its
                  minimum or maximum tuning limit.',
                FAULT EFFECT: 'The BTS can operate properly for months …'
                  Effects in Frequency Synchronization mode: 
                  Effects in Phase Synchronization mode: ….',
                PROPOSED REPAIR ACTION: 'Perform the steps below in the listed order until the fault disappears.
                  Not tracking satellites:
                  1. The most common reason ….
                  2. There might be a malfunction in the GPS receiver. Perform a (remote)power reset for the GPS receiver.
                  3. There might be a HW fault in the GPS receiver. Check the operation
                    and change the GPS module, if needed.'
              "
            },
            keyValuePair: {
              presence: required,
              structure: {
                key: {presence: required, value: alarmId},
                value: {presence: required}
              }
            },
            keyValuePair: {
              presence: required,
              structure: {
                key: {presence: required, value: 'application additional information fields'},
                value: {presence: optional}
              }
            }
          ]
        }
      }
    }
  }
}

YAML Examples

An example YAML file is provided below which registers some events for a hypothetical VNF. Note: some of the lines have been manually wrapped/indented to make it easier to read. Please ignore the section breaks that interrupt this single file; they were added to make it easier to rapidly find examples of different types of events.

Fault
# registration for Fault_vMrf_alarm003
# Constants: the values of domain, eventName, priority, vfstatus,
# version, alarmCondition, eventSeverity, eventSourceType,
# faultFieldsVersion, specificProblem,
# Variables (to be supplied at runtime) include: eventId, lastEpochMicrosec,
# reportingEntityId, reportingEntityName, sequence, sourceId,sourceName,
# startEpochMicrosec
event: {
  presence: required, action: [ any, any, alarm003, RECO-rebuildVnf ],
  structure: {
    commonEventHeader: {
      presence: required, structure: {
        domain: {presence: required, value: fault},
        eventName: {presence: required, value: Fault_vMrf_alarm003},
        eventId: {presence: required},
        nfNamingCode: {value: mrfx},
        priority: {presence: required, value: Medium},
        reportingEntityId: {presence: required},
        reportingEntityName: {presence: required},
        sequence: {presence: required},
        sourceId: {presence: required},
        sourceName: {presence: required},
        startEpochMicrosec: {presence: required},
        lastEpochMicrosec: {presence: required},
        version: {presence: required, value: 3.0}
      }
    },
    faultFields: {
      presence: required, structure: {
        alarmCondition: {presence: required, value: alarm003},
        eventSeverity: {presence: required, value: MAJOR},
        eventSourceType: {presence: required, value: virtualNetworkFunction},
        faultFieldsVersion: {presence: required, value: 2.0},
        specificProblem: {presence: required, value: "Configuration file was corrupt or not present"},
        vfStatus: {presence: required, value: "Requesting Termination"}
      }
    }
  }
}
# registration for clearing Fault_vMrf_alarm003Cleared

# Constants: the values of domain, eventName, priority,
# , version, alarmCondition, eventSeverity, eventSourceType,
# faultFieldsVersion, specificProblem,
# Variables (to be supplied at runtime) include: eventId, lastEpochMicrosec,
# reportingEntityId, reportingEntityName, sequence, sourceId,
# sourceName, startEpochMicrosec, vfStatus

event: {
  presence: required, action: [ any, any, alarm003, Clear ], structure: {
    commonEventHeader: {
      presence: required, structure: {
        domain: {presence: required, value: fault},
        eventName: {presence: required, value: Fault_vMrf_alarm003Cleared},
        eventId: {presence: required},
        nfNamingCode: {value: mrfx},
        priority: {presence: required, value: Medium},
        reportingEntityId: {presence: required},
        reportingEntityName: {presence: required},
        sequence: {presence: required},
        sourceId: {presence: required},
        sourceName: {presence: required},
        startEpochMicrosec: {presence: required},
        lastEpochMicrosec: {presence: required},
        version: {presence: required, value: 3.0}
      }
    },
    faultFields: {
      presence: required, structure: {
        alarmCondition: {presence: required, value: alarm003},
        eventSeverity: {presence: required, value: NORMAL},
        eventSourceType: {presence: required, value: virtualNetworkFunction},
        faultFieldsVersion: {presence: required, value: 2.0},
        specificProblem: {presence: required, value: "Valid configuration file found"},
        vfStatus: {presence: required, value: "Requesting Termination"}
      }
    }
  }
}
Heartbeat
# registration for Heartbeat_vMRF

# Constants: the values of domain, eventName, priority, version
# Variables (to be supplied at runtime) include: eventId, lastEpochMicrosec,
# reportingEntityId, reportingEntityName, sequence, sourceId, sourceName,
# startEpochMicrosec

event: {
  presence: required, heartbeatAction: [3, vnfDown, RECO-rebuildVnf],
  structure: {
    commonEventHeader: {
      presence: required, structure: {
        domain: {presence: required, value: heartbeat},
        eventName: {presence: required, value: Heartbeat_vMrf},
        eventId: {presence: required},
        nfNamingCode: {value: mrfx},
        priority: {presence: required, value: Normal},
        reportingEntityId: {presence: required},
        reportingEntityName: {presence: required},
        sequence: {presence: required},
        sourceId: {presence: required},
        sourceName: {presence: required},
        startEpochMicrosec: {presence: required},
        lastEpochMicrosec: {presence: required},
        version: {presence: required, value: 3.0}
      }
    },
    heartbeatFields: {
      presence: optional, structure:{
        heartbeatFieldsVersion: {presence: required, value: 1.0},
        heartbeatInterval: {presence: required, range: [ 15, 300 ], default: 60 }
      }
    }
  }
}
Measurements
# registration for Measurement_vMRF
# Constants: the values of domain, eventName, priority, version,
# measurementFieldsVersion, additionalMeasurements.namedArrayOfFields.name,
# Variables (to be supplied at runtime) include: eventId, reportingEntityName, sequence,
# sourceName, start/lastEpochMicrosec, measurementInterval,
# concurrentSessions, requestRate, numberOfMediaPortsInUse,
# cpuUsageArray.cpuUsage,cpuUsage.cpuIdentifier, cpuUsage.percentUsage,
# additionalMeasurements.namedArrayOfFields.arrayOfFields,
# vNicPerformance.receivedOctetsAccumulated,
# vNicPerformance.transmittedOctetsAccumulated,
# vNicPerformance.receivedTotalPacketsAccumulated,
# vNicPerformance.transmittedTotalPacketsAccumulated,
# vNicPerformance.vNicIdentifier, vNicPerformance.receivedOctetsDelta,
# vNicPerformance.receivedTotalPacketsDelta,
# vNicPerformance.transmittedOctetsDelta,
# vNicPerformance.transmittedTotalPacketsDelta,
# vNicPerformance.valuesAreSuspect, memoryUsageArray.memoryUsage,
# memoryUsage.memoryConfigured, memoryUsage.vmIdentifier,
# memoryUsage.memoryUsed, memoryUsage.memoryFree

event: {
  presence: required, structure: {
    commonEventHeader: {
      presence: required, structure: {
        domain: {presence: required, value: measurement},
        eventName: {presence: required, value: Measurement_vMrf},
        eventId: {presence: required},
        nfNamingCode: {value: mrfx},
        priority: {presence: required, value: Normal},
        reportingEntityId: {presence: required},
        reportingEntityName: {presence: required},
        sequence: {presence: required},
        sourceId: {presence: required},
        sourceName: {presence: required},
        startEpochMicrosec: {presence: required},
        lastEpochMicrosec: {presence: required},
        version: {presence: required, value: 3.0}
        vesEventListenerVersion: {presence: required, value: 7.1.1}
      }
    },
    measurement: {
      presence: required, structure: {
        measurementFieldsVersion: {presence: required, value: 4.0},
        measurementInterval: {presence: required, range: [ 60, 3600 ], default: 300},
        concurrentSessions: {presence: required, range: [ 0, 100000 ]},
        requestRate: {presence: required, range: [ 0, 100000 ]},
        numberOfMediaPortsInUse: {presence: required, range: [ 0, 100000 ]},
        cpuUsageArray: {
          presence: required, array: [
            cpuUsage: {
              presence: required, structure: {
                cpuIdentifier: {presence: required},
                percentUsage: {
                  presence: required, range: [ 0, 100 ],
                  action: [80, up, CpuUsageHigh, RECO-scaleOut],
                  action: [10, down, CpuUsageLow, RECO-scaleIn]
                }
              }
            }
          ]
        },
        memoryUsageArray: {
          presence: required, array: [
            memoryUsage: {
              presence: required, structure: {
                memoryConfigured: {presence: required, value: 33554432},
                memoryFree: {
                  presence: required, range: [ 0, 33554432 ],
                  action: [100, down, FreeMemLow, RECO-scaleOut],
                  action: [30198989, up, FreeMemHigh, RECO-scaleIn]
                },
                memoryUsed: {presence: required, range: [ 0, 33554432 ]},
                vmIdentifier: {presence: required}
              }
            }
          ]
        },
        additionalMeasurements: {
          presence: required, array: [
            namedArrayOfFields: {
              presence: required, structure: {
                name: {presence: required, value: licenseUsage},
                arrayOfFields: {
                  presence: required, array: [
                    field: {
                      presence: required, structure: {
                        name: {presence: required, value: G711AudioPort},
                        value: {
                          presence: required, range: [ 0, 100000 ],
                          units: numberOfPorts
                        }
                      }
                    },
                    field: {
                      presence: required, structure: {
                        name: {presence: required, value: G729AudioPort},
                        value: {
                          presence: required, range: [ 0, 100000 ],
                          units: numberOfPorts
                        }
                      }
                    },
                    field: {
                      presence: required, structure: {
                        name: {presence: required, value: G722AudioPort},
                        value: {
                          presence: required, range: [ 0, 100000 ],
                          units: numberOfPorts
                        }
                      }
                    },
                    field: {
                      presence: required, structure: {
                        name: {presence: required, value: AMRAudioPort},
                        value: {
                          presence: required, range: [ 0, 100000 ],
                          units: numberOfPorts
                        }
                      }
                    },
                    field: {
                      presence: required, structure: {
                        name: {presence: required, value: AMRWBAudioPort},
                        value: {
                          presence: required, range: [ 0, 100000 ],
                          units: numberOfPorts
                        }
                      }
                    },
                    field: {
                      presence: required, structure: {
                        name: {presence: required, value: OpusAudioPort},
                        value: {
                          presence: required, range: [ 0, 100000 ],
                          units: numberOfPorts
                        }
                      }
                    },
                    field: {
                      presence: required, structure: {
                        name: {presence: required, value: H263VideoPort},
                        value: {
                          presence: required, range: [ 0, 100000 ],
                          units: numberOfPorts
                        }
                      }
                    },
                    field: {
                      presence: required, structure: {
                        name: {presence: required, value: H264NonHCVideoPort},
                        value: {
                          presence: required, range: [ 0, 100000 ],
                          units: numberOfPorts
                        }
                      }
                    },
                    field: {
                      presence: required, structure: {
                        name: {presence: required, value: H264HCVideoPort},
                        value: {
                          presence: required, range: [ 0, 100000 ],
                          units: numberOfPorts
                        }
                      }
                    },
                    field: {
                      presence: required, structure: {
                        name: {presence: required, value: MPEG4VideoPort},
                        value: {
                          presence: required, range: [ 0, 100000 ],
                          units: numberOfPorts
                        }
                      }
                    },
                    field: {
                      presence: required, structure: {
                        name: {presence: required, value: VP8NonHCVideoPort},
                        value: {
                          presence: required, range: [ 0, 100000 ],
                          units: numberOfPorts
                        }
                      }
                    },
                    field: {
                      presence: required, structure: {
                        name: {presence: required, value: VP8HCVideoPort},
                        value: {
                          presence: required, range: [ 0, 100000 ],
                          units: numberOfPorts
                        }
                      }
                    },
                    field: {
                      presence: required, structure: {
                        name: {presence: required, value: PLC},
                        value: {
                          presence: required, range: [ 0, 100000 ],
                          units: numberOfPorts
                        }
                      }
                    },
                    field: {
                      presence: required, structure: {
                        name: {presence: required, value: AEC},
                        value: {
                          presence: required, range: [ 0, 100000 ],
                          units: numberOfPorts
                        }
                      }
                    },
                    field: {
                      presence: required, structure: {
                        name: {presence: required, value: NR},
                        value: {
                          presence: required, range: [ 0, 100000 ],
                          units: numberOfPorts
                        }
                      }
                    },
                    field: {
                      presence: required, structure: {
                        name: {presence: required, value: NG},
                        value: {
                          presence: required, range: [ 0, 100000 ],
                          units: numberOfPorts
                        }
                      }
                    },
                    field: {
                      presence: required, structure: {
                        name: {presence: required, value: NLD},
                        value: {
                          presence: required, range: [ 0, 100000 ],
                          units: numberOfPorts
                        }
                      }
                    },
                    field: {
                      presence: required, structure: {
                        name: {presence: required, value: G711FaxPort},
                        value: {
                          presence: required, range: [ 0, 100000 ],
                          units: numberOfPorts
                        }
                      }
                    },
                    field: {
                      presence: required, structure: {
                        name: {presence: required, value: T38FaxPort},
                        value: {
                          presence: required, range: [ 0, 100000 ],
                          units: numberOfPorts
                        }
                      }
                    },
                    field: {
                      presence: required, structure: {
                        name: {presence: required, value: RFactor},
                        value: {
                          presence: required, range: [ 0, 100000 ],
                          units: numberOfPorts
                        }
                      }
                    },
                    field: {
                      presence: required, structure: {
                        name: {presence: required, value: T140TextPort},
                        value: {
                          presence: required, range: [ 0, 100000 ],
                          units: numberOfPorts
                        }
                      }
                    },
                    field: {
                      presence: required, structure: {
                        name: {presence: required, value: EVSAudioPort},
                        value: {
                          presence: required, range: [ 0, 100000 ],
                          units: numberOfPorts
                        }
                      }
                    }
                  ]
                }
              }
            },
            namedArrayOfFields: {
              presence: required, structure: {
                name: {presence: required, value: mediaCoreUtilization},
                arrayOfFields: {
                  presence: required, array: [
                    field: {
                      presence: required, structure: {
                        name: {presence: required, value: actualAvgAudio},
                        value: {
                          presence: required, range: [ 0, 255 ],
                          action: [80, up, AudioCoreUsageHigh, RECO-scaleOut],
                          action: [10, down, AudioCoreUsageLow, RECO-scaleIn]
                        }
                      }
                    },
                    field: {
                      presence: required, structure: {
                        name: {presence: required, value: modelAvgAudio},
                        value: {
                          presence: required, range: [ 0, 100 ],
                          action: [80, up, AudioCoreUsageHigh, RECO-scaleOut],
                          action: [10, down, AudioCoreUsageLow, RECO-scaleIn]
                        }
                      }
                    },
                    field: {
                      presence: required, structure: {
                        name: {presence: required, value: actualMaxAudio},
                        value: {presence: required, range: [ 0, 255 ]}
                      }
                    },
                    field: {
                      presence: required, structure: {
                        name: {presence: required, value: modelMaxAudio},
                        value: {presence: required, range: [ 0, 100 ]}
                      }
                    },
                    field: {
                      presence: required, structure: {
                        name: {presence: required, value: actualAvgVideo},
                        value: {
                          presence: required, range: [ 0, 255 ],
                          action: [80, up, VideoCoreUsageHigh, RECO-scaleOut],
                          action: [10, down, VideoCoreUsageLow, RECO-scaleIn]
                        }
                      }
                    },
                    field: {
                      presence: required, structure: {
                        name: {presence: required, value: modelAvgVideo},
                        value: {
                          presence: required, range: [ 0, 100 ],
                          action: [80, up, VideoCoreUsageHigh, RECO-scaleOut],
                          action: [10, down, VideoCoreUsageLow, RECO-scaleIn]
                        }
                      }
                    },
                    field: {
                      presence: required, structure: {
                        name: {presence: required, value: actualMaxVideo},
                        value: {presence: required, range: [ 0, 255 ]}
                      }
                    },
                    field: {
                      presence: required, structure: {
                        name: {presence: required, value: modelMaxVideo},
                        value: {presence: required, range: [ 0, 100 ]}
                      }
                    },
                    field: {
                      presence: required, structure: {
                        name: {presence: required, value: actualAvgHcVideo},
                        value: {
                          presence: required, range: [ 0, 255 ],
                          action: [80, up, HcVideoCoreUsageHigh, RECO-scaleOut],
                          action: [10, down, HcVideoCoreUsageLow, RECO-scaleIn]
                        }
                      }
                    },
                    field: {
                      presence: required, structure: {
                        name: {presence: required, value: modelAvgHcVideo},
                        value: {
                          presence: required, range: [ 0, 100 ],
                          action: [80, up, HcVideoCoreUsageHigh, RECO-scaleOut],
                          action: [10, down, HcVideoCoreUsageLow, RECO-scaleIn]
                        }
                      }
                    },
                    field: {
                      presence: required, structure: {
                        name: {presence: required, value: actualMaxHcVideo},
                        value: {presence: required, range: [ 0, 255 ]}
                      }
                    },
                    field: {
                      presence: required, structure: {
                        name: {presence: required, value: modelMaxHcVideo},
                        value: {presence: required, range: [ 0, 100 ]}
                      }
                    }
                  ]
                }
              }
            }
          ]
        },
        vNicPerformanceArray: {
          presence: required, array: [
            vNicPerformance: {
              presence: required, structure: {
                receivedOctetsAccumulated: {
                  presence: required,
                  range: [ 0, 18446744073709551615 ]
                },
                receivedTotalPacketsAccumulated: {
                  presence: required,
                  range: [ 0, 18446744073709551615 ]
                },
                receivedOctetsDelta: {presence: required},
                range: [ 0, 18446744073709551615 ],
                receivedTotalPacketsDelta: {
                  presence: required,
                  range: [ 0, 18446744073709551615 ]
                },
                transmittedOctetsDelta: {
                  presence: required,
                  range: [ 0, 18446744073709551615 ]
                },
                transmittedOctetsAccumulated: {
                  presence: required,
                  range: [ 0, 18446744073709551615 ]
                },
                transmittedTotalPacketsAccumulated: {
                  presence: required,
                  range: [ 0, 18446744073709551615 ]
                },
                transmittedTotalPacketsDelta: {
                  presence: required,
                  range: [ 0, 18446744073709551615 ]
                },
                valuesAreSuspect: {presence: required, value: [ true, false ]},
                vNicIdentifier: {presence: required}
              }
            }
          ]
        }
      }
    }
  }
}
Syslog
# registration for Syslog_vMRF

# Constants: the values of domain, eventName, priority, lastEpochMicrosec, version,
# syslogFields.syslogFieldsVersion, syslogFields.syslogTag
# Variables include: eventId, lastEpochMicrosec, reportingEntityId, reportingEntityName,
# sequence, sourceId, sourceName, startEpochMicrosec,
# syslogFields.eventSourceHost, syslogFields.eventSourceType,
# syslogFields.syslogFacility, syslogFields.syslogMsg

event: {
  presence: required, structure: {
  commonEventHeader: {
    presence: required, structure: {
      domain: {presence: required, value: syslog},
      eventName: {presence: required, value: Syslog_vMrf},
      eventId: {presence: required},
      nfNamingCode: {value: mrfx},
      priority: {presence: required, value: Normal},
      reportingEntityId: {presence: required},
      reportingEntityName: {presence: required},
      sequence: {presence: required},
      sourceId: {presence: required},
      sourceName: {presence: required},
      startEpochMicrosec: {presence: required},
      lastEpochMicrosec: {presence: required},
      version: {presence: required, value: 3.0},
    }
  },
  syslogFields: {
    presence: required, structure: {
      eventSourceHost: {presence: required},
      eventSourceType: {presence: required, value: virtualNetworkFunction},
      syslogFacility: {presence: required, range: [16, 23]},
      syslogSev: {presence: required, value: [Emergency, Alert, Critical, Error]},
      syslogFieldsVersion: {presence: required, value: 3.0},
      syslogMsg: {presence: required},
      syslogSData: {
        presence: required, keyValuePairString: {' ', =, keyValuePairs: [
          keyValuePair: {
            presence: required, structure: {
              key: {presence: required, value: ATTEST},
              value: {presence: required}
            }
          },
          keyValuePair: {
            presence: required, structure: {
              key: {presence: required, value: DATE_IN},
              value: {presence: required}
            }
          },
          keyValuePair: {
            presence: required, structure: {
              key: {presence: required, value: DATE_OUT},
              value: {presence: required}
            }
          },
          keyValuePair: {
            presence: required, structure: {
              key: {presence: required, value: DEST_IN},
              value: {presence: required}
            }
          },
          keyValuePair: {
            presence: required, structure: {
              key: {presence: required, value: FUNCTION},
              value: {presence: required}
            }
          },
          keyValuePair: {
            presence: required, structure: {
              key: {presence: required, value: ICID},
              value: {presence: required}
            }
          },
          keyValuePair: {
            presence: required, structure: {
              key: {presence: required, value: ORIGID},
              value: {presence: required}
            }
          },
          keyValuePair: {
            presence: required, structure: {
              key: {presence: required, value: ORIG_TN},
              value: {presence: required}
            }
          },
          keyValuePair: {
            presence: required, structure: {
              key: {presence: required, value: SIP_REASON_HEADER},
              value: {presence: required}
            }
          },
          keyValuePair: {
            presence: required, structure: {
              key: {presence: required, value: STATE},
              value: {presence: required}
            }
          },
          keyValuePair: {
            presence: required, structure: {
              key: {presence: required, value: STATUS},
              value: {presence: required}
            }
          },
          keyValuePair: {
            presence: required, structure: {
              key: {presence: required, value: VERSTAT},
              value: {presence: required}
            }
          }
        ]}
      }
    }
    syslogTag: {presence: required, value: vMRF},
    additionalFields: {
      presence: required, keyValuePairString: { \|, =, keyValuePairs: [
          keyValuePair: {
            presence: required, structure: {
              key: {presence: required, value: someKeyName},
              value: {presence: required}
            }
          },
          keyValuePair: {
            presence: optional, structure: {
              key: {presence: required, value: someOtherKeyName},
              value: {presence: required}
            }
          }
      ]}
    }
  }
}
Mobile Flow
# registration for mobileFlow
# Constants: the values of domain, eventName, priority, version

# Variables (to be supplied at runtime) include: eventId, reportingEntityName,
# sequence, sourceName, start/lastEpochMicrosec

event: {
  presence: required, structure: {
    commonEventHeader: {
      presence: required, structure: {
        domain: {presence: required, value: mobileFlow},
        eventName: {presence: required, value: mobileFlow},
        eventId: {presence: required},
        nfType: {presence: required, value: sbcx},
        priority: {presence: required, value: Normal},
        reportingEntityName: {presence: required},
        sequence: {presence: required},
        sourceName: {presence: required},
        startEpochMicrosec: {presence: required},
        lastEpochMicrosec: {presence: required},
        version: {presence: required, value: 3.0}
      }
    },
    mobileFlowFieldsVersion: {
      presence: required, structure: {
        applicationType: {presence: optional},
        appProtocolType: {presence: optional},
        appProtocolVersion: {presence: optional},
        cid: {presence: optional},
        connectionType: {presence: optional},
        ecgi: {presence: optional},
        flowDirection: {presence: required},
        gtpPerFlowMetrics: {
          presence: required, structure: {
            avgBitErrorRate: {presence: required},
            avgPacketDelayVariation: {presence: required},
            avgPacketLatency: {presence: required},
            avgReceiveThroughput: {presence: required},
            avgTransmitThroughput: {presence: required},
            durConnectionFailedStatus: {presence: optional},
            durTunnelFailedStatus: {presence: optional},
            flowActivatedBy: {presence: optional},
            flowActivationEpoch: {presence: required},
            flowActivationMicrosec: {presence: required},
            flowActivationTime: {presence: optional},
            flowDeactivatedBy: {presence: optional},
            flowDeactivationEpoch: {presence: required},
            flowDeactivationMicrosec: {presence: required},
            flowDeactivationTime: {presence: required},
            flowStatus: {presence: required},
            gtpConnectionStatus: {presence: optional},
            gtpTunnelStatus: {presence: optional},
            ipTosCountList: {presence: optional},
            ipTosList: {presence: optional},
            largePacketRtt: {presence: optional},
            largePacketThreshold: {presence: optional},
            maxPacketDelayVariation: {presence: required},
            maxReceiveBitRate: {presence: optional},
            maxTransmitBitRate: {presence: optional},
            mobileQciCosCountList: {presence: optional},
            mobileQciCosList: {presence: optional},
            numActivationFailures: {presence: required},
            numBitErrors: {presence: required},
            numBytesReceived: {presence: required},
            numBytesTransmitted: {presence: required},
            numDroppedPackets: {presence: required},
            numGtpEchoFailures: {presence: optional},
            numGtpTunnelErrors: {presence: optional},
            numHttpErrors: {presence: optional},
            numL7BytesReceived: {presence: required},
            numL7BytesTransmitted: {presence: required},
            numLostPackets: {presence: required},
            numOutOfOrderPackets: {presence: required},
            numPacketErrors: {presence: required},
            numPacketsReceivedExclRetrans: {presence: required},
            numPacketsReceivedInclRetrans: {presence: required},
            numPacketsTransmittedInclRetrans: {presence: required},
            numRetries: {presence: required},
            numTimeouts: {presence: required},
            numTunneledL7BytesReceived: {presence: required},
            roundTripTime: {presence: required},
            tcpFlagCountList: {presence: optional},
            tcpFlagList: {presence: optional},
            timeToFirstByte: {presence: required}
          }
        },
        gtpProtocolType: {presence: optional},
        gtpVersion: {presence: optional},
        httpHeader: {presence: optional},
        imei: {presence: optional},
        imsi: {presence: optional},
        ipProtocolType: {presence: required},
        ipVersion: {presence: required},
        lac: {presence: optional},
        mcc: {presence: optional},
        mnc: {presence: optional},
        msisdn: {presence: optional},
        otherEndpointIpAddress: {presence: required},
        otherEndpointPort: {presence: required},
        otherFunctionalRole: {presence: optional},
        rac: {presence: optional},
        radioAccessTechnology: {presence: optional},
        reportingEndpointIpAddr: {presence: required},
        reportingEndpointPort: {presence: required},
        sac: {presence: optional},
        samplingAlgorithm: {presence: optional},
        tac: {presence: optional},
        tunnelId: {presence: optional},
        vlanId: {presence: optional},
        additionalInformation: {
          presence: optional, array: {
            field: {
              presence: required, structure: {
                name: {presence: required, value: name1},
                value: {presence: required}
              }
            },
            field: {
              presence: optional, structure: {
                name: {presence: required, value: name2},
                value: {presence: required}
              }
            }
          }
        }
      }
    }
  }
}
Sip Signaling
# registration for sipSignaling
# Constants: the values of domain, eventName, priority, version
#
# Variables (to be supplied at runtime) include: eventId,
reportingEntityName,
# sequence, sourceName, start/lastEpochMicrosec

event: {
  presence: required, structure: {
    commonEventHeader: {
      presence: required, structure: {
        domain: {presence: required, value: sipSignaling},
        eventName: {presence: required, value: sipSignaling_modelName},
        eventId: {presence: required},
        nfType: {presence: required, value: sbcx},
        priority: {presence: required, value: Normal},
        reportingEntityName: {presence: required},
        sequence: {presence: required},
        sourceName: {presence: required},
        startEpochMicrosec: {presence: required},
        lastEpochMicrosec: {presence: required},
        version: {presence: required, value: 3.0}
      }
    },
    sipSignalingFields: {
      presence: required, structure: {
        compressedSIP: {presence: optional},
        correlator: {presence: required},
        localIpAaddress: {presence: required},
        localPort: {presence: required},
        remoteIpAddress: {presence: required},
        remotePort: {presence: required},
        sipSignalingFieldsVersion: {presence: required},
        summarySip: {presence: optional},
        vnfVendorNameFields: {
          presence: required, structure: {
            vendorName: {presence: required},
            vfModuleName: {presence: optional},
            vnfName: {presence: optional}
          }
        },
        additionalInformation: {
          presence: optional, array: {
            field: {
              presence: required, structure: {
                name: {presence: required, value: name1},
                value: {presence: required}
              }
            },
            field: {
              presence: optional, structure: {
                name: {presence: required, value: name2},
                value: {presence: required}
              }
            }
          }
        }
      }
    }
  }
}
Voice Quality
# registration for voiceQuality
# Constants: the values of domain, eventName, priority, version
# Variables (to be supplied at runtime) include: eventId, lastEpochMicrosec,
# reportingEntityId, reportingEntityName, sequence, sourceId,
# sourceName, startEpochMicrosec

event: {
  presence: required, structure: {
    commonEventHeader: {
      presence: required, structure: {
        domain: {presence: required, value: voiceQualityFields},
        eventName: {presence: required, value: voiceQualityFields_modelName},
        eventId: {presence: required},
        nfType: {presence: required, value: sbcx},
        priority: {presence: required, value: Normal},
        reportingEntityName: {presence: required},
        sequence: {presence: required},
        sourceName: {presence: required},
        startEpochMicrosec: {presence: required},
        lastEpochMicrosec: {presence: required},
        version: {presence: required, value: 3.0}
      }
    },
    voiceQualityFieldsVersion: {
      presence: required, structure: {
        calleeSideCodec: {presence: required},
        callerSideCodec: {presence: required},
        correlator: {presence: required},
        remoteIpAddress: {presence: required},
        endOfCallVqmSummaries: {
          presence: required, structure: {
            adjacencyName: {presence: required},
            endpointDescription: {presence: required},
            endpointAverageJitter: {presence: optional},
            endpointMaxJitter: {presence: optional},
            endpointRtpOctetsLost: {presence: optional},
            endpointRtpPacketsLost: {presence: optional},
            endpointRtpOctetsDiscarded: {presence: optional},
            endpointRtpOctetsReceived: {presence: optional},
            endpointRtpOctetsSent: {presence: optional},
            endpointRtpPacketsDiscarded: {presence: optional},
            endpointRtpPacketsReceived: {presence: optional},
            endpointRtpPacketsSent: {presence: optional},
            localAverageJitter: {presence: optional},
            localMaxJitter: {presence: optional},
            localAverageJitterBufferDelay: {presence: optional},
            localMaxJitterBufferDelay: {presence: optional},
            localRtpOctetsDiscarded: {presence: optional},
            localRtpOctetsLost: {presence: optional},
            localRtpOctetsReceived: {presence: optional},
            localRtpOctetsSent: {presence: optional},
            localRtpPacketsDiscarded: {presence: optional},
            localRtpPacketsLost: {presence: optional},
            localRtpPacketsReceived: {presence: optional},
            localRtpPacketsSent: {presence: optional},
            mosCqe: {presence: optional},
            packetLossPercent: {presence: optional},
            rFactor: {presence: optional},
            roundTripDelay: {presence: optional},
            oneWayDelay: {presence: optional}
          }
        },
        phoneNumber: {presence: required},
        midCallRtcp: {presence: required},
        vendorVnfNameFields: {
          presence: required, structure: {
            vendorName: {presence: required},
            vfModuleName: {presence: optional},
            vnfName: {presence: optional}
          }
        },
        additionalInformation: {
          presence: optional, array: {
            field: {
              presence: required, structure: {
                name: {presence: required, value: name1},
                value: {presence: required}
              }
            },
            field: {
              presence: optional, structure: {
                name: {presence: required, value: name2},
                value: {presence: required}
              }
            }
          }
        }
      }
    }
  }
}
Rules
#Rules

Rules: [
  rule: {
    trigger: CpuUsageHigh || FreeMemLow || AudioCoreUsageHigh ||
    VideoCoreUsageHigh || HcVideoCoreUsageHigh,
    microservices: [scaleOut]
  },
  rule: {
    trigger: CpuUsageLow && FreeMemHigh && AudioCoreUsageLow &&
    VideoCoreUsageLow && HcVideoCoreUsageLow,
    microservices: [scaleIn]
  }
]

Appendix: Historical Change Log

For the latest changes, see the Change Block just before the Table of Contents.

Service: VES Event Listener 7.1.1

Legal Disclaimer

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.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.

Document

VES Event Listener

Revision

7.1.1

Revision Date

January 28th, 2020

Author

Rich Erickson

Contributors:

Min Chen – AT&T

Fred Delaplace - AT&T

Andrew Egan – AT&T

Alok Gupta – AT&T

Marge Hillis – Nokia

Gerard Hynes – AT&T

Ken Kelly – AT&T

Mark Scott – Ericsson

Tim Verall – Intel

Sumit Verdi – VMWare

Table of Contents

Introduction

This document describes the RESTful interface for the VES Event Listener. The VES acronym originally stood for Virtual-function Event Streaming, but VES has been generalized to support network-function event streaming, whether virtualized or not. The VES Event Listener is capable of receiving any event sent in the VES Common Event Format. The Common Event Format is expressed in JSON schema in section 4 of this document. In the Common Event Format, an event consists of a required Common Event Header block (i.e., object) accompanied by zero or more event domain blocks.

It should be understood that events are well structured packages of information, identified by an eventName, which are asynchronously communicated to subscribers who are interested in the eventName. Events can convey measurements, faults, syslogs, threshold crossing alerts and other types of information. Events are simply a way of communicating well-structured packages of information to one or more instances of an Event Listener service.

This document describes a RESTful connectionless push event listener can receive single events or batches of events in the Common Event Format. In future, additional documents may describe other transports which make use of persistent TCP connections for high volumes of streaming events.

Compatibility with ONAP

Unless otherwise stated, this version of the Event Listener specification is compatible with the release of ONAP the specification is released under. In other words, if the specification is released under the Frankfurt ONAP Release, then the VES Event Collectors provided by DCAE will also be compatible with the specification.

Event Registration

All events must be compliant with the common event format, but specific events identified by their eventNames, may require that certain fields, which are optional in the common event format, be present when they are published. For example, a specific eventName may require that specific name-value pairs be present in the extensible structures provided within the Common Event Format.

Events are registered using an extensible YAML format (defined in a separate document), which specifies, for each eventName, the fields that are required, what field values may be sent, and any special handling that should be performed on those eventNames.

Naming Standards for eventName

To prevent naming collisions, eventNames sent as part of the commonEventHeader, should conform to the following naming convention designed to summarize the purpose and type of the event, and to ensure the uniqueness of the eventName:

{DomainAbbreviation}_{PublisherName}_{Description}

Each underscore-separated subfield above should start with a capital letter and use camel-casing to separate words and acronyms. Acronyms should capitalize only the first letter of the acronym. Spaces and underscores should not appear within any subfield.

The DomainAbbreviation subfield derives from the ‘domain’ field in the commonEventHeader, as specified below:

  • ‘Fault’ for the fault domain

  • ‘Heartbeat’ for the heartbeat domain

  • ‘Measurement’ for the measurement domain

  • ‘MobileFlow’ for the mobileFlow domain

  • ‘Notification’ for the notification domain

  • ‘Other’ for the other domain

  • ‘Perf3gpp’ for the perf3gpp domain

  • ‘PnfReg’ for the pnfRegistration domain

  • ‘SipSignaling’ for the sipSignaling domain

  • ‘StateChange’ for the stateChange domain

  • ‘Syslog’ for the syslog domain

  • ‘Tca’ for the thresholdCrossingAlert domain

  • ‘VoiceQuality’ for the voiceQuality domain

The PublisherName subfield describes the vendor product or application publishing the event. This subfield conforms to the following conventions:

  • Vendor products are specified as:

    {productName}-{vendorName}

    For example: Visbc-Metaswitch or Vdbe-Juniper, where a hyphen is used to separate the productName and vendorName subfields. Note that the productName and vendorName subfields must not include hyphens themselves.

    Organizing the information in this way will cause an alphabetical listing of eventNames to sort similar network functions together, rather than to sort them by vendor.

    The productName subfield may describe a NF or a NFC. Where NFC names may be reused across different NF’s, they should be specified as:

    {NfName}:{NfcName}

    where a colon is used to separate the NfName and NfcName subfields. Note that the NfName and NfcName subfields must not include colons themselves.

    The ProductName may also describe other types of vendor modules or components such as a VM, application or hostname. As with NFs and NFCs, parent:child relationships may be communicated using colon as a subfield delimiter.

  • Service providers who adopt the VES Common Event Format for internal use, may provide PublisherName without the vendorName subfield. They would typically identify an application, system, service or microservice publishing the event (e.g., ‘Policy’, ‘So’, ‘MobileCallRecording’ or ‘Dkat’). As with NFs and NFCs, parent:child relationships may be communicated using colon as a subfield delimiter (e.g., ApplicationName:ApplicationComponent).

The final subfield of the eventName name should describe, in a compact camel case format the specific information being conveyed by the event. In some cases, this final subfield may not be required (e.g., in the case of certain heartbeats).

Examples of eventNames following the naming standards are provided below:

  • Tca_Vdbe-Ericsson_CpuThresholdExceeded

  • Heartbeat_Visbc:Mmc-Metaswitch

  • Syslog_Vdbe-Ericsson

  • Fault_MobileCallRecording_PilotNumberPoolExhaustion

  • Other_So:WanBonding_InstantiationPart1Complete

EventId Use Cases Examples

eventId Examples:

NOTE: Please note, the following are only examples, and other formats can be used provided they meet the requirement that the eventId is unique for all events or unique fault occurrence.

Example 1: assumes a unique key for each domain consisting of domain followed by an integer domain<n> or domainId<n>, where <n> is a positive integer, e.g. fault000001, heartbeat000001, measurement000005, notification3gppPerfFileReady0005

Example 2: assumes a unique integer key for all events across all domains <n>: 000000001, 00000002, 000000003

Rules:

  1. All domains except Fault: each time a subsequent event is sent the integer part of eventId will increment by 1. Repeat of eventId assumes duplicate event. Sequence number is set to 0 for all domains except fault.

  2. eventId construction for Fault Events:

    1. Most likely scenario

      • The sourceName on each Fault event is the NF Instance Name (pnf-name or vnf-name or vm-name) as entered in A&AI uniquely identifying this instance of the NF.

      • The eventId on Fault events is the same every time a given fault is raised (including onset and re-raise)

        1. The startEpochMicrosec value for the Fault event is the timestamp for when the fault onset occurs. Subsequent events for the same fault will keep the same startEpochMicrosec value.

        2. lastEpochMicrosec indicates the current event time. This value will be updated for each subsequent event for a given fault.

        3. The sequence number for each Fault event is set to 1 when the fault is raised and increments each time the same fault event is raised, until a clear is sent.

      • After the fault is cleared, a new eventId is used.

    _images/Use-Case-1.png
    1. Alternative Scenario: Network Function When Fault Event Status is Not Maintained.

      • The sourceName on each Fault event is the NF Instance Name (pnf-name or vnf-name or vm-name) as entered in A&AI uniquely identifying this instance of the NF.

      • The eventId on Fault events is the same every time a given fault is raised or cleared, even if it is re-raised after it had previously cleared. So, for example, if EMS loses contact with a particular device then a Fault event might be sent for a raise, re-raise (because EMS has re-tried and still can’t contact the device), clear (because EMS has re-tried and it can contact the device) and then raise again (because EMS has lost contact with the device again). The same eventId is used for all 4 of those Fault events.

      • The startEpochMicrosec value for each Fault event is the timestamp for when that event is generated, not when the fault first occurred. So all 4 of the Fault events in the previous bullet point would have a different timestamp.

      • lastEpochMicrosec indicates the current event time.

      • The sequence number for each Fault event is currently set to 0 on a raise and 1 on a clear. We could change that so that each Fault event is given a new monotonically increasing sequence number whether it is a raise or a clear if that is helpful (which is reset to 0 if the VM restarts) but they won’t be consecutive.

      • Normally, a clear is expected for each fault to be sent from a network function. However a few fault notification types will never be re-raised or cleared. In this case, general rules for VES events shall be followed with a new eventId for each event and sequence number set to 0.

    _images/Use-Case-2.png
Measurement Expansion Fields

When expansion fields are used, the goal is to avoid custom development by the service provider collecting the fields, since custom development adds obvious cost, delay and resource overhead. In the domain of measurements, it is expected that a high percentage (perhaps as high as 90 percent) of use cases for extensible fields can be satisfied by using the additionalMeasurements arrayOfNamedHashMap data structure in combination with a YAML registration file (provided at design time). The YAML registration file conveys meta-information about the processing of additionalMeasurements. For more information, please see the VES Event Registration specification and in particular the aggregationRole, castTo and isHomogeneous keywords.

Syslogs

Syslog’s can be classified as either Control or Session/Traffic. They differ by message content and expected volume:

  • Control logs are generally free-form human-readable text used for reporting errors or warnings supporting the operation and troubleshooting of NFs. The volume of these logs is typically less than 2k per day.

  • Session logs use common structured fields to report normal NF processing such as DNS lookups or firewall rules processed. The volume of these logs is typically greater than 1k per hour (and sometimes as high as 10k per second).

VES supports both classes of syslog, however VES is only recommended for control logs or for lower volume session logs, less than 60k per hour. High volume session logging should use a file-based transport solution.

Support for Protocols Other Than HTTPS

This API specification describes an HTTPS RESTful interface using the JSON content-type.

Alternative API specifications may be provided in future using Google Protobuf, websockets, or Apache Avro.

Configuration Requirements

This section provides network function configuration requirements for connectivity to a VES Event Listener via a RESTful API, using a VES JSON event.

There are several methods available to provide configuration settings to a network function. This document does not specify the exact manner in which the configuration elements described below must be required. The configuration can be provided during instantiation (e.g. preload), provided by an ONAP controller action, or provided manually.

  • VES Event Listener IP Addresses or FQDNs resolved via DNS: Two FQDNs and/or IP Addresses are required. NF shall select one of the 2 FQDNs/IP Addresses for sending events and if the NF is unable to get an acknowledgement within predefined configurable time interval or unable to establish a TCP connection due inability to resolve DNS query or if the VES Event Listener is unresponsive, then the NF shall attempt to use the other FQDN/IP Address to connect to VES Event Listener to deliver the VES Events. The events shall only be sent to one VES Event Listener at a time. Please note: If a FQDN is used, the DNS query would return a single IP address.

  • The active VES Event Listener (either the primary or secondary) will handle all VES events regardless of domain.

  • VES Credentials: If the NF is using Basic Authentication, then the NF must support the provisioning of security and authentication parameters (HTTP username and password) in order to be able to authenticate with the VES Event Listener. The Username and Password should be set unique per NF instance and should be configured during the NF deployment through a Controller or other means. The same password must also be configured into VES Event Listener instance for successful handshake.

  • VES Heartbeat Interval: This must be a configurable parameter; current default is 60 seconds. Note: the heartbeat interval should be greater than the ack timeout value.

  • Measurement Interval: For measurement events, the measurement interval must be configurable and a default of 300 seconds.

  • ACK Timeout Interval: Configurable, default 5 seconds.

Event Domain Requirements/Expectations
  • Heartbeat: Heartbeat events must be sent to VES Event Listener based on configurable parameter.

  • Faults: Fault events must be sent to the VES Event Listener as soon as they occur.

  • Measurements: All measurement events must be sent at the configured measurementInterval. If the NF provides both application and GuestOS metrics, then they must both use the same measurementInterval.

  • Syslogs: Syslog events should be sent to the VES Event Listener as soon as created, unless the NF is in debug mode (verbose logging enabled to get additional data to diagnose a problem), in which case the syslogs must be stored locally in the NF, for later access and possible secure transfer.

  • Pre-defined Events Formats (Domain: Mobile Flow, TCA, State Chang, etc): Other events (State change, TCA, Mobile Flow, etc) may use other pre-defined VES domains from the VES Common Event Format specification based on the role of the NF.

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

Use of Collector FQDNs and/or IP Address
  • The NF must support two configurable endpoints for the VES Event Listener. One will be the active, primary event listener endpoint. The other will be a standby event listener in the event the active endpoint is unavailable.

  • When sending an event (FM, PM, Syslog, HB), the NF shall establish an HTTPS connection to one VES Event Listener FQDN/IP Address (if not already established) and send a VES event to it. Note that connections are not persistent. The events shall only be sent to only one VES Event Listener at a time.

  • The NF must be able to detect that a VES Event Listener endpoint is unavailable, and trigger the fail-over to the backup endpoint. The mechanism for detecting unavailability must be configurable by the Service Operator (e.g. number of attempts, timeout value).

  • If the NF is sending events to the VES Event Listener backup endpoint, then the NF must poll the primary endpoint on a configurable interval to check if the primary endpoint is now available. The NF may use the Heartbeat event or another mechanism to test availability. If the primary endpoint becomes available, then the NF must fallback to the primary endpoint.

  • A NF must only send a unique event to a single VES Event Listener endpoint at a time. In other words, the NF must not send a duplicate event to the secondary endpoint unless the delivery to the primary endpoint failed.

  • If both Primary and Secondary endpoints are not available, then the NF shall buffer the events locally. Refer to the Buffering of Events section for full details.

  • If a NF is unable to establish a connection with a VES Event Listener or does not get an acknowledgement within a specified time, then it should log this failure and, optionally, send a fault event indicating connection/acknowledgement failure via the alternate FQDN/IP Address. The intent of this fault is to inform the Service Operator that the VES Event Listener endpoint has become unreachable by the NF.

Versioning

Three types of version numbers supported by this specification:

  • The API specification itself is versioned. Going forward, the major number of the specification version will be incremented whenever any change could break an existing client (e.g., a field name is deleted or changed). All other changes to the spec (e.g., a field name is added, or text changes are made to the specification itself) will increment only the minor number or patch number. Note that the major number appears in REST resource URLs as v# (where ‘#’ is the major number). Minor and patch numbers are communicated in HTTP headers. For more information, see the API Versioning writeup in section 6.1.

  • The JSON schema is versioned. Going forward, the major number of the JSON schema will be incremented whenever any change could break an existing client (e.g., a field name is deleted or changed). All other changes to the schema (e.g., a field name is added or text changes are made to the field descriptions) will increment only the minor number or patch number.

  • The field blocks are versioned. Field blocks include the commonEventHeader and the domain blocks (e.g., the faultFields block). Going forward, the major number of each field block will be incremented whenever any change to that block could break an existing client (e.g., a field name is deleted or changed). All other changes to that block (e.g., a field name is added or text changes are made to the field descriptions) will increment only the minor number.

Field Block Versions

A summary of the latest field block version enums as of this version of the API spec is provided below:

  • commonEventHeader version 4.1 (note: the enum with support 4.0, 4.0.1, 4.1 to avoid breaking clients of earlier versions of major version 4)

  • commonEventHeader vesEventListenerVersion enum: 7.1 (note: the enum will support 7.0, 7.0.1, 7.1 to avoid breaking clients of earlier versions of major version 7)

  • faultFieldsVersion:4.0

  • heartbeatFieldsVersion: 3.0

  • measurementFieldsVersion: 4.0

  • mobileFlowFieldsVersion: 4.0

  • notificationFieldsVersion: 2.0

  • otherFieldsVersion: 3.0

  • perf3gppFieldsVersion: 1.0

  • pnfRegistrationFieldsVersion: 2.0

  • sigSignalingFieldsVersion: 3.0

  • stateChangeFieldsVersion: 4.0

  • syslogFieldsVersion: 4.0

  • thresholdCrossingFieldsVersion: 4.0

  • voiceQualityFieldsVersion: 4.0

Security

Event sources must identify themselves to the VES Event Listener.

There are 2 methods of HTTP authentication supported: Certificate Authentication and Basic Authentication.

Basic authentication is supported in VES Event Listener for backward compatibility for existing NFs that are already managed by ONAP. New NFs should support Certificate Authentication. Because the security is better, NFs may choose to only support Certificate Authentication and not support Basic Authentication.

Basic Authentication

When using Basic Authentication, the event source must not pass credentials on the query string. Credentials must be sent in an Authorization header as follows:

  1. The username and password are formed into one string as username:password

  2. The resulting string is Base64 encoded to produce the encoded credential.

  3. The encoded credential is communicated in the header after the string Authorization: Basic

Because the credentials are merely encoded but not encrypted, HTTPS (rather than HTTP) should be used. HTTPS will also encrypt and protect event contents.

Sample Request and Response
Sample Request
POST /eventListener/v7 HTTP/1.1
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
content-type: application/json
content-length: 12345
{
    "event": {
        "commonEventHeader": {
            "version": "4.1",
            "vesEventListenerVersion": "7.1.1",
            "domain": "heartbeat",
            "eventName": "Heartbeat_vIsbcMmc",
            "eventId": "heartbeat0000249",
            "sequence": 0,
            "priority": "Normal",
            "reportingEntityId": "cc305d54-75b4-431b-adb2-eb6b9e541234",
            "reportingEntityName": "ibcx0001vm002oam001",
            "sourceId": "de305d54-75b4-431b-adb2-eb6b9e546014",
            "sourceName": "ibcx0001vm002ssc001",
            "nfVendorName": "Ericsson",
            "nfNamingCode": "ibcx",
            "nfcNamingCode": "ssc",
            "startEpochMicrosec": 1413378172000000,
            "lastEpochMicrosec": 1413378172000000,
            "timeZoneOffset": "UTC-05:30"
        }
    }
}
Sample Success Response
HTTPS/1.1 202 Accepted
X-MinorVersion: 1
X-PatchVersion: 1
X-LatestVersion: 7.1
Mutual TLS Certificate Authentication

When using Certificate Authentication, the event source must initialize the HTTPS connection with TLS 1.2 or higher and execute mutual authentication procedures according to RFC5246. The event source must authenticate the VES Listener certificate and must provide its own X.509v3 end-entity certificate to the VES Listener for authentication. The Subject Name in the end-entity certificate must be used according to RFC5280. If a certificate is provided by the NF but it is invalid, the VES Listener is expected to reject the connection and not fall back to basic authentication.

Resource Structure

REST resources are defined with respect to a ServerRoot:

ServerRoot = https://{Domain|IP}:{Port}/{optionalRoutingPath}

The resource structure is provided below:

{ServerRoot}
    |
    |--- /eventListener/v{apiVersion}
             |
             |--- /eventBatch

Figure 1: REST Resource Structure

The {Port} above is typically 8443.

Common Event Format

A JSON schema describing the Common Event Format is provided below and is reproduced in the tables that follow.

JSON

Note on optional fields:

If the event publisher collects a field that is identified as optional in the data structures below, then the event publisher must send that field.

Note on extensible fields:

VES contains various extensible structures (e.g., hashMap) that enable event publishers to send information that has not been explicitly defined in VES data structures.

  • Event publishers must not send information through extensible structures where VES has explicitly defined fields for that information. For example, event publishers must not send information like cpuIdle, through an extensible structure, because VES has explicitly defined a cpuUsage.cpuIdle field for the communication of that information.

  • Keys sent through extensible fields should use camel casing to separate words and acronyms; only the first letter of each acronym shall be capitalized.

Common Event Datatypes
Datatype: arrayOfJsonObject

The arrayOfJsonObject datatype provides an array of json objects, each of which is describ ed by name, schema and other meta-information. It consists of the following fields:

Field

Type

Required?

Description

arrayOfJsonObject

jsonObject [ ]

Yes

Array of jsonObject

Datatype: arrayOfNamedHashMap

The arrayOfNamedHashMap datatype provides an array of hashMaps, each of which is associated with a descriptive name. It consists of the following fields:

Field

Type

Required?

Description

arrayOfNamedHashMap

namedHashMap [ ]

Yes

Array of namedHashMap

Datatype: event

The event datatype consists of the following fields which constitute the ‘root level’ of the common event format:

Field

Type

Required?

Description

commonEventHeader

commonEventHeader

Yes

Fields common to all events

faultFields

faultFields

No

Fields specific to fault events

heartbeatFields

heartbeatFields

No

Fields specific to heartbeat events

measurementFields

measurementFields

No

Fields specific to measurement events

mobileFlowFields

mobileFlowFields

No

Fields specific to mobility flow events

notificationFields

notificationFields

No

Fields specific to notification events

otherFields

otherFields

No

Fields specific to other types of events

perf3gppFields

perf3gppFields

No

Fields specific to perf3gpp events

pnfRegistrationFields

pnfRegistrationFields

No

Fields specific to pnfRegistration events

sipSignalingFields

sipSignalingFields

No

Fields specific to sipSignaling events

stateChangeFields

stateChangeFields

No

Fields specific to state change events

syslogFields

syslogFields

No

Fields specific to syslog events

thresholdCrossingAlertFields

thresholdCrossingAlertFields

No

Fields specific to threshold crossing alert events

voiceQualityFields

voiceQualityFields

No

Fields specific to voiceQuality events

Datatype: eventList

The eventList datatype consists of the following fields:

Field

Type

Required?

Description

eventList

event [ ]

Yes

Array of events

Datatype: hashMap

The hashMap datatype is an ‘associative array’, which is an unordered collection of key-value pairs of the form “key”: “value”, where each key and value are strings. Keys should use camel casing to separate words and acronyms; only the first letter of each acronym should be capitalized.

Datatype: jsonObject

The jsonObject datatype provides a json object schema, name and other meta-information along with one or more object instances that conform to the schema:

Field

Type

Required?

Description

objectInstances

JsonObjectInstance [ ]

Yes

Contains one or more instances of the json object

objectName

string

Yes

Name of the json object

objectSchema

string

No

json schema for the object

objectSchemaUrl

string

No

URL to the json schema for the object

nfSubscribedObjectName

string

No

Name of the object associated with the nfSubscriptionId

nfSubscriptionId

string

No

Identifies an openConfig telemetry subscription on a network function, which configures the network function to send complex object data associated with the jsonObject

Datatype: jsonObjectInstance

The jsonObjectInstance datatype provides meta-information about an instance of a jsonObject along with the actual object instance:

Field

Type

Required?

Description

jsonObject

jsonObject

No

Optional recursive specification of jsonObject

objectInstance

object

No

Contains an instance conforming to the jsonObject schema

objectInstanceEpochMicrosec

number

No

the unix time, aka epoch time, associated with this objectInstance–as microseconds elapsed since 1 Jan 1970 not including leap seconds

objectKeys

key [ ]

No

An ordered set of keys that identifies this particular instance of jsonObject (e.g., that places it in a hierarchy)

Datatype: key

The key datatype is a tuple which provides the name of a key along with its value and relative order; it consists of the following fields:

Field

Type

Required?

Description

keyName

string

Yes

Name of the key

keyOrder

Integer

No

Relative sequence or order of the key (with respect to other keys)

keyValue

string

No

Value of the key

Datatype: namedHashMap

The namedHashMap datatype is a hashMap which is associated with and described by a name; it consists of the following fields:

Field

Type

Required?

Description

name

string

Yes

Name associated with or describing the hashmap

hashMap

hashMap

Yes

One or more key:value pairs

Datatype: requestError

The requestError datatype defines the standard request error data structure:

Field

Type

Required?

Description

messageId

string

Yes

Unique message identifier of the format ‘ABCnnnn’ where ‘ABC’ is either ‘SVC’ for Service Exceptions or ‘POL’ for Policy Exception. Exception numbers may be in the range of 0001 to 9999 where 0001 to 2999 are defined by OMA (see section 5.1) and 3000-9999 are available and undefined.

text

string

Yes

Message text, with replacement variables marked with %n, where n is an index into the list of <variables> elements, starting at 1

url

string

No

Hyperlink to a detailed error resource e.g., an HTML page for browser user agents

variables

string

No

List of zero or more strings that represent the contents of the variables used by the message text

Datatype: vendorNfNameFields

The vendorNfNameFields provides vendor, nf and nfModule identifying information:

Field

Type

Required?

Description

vendorName

string

Yes

Network function vendor name

nfModuleName

string

No

Name of the nfModule generating the event

nfName

string

No

Name of the network function generating the event

Common Event Header Data Types
Datatype: commonEventHeader

The commonEventHeader datatype consists of the following fields common to all events:

Field

Type

Required?

Description

domain

string

Yes

Event domain enumeration: ‘fault’, ‘heartbeat’, ‘measurement’, ‘mobileFlow’ , ‘notification’, ‘other’, ‘perf3gpp’, ‘pnfRegistration’, ‘sipSignaling’, ‘stateChange’, ‘syslog’, ‘thresholdCrossingAlert’, ‘voiceQuality’

eventId

string

Yes

Event key that is unique to the event source. The key must be unique within notification life cycle similar to EventID from 3GPP. It could be a sequential number, or a composite key formed from the event fields, such as domain_sequence. The eventId should not include whitespace. For fault events, eventId is the eventId of the initial alarm; if the same alarm is raised again for changed, acknowledged or cleared cases, eventId must be the same as the initial alarm (along with the same startEpochMicrosec but with a different sequence number). Note: see section 1.3 for eventId use case examples.

eventName

string

Yes

eventType

string

No

internalHeader Fields

internalHeader Fields

No

Fields (not supplied by event sources) that the VES Event Listener service can use to enrich the event if needed for efficient internal processing. This is an empty object which is intended to be defined separately by each service provider (e.g., AT&T) implementing the VES Event Listener.

lastEpochMicrosec

number

Yes

the latest unix time aka epoch time associated with the event from any component–as microseconds elapsed since 1 Jan 1970 not including leap seconds

nfcNamingCode

string

No

Network function component type: 3 characters (aligned with vfc naming standards)

nfNamingCode

string

No

Network function type: 4 characters (aligned with vnf and pnf naming standards)

nfVendorName

string

No

priority

string

Yes

reportingEntityId

string

No

UUID identifying the entity reporting the event or detecting a problem in another vnf/vm or pnf which is experiencing the problem. (Note: the AT&T internal enrichment process shall ensure that this field is populated). The reportingEntityId is an id for the reportingEntityName. See ‘reportingEntityName’ for more information.

reportingEntityName

string

Yes

Name of the entity reporting the event or detecting a problem in another vnf/vm or pnf which is experiencing the problem. May be the same as the sourceName. For synthetic events generated by DCAE, it is the name of the app generating the event.

sequence

integer

Yes

Ordering of events communicated by an event source instance (or 0 if not needed)

sourceId

string

No

UUID identifying the entity experiencing the event issue, which may be detected and reported by a separate reporting entity (note: the AT&T internal enrichment process shall ensure that this field is populated). The sourceId is an id for the sourceName. See ‘sourceName’ for more information.

sourceName

string

Yes

Name of the entity experiencing the event issue, which may be detected and reported by a separate reporting entity. The sourceName identifies the device for which data is collected. A valid sourceName must be inventoried in A&AI. If sourceName is a xNF (vnf or pnf), xNFC or VM, then the event must be reporting data for that particular xNF, xNFC or VM. If the sourceName is a xNF, comprised of multiple xNFCs, the data must be reported/aggregated at the xNF level. Data for individual xNFC must not be included in the xNF sourceName event.

startEpochMicrosec

number

Yes

the earliest unix time aka epoch time associated with the event from any component–as microseconds elapsed since 1 Jan 1970 not including leap seconds. For measurements and heartbeats, where events are collected over predefined intervals, startEpochMicrosec shall be rounded to the nearest interval boundary (e.g., the epoch equivalent of 3:00PM, 3:10PM, 3:20PM, etc…). For fault events, startEpochMicrosec is the timestamp of the initial alarm; if the same alarm is raised again for changed, acknowledged or cleared cases, startEpoch Microsec must be the same as the initial alarm (along with the same eventId and an incremental sequence number). For devices with no timing source (clock), the default value will be 0 and the VES collector will replace it with Collector time stamp (when the event is received)

timeZoneOffset

string

No

Offset to GMT to indicate local time zone for device formatted as ‘UTC+/-hh:mm’; see time_zone_abbreviations for UTC offset examples

version

string

Yes

Version of the event header as “#.#” where # is a digit; see section 1 for the correct digits to use.

vesEventListenerVersion

string

Yes

Version of the ves event listener api spec that this event is compliant with (as “#” or “#.#” or “#.#.#” where # is a digit; see section 1 for the correct digits to use).

Datatype: internalHeaderFields

The internalHeaderFields datatype is an undefined object which can contain arbitrarily complex JSON structures. It is intended to be defined separately by each service provider (e.g., AT&T) implementing the VES Event Listener. The fields in internalHeaderFields are not provided by any event source but instead are added by the VES Event Listener service itself as part of an event enrichment process necessary for efficient internal processing of events received by the VES Event Listener.

Technology Independent Datatypes
‘Fault’ Domain Datatypes
Datatype: faultFields

The faultFields datatype consists of the following fields:

Field

Type

Required?

Description

alarmAdditional Information

hashMap

No

Additional alarm information.

  • Note1: for SNMP mapping to VES, for hash key use OID of varbind, for value use incoming data for that varbind).

  • Note2: Alarm ID for 3GPP should be included (if applicable) in alarmAdditonalInformation as ‘alarmId’:’alarmIdValue’.

Could contain managed object instance as separate key:value; could add probable cause as separate key:value.

alarmCondition

string

Yes

Short name of the alarm condition/problem, such as a trap name. Should not have white space (e.g., tpLgCgiNotInConfig, BfdSessionDown, linkDown, etc…)

alarmInterfaceA

string

No

Card, port, channel or interface name of the device generating the alarm. This could reflect managed object.

eventCategory

string

No

Event category, for example: ‘license’, ‘link’, ‘routing’, ‘security’, ‘signaling’

eventSeverity

string

Yes

Event severity enumeration: ‘CRITICAL’, ‘MAJOR’, ‘MINOR’, ‘WARNING’, ‘NORMAL’. NORMAL is used to represent clear.

eventSourceType

string

Yes

Examples: ‘card’, ‘host’, ‘other’, ‘port’, ‘portThreshold’, ‘router’, ‘slotThreshold’, ‘switch’, ‘virtualMachine’, ‘virtualNetworkFunction’. This could be managed object class.

faultFieldsVersion

string

Yes

Version of the faultFields block as “#.#” where # is a digit; see section 1 for the correct digits to use.

specificProblem

string

Yes

Description of the alarm or problem (e.g., ‘eNodeB 155197 in PLMN 310-410 with eNodeB name KYL05197 is lost’). 3GPP probable cause would be included in this field.

vfStatus

string

Yes

Virtual function status enumeration: ‘Active’, ‘Idle’, ‘Preparing to terminate’, ‘Ready to terminate’, ‘Requesting Termination’

Heartbeat’ Domain Datatypes
Datatype: heartbeatFields

The heartbeatFields datatype is an optional field block for fields specific to heartbeat events; it consists of the following fields:

Field

Type

Required?

Description

additionalFields

hashMap

No

Additional expansion fields if needed

heartbeatFieldsVersion

string

Yes

Version of the heartbeatFields block as “#.#” where # is a digit; see section 1 for the correct digits to use.

heartbeatInterval

Integer

Yes

Current heartbeatInterval in seconds

‘Measurements’ Domain Datatypes

Note: NFs are required to report exactly one Measurement event per period per sourceName.

Datatype: codecsInUse

The codecsInUse datatype consists of the following fields describing the number of times an identified codec was used over the measurementInterval:

Field

Type

Required?

Description

codecIdentifer

string

Yes

Description of the codec

numberInUse

integer

Yes

Number of such codecs in use

Datatype: cpuUsage

The cpuUsage datatype defines the usage of an identifier CPU and consists of the following fields:

Field

Type

Required?

Description

cpuCapacityContention

number

No

The amount of time the CPU cannot run due to contention, in milliseconds over the measurementInterval

cpuDemandAvg

number

No

The total CPU time that the NF/NFC/VM could use if there was no contention, in milliseconds over the measurementInterval

cpuDemandMhz

number

No

CPU demand in MHz

cpuDemandPct

number

No

CPU demand as a percentage of the provisioned capacity

cpuIdentifier

string

Yes

CPU Identifier

cpuIdle

number

No

Percentage of CPU time spent in the idle task

cpuLatencyAvg

number

No

Percentage of time the VM is unable to run because it is contending for access to the physical CPUs

cpuOverheadAvg

number

No

The overhead demand above available allocations and reservations, in milliseconds over the measurementInterval

cpuSwapWaitTime

number

No

Swap wait time, in milliseconds over the measurementInterval

cpuUsageInterrupt

number

No

Percentage of time spent servicing interrupts

cpuUsageNice

number

No

Percentage of time spent running user space processes that have been niced

cpuUsageSoftIrq

number

No

Percentage of time spent handling soft irq interrupts

cpuUsageSteal

number

No

Percentage of time spent in involuntary wait which is neither user, system or idle time and is effectively time that went missing

cpuUsageSystem

number

No

Percentage of time spent on system tasks running the kernel

cpuUsageUser

number

No

Percentage of time spent running un-niced user space processes

cpuWait

number

No

Percentage of CPU time spent waiting for I/O operations to complete

percentUsage

number

Yes

Aggregate cpu usage of the virtual machine on which the xNFC reporting the event is running

Datatype: diskUsage

The diskUsage datatype defines the usage of a disk and consists of the following fields:

Field

Type

Required?

Description

diskBusResets

number

No

Number of bus resets over the measurementInterval

diskCommandsAborted

number

No

Number of disk commands aborted over the measurementInterval

diskCommandsAvg

number

No

Average number of commands per second over the measurementInterval

diskFlushRequests

number

No

Total flush requests of the disk cache over the measurementInterval

diskFlushTime

number

No

Milliseconds spent on disk cache flushing over the measurementInterval

diskIdentifier

string

Yes

Disk Identifier

diskIoTimeAvg

number

No

Milliseconds spent doing input/output operations over 1 sec; treat this metric as a device load percentage where 1000ms matches 100% load; provide the average over the measurement interval

diskIoTimeLast

number

No

Milliseconds spent doing input/output operations over 1 sec; treat this metric as a device load percentage where 1000ms matches 100% load; provide the last value measurement within the measurement interval

diskIoTimeMax

number

No

Milliseconds spent doing input/output operations over 1 sec; treat this metric as a device load percentage where 1000ms matches 100% load; provide the maximum value measurement within the measurement interval

diskIoTimeMin

number

No

Milliseconds spent doing input/output operations over 1 sec; treat this metric as a device load percentage where 1000ms matches 100% load; provide the minimum value measurement within the measurement interval

diskMergedReadAvg

number

No

Number of logical read operations that were merged into physical read operations, e.g., two logical reads were served by one physical disk access; provide the average measurement within the measurement interval

diskMergedReadLast

number

No

Number of logical read operations that were merged into physical read operations, e.g., two logical reads were served by one physical disk access; provide the last value measurement within the measurement interval

diskMergedReadMax

number

No

Number of logical read operations that were merged into physical read operations, e.g., two logical reads were served by one physical disk access; provide the maximum value measurement within the measurement interval

diskMergedReadMin

number

No

Number of logical read operations that were merged into physical read operations, e.g., two logical reads were served by one physical disk access; provide the minimum value measurement within the measurement interval

diskMergedWriteAvg

number

No

Number of logical write operations that were merged into physical write operations, e.g., two logical writes were served by one physical disk access; provide the average measurement within the measurement interval

diskMergedWriteLast

number

No

Number of logical write operations that were merged into physical write operations, e.g., two logical writes were served by one physical disk access; provide the last value measurement within the measurement interval

diskMergedWriteMax

number

No

Number of logical write operations that were merged into physical write operations, e.g., two logical writes were served by one physical disk access; provide the maximum value measurement within the measurement interval

diskMergedWriteMin

number

No

Number of logical write operations that were merged into physical write operations, e.g., two logical writes were served by one physical disk access; provide the minimum value measurement within the measurement interval

diskOctetsRead Avg

number

No

Number of octets per second read from a disk or partition; provide the average measurement within the measurement interval

diskOctetsRead

Last

number

No

Number of octets per second read from a disk or partition; provide the last measurement within the measurement interval

diskOctetsRead Max

number

No

Number of octets per second read from a disk or partition; provide the maximum measurement within the measurement interval

diskOctetsRead Min

number

No

Number of octets per second read from a disk or partition; provide the minimum measurement within the measurement interval

diskOctetsWrite Avg

number

No

Number of octets per second written to a disk or partition; provide the average measurement within the measurement interval

diskOctetsWrite Last

number

No

Number of octets per second written to a disk or partition; provide the last measurement within the measurement interval

diskOctetsWriteMax

number

No

Number of octets per second written to a disk or partition; provide the maximum measurement within the measurement interval

diskOctetsWriteMin

number

No

Number of octets per second written to a disk or partition; provide the minimum measurement within the measurement interval

diskOpsReadAvg

number

No

Number of read operations per second issued to the disk; provide the average measurement within the measurement interval

diskOpsReadLast

number

No

Number of read operations per second issued to the disk; provide the last measurement within the measurement interval

diskOpsReadMax

number

No

Number of read operations per second issued to the disk; provide the maximum measurement within the measurement interval

diskOpsReadMin

number

No

Number of read operations per second issued to the disk; provide the minimum measurement within the measurement interval

diskOpsWriteAvg

number

No

Number of write operations per second issued to the disk; provide the average measurement within the measurement interval

diskOpsWriteLast

number

No

Number of write operations per second issued to the disk; provide the last measurement within the measurement interval

diskOpsWrite Max

number

No

Number of write operations per second issued to the disk; provide the maximum measurement within the measurement interval

diskOpsWriteMin

number

No

Number of write operations per second issued to the disk; provide the minimum measurement within the measurement interval

diskPendingOperationsAvg

number

No

Queue size of pending I/O operations per second; provide the average measurement within the measurement interval

diskPendingOperationsLast

number

No

Queue size of pending I/O operations per second; provide the last measurement within the measurement interval

diskPendingOperationsMax

number

No

Queue size of pending I/O operations per second; provide the maximum measurement within the measurement interval

diskPendingOperationsMin

number

No

Queue size of pending I/O operations per second; provide the minimum measurement within the measurement interval

diskReadCommandsAvg

number

No

Average number of read commands issued per second to the disk over the measurementInterval

diskTime

number

No

Nanoseconds spent on disk cache reads/writes within the measurement interval

diskTimeReadAvg

number

No

Milliseconds a read operation took to complete; provide the average measurement within the measurement interval

diskTimeRead Last

number

No

Milliseconds a read operation took to complete; provide the last measurement within the measurement interval

diskTimeRead Max

number

No

Milliseconds a read operation took to complete; provide the maximum measurement within the measurement interval

diskTimeRead Min

number

No

Milliseconds a read operation took to complete; provide the minimum measurement within the measurement interval

diskTimeWrite Avg

number

No

Milliseconds a write operation took to complete; provide the average measurement within the measurement interval

diskTimeWrite Last

number

No

Milliseconds a write operation took to complete; provide the last measurement within the measurement interval

diskTimeWrite Max

number

No

Milliseconds a write operation took to complete; provide the maximum measurement within the measurement interval

diskTimeWrite Min

number

No

Milliseconds a write operation took to complete; provide the minimum measurement within the measurement interval

diskTotalReadLatencyAvg

number

No

Average read time from the perspective of a Guest OS: sum of the Kernel Read Latency and Physical Device Read Latency in milliseconds over the measurement interval

diskTotalWriteLatencyAvg

number

No

Average write time from the perspective of a Guest OS: sum of the Kernel Write Latency and Physical Device Write Latency in milliseconds over the measurement interval

diskWeightedIoTimeAvg

number

No

Measure in ms over 1 sec of both I/O completion time and the backlog that may be accumulating. Value is the average within the collection interval.

diskWeightedIoTimeLast

number

No

Measure in ms over 1 sec of both I/O completion time and the backlog that may be accumulating. Value is the last within the collection interval.

diskWeightedIoTimeMax

number

No

Measure in ms over 1 sec of both I/O completion time and the backlog that may be accumulating. Value is the maximum within the collection interval.

diskWeightedIoTimeMin

number

No

Measure in ms over 1 sec of both I/O completion time and the backlog that may be accumulating. Value is the minimum within the collection interval.

diskWriteCommandsAvg

number

No

Average number of write commands issued per second to the disk over the measurementInterval

Datatype: filesystemUsage

The filesystemUsage datatype consists of the following fields:

Field

Type

Required?

Description

filesystemName

string

Yes

File system name

blockConfigured

number

Yes

Configured block storage capacity in GB

blockIops

number

Yes

Block storage input-output operations per second

blockUsed

number

Yes

Used block storage capacity in GB

ephemeralConfigured

number

Yes

Configured ephemeral storage capacity in GB

ephemeralIops

number

Yes

Ephemeral storage input-output operations per second

ephemeralUsed

number

Yes

Used ephemeral storage capacity in GB

Datatype: hugePages

The hugePages datatype provides metrics on system hugePages; it consists of the following fields:

Field

Type

Required?

Description

bytesFree

number

No

Number of free hugePages in bytes

bytesUsed

number

No

Number of used hugePages in bytes

hugePagesIdentifier

string

Yes

HugePages identifier

percentFree

number

No

Number of free hugePages in percent

percentUsed

number

No

Number of used hugePages in percent

vmPageNumberFree

number

No

Number of free vmPages in numbers

vmPageNumberUsed

number

No

Number of used vmPages in numbers

Datatype: ipmi (Intelligent Platform Management Interface)

The ipmi datatype provides intelligent platform management interface metrics; it consists of the following fields:

Field

Type

Required?

Description

exitAirTemperature

number

No

System fan exit air flow temperature in Celsius

frontPanelTemperature

number

No

Front panel temp in Celsius

ioModuleTemperature

number

No

Io module temp in Celsius

ipmiBaseboardTemperatureArray

ipmiBaseboard Temperature [ ]

No

Array of ipmiBaseboard Temperature objects

ipmiBaseboardVoltageRegulator Array

ipmiBaseboard VoltageRegulator [ ]

No

Array of ipmiBaseboard VoltageRegulator objects

ipmiBatteryArray

ipmiBattery [ ]

No

Array of ipmiBattery objects

ipmiFanArray

ipmiFan [ ]

No

Array of ipmiFan objects

ipmiGlobalAggregateTemperatureMarginArray

ipmiGlobalAggregateTemperatureMargin []

No

ipmi global aggregate temperature margin

ipmiHsbpArray

ipmiHsbp [ ]

No

Array of ipmiHsbp objects

ipmiNicArray

ipmiNic [ ]

No

Array of ipmiNic objects

ipmiPowerSupplyArray

ipmiPowerSupply [ ]

No

Array of ipmiPowerSupply objects

ipmiProcessorArray

ipmiProcessor [ ]

No

Array of ipmiProcessor objects

systemAirflow

number

No

Airflow in cubic feet per minute (cfm)

Datatype: ipmiBaseboardTemperature

The ipmiBaseboardTemperature datatype consists of the following fields which describe ipmi baseboard temperature metrics:

Field

Type

Required?

Description

baseboardTemperature

number

No

Baseboard temperature in celsius

baseboardTemperatureIdentifier

string

Yes

Identifier for the location where the temperature is taken

Datatype: ipmiBaseboardVoltageRegulator

The ipmiBaseboardVoltageRegulator datatype consists of the following fields which describe ipmi baseboard voltage regulator metrics:

Field

Type

Required?

Description

baseboardVoltageRegulatorIdentifier

string

Yes

Identifier for the baseboard voltage regulator

voltageRegulatorTemperature

number

No

Voltage regulator temperature in celsius

Datatype: ipmiBattery

The ipmiBattery datatype consists of the following fields which describe ipmi battery metrics:

Field

Type

Required?

Description

batteryIdentifier

string

Yes

Identifier for the battery

batteryType

string

No

Type of battery

batteryVoltageLevel

number

No

Battery voltage level

Datatype: ipmiFan

The ipmiFan datatype consists of the following fields which describe ipmi fan metrics:

Field

Type

Required?

Description

fanIdentifier

string

Yes

Identifier for the fan

fanSpeed

number

No

Fan speed in revolutions per minute (rpm)

Datatype: ipmiGlobalAggregateTemperatureMargin

The ipmiGlobalAggregateTemperatureMargin datatype consists of the following fields:

Field

Type

Required?

Description

globalAggregateTemperatureMargin

number

No

Temperature margin in Celsius relative to a throttling thermal trip point

globalAggregateTemperatureMarginIdentifier

string

Yes

Identifier for the ipmi global aggregate temperature margin metrics

Datatype: ipmiHsbp

The ipmiHsbp datatype provides ipmi hot swap backplane power metrics; it consists of the following fields:

Field

Type

Required?

Description

hsbpIdentifier

string

Yes

Identifier for the hot swap backplane power unit

hsbpTemperature

number

No

Hot swap backplane power temperature in celsius

Datatype: ipmiNic

The ipmiNic datatype provides network interface control care metrics; it consists of the following fields:

Field

Type

Required?

Description

nicIdentifier

string

Yes

Identifier for the network interface control card

nicTemperature

number

No

nic temperature in Celsius

Datatype: ipmiPowerSupply

The ipmiPowerSupply datatype provides ipmi power supply metrics; it consists of the following fields:

Field

Type

Required?

Description

powerSupplyCurrentOutputPercent

number

No

Current output voltage as a percentage of the design specified level

powerSupplyIdentifier

string

Yes

Identifier for the power supply

powerSupplyInputPower

number

No

Input power in watts

powerSupplyTemperature

number

No

Power supply temperature in Celsius

Datatype: ipmiProcessor

The ipmiProcessor datatype provides ipmi processor metrics; it consists of the following fields:

Field

Type

Required?

Description

processorDimmAggregateThermalMarginArray

processorDimm AggregateThermal Margin [ ]

No

Array of processorDimmAggregate ThermalMargin objects

processorDtsThermalMargin

number

No

Front panel temperature in celsius

processorIdentifier

string

Yes

Identifier for the power supply

processorThermalControlPercent

number

No

Io module temperatue in celsius

Datatype: latencyBucketMeasure

The latencyBucketMeasure datatype consists of the following fields which describe the number of counts falling within a defined latency bucket:

Field

Type

Required?

Description

countsInTheBucket

number

Yes

Number of counts falling within a defined latency bucket

highEndOfLatencyBucket

number

No

High end of bucket range (typically in ms)

lowEndOfLatencyBucket

number

No

Low end of bucket range (typically in ms)

Datatype: load

The load datatype provides metrics on system cpu and io utilization obtained using /proc/loadavg; it consists of the following fields:

Field

Type

Required?

Description

longTerm

number

No

number of jobs in the run queue (state R, cpu utilization) or waiting for disk I/O (state D, io utilization) averaged over 15 minutes using /proc/loadavg

midTerm

number

No

number of jobs in the run queue (state R, cpu utilization) or waiting for disk I/O (state D, io utilization) averaged over 5 minutes using /proc/loadavg

shortTerm

number

No

number of jobs in the run queue (state R, cpu utilization) or waiting for disk I/O (state D, io utilization) averaged over 1 minute using /proc/loadavg

Datatype: machineCheckException

The machineCheckException datatype describes machine check exceptions; it consists of the following fields:

Field

Type

Required?

Description

correctedMemoryErrors

number

No

Total hardware errors that were corrected by the hardware (e.g. data corruption corrected via ECC) over the measurementInterval. These errors do not require immediate software actions, but are still reported for accounting and predictive failure analysis

correctedMemoryErrors In1Hr

number

No

Total hardware errors that were corrected by the hardware over the last one hour

uncorrectedMemoryErrors

number

No

Total uncorrected hardware errors that were detected by the hardware (e.g., causing data corruption) over the measurementInterval. These errors require a software response.

uncorrectedMemoryErrors In1Hr

number

No

Total uncorrected hardware errors that were detected by the hardware over the last one hour

vmIdentifier

string

Yes

Virtual machine identifier associated with the machine check exception

Datatype: measurementFields

The measurementFields datatype consists of the following fields:

Field

Type

Required?

Description

additionalFields

hashMap

No

Additional measurement fields if needed

additionalMeasurements

arrayOfNamedHashMap

No

Array of named hashMap if needed

additionalObjects

arrayOfJsonObject

No

Array of JSON objects described by name, schema and other meta-information, if needed

codecUsageArray

codecsInUse []

No

Array of codecs in use

concurrentSessions

integer

No

Peak concurrent sessions for the VM or xNF (depending on the context) over the measurementInterval

configuredEntities

integer

No

Depending on the context over the measurementInterval: peak total number of users, subscribers, devices, adjacencies, etc., for the VM, or peak total number of subscribers, devices, etc., for the xNF

cpuUsageArray

cpuUsage []

No

Usage of an array of CPUs

diskUsageArray

diskUsage []

No

Usage of an array of disks

featureUsageArray

hashMap

No

The hashMap key should identify the feature, while the value defines the number of times the identified feature was used

filesystemUsageArray

filesystemUsage [ ]

No

Filesystem usage of the VM on which the xNFC reporting the event is running

hugePagesArray

hugePages [ ]

No

Array of metrics on hugePages

ipmi

ipmi

No

Intelligent platform management interface metrics

latencyDistribution

latencyBucketMeasure [ ]

No

Array of integers representing counts of requests whose latency in milliseconds falls within per-xNF configured ranges; where latency is the duration between a service request and its fulfillment.

loadArray

load [ ]

No

Array of system load metrics

machineCheckExceptionArray

machineCheckException [ ]

No

Array of machine check exceptions

meanRequestLatency

number

No

Mean seconds required to respond to each request for the VM on which the xNFC reporting the event is running

measurementFieldsVersion

string

Yes

Version of the measurementFields block as “#.#” where # is a digit; see section 1 for the correct digits to use.

measurementInterval

number

Yes

Interval over which measurements are being reported in seconds

memoryUsageArray

memoryUsage []

No

Memory usage of an array of VMs

nfcScalingMetric

integer

No

Represents busy-ness of the network function from 0 to 100 as reported by the nfc

nicPerformanceArray

nicPerformance [ ]

No

Performance metrics of an array of network interface cards

numberOfMediaPortsInUse

integer

No

Number of media ports in use

processStatsArray

processStats [ ]

No

Array of metrics on system processes

requestRate

number

No

Peak rate of service requests per second to the xNF over the measurementInterval

Datatype: memoryUsage

The memoryUsage datatype defines the memory usage of a virtual machine and consists of the following fields:

Field

Type

Required?

Description

memoryBuffered

number

No

Kibibytes of temporary storage for raw disk blocks

memoryCached

number

No

Kibibytes of memory used for cache

memoryConfigured

number

No

Kibibytes of memory configured in the virtual machine on which the xNFC reporting the event is running

memoryDemand

number

No

Host demand in kibibytes

memoryFree

number

Yes

Kibibytes of physical RAM left unused by the system

memoryLatencyAvg

number

No

Percentage of time the VM is waiting to access swapped or compressed memory

memorySharedAvg

number

No

Shared memory in kilobytes

memorySlabRecl

number

No

The part of the slab that can be reclaimed such as caches measured in kibibytes

memorySlabUnrecl

number

No

The part of the slab that cannot be reclaimed even when lacking memory measure in kibibytes

memorySwapInAvg

number

No

Amount of memory swapped-in from host cache in kibibytes

memorySwapInRateAvg

number

No

Rate at which memory is swapped from disk into active memory during the interval in kilobytes per second

memorySwapOutAvg

number

No

Amount of memory swapped-out to host cache in kibibytes

memorySwapOutRateAvg

number

No

Rate at which memory is being swapped from active memory to disk during the current interval in kilobytes per second

memorySwapUsedAvg

number

No

Space used for caching swapped pages in the host cache in kibibytes

memoryUsed

number

Yes

Total memory minus the sum of free, buffered, cached and slab memory measured in kibibytes

percentMemoryUsage

number

No

Percentage of memory usage; value = (memoryUsed / (memoryUsed + memoryFree) x 100 if denomintor is nonzero, or 0, if otherwise.

vmIdentifier

string

Yes

Virtual Machine identifier associated with the memory metrics

Datatype: nicPerformance

The nicPerformance datatype consists of the following fields which describe the performance and errors of an of an identified virtual network interface card:

Field

Type

Required?

Description

administrativeState

string

No

Administrative state: enum: ‘inService’, ‘outOfService’

nicIdentifier

string

Yes

Network interface card identifier

operationalState

string

No

Operational state: enum: ‘inService’, ‘outOfService’

receivedBroadcastPacketsAccumulated

number

No

Cumulative count of broadcast packets received as read at the end of the measurement interval

receivedBroadcastPacketsDelta

number

No

Count of broadcast packets received within the measurement interval

receivedDiscardedPacketsAccumulated

number

No

Cumulative count of discarded packets received as read at the end of the measurement interval

receivedDiscardedPacketsDelta

number

No

Count of discarded packets received within the measurement interval

receivedErrorPacketsAccumulated

number

No

Cumulative count of error packets received as read at the end of the measurement interval

receivedErrorPacketsDelta

number

No

Count of error packets received within the measurement interval

receivedMulticastPacketsAccumulated

number

No

Cumulative count of multicast packets received as read at the end of the measurement interval

receivedMulticastPacketsDelta

number

No

Count of multicast packets received within the measurement interval

receivedOctetsAccumulated

number

No

Cumulative count of octets received as read at the end of the measurement interval

receivedOctetsDelta

number

No

Count of octets received within the measurement interval

receivedPercentDiscard

number

No

Percentage of discarded packets received; value = (receivedDiscardedPacketsDelta / receivedTotalPacketsDelta) x 100, if denominator is nonzero, or 0, if otherwise.

receivedPercentError

number

No

Percentage of error packets received; value = (receivedErrorPacketsDelta / receivedTotalPacketsDelta) x 100, if denominator is nonzero, or 0, if otherwise.

receivedTotalPacketsAccumulated

number

No

Cumulative count of all packets received as read at the end of the measurement interval

receivedTotalPacketsDelta

number

No

Count of all packets received within the measurement interval

receivedUnicastPacketsAccumulated

number

No

Cumulative count of unicast packets received as read at the end of the measurement interval

receivedUnicastPacketsDelta

number

No

Count of unicast packets received within the measurement interval

receivedUtilization

number

No

Percentage of utilization received; value = (receivedOctetsDelta / (speed x (lastEpochMicrosec - startEpochMicrosec) )) x 100, if denominator is nonzero, or 0, if otherwise.

speed

number

No

Speed configured in mbps.

transmittedBroadcastPacketsAccumulated

number

No

Cumulative count of broadcast packets transmitted as read at the end of the measurement interval

transmittedBroadcastPacketsDelta

number

No

Count of broadcast packets transmitted within the measurement interval

transmittedDiscardedPacketsAccumulated

number

No

Cumulative count of discarded packets transmitted as read at the end of the measurement interval

transmittedDiscardedPacketsDelta

number

No

Count of discarded packets transmitted within the measurement interval

transmittedErrorPacketsAccumulated

number

No

Cumulative count of error packets transmitted as read at the end of the measurement interval

transmittedErrorPacketsDelta

number

No

Count of error packets transmitted within the measurement interval

transmittedMulticastPacketsAccumulated

number

No

Cumulative count of multicast packets transmitted as read at the end of the measurement interval

transmittedMulticastPacketsDelta

number

No

Count of multicast packets transmitted within the measurement interval

transmittedOctetsAccumulated

number

No

Cumulative count of octets transmitted as read at the end of the measurement interval

transmittedOctetsDelta

number

No

Count of octets transmitted within the measurement interval

transmittedPercentDiscard

number

No

Percentage of discarded packets transmitted; value = (transmittedDiscardedPacketsDelta / transmittedTotalPacketsDelta) x 100, if denominator is nonzero, or 0, if otherwise.

transmittedPercentError

number

No

Percentage of error packets received; value = (transmittedErrorPacketsDelta / transmittedTotalPacketsDelta) x 100, if denominator is nonzero, or 0, if otherwise.

transmittedTotalPacketsAccumulated

number

No

Cumulative count of all packets transmitted as read at the end of the measurement interval

transmittedTotalPacketsDelta

number

No

Count of all packets transmitted within the measurement interval

transmittedUnicastPacketsAccumulated

number

No

Cumulative count of unicast packets transmitted as read at the end of the measurement interval

transmittedUnicastPacketsDelta

number

No

Count of unicast packets transmitted within the measurement interval

transmittedUtilization

number

No

Percentage of utilization transmitted; value = (transmittedOctetsDelta / (speed x (lastEpochMicrosec - startEpochMicrosec))) x 100, if denominator is nonzero, or 0, if otherwise.

valuesAreSuspect

string

Yes

Enumeration: ‘true’ or ‘false’. If ‘true’ then the vNicPerformance values are likely inaccurate due to counter overflow or other conditions.

Datatype: processorDimmAggregateThermalMargin

The processorDimmAggregateThermalMargin datatype provides intelligent platform management interface (ipmi) processor dual inline memory module aggregate thermal margin metrics; it consists of the following fields:

Field

Type

Required?

Description

processorDimmAggregateThermal MarginIdentifier

string

Yes

identifier for the aggregate thermal margin metrics from the processor dual inline memory module

thermalMargin

number

Yes

the difference between the DIMM’s current temperature, in celsius, and the DIMM’s throttling thermal trip

Datatype: processStats

The processStats datatype provides metrics on system processes; it consists of the following fields:

Field

Type

Required?

Description

forkRate

number

No

The number of threads created since the last reboot

processIdentifier

string

Yes

processIdentifier

psStateBlocked

number

No

The number of processes in a blocked state

psStatePaging

number

No

The number of processes in a paging state

psStateRunning

number

No

The number of processes in a running state

psStateSleeping

number

No

The number of processes in a sleeping state

psStateStopped

number

No

The number of processes in a stopped state

psStateZombie

number

No

The number of processes in a zombie state

‘Notification’ Domain Datatypes
Datatype: notificationFields

The notificationFields datatype consists of the following fields:

Field

Type

Required?

Description

additionalFields

hashMap

No

Additional notification fields if needed

arrayOfNamedHashMap

namedHashMap [ ]

No

Array of named hashMaps

changeContact

string

No

Identifier for a contact related to the change

changeIdentifier

string

Yes

System or session identifier associated with the change

changeType

string

Yes

Describes what has changed for the entity, for example: configuration changed, capability added, capability removed…

newState

string

No

New state of the entity, for example: ‘inService’, ‘maintenance’, ‘outOfService’

notificationFieldsVersion

string

Yes

Version of the notificationFields block as “#.#” where # is a digit; see section 1 for the correct digits to use.

oldState

string

No

Previous state of the entity, for example: ‘inService’, ‘maintenance’, ‘outOfService’

stateInterface

string

No

Card or port name of the entity that changed state

The fileReady notification event is used by 3GPP-compliant NFs to notify ONAP that a PM file is available for upload. The notificationFields are populated as follows:

arrayOfNamedHashMap: The array is named for the PM file as defined in 3GPP TS 28.550. The array contains the following key value pairs:

  • location in the form protocol://ipAddress:port/path/filename; e.g. “location” : “ftpes://135.3.1.44:21/pmfiles/A20180531.1030+0600-1045+0600A20000626.2315+0200-2330+0200_NodeBId.gz”

  • compression containing the compression type used for the PM file; e.g. “compression” : “gzip”

  • fileFormatType containing the format type of the PM file; e.g. “fileFormatType” : “org.3GPP.32.435#measCollec”

  • fileFormatVersion containing the format version of the PM file; e.g. “fileFormatVersion” : “V10”

  • other vendor-defined key-value pairs as needed

changeIdentifier: set to PM_MEAS_FILES

changeType: set to fileReady

Other notificationFields are not used for fileReady.

‘Other’ Domain Datatypes
Datatype: otherFields

The otherFields datatype defines fields for events belonging to the ‘other’ domain of the commonEventHeader domain enumeration; it consists of the following fields:

Field

Type

Required?

Description

arrayOfNamedHashMap

arrayOfNamedHashMap

No

Array of named hashMaps

hashMap

hashMap

No

Array of name-value pairs

jsonObjects

arrayOfJsonObject

No

Array of JSON objects described by name, schema and other meta-information

otherFieldsVersion

string

Yes

Version of the otherFields block as “#.#” where # is a digit; see section 1 for the correct digits to use.

‘perf3gpp’ Domain Datatypes
Datatype: measDataCollection

The measDataCollection datatype defines a 3GPP measurement collection structure aligned with the 3GPP PM format; it consists of the following fields:

Field

Type

Required?

Description

formatVersion

string

No

3GPP PM reporting file format version from pre-standard TS 28.550 v2.0.0

granularityPeriod

string

Yes

Granularity period for the PM report in seconds

measInfoList

measInfo [ ]

Yes

Array of measInfo measurements

measObjInstIdList

string [ ]

No

Array of monitored object local distinguished name ids per 3GPP TS 32.300

measuredEntityDn

string

Yes

Distinguished name per 3GPP TS 28.550

measuredEntitySoftwareVersion

string

No

Software version for the NF providing the PM data as specified in 3GPP TS 28.550

measuredEntityUserName

string

No

User Definable name for the measured object per 3GPP TS 28.550

Datatype: measInfo

The measInfo datatype provides measurement information; it consists of the following fields:

Field

Type

Required?

Description

jobId

string

No

Name of the measurement job

measInfoId

oneOf [ measInfoIdInteger , measInfoIdString ]

No

Measurement group Identifier

measTypes

oneOf [ measTypesInteger , measTypesString ]

Yes

Array of measurement identifiers associated with the measurement results expressed as integers for efficiency rather than strings

measValues

measValues [ ]

Yes

Array of measValues

Datatype: measInfoIdInteger

The measInfoIdInteger datatype provides an integer measurement group identifier; it consists of the following fields:

Field

Type

Required?

Description

iMeasInfoId

integer

Yes

Integer measurement group Identifier

Datatype: measInfoIdString

The measInfoIdString datatype provides a string measurement group identifier; it consists of the following fields:

Field

Type

Required?

Description

sMeasInfoId

integer

Yes

String measurement group Identifier

Datatype: measResultInteger

The measResultInteger datatype provides an integer 3GPP PM measurement result; it consists of the following fields:

Field

Type

Required?

Description

p

integer

Yes

Integer reference to the counter

iValue

integer

Yes

Integer counter value

Datatype: measResultNull

The measResultNull datatype provides a null 3GPP PM measurement result; it consists of the following fields:

Field

Type

Required?

Description

p

integer

Yes

Integer reference to the counter

isNull

string

Yes

Enumeration: ‘true’ or ‘false’

Datatype: measResultNumber

The measResultNumber datatype provides a number 3GPP PM measurement result; it consists of the following fields:

Field

Type

Required?

Description

p

integer

Yes

Integer reference to the counter

rValue

number

Yes

Number counter value

Datatype: measResultString

The measResultString datatype provides a string 3GPP PM measurement result; it consists of the following fields:

Field

Type

Required?

Description

p

integer

Yes

Integer reference to the counter

sValue

string

Yes

String counter value

Datatype: measTypesInteger

The measTypesInteger datatype provides an array of integer measurement identifiers associated with the measurement results; it consists of the following fields:

Field

Type

Required?

Description

iMeasTypesList

integer [ ]

Yes

Array of integer measurement identifiers associated with the measurement results

Datatype: measTypesString

The measTypesString datatype provides an array of string measurement identifiers associated with the measurement results; it consists of the following fields:

Field

Type

Required?

Description

sMeasTypesList

string [ ]

Yes

Array of string measurement identifiers associated with the measurement results

Datatype: measValues

The measValues datatype provides 3GPP measurement values; it consists of the following fields:

Field

Type

Required?

Description

measObjAddlFlds

hashMap

No

Additional key-value pairs if needed

measObjInstId

measDataCollection

Yes

Monitored object local distinguished name per 3GPP TS 32.300 and 3GPP TS 32.432

measResults

Array of items where each item is oneOf [ measResultInteger, measResultNull, measResultNumber, measResultString ]

Yes

Array of results

suspectFlag

string

No

Enumeration: ‘true’, ‘false’. Indicates if the values are suspect

Datatype: perf3gppFields

The perf3gppFields datatype defines fields for 3GPP PM format events, based on 3GPP TS 28.550, belonging to the ‘perf3gpp’ domain of the commonEventHeader domain enumeration; it consists of the following fields:

Field

Type

Required?

Description

eventAddlFields

hashMap

No

Additional key-value pairs if needed

measDataCollection

measData Collection

Yes

3GPP measurement collection structure

perf3gppFieldsVersion

string

Yes

Version of the perf3gpp event

‘pnfRegistration’ Domain Datatypes
Datatype: pnfRegistrationFields

The pnfRegistrationFields datatype defines fields for events belonging to the ‘pnfRegistration’ domain of the commonEventHeader domain enumeration; it consists of the following fields:

Field

Type

Required?

Description

additionalFields

hashMap

No

Additional pnfRegistration fields if needed

lastServiceDate

string

No

TS 32.692 dateOfLastService = date of last service; e.g. 15022017

macAddress

string

No

MAC address of OAM interface of the unit

manufactureDate

string

No

TS 32.692 dateOfManufacture = manufacture date of the unit; 24032016

modelNumber

string

No

TS 32.692 versionNumber = version of the unit from vendor; e.g. AJ02. Maps to AAI equip-model

oamV4IpAddress

string

No

IPv4 m-plane IP address to be used by the manager to contact the PNF

oamV6IpAddress

string

No

IPv6 m-plane IP address to be used by the manager to contact the PNF

pnfRegistrationFieldsVersion

string

Yes

Version of the pnfRegistrationFields block as “#.#” where # is a digit; see section 1 for the correct digits to use.

serialNumber

string

No

TS 32.692 serialNumber = serial number of the unit; e.g. 6061ZW3

softwareVersion

string

No

TS 32.692 swName = active SW running on the unit; e.g. 5gDUv18.05.201

unitFamily

string

No

TS 32.692 vendorUnitFamilyType = general type of HW unit; e.g. BBU

unitType

string

No

TS 32.692 vendorUnitTypeNumber = vendor name for the unit; e.g. Airscale

vendorName

string

No

TS 32.692 vendorName = name of manufacturer; e.g. Nokia. Maps to AAI equip-vendor

‘State Change’ Domain Datatypes
Datatype: stateChangeFields

The stateChangeFields datatype consists of the following fields:

Field

Type

Required?

Description

additionalFields

hashMap

No

Additional stateChange fields if needed

newState

string

Yes

New state of the entity: ‘inService’, ‘maintenance’, ‘outOfService’

oldState

string

Yes

Previous state of the entity: ‘inService’ , ‘maintenance’, ‘outOfService’

stateChangeFieldsVersion

string

Yes

Version of the stateChangeFields block as “#.#” where # is a digit; see section 1 for the correct digits to use.

stateInterface

string

Yes

Card or port name of the entity that changed state

‘Syslog’ Domain Datatypes
Datatype: syslogFields

The syslogFields datatype consists of the following fields:

Field

Type

Required?

Description

additionalFields

hashMap

No

Additional syslog fields if needed Ex: {“name1”: “value1”, “name2: “value2” … }

eventSourceHost

string

No

Hostname of the device

eventSourceType

string

Yes

Examples: ‘other’, ‘router’, ‘switch’, ‘host’, ‘card’, ‘port’, ‘slotThreshold’, ‘portThreshold’, ‘virtualMachine’, ‘virtualNetworkFunction’

syslogFacility

integer

No

Numeric code from 0 to 23 for facility:

0 kernel messages

1 user-level messages

2 mail system

3 system daemons

4 security/authorization messages

5 messages generated internally by syslogd

6 line printer subsystem

7 network news subsystem

8 UUCP subsystem

9 clock daemon

10 security/authorization messages

11 FTP daemon

12 NTP subsystem

13 log audit

14 log alert

15 clock daemon (note 2)

16 local use 0 (local0)

17 local use 1 (local1)

18 local use 2 (local2)

19 local use 3 (local3)

20 local use 4 (local4)

21 local use 5 (local5)

22 local use 6 (local6)

23 local use 7 (local7 )

syslogFieldsVersion

string

Yes

Version of the syslogFields block as “#.#” where # is a digit; see section 1 for the correct digits to use.

syslogMsg

string

Yes

Syslog message

syslogMsgHost

string

No

Hostname parsed from non-VES syslog message

syslogPri

integer

No

0-192

Combined Severity and Facility(see rfc5424)

syslogProc

string

No

Identifies the application that originated the message

syslogProcId

number

No

The process number assigned by the OS when the application was started

syslogSData

string

No

A <space> separated list of key=”value” pairs following the rfc5424 standard for SD-ELEMENT.

*Deprecated *

The entire rfc5424 syslogSData object, including square brackets [ ], SD-ID and list of SD-PARAMs

syslogSdId

string

No

0-32 char in format name@number,

i.e., ourSDID@32473

syslogSev

string

No

Level-of-severity text enumeration defined below:

Text Sev Description

Emergency 0 system is unusable

Alert 1 action must be taken immediately

Critical 2 critical conditions

Error 3 error conditions

Warning 4 warning conditions

Notice 5 normal but significant condition

Info 6 Informational messages

Debug 7 debug-level messages

syslogTag

string

Yes

Also known as MsgId. Brief non-spaced text indicating the type of message such as ‘TCPOUT’ or ‘BGP_STATUS_CHANGE’; ‘NILVALUE’ should be used when no other value can be provided

syslogTs

string

No

Timestamp parsed from non-VES syslog message

syslogVer

number

No

IANA assigned version of the syslog protocol specification:

0: VES

1: IANA RFC5424

Examples of syslogSData :

Preferred

ts=”1985-04-12T23:20:50.52Z” tag=”BGP_NEIGHBOR_DOWN” msg=”The BGP session to neighbor 10.10.10.10 is down”

Deprecated

[attinc@1234 ts=”1985-04-12T23:20:50.52Z” tag=”BGP_NEIGHBOR_DOWN” msg=”The BGP session to neighbor 10.10.10.10 is down”]

Syslog references:

https://tools.ietf.org/html/rfc5424#section-6

‘Threshold Crossing Alert’ Domain Datatypes
Datatype: counter

The counter datatype consists of the following fields:

Field

Type

Required?

Description

criticality

string

Yes

Enumeration: ‘CRIT’, ‘MAJ’

hashMap

hashMap

Yes

Key is the name of the counter and value is the current value of the counter

threshholdCrossed

string

Yes

Last threshold that was crossed

Datatype: thresholdCrossingAlertFields

The thresholdCrossingAlertFields datatype consists of the following fields:

Field

Type

Required?

Description

additionalFields

hashMap

No

Additional threshold crossing alert fields if needed

additionalParameters

counter [ ]

Yes

Array of performance counters

alertAction

string

Yes

Enumeration: ‘SET’, ‘CONT’, ‘CLEAR’

alertDescription

string

Yes

Unique short alert description (e.g., NE-CPUMEM)

alertType

string

Yes

Enumeration: ‘CARD-ANOMALY’, ‘INTERFACE-ANOMALY’, ELEMENT-ANOMALY’, ‘SERVICE-ANOMALY’

alertValue

string

No

Calculated API value (if applicable)

associatedAlertIdList

string [ ]

No

List of eventIds associated with the event being reported

collectionTimestamp

string

Yes

Time when the performance collector picked up the data; with RFC 2822 compliant format: ‘Sat, 13 Mar 2010 11:29:05 -0800’

dataCollector

string

No

Specific performance collector instance used

elementType

string

No

Type of network element (internal AT&T field)

eventSeverity

string

Yes

Event severity or priority enumeration: ‘CRITICAL’, ‘MAJOR’, ‘MINOR’, ‘WARNING’ , ‘NORMAL’

eventStartTimestamp

string

Yes

Time closest to when the measurement was made; with RFC 2822 compliant format: ‘Sat, 13 Mar 2010 11:29:05 -0800’

interfaceName

string

No

Physical or logical port or card (if applicable)

networkService

string

No

Network name (internal AT&T field)

possibleRootCause

string

No

Reserved for future use

thresholdCrossing FieldsVersion

string

Yes

Version of the thresholdCrossingAlertFields block as “#.#” where # is a digit; see section 1 for the correct digits to use.

Technology Specific Datatypes
Mobile Flow’ Domain Datatypes
Datatype: gtpPerFlowMetrics

The gtpPerFlowMetrics datatype consists of the following fields:

Field

Type

Required?

Description

avgBitErrorRate

number

Yes

Average bit error rate

avgPacketDelayVariation

number

Yes

Average packet delay variation or jitter in milliseconds for received packets: Average difference between the packet timestamp and time received for all pairs of consecutive packets

avgPacketLatency

number

Yes

Average delivery latency

avgReceiveThroughput

number

Yes

Average receive throughput

avgTransmitThroughput

number

Yes

Average transmit throughput

durConnectionFailedStatus

number

No

Duration of failed state in milliseconds , computed as the cumulative time between a failed echo request and the next following successful error request, over this reporting interval

durTunnelFailedStatus

number

No

Duration of errored state, computed as the cumulative time between a tunnel error indicator and the next following non-errored indicator, over this reporting interval

flowActivatedBy

string

No

Endpoint activating the flow

flowActivationEpoch

number

Yes

Time the connection is activated in the flow (connection) being reported on, or transmission time of the first packet if activation time is not available

flowActivationMicrosec

number

Yes

Integer microseconds for the start of the flow connection

flowActivationTime

string

No

Time the connection is activated in the flow being reported on, or transmission time of the first packet if activation time is not available; with RFC 2822 compliant format: ‘Sat, 13 Mar 2010 11:29:05 -0800’

flowDeactivatedBy

string

No

Endpoint deactivating the flow

flowDeactivationEpoch

number

Yes

Time for the start of the flow connection, in integer UTC epoch time aka UNIX time

flowDeactivationMicrosec

number

Yes

Integer microseconds for the start of the flow connection

flowDeactivationTime

string

Yes

Transmission time of the first packet in the flow connection being reported on; with RFC 2822 compliant format: ‘Sat, 13 Mar 2010 11:29:05 -0800’

flowStatus

string

Yes

Connection status at reporting time as a working / inactive / failed indicator value

gtpConnectionStatus

string

No

Current connection state at reporting time

gtpTunnelStatus

string

No

Current tunnel state at reporting time

ipTosCountList

hashMap

No

Array of key: value pairs where the keys are drawn from the IP Type-of-Service identifiers which range from ‘0’ to ‘255’, and the values are the count of packets that had those ToS identifiers in the flow

ipTosList

string

No

Array of unique IP Type-of-Service values observed in the flow where values range from ‘0’ to ‘255’

largePacketRtt

number

No

large packet round trip time

largePacketThreshold

number

No

large packet threshold being applied

maxPacketDelayVariation

number

Yes

Maximum packet delay variation or jitter in milliseconds for received packets: Maximum of the difference between the packet timestamp and time received for all pairs of consecutive packets

maxReceiveBitRate

number

No

maximum receive bit rate”

maxTransmitBitRate

number

No

maximum transmit bit rate

mobileQciCosCountList

hashMap

No

array of key: value pairs where the keys are drawn from LTE QCI or UMTS class of service strings, and the values are the count of packets that had those strings in the flow

mobileQciCosList

string

No

Array of unique LTE QCI or UMTS class-of-service values observed in the flow

numActivationFailures

number

Yes

Number of failed activation requests, as observed by the reporting node

numBitErrors

number

Yes

number of errored bits

numBytesReceived

number

Yes

number of bytes received, including retransmissions

numBytesTransmitted

number

Yes

number of bytes transmitted, including retransmissions

numDroppedPackets

number

Yes

number of received packets dropped due to errors per virtual interface

numGtpEchoFailures

number

No

Number of Echo request path failures where failed paths are defined in 3GPP TS 29.281 sec 7.2.1 and 3GPP TS 29.060 sec. 11.2

numGtpTunnelErrors

number

No

Number of tunnel error indications where errors are defined in 3GPP TS 29.281 sec 7.3.1 and 3GPP TS 29.060 sec. 11.1

numHttpErrors

number

No

Http error count

numL7BytesReceived

number

Yes

number of tunneled layer 7 bytes received, including retransmissions

numL7BytesTransmitted

number

Yes

number of tunneled layer 7 bytes transmitted, excluding retransmissions

numLostPackets

number

Yes

number of lost packets

numOutOfOrderPackets

number

Yes

number of out-of-order packets

numPacketErrors

number

Yes

number of errored packets

numPacketsReceivedExclRetrans

number

Yes

number of packets received, excluding retransmission

numPacketsReceivedInclRetrans

number

Yes

number of packets received, including retransmission

numPacketsTransmittedInclRetrans

number

Yes

number of packets transmitted, including retransmissions

numRetries

number

Yes

number of packet retrie

numTimeouts

number

Yes

number of packet timeouts

numTunneledL7BytesReceived

number

Yes

number of tunneled layer 7 bytes received, excluding retransmissions

roundTripTime

number

Yes

Round Trip time

tcpFlagCountList

hashMap

No

Array of key: value pairs where the keys are drawn from TCP Flags and the values are the count of packets that had that TCP Flag in the flow

tcpFlagList

string

No

Array of unique TCP Flags observed in the flow

timeToFirstByte

number

Yes

Time in milliseconds between the connection activation and first byte received

Datatype: mobileFlowFields

The mobileFlowFields datatype consists of the following fields:

Field

Type

Required?

Description

additionalFields

hashMap

No

Additional mobileFlow fields if needed

applicationType

string

No

Application type inferred

appProtocolType

string

No

Application protocol

appProtocolVersion

string

No

Application version

cid

string

No

Cell Id

connectionType

string

No

Abbreviation referencing a 3GPP reference point e.g., S1-U, S11, etc

ecgi

string

No

Evolved Cell Global Id

flowDirection

string

Yes

Flow direction, indicating if the reporting node is the source of the flow or destination for the flow

gtpPerFlowMetrics

gtpPer FlowMetrics

Yes

Mobility GTP Protocol per flow metrics

gtpProtocolType

string

No

GTP protocol

gtpVersion

string

No

GTP protocol version

httpHeader

string

No

HTTP request header, if the flow connects to a node referenced by HTTP

imei

string

No

IMEI for the subscriber UE used in this flow, if the flow connects to a mobile device

imsi

string

No

IMSI for the subscriber UE used in this flow, if the flow connects to a mobile device

ipProtocolType

string

Yes

IP protocol type e.g.,TCP, UDP, RTP…

ipVersion

string

Yes

IP protocol version e.g., IPv4, IPv6

lac

string

No

Location area code

mcc

string

No

Mobile country code

mnc

string

No

Mobile network code

mobileFlowFieldsVersion

string

Yes

Version of the mobileFlowFields block as “#.#” where # is a digit; see section 1 for the correct digits to use.

msisdn

string

No

MSISDN for the subscriber UE used in this flow, as an integer, if the flow connects to a mobile device

otherEndpointIpAddress

string

Yes

IP address for the other endpoint, as used for the flow being reported on

otherEndpointPort

integer

Yes

IP Port for the reporting entity, as used for the flow being reported on

otherFunctionalRole

string

No

Functional role of the other endpoint for the flow being reported on e.g., MME, S-GW, P-GW, PCRF…

rac

string

No

Routing area code

radioAccessTechnology

string

No

Radio Access Technology e.g., 2G, 3G, LTE

reportingEndpointIpAddr

string

Yes

IP address for the reporting entity, as used for the flow being reported on

reportingEndpointPort

integer

Yes

IP port for the reporting entity, as used for the flow being reported on

sac

string

No

Service area code

samplingAlgorithm

integer

No

Integer identifier for the sampling algorithm or rule being applied in calculating the flow metrics if metrics are calculated based on a sample of packets, or 0 if no sampling is applied

tac

string

No

Transport area code

tunnelId

string

No

Tunnel identifier

vlanId

string

No

VLAN identifier used by this flow

‘SipSignaling’ Domain Datatypes
Datatype: sipSignalingFields

The sipSignalingFields datatype communicates information about sip signaling messages, parameters and signaling state; it consists of the following fields:

Field

Type

Required?

Description

additionalInformation

hashMap

No

Additional sipSignaling fields

compressedSip

string

No

The full SIP request/response including headers and bodies

correlator

string

Yes

Constant across all events on this call

localIpAddress

string

Yes

Ip address on xNF

localPort

string

Yes

Port on xNF

remoteIpAddress

string

Yes

IP address of peer endpoint

remotePort

string

Yes

Port of peer endpoint

sipSignalingFieldsVersion

string

Yes

Version of the sipSignalingFields block as “#.#” where # is a digit; see section 1 for the correct digits to use.

summarySip

string

No

The SIP Method or Response (‘INVITE’, ‘200 OK’, ‘BYE’, etc)

vendorNfNameFields

vendorNf NameFields

Yes

Vendor, NF and nfModule names

‘Voice Quality’ Domain Datatypes
Datatype: endOfCallVqmSummaries

The endOfCallVqmSummaries datatype provides end of call voice quality metrics; it consists of the following fields:

Field

Type

Required?

Description

adjacencyName

string

Yes

Adjacency name

endpointAverageJitter

number

No

Endpoint average jitter

endpointDescription

string

Yes

Enumeration: ‘Caller’, ‘Callee’

endpointMaxJitter

number

No

Endpoint maximum jitter

endpointRtpOctetsDiscarded

number

No

Endpoint RTP octets discarded

endpointRtpOctetsLost

number

No

Endpoint RTP octets lost

endpointRtpOctetsReceived

number

No

Endpoint RTP octets received

endpointRtpOctetsSent

number

No

Endpoint RTP octets sent

endpointRtpPacketsDiscarded

number

No

Endpoint RTP packets discarded

endpointRtpPacketsLost

number

No

Endpoint RTP packets lost

endpointRtpPacketsReceived

number

No

Endpoint RTP packets received

endpointRtpPacketsSent

number

No

Endpoint RTP packets sent

localAverageJitter

number

No

Local average jitter

localAverageJitterBufferDelay

number

No

Local average jitter buffer delay

localMaxJitter

number

No

Local maximum jitter

localMaxJitterBufferDelay

number

No

Local max jitter buffer delay

localRtpOctetsDiscarded

number

No

Local RTP octets discarded

localRtpOctetsLost

number

No

Local RTP octets lost

localRtpOctetsReceived

number

No

Local RTP octets received

localRtpOctetsSent

number

No

Local RTP octets sent

localRtpPacketsDiscarded

number

No

Local RTP packets discarded

localRtpPacketsLost

number

No

Local RTP packets lost

localRtpPacketsReceived

number

No

Local RTP packets received

localRtpPacketsSent

number

No

Local RTP packets sent

mosCqe

number

No

Decimal range from 1 to 5(1 decimal place)

oneWayDelay

number

No

one-way path delay in milliseconds

packetLossPercent

number

No

Calculated percentage packet loss based on endpoint RTP packets lost (as reported in RTCP) and local RTP packets sent. Direction is based on endpoint description (Caller, Callee). Decimal (2 decimal places)

rFactor

number

No

rFactor from 0 to 100

roundTripDelay

number

No

Round trip delay in milliseconds

Datatype: voiceQualityFields

The voiceQualityFields datatype provides statistics related to customer facing voice products; consists of the following fields:

Field

Type

Required?

Description

additionalInformation

hashMap

No

Additional voice quality fields

calleeSideCodec

string

Yes

Callee codec for the call

callerSideCodec

string

Yes

Caller codec for the call

correlator

string

Yes

Constant across all events on this call

endOfCallVqmSummaries

endOfCallVqm Summaries

No

End of call voice quality metric summaries

phoneNumber

string

No

Phone number associated with the correlator

midCallRtcp

string

Yes

Base64 encoding of the binary RTCP data (excluding Eth/IP/UDP headers)

vendorNfNameFields

vendorNf NameFields

Yes

Vendor, NF and nfModule names

voiceQualityFieldsVersion

string

Yes

Version of the voiceQualityFields block as “#.#” where # is a digit; see section 1 for the correct digits to use.

Exceptions

RESTful Web Services Exceptions

RESTful services generate and send exceptions to clients in response to invocation errors. Exceptions send HTTP status codes (specified later in this document for each operation). HTTP status codes may be followed by an optional JSON exception structure described below. Two types of exceptions may be defined: service exceptions and policy exceptions.

Field Name

Data Type

Required?

Description

messageId

xs:string

Yes

Unique message identifier of the format ‘ABCnnnn’ where ‘ABC’ is either ‘SVC’ for Service Exceptions or ‘POL’ for Policy Exception.

Exception numbers may be in the range of 0001 to 9999 where :

  • 0001 to 2999 are defined by OMA (see OMA’s Common_definitions for details)

  • 3000-9999 are available and undefined

text

xs:string

Yes

Message text, with replacement variables marked with %n, where n is an index into the list of <variables> elements, starting at 1

variables

xs:string [0..unbounded]

No

List of zero or more strings that represent the contents of the variables used by the message text

url

xs:anyUrl

No

Hyperlink to a detailed error resource (e.g., an HTML page for browser user agents).

Service Exceptions

When a service is not able to process a request, and retrying the request with the same information will also result in a failure, and the issue is not related to a service policy issue, then the service will issue a fault using the service exception fault message. Examples of service exceptions include invalid input, lack of availability of a required resource or a processing error.

A service exception uses the letters ‘SVC’ at the beginning of the message identifier. ‘SVC’ service exceptions used by the VES Event Listener API are defined below.

MessageId

Description / Comment

Text

Variables

Parent HTTP Code

SVC0001

General service error (see SVC2000)

<custom error message>

None

400

SVC0002

Bad parameter

Invalid input value for message part %1

%1: message part

400

SVC1000

No server resources

No server resources available to process the request

None

500

SVC2000

More elaborate version of SVC0001

The following service error occurred: %1.

Error code is %2.

%1: human readable description of the error

%2: error code

400

Table - Service Exceptions

Policy Exceptions

When a service is not able to complete because the request fails to meet a policy criteria, then the service will issue a fault using the policy exception fault message. To clarify how a policy exception differs from a service exception, consider that all the input to an operation may be valid as meeting the required input for the operation (thus no service exception), but using that input in the execution of the service may result in conditions that require the service not to complete. Examples of policy exceptions include privacy violations, requests not permitted under a governing service agreement or input content not acceptable to the service provider.

A Policy Exception uses the letters ‘POL’ at the beginning of the message identifier. ‘POL’ policy exceptions used by the VES Event Listener API are defined below.

MessageId

Description / Comment

Text

Variables

Parent HTTP Code

POL0001

General policy error (see POL2000)

A policy error occurred.

None

401

POL1009

User not provisioned for service

User has not been provisioned for service

None

401

POL1010

User suspended from service

User has been suspended from service

None

401

POL2000

More elaborate version of POL0001

The following policy error occurred: %1. Error code is %2.

%1: human readable description of the error

%2: error code

401

POL9003

Message size exceeds limit

Message content size exceeds the allowable limit

None

400

Table - Policy Exceptions

RESTful Web Services Definition

REST Operation Overview
REST Operation Summary

Operation Action

HTTP

Verb

Resource URL relative to {ServerRoot}, which is defined in section 3

publishAnyEvent

POST

/eventListener/v{apiVersion}

publishEventBatch

POST

/eventListener/v{apiVersion}/eventBatch

Table - REST Operation Summary

Api Versioning

apiVersion is used to describe the major version number of the event listener API (which is the same as the major version number of this specification). When this number changes, the implication is: the new major version will break clients of older major versions in some way, if they try to use the new API without modification (e.g., unmodified v1 clients would not be able to use v2 without error).

The Event Listener shall provide the following HTTP headers in response to all requests. Additionally, clients may populate these headers on requests to indicate the specific version they are interested in.

  • X-MinorVersion: 1

  • X-PatchVersion: 1

  • X-LatestVersion: 7.1

If a client requests major version 7 (per the REST resource URL) and does not specify the above headers, then they will be provided with the latest patch version of 7.0.x (which is 7.0.1). If the client wants a minor version of major version 7, then they need to supply the X-MinorVersion header with their request. For example, if they request major version 7 with X-MinorVersion: 1, they will get the latest patch version of 7.1, which is 7.1.1.

Buffering of Events

{ServerRoot} is defined in section 3 of this document, which defines the REST resource URL. One or more FQDNs may be provisioned in an event source when it is instantiated or updated. If an event source is unable to reach any of the provisioned FQDNs, it should buffer the event data specified below, up to a maximum of 1 hour, and re-transmit them once a connection has been established.

The following events should be buffered:

  • Faults with eventSeverity of MINOR, MAJOR, NORMAL, or CRITICAL with following expected behavior:

    • NF keeps a First-In-First-Out buffer.

    • Until the collectors are working again, it is desired that the NF sends the final state events only, and not intermediate ones. However, it is acceptable to buffer all events and send them over to the collector in the same order in which they were generated/received.

  • When one VES Event Listener connectivity is re-established, NF should first send the buffered events and then start sending the new events.

    • Syslog with syslogSev of Emergency, Alert, Critical, Error, or Warning

  • All measurements events

publishEventBatch Requirements

Buffered events can be sent in batch using publishEventBatch. However, a NF vendor must only include multiple events for the same domain in the publishEventBatch. The publishEventBatch event must also conform to event size limits.

publishEventBatch events are handled similarly to a single event. The acknowledgement from the VES Event Listener is for the publishEventBatch and not individual events within the publishEventBatch.

Debug Mode

NFs acting as event sources should not send syslog events to the VES Event Listener during debug mode, but should store syslog events locally for access, and possible FTP transfer, via the NF console (e.g., command line interface).

Message Size

The maximum allowed message size is 2 megabytes of uncompressed text. However,messages of this size have been known to cause performance and data loss. It is strongly recommended,that messages not exceed 1 megabyte. In a future version of the specification, a 1 megabyte limit will become a mandatory requirement.

Operation: publishAnyEvent
Functional Behavior

Allows authorized clients to publish any single event to the VES event listener.

  • Supports only HTTPS access.

  • Uses the HTTP verb POST

  • Supports JSON content types

  • Provides HTTP response codes as well as Service and Policy error messages

Call Flow

publishAnyEvent Call Flow

Input Parameters

Header Fields (note: all parameter names shall be treated as case-insensitive):

Parameter

Data Type

Required?

Brief description

Accept

string

No

Determines the format of the body of the response. Valid values are:

  • application/json

Authorization

string

No

The username and password are formed into one string as username:password. This string is then Base64 encoded to produce the encoded credential which is communicated in the header after the string “Authorization: Basic “. See examples below. If the Authorization header is missing, then an HTTP 400 Invalid Request message shall be returned. If the string supplied is invalid, then an HTTP 401 Unauthorized message shall be returned.

Content-length

integer

No

Note that content length is limited to 2 Megabyte (see Message Size)

Content-type

string

Yes

Must be set to one of the following values:

  • application/json

X-MinorVersion

integer

No

The minor version of the API requested by the client

X-PatchVersion

integer

No

The patch version of the API requested by the client

X-LatestVersion

string

No

The full version of the API requested by the client expressed as {major}.{minor}.{patch}

Body Fields:

Parameter

Data Type

Required?

Brief description

Event

event

Yes

Contains the JSON structure of the common event format.

Output Parameters

Header fields:

Parameter

Data Type

Required?

Brief description

Content-length

integer

No

Used only in error conditions

Content-type

string

No

Used only in error conditions

Date

datetime

No

Date time of the response in GMT

X-MinorVersion

integer

Yes

The minor version of the API service

X-PatchVersion

integer

Yes

The patch version of the API service

X-LatestVersion

string

Yes

The full version of the API service expressed as {major}. {minor}.{patch}

Body Fields (for success responses): no content is provided.

Body Fields (for error responses):

Parameter

Data Type

Required?

Brief description

requestError

requestError

Yes(for errors)

Used only in error conditions

HTTP Status Codes

Code

Reason Phrase

Description

202

Accepted

The request has been accepted for processing

400

Bad Request

Many possible reasons not specified by the other codes (e.g., missing required parameters or incorrect format) . The response body may include a further exception code and text. HTTP 400 errors may be mapped to SVC0001 (general service error), SVC0002 (bad parameter), SVC2000 (general service error with details) or PO9003 (message content size exceeds the allowable limit).

401

Unauthorized

Authentication failed or was not provided. HTTP 401 errors may be mapped to POL0001 (general policy error) or POL2000 (general policy error with details).

404

Not Found

The server has not found anything matching the Request-URI. No indication is given of whether the condition is temporary or permanent.

405

Method Not Allowed

A request was made of a resource using a request method not supported by that resource (e.g., using PUT on a REST resource that only supports POST).

500

Internal Server Error

The server encountered an internal error or timed out; please retry (general catch-all server-side error).HTTP 500 errors may be mapped to SVC1000 (no server resources).

Sample Request and Response
Sample Request
POST  /eventListener/v7 HTTP/1.1
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
content-type: application/json
content-length: 12345
X-MinorVersion: 1

{
    "event": {
        "commonEventHeader": {
            "version": "4.1",
            "vesEventListenerVersion": "7.1.1",
            "domain": "fault",
            "eventName": "Fault_Vscf:Acs-Ericcson_PilotNumberPoolExhaustion",
            "eventId": "fault0000245",
            "sequence": 1,
            "priority": "High",
            "reportingEntityId": "cc305d54-75b4-431b-adb2-eb6b9e541234",
            "reportingEntityName": "ibcx0001vm002oam001",
            "sourceId": "de305d54-75b4-431b-adb2-eb6b9e546014",
            "sourceName": "scfx0001vm002cap001",
            "nfVendorName": "Ericsson",
            "nfNamingCode": "scfx",
            "nfcNamingCode": "ssc",
            "startEpochMicrosec": 1413378172000000,
            "lastEpochMicrosec": 1413378172000000,
            "timeZoneOffset": "UTC-05:30"
        },
        "faultFields": {
            "faultFieldsVersion": 4.0,
            "alarmCondition": "PilotNumberPoolExhaustion",
            "eventSourceType": "other",
            "specificProblem": "Calls cannot complete - pilot numbers are unavailable",
            "eventSeverity": "CRITICAL",
            "vfStatus": "Active",
            "alarmAdditionalInformation": {
                "PilotNumberPoolSize": "1000"
            }
        }
    }
}
Sample Success Response
HTTPS/1.1 202 Accepted
X-MinorVersion: 1
X-PatchVersion: 1
X-LatestVersion: 7.1.1
Sample Error Responses
Sample Policy Exception
HTTPS/1.1 400 Bad Request
content-type: application/json
content-length: 12345
Date: Thu, 04 Jun 2009 02:51:59 GMT
X-MinorVersion: 1
X-PatchVersion: 1
X-LatestVersion: 7.1.1

{
  "requestError": {
    "policyException": {
      "messageId": "POL9003",
      "text": "Message content size exceeds the allowable limit",
    }
  }
}
Sample Service Exception
HTTPS/1.1 400 Bad Request
content-type: application/json
content-length: 12345
Date: Thu, 04 Jun 2009 02:51:59 GMT
X-MinorVersion: 1
X-PatchVersion: 1
X-LatestVersion: 7.1.1

{
  "requestError": {
    "serviceException": {
      "messageId": "SVC2000",
      "text": "Missing Parameter: %1. Error code is %2"
      "variables": [
        "severity",
        "400"
      ]
    }
  }
}
Operation: publishEventBatch
Functional Behavior

Allows authorized clients to publish a batch of events to the VES event listener.

  • Supports only HTTPS access.

  • Uses the HTTP verb POST

  • Supports JSON content types

  • Provides HTTP response codes as well as Service and Policy error messages

Call Flow

publishEventBatch Call Flow

Input Parameters

Header Fields (note: all parameter names shall be treated as case-insensitive):

Parameter

Data Type

Required?

Brief description

Accept

string

No

Determines the format of the body of the response. Valid values are:

  • application/json

Authorization

string

No

The username and password are formed into one string as “username:password” . This string is then Base64 encoded to produce the encoded credential which is communicated in the header after the string “Authorization: Basic”. See examples below. If the Authorization header is missing, then an HTTP 400 Invalid Request message shall be returned. If the string supplied is invalid, then an HTTP 401 Unauthorized message shall be returned.

Content-length

integer

No

Note that content length is limited to 2 megabyte (see Message Size).

Content-type

string

Yes

Must be set to one of the following values:

  • application/json

X-MinorVersion

integer

No

The minor version of the API requested by the client

X-PatchVersion

integer

No

The patch version of the API requested by the client

X-LatestVersion

string

No

The full version of the API requested by the client expressed as {major}.{minor}.{patch}

Body Fields:

Parameter

Data Type

Required?

Brief description

eventList

eventList

Yes

Array of events conforming to the common event format.

Output Parameters

Header fields:

Parameter

Data Type

Required?

Brief description

Content-length

integer

No

Used only in error conditions

Content-type

string

No

Used only in error conditions

Date

datetime

No

Date time of the response in GMT

X-MinorVersion

integer

Yes

The minor version of the API service

X-PatchVersion

integer

Yes

The patch version of the API service

X-LatestVersion

string

Yes

The full version of the API service expressed as {major}.{minor}.{patch}

Body Fields (for success responses: no content is provided.

Body Fields (for error responses):

Parameter

Data Type

Required?

Brief description

requestError

requestError

Yes(for errors)

Used only in error conditions

HTTP Status Codes

Code

Reason Phrase

Description

202

Accepted

The request has been accepted for processing

400

Bad Request

Many possible reasons not specified by the other codes (e.g., missing required parameters or incorrect format) . The response body may include a further exception code and text. HTTP 400 errors may be mapped to SVC0001 (general service error), SVC0002 (bad parameter), SVC2000 (general service error with details) or PO9003 (message content size exceeds the allowable limit).

401

Unauthorized

Authentication failed or was not provided. HTTP 401 errors may be mapped to POL0001 (general policy error) or POL2000 (general policy error with details).

404

Not Found

The server has not found anything matching the Request-URI. No indication is given of whether the condition is temporary or permanent.

405

Method Not Allowed

A request was made of a resource using a request method not supported by that resource (e.g., using PUT on a REST resource that only supports POST).

500

Internal Server Error

The server encountered an internal error or timed out; please retry (general catch-all server-side error).HTTP 500 errors may be mapped to SVC1000 (no server resources).

Sample Request and Response
Sample Request
POST /eventListener/v7/eventBatch HTTP/1.1
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
content-type: application/json
content-length: 12345
X-MinorVersion: 1

{
   "eventList": [
      {
         "commonEventHeader": {
            "version": "4.1",
            "vesEventListenerVersion": "7.1.1",
            "domain": "fault",
            "eventName": "Fault_Vscf:Acs-Ericcson_PilotNumberPoolExhaustion",
            "eventId": "fault0000250",
            "sequence": 1,
            "priority": "High",
            "reportingEntityId": "cc305d54-75b4-431b-adb2-eb6b9e541234",
            "reportingEntityName": "ibcx0001vm002oam0011234",
            "sourceId": "de305d54-75b4-431b-adb2-eb6b9e546014",
            "sourceName": "scfx0001vm002cap001",
            "nfVendorName": "Ericsson",
            "nfNamingCode": "scfx",
            "nfcNamingCode": "ssc",
            "startEpochMicrosec": 1413378172000000,
            "lastEpochMicrosec": 1413378172000000,
            "timeZoneOffset": "UTC-05:30"
         },
         "faultFields": {
            "faultFieldsVersion": 4.0,
            "alarmCondition": "PilotNumberPoolExhaustion",
            "eventSourceType": "other",
            "specificProblem": "Calls cannot complete - pilot numbers are unavailable",
            "eventSeverity": "CRITICAL",
            "vfStatus": "Active",
            "alarmAdditionalInformation": {
                "PilotNumberPoolSize": "1000"
            }
         }
      },
      {
         "commonEventHeader": {
            "version": "4.1",
            "vesEventListenerVersion": "7.1.1",
            "domain": "fault",
            "eventName": " Fault_Vscf:Acs-Ericcson_RecordingServerUnreachable",
            "eventId": "fault0000251",
            "sequence": 0,
            "priority": "High",
            "reportingEntityId": "cc305d54-75b4-431b-adb2-eb6b9e541234",
            "reportingEntityName": "ibcx0001vm002oam0011234",
            "sourceId": "de305d54-75b4-431b-adb2-eb6b9e546014",
            "sourceName": "scfx0001vm002cap001",
            "nfVendorName": "Ericsson",
            "nfNamingCode": "scfx",
            "nfcNamingCode": "ssc",
            "startEpochMicrosec": 1413378172000010,
            "lastEpochMicrosec": 1413378172000010,
            "timeZoneOffset": "UTC-05:30"
         },
         "faultFields": {
            "faultFieldsVersion": 4.0,
            "alarmCondition": "RecordingServerUnreachable",
            "eventSourceType": "other",
            "specificProblem": "Recording server unreachable",
            "eventSeverity": "CRITICAL",
            "vfStatus": "Active"
         }
      }
   ]
}
Sample Success Response
HTTPS/1.1 202 Accepted
X-MinorVersion: 1
X-PatchVersion: 1
X-LatestVersion: 7.1.1
Sample Error Responses
Sample Policy Exception
HTTPS/1.1 400 Bad Request
content-type: application/json
content-length: 12345
Date: Thu, 04 Jun 2009 02:51:59 GMT
X-MinorVersion: 1
X-PatchVersion: 1
X-LatestVersion: 7.1.1

{
  "requestError": {
    "policyException": {
      "messageId": "POL9003",
      "text": "Message content size exceeds the allowable limit",
    }
  }
}
Sample Service Exception
HTTPS/1.1 400 Bad Request
content-type: application/json
content-length: 12345
Date: Thu, 04 Jun 2009 02:51:59 GMT
X-MinorVersion: 1
X-PatchVersion: 1
X-LatestVersion: 7.1.1

{
  "requestError": {
    "serviceException": {
      "messageId": "SVC2000",
      "text": "Missing Parameter: %1. Error code is %2"
      "variables": [
        "severity",
        "400"
      ]
    }
  }
}

Terminology

Terminology used in this document is summarized below:

A&AI. Active & Available Inventory is the ONAP component that provides data views of Customer Subscriptions, Products, Services, Resources, and their relationships.

Alarm Condition. Short name of the alarm condition/problem, such as a trap name.

APPC (formerly APP-C). Application Controller. Handles the life cycle management of Virtual Network Functions (VNFs).

ASDC. AT&T Service Design and Creation Platform: the original name for the SDC. Replaced by SDC.

Common Event Format. A JSON schema describing events sent to the VES Event Listener.

Common Event Header. A component of the Common Event Format JSON structure. This datatype consists of fields common to all events.

DCAE. Data Collection Analysis and Events. DCAE is the ONAP subsystem that supports closed loop control and higher-level correlation for business and operations activities. DCAE collects performance, usage, and configuration data, provides computation of analytics, aids in trouble-shooting and management, and publishes event, data, and analytics to the rest of the ONAP system for FCAPS functionality.

DMaaP. Data Movement as a Platform. A set of common services provided by ONAP, including a Message Router, Data Router, and a Data Bus Controller.

Domain. In VES, an event ‘domain’ identifies a broad category of events (e.g., ‘fault’ or ‘measurement’), each of which is associated with a VES domain field block, which is sent with the commonEventHeader when events of that category are generated.

Epoch. The number of seconds that have elapsed since 00:00:00 Coordinated Universal Time (UTC), Thursday, 1 January 1970. Every day is treated as if it contains exactly 86400 seconds, so leap seconds are not applied to seconds since the Epoch. In VES Epoch times are measured in microseconds.

Event. A well-structured packet of network management information identified by an eventName which is asynchronously communicated to one or more instances of an Event Listener service to subscribers interested in that eventName. Events can convey measurements, faults, syslogs, threshold crossing alerts, and others types of information.

Event Id. Event key that is unique to the event source. The key must be unique within notification life cycle similar to EventID from 3GPP. It could be a sequential number, or a composite key formed from the event fields, such as sourceName_alarmCondition_startEpoch. The eventId should not include whitespace. For fault events, eventId is the eventId of the initial alarm; if the same alarm is raised again for changed, acknowledged or cleared cases, eventId must be the same as the initial alarm (along with the same startEpochMicrosec and an incremental sequence number.

Event Name. Identifier for specific types of events. Specific eventNames registered by the YAML may require that certain fields, which are optional in the Common Event Format, be present when events with that eventName are published.

Event Streaming. The delivery of network management event information in real time.

Extensible Data Structures. Data structures (e.g., hashMap) that allow event sources to send information not specifically identified in the VES schema.

Hash Map. A hash table, or data structure, used to implement an associative array, a structure than can map keys to values. In VES 6.0, all name-value pair structures were changed to hash maps (i.e., {‘name’: ‘keyName’, ‘value’: ‘keyValue’} was replaced with {‘keyName’: ‘keyValue’}).

ICE. Incubation and Certification Environment. Facilitates vendors and third-party in developing virtual network functions using ONAP and a network cloud.

IPMI. The Intelligent Platform Management Interface.

JSON. Java Script Object Notation. JSON is an open-standard file format that uses human-readable text to transmit data objects consisting of attribute–value pairs and array data types (or any other serializable value). It is a very common data format used for asynchronous browser–server communication.

NF. Network Function. Generalized name for a VNF or PNF.

NFC. Network Function Component. Generalized name for a VNFC or a component of a PNF.

ONAP. Open Network Automation Platform.

PNF. Physical Network Function.

Policy. Course of action for the management of the network. The ONAP Policy Framework is a comprehensive policy design, deployment, and execution environment. The Policy Framework is the *decision making* component in an ONAP system. It allows you to specify, deploy, and execute the governance of the features and functions in your ONAP system, be they closed loop, orchestration, or more traditional open loop use case implementations. The Policy Framework is the component that is the source of truth for all policy decisions.

Reporting Entity Name. Name of the entity reporting the event or detecting a problem in another vnf/vm or pnf which is experiencing the problem. May be the same as the sourceName. Not used for performance measurements currently.

SDC. Service Design and Creation Platform: The ONAP visual modeling and design tool. It creates internal metadata that describes assets used by all ONAP components, both at design time and run time. The SDC manages the content of a catalog, and assemblies of selected catalog to define how and when VNFs are realized in a target environment.

Source Name: Name of the entity experiencing the event issue, which may be detected and reported by a separate reporting entity. The sourceName identifies the device for which data is collected. A valid sourceName must be inventoried in A&AI.

Specific Problem. Description of the alarm or problem.

VES. Virtual Function Event Stream. In 6.0, the definition of VES was expanded to include event streaming for VNF, PNF and infrastructure. The VES Event Listener can receive any event sent in the VES Common Event Format.

VES Event Listener. A RESTful connectionless push event listener capable of receiving single events or batches of events sent in the Common Event Format.

VM. Virtual Machine.

VNF. Virtual Network Function. A VNF is a virtualized task formerly carried out by proprietary, dedicated network hardware. (Examples: virtual firewall, virtual DNS). A VNF can also be defined as a specific kind of Vendor Software Product.

YAML. A data serialization language and superset of JSON.

VNFC. Virtual Network Function Component. A VNFC is a part of a VNF. It is a stand-alone executable that is loosely-coupled, granular, re-usable, and responsible for a single capability.

Appendix: Historical Change Log

For the latest changes, see the Change Block just before the Table of Contents.

Date

Revision

Description

5/22/2015

0.1

Initial Release - Draft

5/29/2015

0.2

  • Introduction: removed all system names and references to internal AT&T components

  • Security: changed ‘event publisher’ to ‘event source’

  • Generic Event Format: updated the JSON schema per the below:

  • eventHeader: clarified the description of id, made sourceId a required field, changed the datatype of timestamps to timestamp [ ]

  • performanceFields: removed overflowFields

  • tmestamp: added a description of this datatype

  • Exceptions: fixed indentation of sections

  • Approvers: updated the list of approvers and added attuids

6/3/2015

0.3

  • Updated the security section to use HTTP Basic Authentication per AT&T REST standards. Updated the input parameters and messaging examples to use the new security scheme.

6/5/2015

0.4

  • Added otherFields sub section to the defined datatypes

  • Added locale field to the eventHeader.

6/5/2015

0.5

  • Updated the embedded event format json schema to match the changes made in v0.4

6/10/2015

0.6

  • Updated the {ServerRoot} format to contain an optional routing path (for D2 service modules).

7/7/2015

0.7

Common Event Format updates:

  • EventHeader: added ‘measurement’ to the ‘domain’ enumeration; changed ‘locale’ to ‘location’ and clarified in the description that this should be a clli code

  • Added a MeasurementFields datatype, which required the addition of the following datatypes: codecsInUse, cpuUsage, diskUsage, featuresInUse, memoryUsage

7/15/2015

1.0

  • Changed sourceInstance in the eventHeader to be an array of name value pairs

  • Changed the performanceFields block to thresholdCrossingAlertFields. Updated the domain field of the eventHeader to match.

7/23/2015

v1.1

Changes to eventHeader data format:

  • moved sourceInstance to internalHeaderFields

  • moved serviceInstanceId to internalHeaderFields

  • moved productId to internalHeaderFields

  • moved subscriberId to internalHeaderFields

  • moved location to internalHeaderFields

  • added the following new fields in internalHeaderFields: policyType, policyName, correlationEventType, correlationType, correlationName, correlationRootEventId

Changes to faultFields data format:

  • moved the eventSourceDeviceDescription to internalFaultFields and renamed it equipmentVendorModel

  • moved eventSourceHostname to internalFaultFields

  • changed alarmObjectInterface to alarmInterfaceA

  • changed alarmRemoteObject to alarmRemoteObjectZ and

    moved it to internalFaultFields

  • changed alarmRemoteObjectInterface to alarmInterfaceZ and moved it to internalFaultFields

Changes to thresholdCrossingFields data format:

  • changed several references from the old ‘performanceFields’ block to the new ‘thresholdCrossingFields’ block

Other:

  • Fixed several comma and colon syntax errors in the JSON schema as detected by a JSON schema syntax checker.

8/11/2015

v1.2

Timestamp format:

  • Section 4.18: added a note in the datetime field of the Timestamp datatype specifying the (GMT) format required

  • Updated the JSON schema with the same information

Event Header Severity Enumeration:

  • Section 4.8: modified the severity enumeration to remove the numbers in parentheses that followed the names. The names were not changed.

  • Updated the JSON schema with the same information.

8/20/2015

v1.3

JSON Schema rev’d to v9:

  • Alphabetized all fields in the JSON schema

  • Fixed the way arrays were specified (JSON schema syntax issue)

Sample Responses:

  • 2.1.1.1: alphabetized fields, fixed timestamps array depiction, fixed severity enum value to conform to latest format

  • 6.2.6.1: alphabetized fields, fixed timestamps array depiction, fixed severity enum value to conform to latest format

  • 6.3.6.1: alphabetized fields, fixed timestamps array depiction, fixed severity enum value to conform to latest format

  • 6.4.6.1: alphabetized fields, fixed timestamps array depiction, fixed eventList array depection, fixed severity enum value to conform to latest format

9/16/2015

v1.4

JSON Schema rev’d to v10:

  • Fixed an error in the way that the top level “event” object was specified in the v9 json schema. This was discovered when validating examples against the schema using this site: http://json-schema-validator.herokuapp.com/index.jsp

  • Changed the embedded json file in section 4

Sample Responses:

  • Removed an extra comma after the timestamp brace in section 6.2.6 and 6.3.6.

11/11/2015

v1.5

Section 4 was the only section changed: JSON Schema rev’d to v11 and Datatype tables were updated to match . Numerous data structure changes were made based on VNF vendor proof of concept feedback. Modified sample requests and responses to match.

11/12/2015

v1.6

  • The internalFaultFields were merged into the internalHeaderFields; then the internalFaultFields datatype was deleted.

  • Updated the JSON schema to v12.

  • Also corrected some background color issues in the sample requests and responses.

1/18/2016

v1.7

  • Section 2 changes: updated the sample request to conform with the changes below

  • Section 4 datatype changes:

  • Changed ‘eventHeader’ to ‘commonEventHeader’

  • Moved ‘eventSeverity’ from the ‘commonEventHeader’ to ‘faultFields’

  • Added ‘priority’ to ‘commonEventHeader’

  • moved ‘vFstatus’ to ‘faultFields’

  • removed ‘firstDateTime’ and ‘lastDateTime’ and changed ‘firstEpoch’ to ‘startEpochMicrosec’ and changed ‘lastEpoch’ to ‘lastEpochMicrosec’.

  • Added ‘functionalRole’ to the commonEventHeader

  • In the commonEventHeader, changed the ‘eventDomain’ enumeration to remove ‘measurements’ and add ‘measurementsForVfScaling’.

  • Changed the ‘measurementFields’ to ‘measurementsForVfScalingFields’

  • In the commonEventHeader, changed the following fields:

  • ‘eventDomain’ to ‘domain’

  • ‘eventSequence’ to ‘sequence’

  • ‘eventSourceId’ to ‘sourceId’

  • ‘eventSounceName’ to ‘sourceName’

  • Updated the JSON schema to v13

  • Section 6 changes: updated the input parameters and sample requests to conform to the changes above.

  • Section 7: changed the section from Approvers to Contributors.

1/22/2016

v1.8

  • Section 4: Added support for ‘mobileFlow’ in the commonEventHeader ‘domain’ enumeration. Added the mobileFlowFields datatype and the gtpPerFlowMetrics datatype referenced by that datatype.

  • Section 7: alphabetized the contributors

2/11/2016

v1.9

  • Added section 1.3: Naming Standard for Event Types

2/12/2016

v2.0

  • Updated request – response examples to reflect the naming standards for event types introduced in v1.9

  • Added a paragraph on use of Avro as a transport in section 1.4

3/11/2016

v2.1

  • Updated the embedded JSON schema to v15 to fix a typo in the required fields for the measurementsForVfScalingFields, namely, changed ‘configuredEntites’ to ‘configuredEntities’. Additionally, added an ‘Event Listener’ title block at the bottom of the file with a single required event object.

3/15/2016

v2.2

  • Added mobileFlowFields to the event datatype definition in section 4.7 and updated the embedded json schema at the top of section 4 to v16.

4/26/2016

v2.3

  • Generic Event Format updates: 1) made ‘priority’ lowercase in the Word doc table for commonEventHeader; 2) added ‘requestError’ data structure to the Word doc and JSON schema (which is now at v17)

4/27/2016

v2.4

  • JSON Schema: In the ‘event’ data structure, changed ‘thresholdCrossingFields’ to ‘thresholdCrossingAlertFields’ to product v18 of the schema.

  • ‘codecsInUse’ data structure: changed ‘numberInUse’

    to ‘codecUtilization’

5/26/2016

v2.5

  • Changed responses from ‘204 No Content’ to ‘202 Accepted’ and added a body to the response that enable AT&T to throttle the events being sent and/or to request the current state of throttling at the event source.

  • Added new datatypes to support the above: eventDomainThrottleSpecification, eventDomainThrottleSpecificationList, eventThrottlingState, suppressedNvPairs

  • Modifed the commonEventFormat json schema to v19

  • Note: for the VendorEventListener: added new licensing language on the back of the title page; added an “attCopyrightNotice” definition at the top of the commonEventFormat_Vendors.json file; also removed all references to internalHeaderFields from this file and from the VendorEventListener spec.

8/9/2016

v2.6

  • commonHeader: added a note on the description of sourceId and sourceName in the commonHeader: “use reportingEntity for domains that provide more detailed source info”

  • commonHeader: deleted the capacity, measurementsForVfScaling and usage domains in the domain enumeration

  • commonHeader: added the following domains to the domain enumeration: licensingKci, scalingKpi, stateChange

  • event: removed references to capacityFields, measurementsForVfScalingFields and usageFields and added references to licensingKciFields, scalingKpiFields, stateChangeFields

  • licensingKciFields: added this section along with ‘additionalMeasurements’, which is an optional list of measurementGroup structures. Changed the name of kciFieldsVersion to licensingKciFieldsVersion.

  • scalingKpiFields: added this section but changed measurementFieldsVersion to scalingKpiFieldsVersion

  • stateChangeFields: added this section along with ‘additionalFields’, which is an optional list of name-value pairs. Other fields included newState and oldState which were enumerations of the following possible states: ‘inService’, ‘maintenance’, ‘outOfService’

  • sysLogFields: added ‘additionalFields’, which is an optional list of name-value pairs

  • vNicUsage: added two required fields to the vNicUsage data structure: packetsIn and packetsOut

8/10/2016

v2.7

  • commonHeader: removed the note on the description of sourceId and sourceName in the commonHeader: “use reportingEntity for domains that provide more detailed source info”

  • commonHeader: added measurementsForVfScaling domain back and removed the licensingKci and scalingKpi domains

  • event: removed references to licensingKciFields and scalingKpiFields; added references to measurementsForVfScalingFields

  • measurementsForVfScalingFields: combined the kciDetail and kpiDetail structures into the measurementsForVfScalingFields structure; referenced the errors structure

  • errors: added a new structure to capture the receive and transmit errors for the measurements domain

  • removed the following structures: kci, kpi, scalingKpiFields and licensingKciFields

  • eventDomainThrottleSpecification: updated the reference to commonEventHeader domain field

  • faultFields: removed the numbers from the enumerated strings for eventSourceType

  • vNicUsage: made the broadcast, multicast and unicast fields optional

  • contributors: updated Alok’s organizational area

8/12/2016

v2.8

  • commonHeader: copied the descriptions of sourceId and sourceName from the JSON schema into the word document tables.

  • sample request examples: moved the reportingEntityId and reportingEntityNames to the same relative place in all sample requests in the document

  • Fixed the sample request shown for publishEventBatch to take an eventList as input.

  • Fixed the sample request shown for publishSpecificTopic to put the topic in the URL

  • errors: changed the receiveErrors and transmitErrors fields to be datatype number

  • codesInUse: changed ‘codecUtilization’ to ‘numberinUse’

  • vNicUsage: updated the description of the fields

8/27/2016

v2.9

  • Added a note “(currently: 1.1)” in the descriptions of the following fields: commonEventHeader:version, faultFields:faultFieldsVersion, measurementsForVfScalingFields:measurementsForVfScalingFieldsVersion, stateChangeFields:stateChangeFieldsVersion, sysLogFields:syslogFieldsVersion, thresholdCrossingAlertFields:thresholdCrossingFieldsVersion

  • stateChangeFields: made stateInterface mandatory

  • changed ‘enum’ to ‘enumeration’ throughout section 4 of the document (note: this can’t be done in the JSON schema).

  • measurementsForVfScalingFields: made the following fields optional: conurrentSessions, configuredEntitites, cpuUsageArray, fileSystemUsageArray, memoryConfigured, memoryUsed, requestRate, vNicUsageArray

  • measurementsForVfScalingFields: concurrentSessions and configuredEntities: changed the description to support both VMs and VNFs

  • measurementsFor VfScalingFields: clarified the descriptions of latencyDistribution, measurementInverval and requestRate

  • syslogFields: clarified the descriptions of syslogSData, syslogTag, syslogVer

  • thresholdCrossingAlertFields: made the following fields optional and clarified their descriptions: elementType, networkService

  • command and commandList: created a list of command structures to enable the event collector to request changes of event sources. Commands consist of a commandType along with optional fields (whose presence is indicated by the commandType). Three command types are currently supported: ‘measurementIntevalChange’, ‘provideThrottlingState’ and ‘throttlingSpecification’.

  • eventDomainThrottleSpecificationList: removed this and replaced it with commandList.

  • Operations and Sample Requests: modified the operations and samples to support the new command and commandList structures.

9/1/2016

v2.10

  • measurementsForVfScaling block: made the following fields optional: latencyDistribution (which is an array of latencyBucketMeasure structures) and meanRequestLatency. Updated the JSON schemas (now v24) to match.

9/16/2016

v2.11

  • 1 Introduction: updated the introduction to clarify the usage of eventTypes and the possibility of support for other protocols.

  • 6.1 REST Operation Overview: added two new subsections (6.1.2 and 6.1.3) discussing Api Version and Commands Toward Event Source Clients.

  • 6.2 publishAnyEvent: fixed the sample to conform to the latest changes

  • 6.3 publishSpecificTopic: fixed the sample to conform to the latest changes

  • 6.4 publishEventBatch: fixed the sample to conform to the latest changes

  • 6.5 provideThrottlingState operation: added the Input Parameters section heading back and fixed the sample request to provide eventThrottlingState (instead of eventThrottlingClientState).

  • The remaining bullets describe changes made to section 4 datatypes in alphabetical order:

  • command datatype: referenced the new section 6.1.3 which provides an explanation of command state expectations and requirements for a given eventSource:

  • commonEventHeader datatype:

    • made sourceId and reportingEntityId fields optional (although the internal Generic Event Listener spec indicates, in the field descriptions, that the AT&T enrichment process shall ensure that these fields are populated)

    • domain enumeration: changed measurementsForVfScalingFields to measurementsForVfScaling

  • eventDomainThrottleSpecificationList: added this array of eventDomainThrottleSpecification stuctures back to the schema because it is used by the provideThrottlingState operation.

  • eventList: added eventList back to the vendor version of the commonEventFormat. This is used by the publishEventBatch operation.

  • faultFields datatype:

    • eventSourceType: made this a string (and provided the previous enumerated values as examples)

  • filesystemUsage datatype:

    • changed vmIdentifier to filesystemName

  • gtpPerFlowMetrics datatype:

    • flowActivationTime: changed the format and description to be compliant with RFC 2822.

    • flowDeactivationTime: changed the format and description to be compliant with RFC 2822.

  • internalHeaderFields datatype:

    • Added the following optional fields: firstDateTime, lastDateTime compliant with RFC 2822. Noted in the description that these fields must be supplied for events in the following domains: fault, thresholdCrossingAlerts and measurementsForVfScaling.

    • ticketingTimestamp: changed the format and description to be compliant with RFC 2822.

  • syslogFields datatype:

    • eventSourceType: made this a string (and provided the previous enumerated values, without the numbers, as examples)

  • thresholdCrossingAlerts dataypte:

    • collectionTimestamp: changed the format and description to be compliant with RFC 2822.

    • eventStartTimestamp: changed the format and description to be compliant with RFC 2822.

    • added the same eventSeverity field as from the faultFields and made it required

9/23/2016

v2.12

  • Section 4 Datatypes: commonEventHeader: made reportingEntityName a required field (note: the JSON schema already had this field as required)

11/29/2016

v3.0

  • Introduction:

    • Introductory paragraph: changed ‘…Common Event Header Block followed by zero or more event domain blocks’ to ‘…Common Event Header Block accompanied by zero or more event domain blocks’ since the order of the blocks on the wire is not guaranteed.

    • Added Section 1.5 Versioning

  • Section 4: codec processing:

    • CommonEventFormat_Vendors schema only: codesInUse: changed required field from “codecUtilization” which was removed previously to “numberInUse” which is the new field name.

    • added ‘codecSelected’ datatype

    • added ‘codecSelectedTranscoding’ datatype

  • Section 4 and section 6: command processing:

    • Added commandListEntry which is an object that references the command object.

    • commandList: changed commandList to contain an array of commandListEntry objects.

    • Updated sample responses in section 6 where commands are used

  • Section 4: commonEventHeader:

    • Incremented version to 1.2

    • added two new values to the ‘domain’ enumeration: ‘serviceEvents’ and ‘signaling

  • Section 4: added endOfCallVqmSummaries datatype

  • Section 4: ‘event’: added two fields: ‘serviceEventsFields’ and ‘signalingFields’

  • Section 4: added ‘eventInstanceIdentifier’datatype

  • Section 4: CommonEventListener only: internalHeaderFields:

    • added ‘internalHeaderFieldsVersion’(initially set to 1.1)

    • added ‘correlationFirstEpoch’

    • added ‘closedLoopControlName’

    • added ‘closedLoopFlag’

    • added ‘collectorTimeStamp’

    • added ‘eventTag’

    • added ‘tenantName’

    • changed ‘operationalStatus’ to ‘inMaint’

    • added required fields in the schema to match the word doc: ‘equipmentNameCode’, ‘equipmentType’, ‘equipmentVendor’, ‘inMaint’, ‘provStatus’

  • Section 4: added ‘marker’datatype

  • Section 4: added ‘midCallRtcp’ datatype

  • Section 4: mobileFlowFields:

    • added ‘mobileFlowFieldsVersion’(initially set to 1.1)

  • Section 4: added ‘serviceEventsFields’datatype

  • Section 4: added ‘signalingFields’ datatype

  • Section 4: syslogFields:

    • Incremented syslogFieldsVersion to 1.2

    • added ‘syslogPri’

    • added ‘syslogSev’

    • added ‘syslogSdId’

  • Section 4: thresholdCrossingAlertFields:

    • Incremented thresholdCrossingFieldsVersion to 1.2

    • added ‘additionalFields’ which is an optional list of name value pairs.

  • Section 4: schema v26.0 embedded reflecting the above changes.

  • Section 6 and Section 2: changed all sample requests to use /v3 in the REST Resource URL.

12/1/2016

v3.1

  • Section 6: Updated the call flow diagrams to show ‘v3’

1/5/2017

v4.0

  • Combined the Generic Event Listener and Vendor Event Listener into a single API service specification with version 4.0.

  • Changed the title to VES (Virtual Function Event Streaming) Listener.

  • Changed references to ‘generic event’ to ‘common event’ or ‘VES event’ (depending on the context) throughout the document.

  • Used the Legal Disclaimer from the Vendor Event Listener on the back of the title page.

  • Section 1: Introduction changes:

    • modified wording to reference ‘VES’

    • removed the ‘Audience’ section, which described various AT&T groups the documented was intended for

    • tweaked the naming standards for event types to clarify the purpose of the naming conventions

  • Section 3: Resource Structure: added a sentence describing the FQDN and port used in the resource URL.

  • Section 4: Common Event Format changes:

    • renamed the section to ‘Common Event Format’ from ‘Generic Event Format’

    • reorganized the datatypes into separate sections ; sections were defined for each of the domains as well as for common event, common event header and command list processing

    • codecSelected datatype: removed this datatype

    • codecSelectedTranscoding datatype: removed this datatype

    • command datatype: added an enumerated value to commandType: ‘heartbeatIntervalChange’

    • commonEventHeader: added internalHeaderFields to the commonEventHeader, defined as “Fields (not supplied by event sources) that the VES Event Listener service can use to enrich the event if needed for efficient internal processing. This is an empty object which is intended to be defined separately by each provider implementing the VES Event Listener.”

    • commonEventHeader: removed two enumerated values , ‘serviceEvents’ and ‘signaling’ from the domain enumeration

    • commonEventHeader version: incremented the version to 2.0

    • endOfCallVqmSummaries datatype: removed this datatype

    • event: changed the description of the event datatype to: “fields which constitute the ‘root level’ of the common event format”

    • event: removed ‘serviceEventFields’ and ‘signalingFields’ from the definition

    • event: fixed a misspelling of ‘thresholdCrossingAlertFields’, which was only present in the Word document

    • eventInstanceIdentifier datatype: removed this datatype

    • internalHeaderFIelds datatype: defined this as follows: “The internalHeaderFields datatype is an undefined object which can contain arbitrarily complex JSON structures. It is intended to be defined separately by each provider implementing the VES Event Listener. The fields in internalHeaderFields are not provided by any event source but instead are added by the VES Event Listener service itself as part of an event enrichment process necessary for efficient internal processing of events received by the VES Event Listener”

    • marker datatype: removed this datatype

    • measurementsForVfScalingFields datatype: clarified that memoryConfigured and memoryUsed are measured in MB

    • midCallRtcp datatype: removed this datatype

    • mobileFlowFields datatype: added ‘additionalFields’

    • mobileFlowFields datatype: incremented the version number for this field block to 1.2

    • serviceEventsFields datatype: removed this datatype

    • signalingFields datatype: removed this datatype

    • syslogFields: added three fields to the schema that were previously described in the document but not incorporated into the schema: syslogPri, syslogSev, syslogSdId

    • syslogFields version: incremented the version to 2.0

  • Modified the Common Event Format JSON schema to v27.0 to incorporate the above changes. Also, added the AT&T Copyright Notice from the top of the retired CommonEventFormat_Vendors schema.

  • Section 6 and 2: changed all sample requests to use /v4 in the REST Resource URL and call flow diagrams

  • Section 6.1.3: added a row to the table in this section describing the ‘heartbeatIntervalChange’ command.

  • Section 6.1.4: added this new section describing expectations for buffering of events should all REST resource URL FQDNs be unreachable.

  • Section 6 Sample Requests: modified all sample requests showing the return of a commandList toward the event source to incorporate a heartbeatIntervalChange command; also corrected the spelling in the samples for the measurementIntervalChange command.

  • Section 7: Contributors: removed this section

3/21/2017

v4.1

  • JSON Schema changes to produce v27.2 (note: an earlier draft version of v27.1 had been distributed to a few individuals):

    • To support use of the schema with event batches, removed the following statement near the end of the schema file:

    “required”: [ “event” ]

  • Fixed the characters used in some of the quotes

  • Fixed some typos in the descriptions.

  • Removed the booleans, which were non-essential and which were causing problems across different implementations.

  • Section 4.5.7 measurementsForVfScalingFields:

    • Fixed the spelling of measurementsForVfScalingFields in the Word document

  • Section 2 and 6 sample requests and responses:

    • Removed quotes from numbers: sequence, and first/lastEpochMicrosec.

    • Fixed all quote characters, some of which were using unusual symbols that wouldn’t validate with the json-schema Python package.

  • Section 6.2.6.1, 6.3.6.1, 6.4.6.1 sample requests:

    • Added an alarmAdditionalInformation field array to the sample requests.

    • Added missing commas.

  • Section 6.5.6.1 provideThrottlingState sample requests:

    • Fixed the eventDomainThrottleSpecificationList to pass an array of anonymous eventDomainThrottleSpecification objects.

    • Added missing quotes.

  • Fixed the suppressedNvPairsList to pass an array of anonymous suppressedNvPairs objects.

4/14/2017

v5.0

  • Section 1 Introduction:

    • Clarified the Introduction (Section 1).

    • Changed Section 1.1 title from ‘Terminology’ to ‘Event Registration’ and referenced the YAML event registration format, defined in a separate document.

    • Clarified naming standards for eventName.

  • Section 3: updated the REST resource structure

  • Section 4.1 command list processing datatypes:

    • Got rid of commandListEntry and returned commandList to a simple array of commands.

    • Added heartbeatInterval to the command datatype.

    • Changed the datatype of measurementInterval from number to integer.

  • Section 4.2 common event datatypes:

    • event dataType: Added heartbeatFields, sipSignalingFields and voiceQualityFields to the event datatype as optional field blocks

    • Added jsonObject which provides a json object schema, name and other meta-information along with one or more object instances.

    • Added jsonObjectInstance which provides meta-information about an instance of a jsonObject along with the actual object instance

    • Added the ‘key’ datatype

    • Added the namedArrayOfFields datatype

    • Added vendorVnfNameFields

  • Section 4.3 common event header fields:

    • Add two new enumerations to domain: ‘sipSignaling’ and ‘voiceQuality’

    • Renamed eventType to eventName. Note that the original usage of eventType was formally described in the Introduction back on 2/11/2016 with v1.9.

    • Made eventName a required field

    • Created a new field called eventType with a meaning that is different than the old eventType

    • Removed functionalRole, which was replaced by the following two fields.

    • Added nfNamingCode

    • Added nfcNamingCode

    • Changed version to 3.0 (major version change) and made it a required field

  • Section 4.4: faultFields:

    • added one optional field: eventCategory

    • made faultFieldsVersion a required field

    • changed faultFieldsVersion to 2.0 (major version change)

    • fixed a typo on the spelling of alarmInterfaceA

    • clarified field descriptions

  • Section 4.5: added heartbeatFields datatype which can be used to communicate heartbeatInterval. Note: this change was previously made in v4.2

  • Section 4.6 measurements for vf scaling datatypes: changed the following datatypes from number to integer:

    • In measurementsForVfScalingFields: concurrentSessions, configuredEntities, numberOfMediaPortsInUse, vnfcScalingMetric

    • In codecsInUse: numberInUse

    • In featuresInUse: featureUtilization

  • Section 4.6.2 modified cpuUsage

  • Section 4.6.3 added diskUsage

  • Section 4.6.7 measurementsForVfScalingFields:

    • fixed the spelling of the measurementsForVfScalingFields in the Word document

    • added additionalFields, which is an array of fields (i.e., name-value pairs)

    • changed additionalMeasurements to reference the common datatype namedArrayOfFields (instead of referencing measurementGroup)

    • added additionalObjects which is an array of jsonObjects described by name, keys and schema

    • deleted aggregateCpuUsage

    • added diskUsageArray

    • deleted measurementGroup (which was replaced by the common datatype: namedArrayOfFields

    • added memoryUsageArray

    • deleted memoryConfigured and memoryUsed

    • deleted errors and vNicUsageArray

    • added vNicPerformanceArray

    • changed the measurementsForVfScalingVersion to 2.0 (major version change) and made it a required field. Also changed the name of this version field in the Word document to match that in the JSON schema.

  • Section 4.6.8 added memoryUsage

  • Section 4.6.9 vNicPerformance: replaced vNicUsage and errors with vNicPerformance

  • Section 4.7 mobile flow fields changes:

    • Made mobileFlowFieldsVersion a required field and changed the mobileFlowFieldsVersion to 2.0 (major version change).

    • Changed the datatype of flowActivationTime and flowDeactivationTime in the Word doc to string.

    • changed the following datatypes from number to integer: otherEndpointPort, reportingEndpointPort, samplingAlgorithm

  • Section 4.8: otherFields:

    • Added otherFieldsVersion (set at 1.1)

    • Added hashOfNameValuePairArrays

    • Added jsonObjects

    • Added nameValuePairs

  • Section 4.9: added sipSignaling domain datatypes with 4.8.1 sipSignalingFields. sipSignalingFieldsVersion is set at 1.0

  • Section 4.10 stateChangeFields: made stateChangeFieldsVersion a required field and set it to 2.0 (major version change).

  • Section 4.11 syslogFields:

    • Changed the following datatypes from number to integer: syslogFacility, syslogPri

    • Changed additionalFields from a field [ ] to a string which takes name=value pairs delimited by a pipe symbol.

    • Changed syslogFieldsVersion to 3.0 (major version change) and made it a required field

    • Made syslogSev an enumerated string (previously just a string)

  • Section 4.12 thresholdCrossingAlertFields: made thresholdCrossingFieldsVersion a required field and set it to 2.0 (major version change).

  • Section 4.132: added voice quality domain datatypes with 4.13.1 endOfCallVqmSummaries and 4.13.2 voiceQualityFields. voiceQualityFieldsVersion is set at 1.0

  • JSON Schema: changed the schema to v28.0 and incorporated all of the changes above.

  • Additional JSON Schema changes that are part of v28: Note: The following changes are provided relative to API Spec v4.0 (which embedded JSON schema v27.0), but they were also made in an interim release v4.1 (which embedded JSON schema v27.2):

    • To support use of the schema with event batches, removed the following statement near the end of the schema file:

    “required”: [ “event” ]

  • Fixed the characters used in some of the quotes

  • Fixed some typos in the descriptions.

  • Removed the booleans, which were non-essential and which were causing problems across different implementations.

  • Section 2 and 6 sample requests and responses (also incorporated in interim release 4.1):

    • Removed quotes from numbers: sequence, and first/lastEpochMicrosec.

    • Fixed all quote characters, some of which were using unusual symbols that wouldn’t validate with the json-schema Python package.

  • Section 2 and 6 sample requests and responses (only in v5.0):

    • Changed the version numbers in the URL string.

    • Added nfNamingCode and nfcNamingCode and removed functionalRole

  • Section 6 call flows: updated the version number (only in v5.0).

  • Section 6: removed the publishSpecificTopic operation

  • Section 6.1.4: Buffering: clarified event source expectations for buffering (only in v5.0).

  • Section 6.2.6.1, 6.3.6.1 sample requests (also incorporated in interim release 4.1):

    • Added an alarmAdditionalInformation field array to the sample requests.

    • Added missing commas.

  • Section 6.2.6.3, 6.3.6.3 commandList sample responses (only in v5.0):

    • Fixed the commandList sample responses to pass an array of anonymous command objects (rather than an array of commandListEntry objects).

    • Fixed the heartbeatIntervalChange commandType to pass a heartbeatInterval value instead of a measurementInterval value.

    • Removed quotes from the measurementInterval and heartbeatInterval values since they are numbers.

  • Section 6.4.6.1 provideThrottlingState sample requests(also incorporated in interim release 4.1):

    • Fixed the eventDomainThrottleSpecificationList to pass an array of anonymous eventDomainThrottleSpecification objects.

    • Added missing quotes.

    • Fixed the suppressedNvPairsList to pass an array of anonymous suppressedNvPairs objects (also incorporated in interim release 4.1).

5/22/2017

v5.1

  • Footers: removed proprietary markings and updated copyrights to 2017

  • Section 4.2.3: field:

    • Changed the API spec to make ‘name’ and ‘value’ start with lowercase letters. Note: this did not affect the schema, which already had them as lowercase.

  • JSON Schema:

    • measurementGroup: deleted this object since it was replaced with ‘namedArrayOfFields’ in v28.0 and was no longer being used.

    • namedArrayOfFields: Fixed an error in the specification of required fields: from ‘measurements’ to ‘arrayOfFields’.

  • Changed the version of the JSON schema to 28.1

6/14/2017

v5.2

  • JSON Schema: created v28.2 by changing the field descriptions in the memoryUsage object to refer to ‘kibibytes’ instead of ‘kilobytes’. There were no changes to the 28.1 structure.

  • Word Document: measurementsForVfScaling Domain: memoryUsage object: changed the field descriptions in this object to refer to ‘kibibytes’ instead of ‘kilobytes’. There were no changes to the memoryUsage structure.

  • Reorganized the Word document to group the data structures in Section 4 into three broad categories to better align with the VNF Guidelines documentation that has been prepared for vendors:

    • Common Event Datatypes:

      • Command List Processing Datatypes

      • Common Event Datatypes

      • Common Event Header Datatypes

    • Technology Independent Datatypes:

      • ‘Fault Domain Datatypes

      • ‘Heartbeat’ Domain Datatypes

      • ‘Measurements For Vf Scaling’ Domain Datatypes

      • ‘Other’ Domain Datatypes

      • ‘State Change’ Domain Datatypes

      • ‘Syslog’ Domain Datatypes

      • ‘Threshold Crossing Alert’ Domain Datatypes

    • Technology Specify Datatypes:

      • ‘Mobile Flow’ Domain Datatypes

      • ‘Sip Signaling’ Domain Datatypes

      • ‘Voice Quality’ Domain Datatypes

  • Section 6.1.3: Commands Toward Event Source Clients: Added a statement: “Note: Vendors are not currently required to implement support for command processing; in addition, command processing may be supported by an App-C interface in future.”

6/22/2017

v5.3

  • JSON Schema: created v28.3 by correcting an error in the sipSignalingFields: changed vnfVendorNameFields to vendorVnfNameFields. Embedded the new schema at the top of section 4.

9/12/2017

v5.4

  • Note: There no changes to any data structures or operations in this version.

  • JSON Schema: created v28.4 embedded at the top of section 4:

    • Added a reference to eventList in the properties defined under the schema title. This enables the schema to correctly validate event batches in addition to just events.

    • Moved the schema title to the top of the schema and changed the text from “Event Listener” to “VES Event Listener”

    • Added a schema header block under the title to clearly communicate the schema version, associated API and last-modified information

  • Changed the date in the copyright notice to 2017

9/19/2017

v5.4.1

  • Note: There no changes to any data structures or operations in this version.

  • Back of Cover Page: updated the license and copyright notice to comply with ONAP guidelines

  • JSON Schema: updated the JSON schema to v28.4.1: updated the copyright notice and license to comply with ONAP guidelines

6/28/2018

v6.0

  • Added contributors to the title page.

  • Updated references to ‘vnf’ ‘vnfc’ to either ‘nf’ and ‘nfc’ or ‘xNf’ and ‘xNfc’ to generalize support across both vnfs and pnfs.

  • Section 1:

    • clarified the meaning of the VES acronym

    • changed references from ASDC to SDC and from MSO to SO

    • clarified the requirements for eventNames.

    • Added a section of EventId use case examples

    • Added a new section on measurement expansion fields

    • Added a new section of syslogs

    • clarified the versioning section and referenced the new API Versioning section in section 6.

    • Added a list of all the latest field block version numbers in this version of the API spec.

  • Section 2: updated the sample to show use of new HTTP versioning headers. Added a note indicating that support for mutual SSL would be provided in future.

  • Section 3: updated the resource structure remove the clientThrottlingState resource.

  • Section 4: hashMaps. Changed all name-value pair structures to hashMaps causing the following data model and JSON schema (to v29.0) changes:

    • 4.1.1: Common Event Datatypes:

      • removed “field” and added “hashMap”

      • removed “namedArrayOfFields” and added “namedHashMap”

      • added arrayOfNamedHashMap

      • added arrayOfJsonObject

    • 4.2.1: Fault Domain Datatypes:

      • changed the faultFields version to 3.0 (major change)

      • changed faultFields.alarmAdditionalInformation to reference a hashMap

    • 4.2.2: Heartbeat Domain Datatypes:

      • changed the heartbeatFieldsVersion to 2.0 (major change)

      • changed heartbeatFields.additionalFields to reference a hashMap

    • 4.2.3: Measurement Domain Datatypes:

      • changed the measurementFieldsVersion to 3.0 (major change)

      • changed measurementFields.additionalFields to reference a hashMap

      • changed measurement.additionalMesurements to reference a namedHashMap [ ]

      • modified measurementFields.featureUsageArray to reference a hashmap and removed ‘featuresInUse’

      • added the following datatypes which are now referenced as items in arrays within measurementFields: hugePages, load, machineCheckException, processStats

    • 4.2.5: Other Domain Datatypes:

      • Change the otherFieldsVersion to 2.0 (major change)

      • changed otherFields.nameValuePairs to reference a hashMap and renamed it hashMap

      • changed otherFields.hashOfNameValuePairArrrays to reference a namedHashMap and renamed it arrayOfNamedHashMap

    • 4.2.7: State Change Domain Datatypes:

      • changed the stateChangeFiledsVersion to 3.0 (major change)

      • changed stateChangeFields.additionalFields to reference a hashMap

    • 4.2.9: Threshold Crossing Alert Domain Datatypes:

      • changed the thresholdCrossingAlertFieldsVersion to 3.0 (major change)

      • changed thresholdCrossingAlertFields.additionalFields to reference a hashMap

      • counter: removed name and value elements and replaced with a hashMap

    • 4.3.1: Mobile Flow Domain Datatypes:

      • changed the mobileFlowFieldsVersion to 3.0 (major change)

      • changed mobileFlowFields.additionalFields to reference a hashMap

      • gtpPerFlowMetrics: modified ipTosCountList to reference hashmap

      • gtpPerFlowMetrics: modified mobileQciCosCountList to reference hashmap

      • gtpPerFlowMetrics: modified tcpFlagCountList to reference hashmap

    • 4.3.2: Sip Signaling Domain Datatypes:

      • changed the sigSignalingFieldsVersion to 2.0 (major change)

      • changed sipSignalingFields.additionalInformation to reference a hashMap

    • 4.3.3: Voice Quality Domain Datatypes:

      • change the voiceQualityFieldsVersion to 2.0 (major change)

      • changed voiceQualityFields.additionalInformation to reference a hashMap

  • Section 4: added notes at the top of section 4 clarifying expectations and requirements for optional fields, extensible fields and keys sent through extensible fields.

  • Common Event Data Types: Section 4.1.1.9 Changed vendorVnfNameFields to vendorNfNameFields; updated Section 4.3.2 SipSignaling and 4.3.3 Voice Quality to refer to the renamed object

  • Common Event Header Section 4.1.2:

    • clarified the descriptions of eventId, reportingEntityName, sourceName and startEpochMicroseconds.

    • Added ‘notification’ and ‘pngRegistration’ to the domain enumeration.

    • added a new timeZoneOffsest field

  • Fault Domain Section 4.2.1: clarified the definitions of alarmCondition, eventSeverity and specificProblem

  • Measurements Domain Section 4.2.3: changed the name of this domain from ‘measurementsForVfScaling’ to ‘measurement’

    • measurementsForVfScaling measurement

    • measurementsForVfScalingFields measurementFields

    • measurementsForVfScalingVersion measurementFieldsVersion

    • the ‘mfvs’ abbreviation measurement

  • Measurements Domain Section 4.2.3 cpuUsage: added seven optional fields to this structure: cpuCapacityContention, cpuDemandAvg, cpuDemandMhz, cpuDemandPct, cpuLatencyAverage, cpuOverheadAvg, cpuSwapWaitTime

  • Measurements Domain Section 4.2.3 diskUsage: added ten optional fields to this structure: diskBusResets, diskCommandsAborted, diskCommandsAvg , diskFlushRequests, diskFlushTime, diskReadCommandsAvg, diskTime, diskTotalReadLatencyAvg, diskTotalWriteLatencyAvg, diskWriteCommandsAvg

  • Measurements Domain Section 4.2.3: added a new ‘ipmi’ datatype along with following ‘supporting’ datatypes: ipmiBaseboardTemperature, ipmiBaseboardVoltageRegulator, ipmiBattery, ipmiFan, ipmiGlobalAggregateTemperatureMargin, ipmiHsbp, ipmiNic, ipmiPowerSupply, ipmiProcessor, processorDimmAggregateThermalMargin

  • Measurements Domain Section 4.2.3: added a new ‘load’ datatype

  • Measurements Domain Section 4.2.3 memoryUsage: added eight optional fields to this structure: memoryDemand, memoryLatencyAvg, memorySharedAvg, memorySwapInAvg, memorySwapInRateAvg, memorySwapOutAvg, memorySwapOutRateAvg, memorySwapUsedAvg

  • Measurements Domain Section 4.2.3: modified measurementFields to include the following new fields: hugePagesArray, ipmi, loadArray, memoryErrors, processStatusArray, rdtArray

  • Measurements Domain Section 4.2.3 renamed vNicPerformance to nicPerformance and changed vNicIdentifer to nicIdentifier

  • Notification Domain Section 4.2.4: added notificationFields to support a new notification domain.

  • pnfRegistration Domain Section 4.2.7: added pnfRegistrationFields to support a new registration domain.

  • sysLog Domain Section 4.2.8: added two new fields: syslogMsgHost and syslogTs. Clarified field descriptions. Clarified syslogSData example.

  • endOfCallVqmSummaries Section 4.3.3.1:

    • converted endpointJitter into two fields: endpointAverageJitter and endpointMaxJitter

    • converted localJitter into two fields: localAverageJitter and localMaxJitter

    • added two fields: localAverageJitterBufferDelay and localMaxJitterBufferDelay

    • added endpointRtpOctetsLost and endpointRtpPacketsLost

    • added localRtpOctetsLost and localRtpPacketsLost

    • converted packetsLost into oneWayDelay

  • API Versioning:

    • Section 1.4: clarified the versioning section and linked it to the following new section 6.1.2

    • Section 6.1.2: Added requirements for HTTP headers communicating minor, patch and latest version information.

    • Section 2 and 6 sample messages: clarified examples to use the new HTTP headers

  • Section 6.1.4: Added a section specifying message size limits.

  • Section2 6.2.6.1 and 6.3.6.1: corrected additionalInformation examples to use hashMap instead of name-value pair fields.

  • Section 7: Added a section on Terminology.

  • Command List Processing: removed command list processing from the document and schema:

    • Modified the Section 3 resource structure to align with these changes.

    • Removed Section 4 Datatypes: command, commandList, eventDomainThrottleSpecification, eventDomainThrottleSpecificationList, eventThrottlingState, suppressedNvPairs

    • Removed Section 6.1 description of commands toward event source clients

  • Removed Section 6.4 operation: provideThrottlingState

7/30/2018

v7.0

  • General:

    • Fixed typos throughout

    • Changed example versions to v7

  • Section1:

    • Clarified casing and use of dashes versus colons in eventName examples

    • Updated all field block versions

  • Section 2: added a note clarifying that TLS 1.2 or higher must be used for HTTPS connections.

  • Section 4 embedded schema changed to v30:

    • Added ” ‘additionalProperties’: false ” to objects to reject events that attempt to send properties that are not listed in the ‘properties’ keyword. Note: does not affect hashmap extensible fields.

    • Changed all versions in all field blocks from number to string enum with the version number fixed by the enum so the schema can validate events that attempt to send non-standard field blocks.

    • Changed syslog additionalFields to a hashMap

  • Section 4:

    • Fixed section heading numbers that were the same

    • 4.1.1: jsonObjectInstance: added an optional recursive jsonObject and removed all required fields from this object

    • 4.1.2: commonEventHeader:

      • nfVendorName: added this optional field

      • timeZoneOffset: changed from number to string with a particular format specified

      • version was changed from number to string (as were all the version fields of all the field blocks)

      • vesCommonEventListenerVersion: added this required field as a string enumeration

    • 4.2.3: Measurements Domain:

      • Added a note clarifying that NFs are required to report exactly one Measurement event per period per sourceName

      • diskUsage: added four new optional fields: diskWeightedIoTimeAve, diskWeightedIoTimeLast , diskWeightedIoTimeMax, diskWeightedIoTimeMin

      • memoryUsage: add one new optional field: percentMemoryUsage

      • nicPerformance: added nine new optional fields: administrativeState, operationalState , receivedPercentDiscard, receivedPercentError, receivedUtilization, speed, transmittedPercentDiscard, transmittedPercentError, transmittedUtilization

      • processorDimmAggregateThermalMargin: make the thermalMargin field required

    • 4.2.8: Syslog Domain:

  • Corrected the example at the end of the section

7/31/2018

v7.0.1

  • Section 4: The schema embedded at the top of section 4 was patched to correct a header field name error—the schema version moves from 30 to 30.0.1:

    • Changed commonEventHeader field: ‘vesCommonEventFormatVersion’ field to ‘vesEventListenerVersion’ and set the enum to 7.0.1

    • Also changed the commonEventHeader ‘required’ array to reflect use the corrected field name: ‘vesEventListenerVersion’

    • Changed the commonEventHeader ‘version’ field enumeration to 4.0.1

  • Section1:

    • Changed the field block versions for the common header for ‘vesEventListenerVersion’ (to 7.0.1) and ‘version’ (to 4.0.1).

  • Sections 2 and 6:

    • Changed the commonEventHeader version fields above, in the sample message requests and responses; also updated the faultFieldsVersion to 4.0

  • Section 6.1.2: Changed the X-LatestVersion to 7.0.1 and the X-PatchVersion to 1

12/10/2018

v7.1

  • Section 1.2: Added Notification domain Perf3gpp domain and changed a reference from ‘measurements domain’ to ‘measurement domain’.

  • Section 1.7.1: Field Block Versions: added ‘perf3gppFields’ version at 1.0 and changed the following version enumerations so that existing clients of major version 7 would not be broken by this VES minor version change, in accordance with semantic versioning definitions:

    • commonEventHeader: changed to ‘vesEventListenerVersion’ enum to accept either 7.0 or 7.0.1 or 7.1.

    • commonEventHeader: changed ‘version’ enum to accept either 4.0 or 4.0.1 or 4.1

  • Section 2:

    • changed sample request and responses to reference 7.1 instead of 7.0.1 (and version 4.1 of the commonEventHeader version, instead of v4.0.1)

    • added a sub section on service provider support for mutual ssl certificate authentication

  • Section 4.1.2.1:

    • CommonEventHeader timeZoneOffset changed description from ‘UTC+/-hh.mm’ to ‘UTC+/-hh:mm’

    • Added ‘perf3gpp’ to the domain enumeration

  • Section 4.2.3: Measurement Domain Datatypes:

    • In ‘MeasurementFields’: Changed ‘ipmiArray’ to ‘ipmi’ and made the type ‘object’

    • ‘ipmiProcessor’: changed ‘pprocessorThermalControl’ to ‘processorThermalControl’

    • ‘machineCheckException’: changed ‘processIdentifier’ to ‘vmIdentifier’

  • Section 4.2.6: added the perf3gpp domain

  • Section 4 embedded schema:

    • Changed the schema version from 30.0.1 to 30.1 as a result of the changes below:

    • commonEventHeader: changed to ‘vesEventListenerVersion’ enum to accept either 7.0, 7.0.1 or 7.1

    • commonEventHeader: changed the ‘version’ field enumeration to accept either 4.0, 4.0.1 or 4.1

    • commonEventHeader: changed the ‘domain’ enumeration to add support for the perf3gpp domain.

    • ‘event’: added a reference to ‘perf3gppFields’

    • ‘hugePages’: changed the type of hugePagesIdentifier from number to string

    • ‘ipmiGlobalAggregateTemperatureMargin’: changed ‘pmiGlobalAggregateTemperatureMarginIdentifier’ to ‘globalAggregateTemperatureMarginIdentifier’

    • ‘perf3gppFields’: added this object

  • Section 6: changed references throughout from v7.0.1 to v7.1 and v4.0.1 (of the commonEventHeader version) to v4.1

  • Changed the location of the doc to VNF Requirements and changed the formatting

1/28/202

v7.1.1

  • Changed event sizes from 2Mb to 1Mb

  • Configuration Requirement comments addressed

  • Changed DCAE Collector to VES Event Listener

  • Replaced VNF with NF where appropriate

  • Updated publishAnyEvent and publishBatchEvent to clarify both one way and mutual TLS are supported

  • Changed authorization for publishEventBatch because certification authorization is also supported

  • Updated fault use case in EventId Use Case Examples based on Ericsson feedback

  • Added new Configuration Requirements section

  • Added new Event Domain Requirements section

  • Updated security requirements based on agreements in ONAP Security Committee with details on 2-way certificate support

  • Provided clarifications on event buffering

  • Added Event Handling Requirements for publishEventFlow

  • Updated Field Block Versions to support existing clients of major version 7

  • Updated sample request and response schemas

  • Updated embedded schema as follows:

    • Changed schema version to 30.1.1

    • Changed measValues to measValuesList and similar changes throughout

    • Changed iMeasTypesList to sMeasTypesList

  • Corrected publishEventBatch call flow diagram

  • Changed AuthorizationHeader to Required? = NO for publishAnyEvent operation

  • Relaxed various requirements related to camel casing of values from ‘must’ to ‘should’

Service: VES Event Listener 5.4.1

Table of Contents

Introduction

This document describes the RESTful interface for the VES (Virtual function Event Streaming) Event Listener. The VES Event Listener is capable of receiving any event sent in the VES Common Event Format. The Common Event Format is a JSON structure consisting of a required Common Event Header Block accompanied by zero or more event domain blocks. A JSON Schema of the VES Common Event Format is provided in Section 4 of this document.

It should be understood that events are well structured packages of information, identified by an eventName, which are asynchronously communicated to subscribers who are interested in the eventName. Events can convey measurements, faults, syslogs, threshold crossing alerts and others types of information. Events are simply a way of communicating well-structured packages of information to one or more instances of an Event Listener service.

This document describes a RESTful connectionless push event listener that is capable of receiving single events or batches of events in the Common Event Format. In future, additional documents may describe other transports which make use of persistent TCP connections for high volumes of streaming events.

Event Registration

All events must be compliant with the common event format, but specific events identified by their eventNames, may require that certain fields, which are optional in the common event format, be present when they are published. For example, a specific eventName may require that specific name-value pairs be present in the extensible structures provided within the Common Event Format.

Events are registered using an extensible YAML format (defined in a separate document), which specifies, for each eventName, the fields that are required, what field values may be sent, and any special handling that should be performed on those eventNames.

Naming Standards for eventName

To prevent naming collisions, eventNames sent as part of the commonEventHeader, should conform to the following naming convention designed to summarize the purpose and type of the event, and to ensure the uniqueness of the eventName:

{DomainAbbreviation}_{SdcModel or ApplicationPlatform}_{DescriptionOfInfoBeingConveyed}

Domain abbreviations are derived from the ‘domain’ field in the commonEventHeader, as specified below: - ‘Fault’for the fault domain - ‘Heartbeat’for the heartbeat domain - ‘Mfvs’for the measurementsForVfScaling domain - ‘MobileFlow’for the mobileFlow domain - ‘Other’for the other domain - ‘SipSignaling’for the sipSignaling domain - ‘StateChange’for the stateChange domain - ‘Syslog’for the syslog domain - ‘Tca’for the thresholdCrossingAlert domain - ‘voiceQuality’for the voiceQuality domain

SDC (the ONAP Service Design and Creation environment) defines and catalogs specific services, VNFs, VF modules and other entities, which are generically referred to as ‘SDC models’. The SDC model that an event is associated with should be indicated in the second subfield within the eventName. If the event is not associated with an Sdc model but is instead being generated by an application platform like SO, then a string identifying the Application Platform may be used instead. In either case, all subfield names should be converted to camel case format (with no spaces, hyphens or underscores).

The final subfield of the eventName name should describe, in a compact camel case format (with no spaces, hyphens or underscores), the specific information being conveyed by the event. In some cases, this final subfield will not be required (e.g., in the case of Heartbeats or in the case of an event source which, for a domain like syslog, defines only one eventName to support it):

Examples of eventNames following the naming standards are provided below:

  • Fault_MobileCallRecording_PilotNumberPoolExhaustion

  • Heartbeat_vIsbcMmc

  • Other_WanBonding_InstantiationPart1Complete

  • Syslog_vDbe

  • Tca_vDbe_CpuThresholdExceeded

  • Other_SO_InstantiationPhase1Complete

Any questions about the naming of eventNames should be resolved as part of service and resource onboarding to the ONAP Service Design and Creation environment (i.e., SDC).

Support for Protocols Other Than HTTPS

This API specification describes an HTTPS RESTful interface using the JSON content-type.

Alternative specifications may be provided in future using Websockets, which would establish a permanent TCP socket, or Apache Avro which provides a binary format over an RPC protocol to be defined. Both would leverage the JSON schema provided in this document.

Versioning

Three types of version numbers supported by this specification:

  • The API specification itself is versioned. Going forward, the major number of the specification version will be incremented whenever any change could break an existing client (e.g., a field name is deleted or changed). All other changes to the spec (e.g., a field name is added or text changes are made to the specification itself) will increment only the minor number. Note that the major number appears in REST resource URLs as v# (where ‘#’is the major number).

  • The JSON schema is versioned. Going forward, the major number of the JSON schema will be incremented whenever any change could break an existing client (e.g., a field name is deleted or changed). All other changes to the schema (e.g., a field name is added or text changes are made to the field descriptions) will increment only the minor number.

  • The field blocks are versioned. Field blocks include the commonEventHeader and the domain blocks (e.g., the faultFields block). Going forward, the major number of each field block will be incremented whenever any change to that block could break an existing client (e.g., a field name is deleted or changed). All other changes to that block (e.g., a field name is added or text changes are made to the field descriptions) will increment only the minor number.

Security

Event sources must identify themselves to the VES Event Listener.

Event source credentials are passed using HTTP Basic Authentication.

Credentials must not be passed on the query string. Credentials must be sent in an Authorization header as follows:

  1. The username and password are formed into one string as “username:password”

  2. The resulting string is Base64 encoded to produce the encoded credential.

  3. The encoded credential is communicated in the header after the string “Authorization: Basic “

Because the credentials are merely encoded but not encrypted, HTTPS (rather than HTTP) should be used. HTTPS will also encrypt and protect event contents.

Examples are provided below.

Sample Request and Response

Sample Request

POST /eventListener/v5 HTTPS/1.1
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
content-type: application/json
content-length: 12345
{
   "event": {
     "commonEventHeader": {
       "version": 3.0,
       "domain": "heartbeat",
       "eventName": "Heartbeat\_vIsbcMmc",
       "eventId": "ab305d54-85b4-a31b-7db2fb6b9e546015",
       "sequence": 0,
       "priority": "Normal",
       "reportingEntityId": "cc305d54-75b4-431badb2eb6b9e541234",
       "reportingEntityName": "EricssonOamVf",
       "sourceId": "de305d54-75b4-431b-adb2-eb6b9e546014",
       "sourceName": "ibcx0001vm002ssc001",
       "nfNamingCode": "ibcx",
       "nfcNamingCode": "ssc",
       "startEpochMicrosec": 1413378172000000,
       "lastEpochMicrosec": 1413378172000000
      }
   }
 }

Sample Success Response

HTTPS/1.1 202 Accepted

REST resources are defined with respect to a ServerRoot:

ServerRoot = /{optionalRoutingPath}

The resource structure is provided below:

{ServerRoot}
    |
    |--- /eventListener/v{apiVersion}
             |
             |--- /eventBatch

Figure 1: REST Resource Structure

The {Domain} or FQDN above is typically provisioned into each eventsource when it is instantiated. The {Port} above is typically 8443.

A JSON schema describing the Common Event Format is provided below and is reproduced in the tables that follow.

Common Event Datatypes

Common Event Datatypes

Datatype: event

The event datatype consists of the following fields which constitute the ‘root level’of the common event format:

Field

Type

Required?

Description

commonEventHeader

commonEventHeader

Yes

Fields common to all events

faultFields

faultFields

No

Fields specific to fault events

heartbeatFields

heartbeatFields

No

Fields specific to heartbeat events

measurementsForVfScalingFields

measurementsForVfScalingFields

No

Fields specific to measurementsForVfScaling events

mobileFlowFields

mobileFlowFields

No

Fields specific to mobility flow events

otherFields

otherFields

No

Fields specific to other types of events

sipSignalingFields

sipSignalingFields

No

Fields specific to sipSignaling events

stateChangeFields

stateChangeFields

No

Fields specific to state change events

syslogFields

syslogFields

No

Fields specific to syslog events

thresholdCrossingAlertFields

thresholdCrossingAlertFields

No

Fields specific to threshold crossing alert events

voiceQualityFields

voiceQualityFields

No

Fields specific to voiceQuality events

Datatype: eventList

The eventList datatype consists of the following fields:

Field

Type

Required?

Description

eventList

event [ ]

Yes

Array of events

Datatype: field

The field datatype consists of the following fields:

Field

Type

Required?

Description

name

string

Yes

Name of the field

value

string

Yes

Value of the named field

Datatype: jsonObject

The jsonObject datatype provides a json object schema, name and other meta-information along with one or more object instances that conform to the schema:

Field

Type

Required?

Description

objectInstances

JsonObjectInstance [ ]

Yes

Contains one or more instances of the json object

objectName

string

Yes

Name of the json object

objectSchema

string

No

json schema for the object

objectSchemaUrl

string

No

URL to the json schema for the object

nfSubscribedObjectName

string

No

Name of the object associated with the nfSubscriptionId

nfSubscriptionId

string

No

Identifies an openConfig telemetry subscription on a network function, which configures the network function to send complex object data associated with the jsonObject

Datatype: jsonObjectInstance

The jsonObjectInstance datatype provides meta-information about an instance of a jsonObject along with the actual object instance:

Field

Type

Required?

Description

objectInstance

object

Yes

Contains an instance conforming to the jsonObject schema

objectInstanceEpochMicrosec

number

No

the unix time, aka epoch time, associated with this objectInstance–as microseconds elapsed since 1 Jan 1970 not including leap seconds

objectKeys

key [ ]

No

An ordered set of keys that identifies this particular instance of jsonObject (e.g., that places it in a hierarchy)

Datatype: key

The key datatype is a tuple which provides the name of a key along with its value and relative order; it consists of the following fields:

Field

Type

Required?

Description

keyName

string

Yes

Name of the key

keyOrder

Integer

No

Relative sequence or order of the key (with respect to other keys)

keyValue

string

No

Value of the key

Datatype: namedArrayOfFields

The namedArrayOfFields datatype is an array of name value pairs along with a name for the array; it consists of the following fields:

Field

Type

Required?

Description

name

string

Yes

Name for the array of name-value pairs

arrayOfFields

field [ ]

Yes

Name-value pairs

Datatype: requestError

The requestError datatype defines the standard request error data structure:

Field

Type

Required?

Description

messageId

string

Yes

Unique message identifier of the format ‘ABCnnnn’where ‘ABC’is either ‘SVC’for Service Exceptions or ‘POL’for Policy Exception. Exception numbers may be in the range of 0001 to 9999 where 0001 to 2999 are defined by OMA (see section 5.1) and 3000-9999 are available and undefined.

text

string

Yes

Message text, with replacement variables marked with %n, where n is an index into the list of <variables> elements, starting at 1

url

string

No

Hyperlink to a detailed error resource e.g., an HTML page for browser user agents

variables

string

No

List of zero or more strings that represent the contents of the variables used by the message text

Datatype: vendorVnfNameFields

The vendorVnfNameFields provides vendor, vnf and vfModule identifying information:

Field

Type

Required?

Description

vendorName

string

Yes

VNF vendor name

vfModuleName

string

No

The Sdc vfModuleName for the vfModule generating the event

vnfName

string

No

The Sdc modelName for the VNF generating the event

‘Common Event Header’Datatypes

Datatype: commonEventHeader

The commonEventHeader datatype consists of the following fields common to all events:

Field

Type

Required?

Description

version

number

Yes

Version of the event header (currently: 3.0)

eventName

string

Yes

Unique event name (see section 1 for more information)

domain

string

Yes

Event domain enumeration: ‘fault’, ‘heartbeat’, ‘measurementsForVfScaling’, ‘mobileFlow’, ‘other’, ‘sipSignaling’, ‘stateChange’, ‘syslog’, ‘thresholdCrossingAlert’, ‘voiceQuality’

eventId

string

Yes

Event key that is unique to the event source

eventType

string

No

For example: ‘applicationVnf’, ‘guestOS’, ‘hostOS’, ‘platform’

nfcNamingCode

string

No

Network function component type: 3 characters (aligned with vfc naming standards)

nfNamingCode

string

No

Network function type: 4 characters (aligned with vnf naming standards)

sourceId

string

No

UUID identifying the entity experiencing the event issue (note: the AT&T internal enrichment process shall ensure that this field is populated)

sourceName

string

Yes

Name of the entity experiencing the event issue

reportingEntityId

string

No

UUID identifying the entity reporting the event, for example an OAM VM (note: the AT&T internal enrichment process shall ensure that this field is populated)

reportingEntityName

string

Yes

Name of the entity reporting the event, for example, an EMS name. May be the same as the sourceName. For synthetic events generated by DCAE, it is the name of the app generating the event.

priority

string

Yes

Processing priority enumeration: ‘High’, ‘Medium’, ‘Normal’, ‘Low’

startEpochMicrosec

number

Yes

the earliest unix time aka epoch time associated with the event from any component–as microseconds elapsed since 1 Jan 1970 not including leap seconds

lastEpochMicrosec

number

Yes

the latest unix time aka epoch time associated with the event from any component–as microseconds elapsed since 1 Jan 1970 not including leap seconds

sequence

integer

Yes

Ordering of events communicated by an event source instance (or 0 if not needed)

internalHeader Fields

internalHeader Fields

No

Fields (not supplied by event sources) that the VES Event Listener service can use to enrich the event if needed for efficient internal processing. This is an empty object which is intended to be defined separately by each provider implementing the VES Event Listener.

Datatype: internalHeaderFields

The internalHeaderFields datatype is an undefined object which can contain arbitrarily complex JSON structures. It is intended to be defined separately by each provider implementing the VES Event Listener.

The fields in internalHeaderFields are not provided by any event source but instead are added by the VES Event Listener service itself as part of an event enrichment process necessary for efficient internal processing of events received by the VES Event Listener:

Technology Independent Datatypes

‘Fault’Domain Datatypes

Datatype: faultFields

The faultFields datatype consists of the following fields:

Field

Type

Required?

Description

faultFieldsVersion

number

Yes

Version of the faultFields block (currently: 2.0)

eventSeverity

string

Yes

Event severity enumeration: ‘CRITICAL’, ‘MAJOR’, ‘MINOR’, ‘WARNING’, ‘NORMAL’

eventSourceType

string

Yes

Examples: ‘card’, ‘host’, ‘other’, ‘port’, ‘portThreshold’, ‘router’, ‘slotThreshold’, ‘switch’, ‘virtualMachine’, ‘virtualNetworkFunction’

eventCategory

string

No

Event category, for example: ‘license’, ‘link’, ‘routing’, ‘security’, ‘signaling’

alarmCondition

string

Yes

Alarm condition reported by the device (e.g., ‘tpLgCgiNotInConfig’)

specificProblem

string

Yes

Short description of the alarm or problem (e.g., ‘This event is sent when the LG is asked to perform a location for a CGI that is not in its configuration’)

vfStatus

string

Yes

Virtual function status enumeration: ‘Active’, ‘Idle’, ‘Preparing to terminate’, ‘Ready to terminate’, ‘Requesting Termination’

alarmInterfaceA

string

No

Card, port, channel or interface name of the device generating the alarm

alarmAdditional Information

field [ ]

No

Additional alarm information (note: for SNMP mapping to VES, for name use OID of varbind, for value use incoming data for that varbind)

‘Heartbeat’Domain Datatypes

Datatype: heartbeatFields

The heartbeatFields datatype is an optional field block for fields specific to heartbeat events; it consists of the following fields:

Field

Type

Required?

Description

heartbeatFieldsVersion

number

Yes

Version of the heartbeatFields block (currently: 1.0)

additionalFields

field [ ]

No

Additional expansion fields if needed

heartbeatInterval

Integer

Yes

Current heartbeatInterval in seconds

Measurements For VF Scaling’Domain Datatypes

Datatype: codecsInUse

The codecsInUse datatype consists of the following fields describing the number of times an identified codec was used over the measurementInterval:

Field

Type

Required?

Description

codecIdentifer

string

Yes

Description of the codec

numberInUse

integer

Yes

Number of such codecs in use

Datatype: cpuUsage

The cpuUsage datatype defines the usage of an identifier CPU and consists of the following fields:

Field

Type

Required?

Description

cpuIdentifier

string

Yes

CPU Identifier

cpuIdle

number

No

Percentage of CPU time spent in the idle task

cpuUsageInterrupt

number

No

Percentage of time spent servicing interrupts

cpuUsageNice

number

No

Percentage of time spent running user space processes that have been niced

cpuUsageSoftIrq

number

No

Percentage of time spent handling soft irq interrupts

cpuUsageSteal

number

No

Percentage of time spent in involuntary wait which is neither user, system or idle time and is effectively time that went missing

cpuUsageSystem

number

No

Percentage of time spent on system tasks running the kernel

cpuUsageUser

number

No

Percentage of time spent running un-niced user space processes

cpuWait

number

No

Percentage of CPU time spent waiting for I/O operations to complete

percentUsage

number

Yes

Aggregate cpu usage of the virtual machine on which the VNFC reporting the event is running

Datatype: diskUsage

The diskUsage datatype defines the usage of a disk and consists of the following fields:

Field

Type

Required?

Description

diskIdentifier

string

Yes

Disk Identifier

diskIoTimeAvg

number

No

Milliseconds spent doing input/output operations over 1 sec; treat this metric as a device load percentage where 1000ms matches 100% load; provide the average over the measurement interval

diskIoTimeLast

number

No

Milliseconds spent doing input/output operations over 1 sec; treat this metric as a device load percentage where 1000ms matches 100% load; provide the last value measurement within the measurement interval

diskIoTimeMax

number

No

Milliseconds spent doing input/output operations over 1 sec; treat this metric as a device load percentage where 1000ms matches 100% load; provide the maximum value measurement within the measurement interval

diskIoTimeMin

number

No

Milliseconds spent doing input/output operations over 1 sec; treat this metric as a device load percentage where 1000ms matches 100% load; provide the minimum value measurement within the measurement interval

diskMergedReadAvg

number

No

Number of logical read operations that were merged into physical read operations, e.g., two logical reads were served by one physical disk access; provide the average measurement within the measurement interval

diskMergedReadLast

number

No

Number of logical read operations that were merged into physical read operations, e.g., two logical reads were served by one physical disk access; provide the last value measurement within the measurement interval

diskMergedReadMax

number

No

Number of logical read operations that were merged into physical read operations, e.g., two logical reads were served by one physical disk access; provide the maximum value measurement within the measurement interval

diskMergedReadMin

number

No

Number of logical read operations that were merged into physical read operations, e.g., two logical reads were served by one physical disk access; provide the minimum value measurement within the measurement interval

diskMergedWriteAvg

number

No

Number of logical write operations that were merged into physical write operations, e.g., two logical writes were served by one physical disk access; provide the average measurement within the measurement interval

diskMergedWriteLast

number

No

Number of logical write operations that were merged into physical write operations, e.g., two logical writes were served by one physical disk access; provide the last value measurement within the measurement interval

diskMergedWriteMax

number

No

Number of logical write operations that were merged into physical write operations, e.g., two logical writes were served by one physical disk access; provide the maximum value measurement within the measurement interval

diskMergedWriteMin

number

No

Number of logical write operations that were merged into physical write operations, e.g., two logical writes were served by one physical disk access; provide the minimum value measurement within the measurement interval

diskOctetsRead Avg

number

No

Number of octets per second read from a disk or partition; provide the average measurement within the measurement interval

diskOctetsRead Last

number

No

Number of octets per second read from a disk or partition; provide the last measurement within the measurement interval

diskOctetsRead Max

number

No

Number of octets per second read from a disk or partition; provide the maximum measurement within the measurement interval

diskOctetsRead Min

number

No

Number of octets per second read from a disk or partition; provide the minimum measurement within the measurement interval

diskOctetsWrite Avg

number

No

Number of octets per second written to a disk or partition; provide the average measurement within the measurement interval

diskOctetsWrite Last

number

No

Number of octets per second written to a disk or partition; provide the last measurement within the measurement interval

diskOctetsWriteMax

number

No

Number of octets per second written to a disk or partition; provide the maximum measurement within the measurement interval

diskOctetsWriteMin

number

No

Number of octets per second written to a disk or partition; provide the minimum measurement within the measurement interval

diskOpsReadAvg

number

No

Number of read operations per second issued to the disk; provide the average measurement within the measurement interval

diskOpsReadLast

number

No

Number of read operations per second issued to the disk; provide the last measurement within the measurement interval

diskOpsReadMax

number

No

Number of read operations per second issued to the disk; provide the maximum measurement within the measurement interval

diskOpsReadMin

number

No

Number of read operations per second issued to the disk; provide the minimum measurement within the measurement interval

diskOpsWriteAvg

number

No

Number of write operations per second issued to the disk; provide the average measurement within the measurement interval

diskOpsWriteLast

number

No

Number of write operations per second issued to the disk; provide the last measurement within the measurement interval

diskOpsWrite Max

number

No

Number of write operations per second issued to the disk; provide the maximum measurement within the measurement interval

diskOpsWriteMin

number

No

Number of write operations per second issued to the disk; provide the minimum measurement within the measurement interval

diskPendingOperationsAvg

number

No

Queue size of pending I/O operations per second; provide the average measurement within the measurement interval

diskPendingOperationsLast

number

No

Queue size of pending I/O operations per second; provide the last measurement within the measurement interval

diskPendingOperationsMax

number

No

Queue size of pending I/O operations per second; provide the maximum measurement within the measurement interval

diskPendingOperationsMin

number

No

Queue size of pending I/O operations per second; provide the minimum measurement within the measurement interval

diskTimeReadAvg

number

No

Milliseconds a read operation took to complete; provide the average measurement within the measurement interval

diskTimeRead Last

number

No

Milliseconds a read operation took to complete; provide the last measurement within the measurement interval

diskTimeRead Max

number

No

Milliseconds a read operation took to complete; provide the maximum measurement within the measurement interval

diskTimeRead Min

number

No

Milliseconds a read operation took to complete; provide the minimum measurement within the measurement interval

diskTimeWrite Avg

number

No

Milliseconds a write operation took to complete; provide the average measurement within the measurement interval

diskTimeWrite Last

number

No

Milliseconds a write operation took to complete; provide the last measurement within the measurement interval

diskTimeWrite Max

number

No

Milliseconds a write operation took to complete; provide the maximum measurement within the measurement interval

diskTimeWrite Min

number

No

Milliseconds a write operation took to complete; provide the minimum measurement within the measurement interval

Datatype: featuresInUse

The featuresInUse datatype consists of the following fields which describe the number of times an identified feature was used over the measurementInterval:

Field

Type

Required?

Description

featureIdentifer

string

Yes

Description of the feature

featureUtilization

integer

Yes

Number of times the identified feature was used

Datatype: filesystemUsage

The filesystemUsage datatype consists of the following fields:

Field

Type

Required?

Description

filesystemName

string

Yes

File system name

blockConfigured

number

Yes

Configured block storage capacity in GB

blockIops

number

Yes

Block storage input-output operations per second

blockUsed

number

Yes

Used block storage capacity in GB

ephemeralConfigured

number

Yes

Configured ephemeral storage capacity in GB

ephemeralIops

number

Yes

Ephemeral storage input-output operations per second

ephemeralUsed

number

Yes

Used ephemeral storage capacity in GB

Datatype: latencyBucketMeasure

The latencyBucketMeasure datatype consists of the following fields which describe the number of counts falling within a defined latency bucket:

Field

Type

Required?

Description

countsInTheBucket

number

Yes

Number of counts falling within a defined latency bucket

highEndOfLatencyBucket

number

No

High end of bucket range (typically in ms)

lowEndOfLatencyBucket

number

No

Low end of bucket range (typically in ms)

Datatype: measurementsForVfScalingFields

The measurementsForVfScalingFields datatype consists of the following fields:

Field

Type

Required?

Description

measurementsForVfScalingVersion

number

Yes

Version of the measurementsForVfScalingFields block (currently: 2.0)

additionalFields

field [ ]

No

Additional measurement fields if needed

additionalMeasurements

namedArrayOfFields [ ]

No

Array of named name-value-pair arrays if needed

additionalObjects

jsonObject [ ]

No

Array of JSON objects described by name, schema and other meta-information, if needed

codecUsageArray

codecsInUse []

No

Array of codecs in use

concurrentSessions

integer

No

Peak concurrent sessions for the VM or VNF (depending on the context) over the measurementInterval

configuredEntities

integer

No

Depending on the context over the measurementInterval: peak total number of users, subscribers, devices, adjacencies, etc., for the VM, or peak total number of subscribers, devices, etc., for the VNF

cpuUsageArray

cpuUsage []

No

Usage of an array of CPUs

diskUsageArray

diskUsage []

No

Usage of an array of disks

featureUsageArray

featuresInUse []

No

Array of features in use

filesystemUsageArray

filesystemUsage []

No

Filesystem usage of the VM on which the VNFC reporting the event is running

latencyDistribution

latencyBucketMeasure [ ]

No

Array of integers representing counts of requests whose latency in milliseconds falls within per-VNF configured ranges; where latency is the duration between a service request and its fulfillment.

meanRequestLatency

number

No

Mean seconds required to respond to each request for the VM on which the VNFC reporting the event is running

measurementInterval

number

Yes

Interval over which measurements are being reported in seconds

memoryUsageArray

memoryUsage []

No

Memory usage of an array of VMs

numberOfMediaPortsInUse

integer

No

Number of media ports in use

requestRate

number

No

Peak rate of service requests per second to the VNF over the measurementInterval

vnfcScalingMetric

integer

No

Represents busy-ness of the VNF from 0 to 100 as reported by the VNFC

vNicPerformanceArray

vNicPerformance [ ]

No

Performance metrics of an array of virtual network interface cards

Datatype: memoryUsage

The memoryUsage datatype defines the memory usage of a virtual machine and consists of the following fields:

Field

Type

Required?

Description

memoryBuffered

number

No

Kibibytes of temporary storage for raw disk blocks

memoryCached

number

No

Kibibytes of memory used for cache

memoryConfigured

number

No

Kibibytes of memory configured in the virtual machine on which the VNFC reporting the event is running

memoryFree

number

Yes

Kibibytes of physical RAM left unused by the system

memorySlabRecl

number

No

The part of the slab that can be reclaimed such as caches measured in kibibytes

memorySlabUnrecl

number

No

The part of the slab that cannot be reclaimed even when lacking memory measure in kibibytes

memoryUsed

number

Yes

Total memory minus the sum of free, buffered, cached and slab memory measured in kibibytes

vmIdentifier

string

Yes

Virtual Machine identifier associated with the memory metrics

Datatype: vNicPerformance

The vNicPerformance datatype consists of the following fields which describe the performance and errors of an of an identified virtual network interface card:

Field

Type

Required?

Description

receivedBroadcastPacketsAccumulated

number

No

Cumulative count of broadcast packets received as read at the end of the measurement interval

receivedBroadcastPacketsDelta

number

No

Count of broadcast packets received within the measurement interval

receivedDiscardedPacketsAccumulated

number

No

Cumulative count of discarded packets received as read at the end of the measurement interval

receivedDiscardedPacketsDelta

number

No

Count of discarded packets received within the measurement interval

receivedErrorPacketsAccumulated

number

No

Cumulative count of error packets received as read at the end of the measurement interval

receivedErrorPacketsDelta

number

No

Count of error packets received within the measurement interval

receivedMulticastPacketsAccumulated

number

No

Cumulative count of multicast packets received as read at the end of the measurement interval

receivedMulticastPacketsDelta

number

No

Count of multicast packets received within the measurement interval

receivedOctetsAccumulated

number

No

Cumulative count of octets received as read at the end of the measurement interval

receivedOctetsDelta

number

No

Count of octets received within the measurement interval

receivedTotalPacketsAccumulated

number

No

Cumulative count of all packets received as read at the end of the measurement interval

receivedTotalPacketsDelta

number

No

Count of all packets received within the measurement interval

receivedUnicastPacketsAccumulated

number

No

Cumulative count of unicast packets received as read at the end of the measurement interval

receivedUnicastPacketsDelta

number

No

Count of unicast packets received within the measurement interval

transmittedBroadcastPacketsAccumulated

number

No

Cumulative count of broadcast packets transmitted as read at the end of the measurement interval

transmittedBroadcastPacketsDelta

number

No

Count of broadcast packets transmitted within the measurement interval

transmittedDiscardedPacketsAccumulated

number

No

Cumulative count of discarded packets transmitted as read at the end of the measurement interval

transmittedDiscardedPacketsDelta

number

No

Count of discarded packets transmitted within the measurement interval

transmittedErrorPacketsAccumulated

number

No

Cumulative count of error packets transmitted as read at the end of the measurement interval

transmittedErrorPacketsDelta

number

No

Count of error packets transmitted within the measurement interval

transmittedMulticastPacketsAccumulated

number

No

Cumulative count of multicast packets transmitted as read at the end of the measurement interval

transmittedMulticastPacketsDelta

number

No

Count of multicast packets transmitted within the measurement interval

transmittedOctetsAccumulated

number

No

Cumulative count of octets transmitted as read at the end of the measurement interval

transmittedOctetsDelta

number

No

Count of octets transmitted within the measurement interval

transmittedTotalPacketsAccumulated

number

No

Cumulative count of all packets transmitted as read at the end of the measurement interval

transmittedTotalPacketsDelta

number

No

Count of all packets transmitted within the measurement interval

transmittedUnicastPacketsAccumulated

number

No

Cumulative count of unicast packets transmitted as read at the end of the measurement interval

transmittedUnicastPacketsDelta

number

No

Count of unicast packets transmitted within the measurement interval

valuesAreSuspect

string

Yes

Enumeration: ‘true’or ‘false’. If ‘true’then the vNicPerformance values are likely inaccurate due to counter overflow or other condtions.

vNicIdentifier

string

Yes

vNic identification

‘Other’Domain Datatypes

Datatype: otherFields

The otherFields datatype defines fields for events belonging to the ‘other’ domain of the commonEventHeader domain enumeration; it consists of the following fields:

Field

Type

Required?

Description

otherFieldsVersion

number

Yes

Version of the otherFields block (currently: 1.1)

hashOfNameValuePairArrays

namedArrayOfFields [ ]

No

Array of named name-value-pair arrays

jsonObjects

jsonObject [ ]

No

Array of JSON objects described by name, schema and other meta-information

nameValuePairs

field [ ]

No

Array of name-value pairs

‘State Change’Domain Datatypes

Datatype: stateChangeFields

The stateChangeFields datatype consists of the following fields:

Field

Type

Required?

Description

stateChangeFieldsVersion

number

Yes

Version of the stateChangeFields block (currently: 2.0)

additionalFields

field [ ]

No

Additional stateChange fields if needed

newState

string

Yes

New state of the entity: ‘inService’, ‘maintenance’, ‘outOfService’

oldState

string

Yes

Previous state of the entity: ‘inService’, ‘maintenance’, ‘outOfService’

stateInterface

string

Yes

Card or port name of the entity that changed state

‘Syslog’Domain Datatypes

Datatype: syslogFields

The syslogFields datatype consists of the following fields:

Field

Type

Required?

Description

syslogFieldsVersion

number

Yes

Version of the syslogFields block (currently: 3.0)

additionalFields

string

No

Additional syslog fields if needed, provided as name=value delimited by a pipe | symbol, for example: "name1=value1|name2=value2|"

eventSourceHost

string

No

Hostname of the device

eventSourceType

string

Yes

Examples: ‘other’, ‘router’, ‘switch’, ‘host’, ‘card’, ‘port’, ‘slotThreshold’, ‘portThreshold’, ‘virtualMachine’, ‘virtualNetworkFunction’

syslogFacility

integer

No

Numeric code from 0 to 23 for facility:

0 kernel messages

1 user-level messages

2 mail system

3 system daemons

4 security/authorization messages

5 messages generated internally by syslogd

6 line printer subsystem

7 network news subsystem

8 UUCP subsystem

9 clock daemon

10 security/authorization messages

11 FTP daemon

12 NTP subsystem

13 log audit

14 log alert

15 clock daemon (note 2)

16 local use 0 (local0)

17 local use 1 (local1)

18 local use 2 (local2)

19 local use 3 (local3)

20 local use 4 (local4)

21 local use 5 (local5)

22 local use 6 (local6)

23 local use 7 (local7 )

syslogMsg

string

Yes

Syslog message

syslogPri

integer

No

0-192

Combined Severity and Facility

syslogProc

string

No

Identifies the application that originated the message

syslogProcId

number

No

A change in the value of this field indicates a discontinuity in syslog reporting

syslogSData

string

No

Syslog structured data consisting of a structured data Id followed by a set of key value pairs (see below for an example)

**Note: SD-ID may not be present if syslogSdId is populated

syslogSdId

string

No

0-32 char in format name@number,

i.e., ourSDID@32473

syslogSev

string

No

Level-of-severity enumeration in quotes below:

‘Emergency’: system is unusable

‘Alert’: action must be taken immediately

‘Critical’: critical conditions

‘Error’: error conditions

‘Warning’: warning conditions

‘Notice’: normal but significant condition

‘Info’: Informational: informational messages

‘Debug’: debug-level messages

syslogTag

string

Yes

MsgId indicating the type of message such as ‘TCPOUT’or ‘TCPIN’; ‘NILVALUE’should be used when no other value can be provided

syslogVer

number

No

IANA assigned version of the syslog protocol specification (typically ‘1’)

Example of syslogSData:

STRUCTURED-DATA = NILVALUE / 1*SD-ELEMENT

SD-ELEMENT = “[” SD-ID *(SP SD-PARAM) “]”

SD-PARAM = PARAM-NAME “=” %d34 PARAM-VALUE %d34

SD-ID = SD-NAME

PARAM-NAME = SD-NAME

PARAM-VALUE = UTF-8-STRING ; characters ‘”’, ‘\’ and

; ‘]’ MUST be escaped.

SD-NAME = 1*32PRINTUSASCII

; except ‘=’, SP, ‘]’, %d34 (“)

‘Threshold Crossing Alert’Domain Datatypes

Datatype: counter

The counter datatype consists of the following fields:

Field

Type

Required?

Description

name

string

Yes

Name of the counter

value

string

Yes

Current value of the counter

threshholdCrossed

string

Yes

Last threshold that was crossed

criticality

string

Yes

Enumeration: ‘CRIT’, ‘MAJ’

Datatype: thresholdCrossingAlertFields

The thresholdCrossingAlertFields datatype consists of the following fields:

Field

Type

Required?

Description

thresholdCrossing FieldsVersion

number

Yes

Version of the thresholdCrossingAlertFields block (currently: 2.0)

additionalFields

field [ ]

No

Additional threshold crossing alert fields if needed

additionalParameters

counter [ ]

Yes

Array of performance counters

alertAction

string

Yes

Enumeration: ‘SET’, ‘CONT’, ‘CLEAR’

alertDescription

string

Yes

Unique short alert description (e.g., NE-CPUMEM)

alertType

string

Yes

Enumeration: ‘CARD-ANOMALY’, ‘INTERFACE-ANOMALY’, ELEMENT-ANOMALY’, ‘SERVICE-ANOMALY’

alertValue

string

No

Calculated API value (if applicable)

associatedAlertIdList

string [ ]

No

List of eventIds associated with the event being reported

collectionTimestamp

string

Yes

Time when the performance collector picked up the data; with RFC 2822 compliant format: ‘Sat, 13 Mar 2010 11:29:05 -0800’

dataCollector

string

No

Specific performance collector instance used

elementType

string

No

Type of network element (internal AT&T field)

eventSeverity

string

Yes

Event severity or priority enumeration: ‘CRITICAL’, ‘MAJOR’, ‘MINOR’, ‘WARNING’, ‘NORMAL’

eventStartTimestamp

string

Yes

Time closest to when the measurement was made; with RFC 2822 compliant format: ‘Sat, 13 Mar 2010 11:29:05 -0800’

interfaceName

string

No

Physical or logical port or card (if applicable)

networkService

string

No

Network name (internal AT&T field)

possibleRootCause

string

No

Reserved for future use

Technology Specific Datatypes

‘Mobile Flow’ Domain Datatypes

Datatype: gtpPerFlowMetrics

The gtpPerFlowMetrics datatype consists of the following fields:

Datatype: mobileFlowFields

The mobileFlowFields datatype consists of the following fields:

Field

Type

Required?

Description

mobileFlowFieldsVersion

number

Yes

Version of the mobileFlowFields block (currently: 2.0)

additionalFields

field [ ]

No

Additional mobileFlow fields if needed

applicationType

string

No

Application type inferred

appProtocolType

string

No

Application protocol

appProtocolVersion

string

No

Application version

cid

string

No

Cell Id

connectionType

string

No

Abbreviation referencing a 3GPP reference point e.g., S1-U, S11, etc

ecgi

string

No

Evolved Cell Global Id

flowDirection

string

Yes

Flow direction, indicating if the reporting node is the source of the flow or destination for the flow

gtpPerFlowMetrics

gtpPer FlowMetrics

Yes

Mobility GTP Protocol per flow metrics

gtpProtocolType

string

No

GTP protocol

gtpVersion

string

No

GTP protocol version

httpHeader

string

No

HTTP request header, if the flow connects to a node referenced by HTTP

imei

string

No

IMEI for the subscriber UE used in this flow, if the flow connects to a mobile device

imsi

string

No

IMSI for the subscriber UE used in this flow, if the flow connects to a mobile device

ipProtocolType

string

Yes

IP protocol type e.g., TCP, UDP, RTP…

ipVersion

string

Yes

IP protocol version e.g., IPv4, IPv6

lac

string

No

Location area code

mcc

string

No

Mobile country code

mnc

string

No

Mobile network code

msisdn

string

No

MSISDN for the subscriber UE used in this flow, as an integer, if the flow connects to a mobile device

otherEndpointIpAddress

string

Yes

IP address for the other endpoint, as used for the flow being reported on

otherEndpointPort

integer

Yes

IP Port for the reporting entity, as used for the flow being reported on

otherFunctionalRole

string

No

Functional role of the other endpoint for the flow being reported on e.g., MME, S-GW, P-GW, PCRF…

rac

string

No

Routing area code

radioAccessTechnology

string

No

Radio Access Technology e.g., 2G, 3G, LTE

reportingEndpointIpAddr

string

Yes

IP address for the reporting entity, as used for the flow being reported on

reportingEndpointPort

integer

Yes

IP port for the reporting entity, as used for the flow being reported on

sac

string

No

Service area code

samplingAlgorithm

integer

No

Integer identifier for the sampling algorithm or rule being applied in calculating the flow metrics if metrics are calculated based on a sample of packets, or 0 if no sampling is applied

tac

string

No

Transport area code

tunnelId

string

No

Tunnel identifier

vlanId

string

No

VLAN identifier used by this flow

‘SipSignaling’Domain Datatypes

Datatype: sipSignalingFields

The sipSignalingFields datatype communicates information about sip signaling messages, parameters and signaling state; it consists of the following fields:

Field

Type

Required?

Description

sipSignalingFieldsVersion

number

Yes

Version of the sipSignalingFields block (currently: 1.0)

additionalInformation

field [ ]

No

Additional sipSignaling fields

compressedSip

string

No

The full SIP request/response including headers and bodies

correlator

string

Yes

Constant across all events on this call

localIpAddress

string

Yes

IP address on VNF

localPort

string

Yes

Port on VNF

remoteIpAddress

string

Yes

IP address of peer endpoint

remotePort

string

Yes

Port of peer endpoint

summarySip

string

No

The SIP Method or Response (‘INVITE’, ‘200 OK’, ‘BYE’, etc)

vendorVnfNameFields

vendorVnfNameFields

Yes

Vendor, VNF and VfModule names

‘Voice Quality’Domain Datatypes

Datatype: endOfCallVqmSummaries

The endOfCallVqmSummaries datatype provides end of call voice quality metrics; it consists of the following fields:

Field

Type

Required?

Description

adjacencyName

string

Yes

Adjacency name

endpointDescription

string

Yes

Enumeration: ‘Caller’, ‘Callee’

endpointJitter

number

No

Endpoint jitter

endpointRtpOctetsDiscarded

number

No

Endpoint RTP octets discarded

endpointRtpOctetsReceived

number

No

Endpoint RTP octets received

endpointRtpOctetsSent

number

No

Endpoint RTP octets sent

endpointRtpPacketsDiscarded

number

No

Endpoint RTP packets discarded

endpointRtpPacketsReceived

number

No

Endpoint RTP packets received

endpointRtpPacketsSent

number

No

Endpoint RTP packets sent

localJitter

number

No

Local jitter

localRtpOctetsDiscarded

number

No

Local RTP octets discarded

localRtpOctetsReceived

number

No

Local RTP octets received

localRtpOctetsSent

number

No

Local RTP octets sent

localRtpPacketsDiscarded

number

No

Local RTP packets discarded

localRtpPacketsReceived

number

No

Local RTP packets received

localRtpPacketsSent

number

No

Local RTP packets sent

mosCqe

number

No

Decimal range from 1 to 5 (1 decimal place)

packetsLost

number

No

Packets lost

packetLossPercent

number

No

Calculated percentage packet loss based on endpoint RTP packets lost (as reported in RTCP) and local RTP packets sent. Direction is based on endpoint description (Caller, Callee). Decimal (2 decimal places)

rFactor

number

No

rFactor from 0 to 100

roundTripDelay

number

No

Round trip delay in milliseconds

Datatype: voiceQualityFields

The voiceQualityFields datatype provides statistics related to customer facing voice products; consists of the following fields:

Field

Type

Required?

Description

voiceQualityFieldsVersion

number

Yes

Version of the voiceQualityFields block (currently: 1.0)

additionalInformation

field [ ]

No

Additional voice quality fields

calleeSideCodec

string

Yes

Callee codec for the call

callerSideCodec

string

Yes

Caller codec for the call

correlator

string

Yes

Constant across all events on this call

endOfCallVqmSummaries

endOfCallVqm Summaries

No

End of call voice quality metric summaries

phoneNumber

string

No

Phone number associated with the correlator

midCallRtcp

string

Yes

Base64 encoding of the binary RTCP data (excluding Eth/IP/UDP headers)

vendorVnfNameFields

vendorVnfNameFields

Yes

Vendor, VNF and VfModule names

RESTful Web Services Exceptions

RESTful services generate and send exceptions to clients in response to invocation errors. Exceptions send HTTP status codes (specified later in this document for each operation). HTTP status codes may be followed by an optional JSON exception structure described below. Two types of exceptions may be defined: service exceptions and policy exceptions.

Field Name

Data Type

Required?

Description

messageId

xs:string

Yes

Unique message identifier of the format ‘ABCnnnn’where ‘ABC’is either ‘SVC’for Service Exceptions or ‘POL’for Policy Exception.

Exception numbers may be in the range of 0001 to 9999 where :

text

xs:string

Yes

Message text, with replacement variables marked with %n, where n is an index into the list of <variables> elements, starting at 1

variables

xs:string [0..unbounded]

No

List of zero or more strings that represent the contents of the variables used by the message text.

url

xs:anyUrl

No

Hyperlink to a detailed error resource (e.g., an HTML page for browser user agents).

Service Exceptions

When a service is not able to process a request, and retrying the request with the same information will also result in a failure, and the issue is not related to a service policy issue, then the service will issue a fault using the service exception fault message. Examples of service exceptions include invalid input, lack of availability of a required resource or a processing error.

A service exception uses the letters ‘SVC’ at the beginning of the message identifier. ‘SVC’service exceptions used by the VES Event Listener API are defined below.

MessageId

Description / Comment

Text

Variables

Parent HTTP Code

SVC0001

General service error (see SVC2000)

<custom error message>

None

400

SVC0002

Bad parameter

Invalid input value for message part %1

%1: message part

400

SVC1000

No server resources

No server resources available to process the request

None

500

SVC2000

More elaborate version of SVC0001

The following service error occurred: %1. Error code is %2.

%1: human readable description of the error

%2: error code

400

Table - Service Exceptions

Policy Exceptions

When a service is not able to complete because the request fails to meet a policy criteria, then the service will issue a fault using the policy exception fault message. To clarify how a policy exception differs from a service exception, consider that all the input to an operation may be valid as meeting the required input for the operation (thus no service exception), but using that input in the execution of the service may result in conditions that require the service not to complete. Examples of policy exceptions include privacy violations, requests not permitted under a governing service agreement or input content not acceptable to the service provider.

A Policy Exception uses the letters ‘POL’ at the beginning of the message identifier. ‘POL’policy exceptions used by the VES Event Listener API are defined below.

MessageId

Description / Comment

Text

Variables

Parent HTTP Code

POL0001

General policy error (see POL2000)

A policy error occurred.

None

401

POL1009

User not provisioned for service

User has not been provisioned for service

None

401

POL1010

User suspended from service

User has been suspended from service

None

401

POL2000

More elaborate version of POL0001

The following policy error occurred: %1. Error code is %2.

%1: human readable description of the error

%2: error code

401

POL9003

Message size exceeds limit

Message content size exceeds the allowable limit

None

400

Table - Policy Exceptions

REST Operation Overview

REST Operation Summary

Operation Action

HTTP

Verb

Resource URL relative to {ServerRoot}, which is defined in section 3

publishAnyEvent

POST

/eventListener/v{apiVersion}

publishEventBatch

POST

/eventListener/v{apiVersion}/eventBatch

Table - REST Operation Summary

API Version

apiVersion is used to describe the major version number of the event listener API (which is the same as the major version number of this specification). When this number changes, the implication is: clients of older versions will break in some way, if they try to use the new API without modification (e.g., unmodified v1 clients would not be able to use v2 without error).

Buffering of Events

{ServerRoot} is defined in section 3 of this document, which defines the REST resource URL. One or more FQDNs may be provisioned in an event source when it is instantiated or updated. If an event source is unable to reach any of the provisioned FQDNs, it should buffer the event data specified below, up to a maximum of 1 hour, until a connection can be established and the events can be successfully delivered to the VES Event Listener service.

During such an outage, only the following events should be buffered:

  • Faults with eventSeverity of “MINOR”, “MAJOR” or “CRITICAL”

  • Syslogs with syslogSev of 0-5

  • All MeasurementsForVfScaling events

VNFs acting as event sources should not send syslog events to the VES Event Listener during debug mode (which is controlled via the Netconf management interface), but should store syslog events locally for access, and possible FTP transfer, via the VNF console (e.g., command line interface).

If the internal event source event buffer or local storage should overflow, then the event source should send a Fault event, and should discard events in a first-in, first-out (FIFO) manner (i.e., discard oldest events first).

Operation: publishAnyEvent

Functional Behavior

Allows authorized clients to publish any single event to the VES event listener.

  • Supports only secure HTTPS (one way SSL) access.

  • Uses the HTTP verb POST

  • Supports JSON content types

  • Provides HTTP response codes as well as Service and Policy error messages

Call Flow

image1

Figure 2 - publishAnyEvent Call Flow

Input Parameters

Header Fields (note: all parameter names shall be treated as case-insensitive):

Parameter

Data Type

Required?

Brief description

Accept

string

No

Determines the format of the body of the response. Valid values are:

  • application/json

Authorization

string

Yes

The username and password are formed into one string as “username:password”. This string is then Base64 encoded to produce the encoded credential which is communicated in the header after the string “Authorization: Basic “. See examples below. If the Authorization header is missing, then an HTTP 400 Invalid Request message shall be returned. If the string supplied is invalid, then an HTTP 401 Unauthorized message shall be returned.

Content-length

integer

No

Note that content length is limited to 1Megabyte.

Content-type

string

Yes

Must be set to one of the following values:

  • application/json

Body Fields:

Parameter

Data Type

Required?

Brief description

Event

event

Yes

Contains the JSON structure of the common event format.

Output Parameters

Header fields:

Parameter

Data Type

Required?

Brief description

Content-length

integer

No

Used only in error conditions.

Content-type

string

No

Used only in error conditions

Date

datetime

Yes

Date time of the response in GMT

Body Fields (for success responses): no content is provided and the header fields are not required.

Body Fields (for error Responses):

Parameter

Data Type

Required?

Brief description

requestError

requestError

Yes (for errors)

Used only in error conditions.

HTTP Status Codes

Code

Reason Phrase

Description

202

Accepted

The request has been accepted for processing

400

Bad Request

Many possible reasons not specified by the other codes (e.g., missing required parameters or incorrect format). The response body may include a further exception code and text. HTTP 400 errors may be mapped to SVC0001 (general service error), SVC0002 (bad parameter), SVC2000 (general service error with details) or PO9003 (message content size exceeds the allowable limit).

401

Unauthorized

Authentication failed or was not provided. HTTP 401 errors may be mapped to POL0001 (general policy error) or POL2000 (general policy error with details).

404

Not Found

The server has not found anything matching the Request-URI. No indication is given of whether the condition is temporary or permanent.

405

Method Not Allowed

A request was made of a resource using a request method not supported by that resource (e.g., using PUT on a REST resource that only supports POST).

500

Internal Server Error

The server encountered an internal error or timed out; please retry (general catch-all server-side error).HTTP 500 errors may be mapped to SVC1000 (no server resources).

Sample Request and Response

Sample Request

POST /eventListener/v5 HTTPS/1.1
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
content-type: application/json
content-length: 12345
{
    "event": {
        "commonEventHeader": {
            "version": 3.0,
            "domain": "fault",
            "eventName": Fault\_MobileCallRecording\_PilotNumberPoolExhaustion",
            "eventId": "ab305d54-85b4-a31b-7db2-fb6b9e546015",
            "sequence": 0,
            "priority": "High",
            "reportingEntityId": "cc305d54-75b4-431b-adb2-eb6b9e541234",
            "reportingEntityName": "EricssonOamVf",
            "sourceId": "de305d54-75b4-431b-adb2-eb6b9e546014",
            "sourceName": "scfx0001vm002cap001",
            "nfNamingCode": "scfx",
            "nfcNamingCode": "ssc",
            "startEpochMicrosec": 1413378172000000,
            "lastEpochMicrosec": 1413378172000000
        },
        "faultFields": {
            "faultFieldsVersion": 2.0,
            "alarmCondition": "PilotNumberPoolExhaustion",
            "eventSourceType": "other",
            "specificProblem": "Calls cannot complete - pilot numbers are unavailable",
            "eventSeverity": "CRITICAL",
            "vfStatus": "Active",
            "alarmAdditionalInformation": [
                {
                "name": "PilotNumberPoolSize",
                "value": "1000"
                }
            ]
        }
    }
}

Sample Success Response #1

HTTPS/1.1 202 Accepted

Sample Policy Exception

HTTPS/1.1 400 Bad Request
content-type: application/json
content-length: 12345
Date: Thu, 04 Jun 2009 02:51:59 GMT
{
    "requestError": {
        "policyException": {
            "messageId": "POL9003",
            "text": "Message content size exceeds the allowable limit",
        }
    }
}
HTTPS/1.1 400 Bad Request
content-type: application/json
content-length: 12345
Date: Thu, 04 Jun 2009 02:51:59 GMT
{
    "requestError": {
        "serviceException": {
            "messageId": "SVC2000",
            "text": "Missing Parameter: %1. Error code is %2"
            "variables": [
                "severity",
                "400"
            ]
        }
    }
}

Operation: publishEventBatch

Functional Behavior

Allows authorized clients to publish any single event to the VES event listener.

  • Supports only secure HTTPS (one way SSL) access.

  • Uses the HTTP verb POST

  • Supports JSON content types

  • Provides HTTP response codes as well as Service and Policy error messages

Call Flow

image2

Figure 3 publishEventBatch Call Flow

Input Parameters

Header Fields (note: all parameter names shall be treated as case-insensitive):

Parameter

Data Type

Required?

Brief description

Accept

string

No

Determines the format of the body of the response. Valid values are:

  • application/json

Authorization

string

Yes

The username and password are formed into one string as “username:password”. This string is then Base64 encoded to produce the encoded credential which is communicated in the header after the string “Authorization: Basic “. See examples below. If the Authorization header is missing, then an HTTP 400 Invalid Request message shall be returned. If the string supplied is invalid, then an HTTP 401 Unauthorized message shall be returned.

Content-length

integer

No

Note that content length is limited to 1Megabyte.

Content-type

string

Yes

Must be set to one of the following values:

  • application/json

Body Fields:

Parameter

Data Type

Required?

Brief description

eventList

eventList

Yes

Array of events conforming to the common event format.

Output Parameters

Header fields:

Parameter

Data Type

Required?

Brief description

Content-length

integer

No

Used only in error conditions.

Content-type

string

No

Used only in error conditions

Date

datetime

Yes

Date time of the response in GMT

Body Fields (for success responses): no content is provided and the header fields are not required.

Body Fields (for error Responses):

Parameter

Data Type

Required?

Brief description

requestError

requestError

Yes (for errors)

Used only in error conditions.

HTTP Status Codes

Code

Reason Phrase

Description

202

Accepted

The request has been accepted for processing

400

Bad Request

Many possible reasons not specified by the other codes (e.g., missing required parameters or incorrect format). The response body may include a further exception code and text. HTTP 400 errors may be mapped to SVC0001 (general service error), SVC0002 (bad parameter), SVC2000 (general service error with details) or PO9003 (message content size exceeds the allowable limit).

401

Unauthorized

Authentication failed or was not provided. HTTP 401 errors may be mapped to POL0001 (general policy error) or POL2000 (general policy error with details).

404

Not Found

The server has not found anything matching the Request-URI. No indication is given of whether the condition is temporary or permanent.

405

Method Not Allowed

A request was made of a resource using a request method not supported by that resource (e.g., using PUT on a REST resource that only supports POST).

500

Internal Server Error

The server encountered an internal error or timed out; please retry (general catch-all server-side error).HTTP 500 errors may be mapped to SVC1000 (no server resources).

Sample Request and Response

Sample Request

POST /eventListener/v5/eventBatch HTTPS/1.1
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
content-type: application/json
content-length: 12345
{
    "eventList": [
    {
        "commonEventHeader": {
            "version": 3.0,
            "domain": "fault",
            "eventName": "Fault\_MobileCallRecording\_PilotNumberPoolExhaustion",
            "eventId": "ab305d54-85b4-a31b-7db2-fb6b9e546015",
            "sequence": 0,
            "priority": "High",
            "reportingEntityId": "cc305d54-75b4-431b-adb2-eb6b9e541234",
            "reportingEntityName": "EricssonOamVf",
            "sourceId": "de305d54-75b4-431b-adb2-eb6b9e546014",
            "sourceName": "scfx0001vm002cap001",
            "nfNamingCode": "scfx",
            "nfcNamingCode": "ssc",
            "startEpochMicrosec": 1413378172000000,
            "lastEpochMicrosec": 1413378172000000
        },
        "faultFields": {
            "faultFieldsVersion": 2.0,
            "alarmCondition": "PilotNumberPoolExhaustion",
            "eventSourceType": "other",
            "specificProblem": "Calls cannot complete - pilot numbers are unavailable",
            "eventSeverity": "CRITICAL",
            "vfStatus": "Active",
            "alarmAdditionalInformation": [
                {
                    "name": "PilotNumberPoolSize",
                    "value": "1000"
                }
            ]
        }
    },
    {
        "commonEventHeader": {
            "version": 3.0,
            "domain": "fault",
            "eventName": "Fault\_MobileCallRecording\_RecordingServerUnreachable",
            "eventId": "ab305d54-85b4-a31b-7db2-fb6b9e546025",
            "sequence": 0,
            "priority": "High",
            "reportingEntityId": "cc305d54-75b4-431b-adb2-eb6b9e541234",
            "reportingEntityName": "EricssonOamVf",
            "sourceId": "de305d54-75b4-431b-adb2-eb6b9e546014",
            "sourceName": "scfx0001vm002cap001",
            "nfNamingCode": "scfx",
            "nfcNamingCode": "ssc",
            "startEpochMicrosec": 1413378172000010,
            "lastEpochMicrosec": 1413378172000010
        },
        "faultFields": {
            "faultFieldsVersion": 2.0,
            "alarmCondition": "RecordingServerUnreachable",
            "eventSourceType": "other",
            "specificProblem": "Recording server unreachable",
            "eventSeverity": "CRITICAL",
            "vfStatus": "Active"
        }
    }
    ]

}

Sample Success Response #1

HTTPS/1.1 202 Accepted

Sample Policy Exception

  HTTPS/1.1 400 Bad Request
  content-type: application/json
  content-length: 12345
  Date: Thu, 04 Jun 2009 02:51:59 GMT
  {
      "requestError": {
          "policyException": {
              "messageId": "POL9003",
              "text": "Message content size exceeds the allowable limit",
          }
      }
}
HTTPS/1.1 400 Bad Request
content-type: application/json
content-length: 12345
Date: Thu, 04 Jun 2009 02:51:59 GMT
{
    "requestError": {
    "serviceException": {
        "messageId": "SVC2000",
        "text": "Missing Parameter: %1. Error code is %2"
        "variables": [
            "severity",
            "400"
        ]
        }
    }
}

Service: VES Event Listener 7.2.1

Legal Disclaimer

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.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.

Document

VES Event Listener

Revision

7.2.1

Revision Date

January 16th, 2021

Author

Trevor Lovett

Contributors:

Min Chen – AT&T

Fred Delaplace - AT&T

Andrew Egan – AT&T

Alok Gupta – AT&T

Marge Hillis – Nokia

Gerard Hynes – AT&T

Ken Kelly – AT&T

Damian Nowak - Nokia

Mark Scott – Ericsson

Tim Verall – Intel

Sumit Verdi – VMWare

Trevor Lovett – AT&T

Rich Erickson – AT&T

Table of Contents

Introduction

This document describes the RESTful interface for the VES Event Listener. The VES acronym originally stood for Virtual-function Event Streaming, but VES has been generalized to support network-function event streaming, whether virtualized or not. The VES Event Listener is capable of receiving any event sent in the VES Common Event Format. In the VES Common Event Format, an event consists of a required Common Event Header (i.e., object) accompanied by zero or more event domain blocks.

It should be understood that events are well structured packages of information, identified by an eventName, which are asynchronously communicated to subscribers who are interested in the eventName. Events can convey measurements, faults, syslogs, threshold crossing alerts and other types of information. Events are simply a way of communicating well-structured packages of information to one or more instances of an VES Event Listener service.

This document describes a RESTful, connectionless, push event listener that can receive single events or batches of events in the Common Event Format.

Versioning

Three types of version numbers supported by this specification:

  • The API specification itself is versioned. Going forward, the major number of the specification version will be incremented whenever any change could break an existing client (e.g., a field name is deleted or changed). All other changes to the spec (e.g., a field name is added, or text changes are made to the specification itself) will increment only the minor number or patch number. Note that the major number appears in REST resource URLs as v# (where ‘#’ is the major number). Minor and patch numbers are communicated in HTTP headers. For more information, see the API Versioning writeup in section 6.1.

  • The JSON schema is versioned. Going forward, the major number of the JSON schema will be incremented whenever any change could break an existing client (e.g., a field name is deleted or changed). All other changes to the schema (e.g., a field name is added or text changes are made to the field descriptions) will increment only the minor number or patch number.

  • The field blocks are versioned. Field blocks include the commonEventHeader and the domain blocks (e.g., the faultFields block). Going forward, the major number of each field block will be incremented whenever any change to that block could break an existing client (e.g., a field name is deleted or changed). All other changes to that block (e.g., a field name is added or text changes are made to the field descriptions) will increment only the minor number.

Client Requirements

Any NF or client library that is responsible for delivering VES events to a VES Event Listener must comply with this specification to ensure events are received, accepted, and processed properly.

Because the VES specification relies on clients to push events to the VES Event Listener, the client assumes certain responsibilities such as:

  • Providing configuration options supporting integration into a Service Provider environment

  • Ensuring reliable delivery of events

  • Customization of default behaviors based on Service Provider needs

While the documentation of these expectations are beyond the Event Listener specification, these requirements are documented in the ONAP VNF Requirements for VES Monitoring Requirements.

Compatibility with ONAP

Unless otherwise stated, this version of the Event Listener specification is compatible with the release of ONAP the specification is released under. In other words, if the specification is released under the Guilin ONAP release, then the VES Event Listeners provided by DCAE will also be compatible with this specification.

Support for Protocols Other Than HTTPS

This API specification describes an HTTPS RESTful interface using the JSON content-type.

Alternative API specifications may be provided in future using Google Protocol Buffers, WebSockets, or Apache Avro.

Field Block Versions

A summary of the latest field block version enums as of this version of the API spec is provided below:

  • commonEventHeader version 4.1 (note: the enum with support 4.0, 4.0.1, 4.1 to avoid breaking clients of earlier versions of major version 4)

  • commonEventHeader vesEventListenerVersion enum: 7.2.1 (note: the enum will support 7.0, 7.0.1, 7.1, 7.1.1, 7.2, 7.2.1 to avoid breaking clients of earlier versions of major version 7)

  • faultFieldsVersion:4.0

  • heartbeatFieldsVersion: 3.0

  • measurementFieldsVersion: 4.0

  • mobileFlowFieldsVersion: 4.0

  • notificationFieldsVersion: 2.0

  • otherFieldsVersion: 3.0

  • perf3gppFieldsVersion: 1.0

  • pnfRegistrationFieldsVersion: 2.1 (note: the enum supports 2.0 and 2.1, to avoid breaking clients of earlier versions of major version 2)

  • sigSignalingFieldsVersion: 3.0

  • stateChangeFieldsVersion: 4.0

  • stndDefinedFieldsVersion: 1.0

  • syslogFieldsVersion: 4.0

  • thresholdCrossingFieldsVersion: 4.0

  • voiceQualityFieldsVersion: 4.0

Common Event Format

A JSON schema describing the Common Event Format is provided below and is reproduced in the tables that follow.

JSON

Note on optional fields:

If the event publisher collects a field that is identified as optional in the data structures below, then the event publisher must send that field.

Note on extensible fields:

VES contains various extensible structures (e.g., hashMap) that enable event publishers to send information that has not been explicitly defined in VES data structures.

  • Event publishers must not send information through extensible structures where VES has explicitly defined fields for that information. For example, event publishers must not send information like cpuIdle, through an extensible structure, because VES has explicitly defined a cpuUsage.cpuIdle field for the communication of that information.

  • Keys sent through extensible fields should use camel casing to separate words and acronyms; only the first letter of each acronym shall be capitalized.

Common Event Datatypes
Datatype: arrayOfJsonObject

The arrayOfJsonObject datatype provides an array of json objects, each of which is describ ed by name, schema and other meta-information. It consists of the following fields:

Field

Type

Required?

Description

arrayOfJsonObject

jsonObject [ ]

Yes

Array of jsonObject

Datatype: arrayOfNamedHashMap

The arrayOfNamedHashMap datatype provides an array of hashMaps, each of which is associated with a descriptive name. It consists of the following fields:

Field

Type

Required?

Description

arrayOfNamedHashMap

namedHashMap [ ]

Yes

Array of namedHashMap

Datatype: event

The event datatype consists of the following fields which constitute the ‘root level’ of the common event format:

Field

Type

Required?

Description

commonEventHeader

commonEventHeader

Yes

Fields common to all events

faultFields

faultFields

No

Fields specific to fault events

heartbeatFields

heartbeatFields

No

Fields specific to heartbeat events

measurementFields

measurementFields

No

Fields specific to measurement events

mobileFlowFields

mobileFlowFields

No

Fields specific to mobility flow events

notificationFields

notificationFields

No

Fields specific to notification events

otherFields

otherFields

No

Fields specific to other types of events

perf3gppFields

perf3gppFields

No

Fields specific to perf3gpp events

pnfRegistrationFields

pnfRegistrationFields

No

Fields specific to pnfRegistration events

sipSignalingFields

sipSignalingFields

No

Fields specific to sipSignaling events

stateChangeFields

stateChangeFields

No

Fields specific to state change events

stndDefinedFields

stndDefinedFields

No

Fields specific to standards defined events

syslogFields

syslogFields

No

Fields specific to syslog events

thresholdCrossingAlertFields

thresholdCrossingAlertFields

No

Fields specific to threshold crossing alert events

voiceQualityFields

voiceQualityFields

No

Fields specific to voiceQuality events

Datatype: eventList

The eventList datatype consists of the following fields:

Field

Type

Required?

Description

eventList

event [ ]

Yes

Array of events

Datatype: hashMap

The hashMap datatype is an ‘associative array’, which is an unordered collection of key-value pairs of the form “key”: “value”, where each key and value are strings. Keys should use camel casing to separate words and acronyms; only the first letter of each acronym should be capitalized.

Datatype: jsonObject

The jsonObject datatype provides a json object schema, name and other meta-information along with one or more object instances that conform to the schema:

Field

Type

Required?

Description

objectInstances

JsonObjectInstance [ ]

Yes

Contains one or more instances of the json object

objectName

string

Yes

Name of the json object

objectSchema

string

No

json schema for the object

objectSchemaUrl

string

No

URL to the json schema for the object

nfSubscribedObjectName

string

No

Name of the object associated with the nfSubscriptionId

nfSubscriptionId

string

No

Identifies an openConfig telemetry subscription on a network function, which configures the network function to send complex object data associated with the jsonObject

Datatype: jsonObjectInstance

The jsonObjectInstance datatype provides meta-information about an instance of a jsonObject along with the actual object instance:

Field

Type

Required?

Description

jsonObject

jsonObject

No

Optional recursive specification of jsonObject

objectInstance

object

No

Contains an instance conforming to the jsonObject schema

objectInstanceEpochMicrosec

number

No

the unix time, aka epoch time, associated with this objectInstance–as microseconds elapsed since 1 Jan 1970 not including leap seconds

objectKeys

key [ ]

No

An ordered set of keys that identifies this particular instance of jsonObject (e.g., that places it in a hierarchy)

Datatype: key

The key datatype is a tuple which provides the name of a key along with its value and relative order; it consists of the following fields:

Field

Type

Required?

Description

keyName

string

Yes

Name of the key

keyOrder

Integer

No

Relative sequence or order of the key (with respect to other keys)

keyValue

string

No

Value of the key

Datatype: namedHashMap

The namedHashMap datatype is a hashMap which is associated with and described by a name; it consists of the following fields:

Field

Type

Required?

Description

name

string

Yes

Name associated with or describing the hashmap

hashMap

hashMap

Yes

One or more key:value pairs

Datatype: requestError

The requestError datatype defines the standard request error data structure:

Field

Type

Required?

Description

messageId

string

Yes

Unique message identifier of the format ‘ABCnnnn’ where ‘ABC’ is either ‘SVC’ for Service Exceptions or ‘POL’ for Policy Exception. Exception numbers may be in the range of 0001 to 9999 where 0001 to 2999 are defined by OMA (see section 5.1) and 3000-9999 are available and undefined.

text

string

Yes

Message text, with replacement variables marked with %n, where n is an index into the list of <variables> elements, starting at 1

url

string

No

Hyperlink to a detailed error resource e.g., an HTML page for browser user agents

variables

string

No

List of zero or more strings that represent the contents of the variables used by the message text

Datatype: vendorNfNameFields

The vendorNfNameFields provides vendor, nf and nfModule identifying information:

Field

Type

Required?

Description

vendorName

string

Yes

Network function vendor name

nfModuleName

string

No

Name of the nfModule generating the event

nfName

string

No

Name of the network function generating the event

Common Event Header Data Types
Datatype: commonEventHeader

The commonEventHeader datatype consists of the following fields common to all events:

Field

Type

Required?

Description

domain

string

Yes

Event domain enumeration: ‘fault’, ‘heartbeat’, ‘measurement’, ‘mobileFlow’ , ‘notification’, ‘other’, ‘perf3gpp’, ‘pnfRegistration’, ‘sipSignaling’, ‘stateChange’,‘stndDefined’, ‘syslog’, ‘thresholdCrossingAlert’, ‘voiceQuality’

eventId

string

Yes

Event key that is unique to the event source. The key must be unique within notification life cycle similar to EventID from 3GPP. It could be a sequential number, or a composite key formed from the event fields, such as domain_sequence. The eventId should not include whitespace. For fault events, eventId is the eventId of the initial alarm; if the same alarm is raised again for changed, acknowledged or cleared cases, eventId must be the same as the initial alarm (along with the same startEpochMicrosec but with a different sequence number). See EventId Use Cases Examples for additional guidance on eventId usage.

eventName

string

Yes

See Best Practices for eventName for additional information on naming events

eventType

string

No

internalHeader Fields

internalHeader Fields

No

Fields (not supplied by event sources) that the VES Event Listener service can use to enrich the event if needed for efficient internal processing. This is an empty object which is intended to be defined separately by each service provider (e.g., AT&T) implementing the VES Event Listener.

lastEpochMicrosec

number

Yes

the latest unix time aka epoch time associated with the event from any component–as microseconds elapsed since 1 Jan 1970 not including leap seconds

nfcNamingCode

string

No

Network function component type: 3 characters (aligned with vfc naming standards)

nfNamingCode

string

No

Network function type: 4 characters (aligned with vnf and pnf naming standards)

nfVendorName

string

No

priority

string

Yes

reportingEntityId

string

No

UUID identifying the entity reporting the event or detecting a problem in another vnf/vm or pnf which is experiencing the problem. (Note: the AT&T internal enrichment process shall ensure that this field is populated). The reportingEntityId is an id for the reportingEntityName. See ‘reportingEntityName’ for more information.

reportingEntityName

string

Yes

Name of the entity reporting the event or detecting a problem in another vnf/vm or pnf which is experiencing the problem. May be the same as the sourceName. For synthetic events generated by DCAE, it is the name of the app generating the event.

sequence

integer

Yes

Ordering of events communicated by an event source instance (or 0 if not needed)

sourceId

string

No

UUID identifying the entity experiencing the event issue, which may be detected and reported by a separate reporting entity (note: the AT&T internal enrichment process shall ensure that this field is populated). The sourceId is an id for the sourceName. See ‘sourceName’ for more information.

sourceName

string

Yes

Name of the entity experiencing the event issue, which may be detected and reported by a separate reporting entity. The sourceName identifies the device for which data is collected. A valid sourceName must be inventoried in A&AI. If sourceName is a xNF (vnf or pnf), xNFC or VM, then the event must be reporting data for that particular xNF, xNFC or VM. If the sourceName is a xNF, comprised of multiple xNFCs, the data must be reported/aggregated at the xNF level. Data for individual xNFC must not be included in the xNF sourceName event.

startEpochMicrosec

number

Yes

the earliest unix time aka epoch time associated with the event from any component–as microseconds elapsed since 1 Jan 1970 not including leap seconds. For measurements and heartbeats, where events are collected over predefined intervals, startEpochMicrosec shall be rounded to the nearest interval boundary (e.g., the epoch equivalent of 3:00PM, 3:10PM, 3:20PM, etc…). For fault events, startEpochMicrosec is the timestamp of the initial alarm; if the same alarm is raised again for changed, acknowledged or cleared cases, startEpoch Microsec must be the same as the initial alarm (along with the same eventId and an incremental sequence number). For devices with no timing source (clock), the default value will be 0 and the VES collector will replace it with Collector time stamp (when the event is received)

stndDefinedNamespace

string

No

Standards-organization defined event namespace; expected usage includes event routing by the event listener

timeZoneOffset

string

No

Offset to GMT to indicate local time zone for device formatted as ‘UTC+/-hh:mm’; see time_zone_abbreviations for UTC offset examples

version

string

Yes

Version of the event header as “#.#” where # is a digit; see section 1 for the correct digits to use.

vesEventListenerVersion

string

Yes

Version of the ves event listener api spec that this event is compliant with (as “#” or “#.#” or “#.#.#” where # is a digit; see section 1 for the correct digits to use).

Datatype: internalHeaderFields

The internalHeaderFields datatype is an undefined object which can contain arbitrarily complex JSON structures. It is intended to be defined separately by each service provider (e.g., AT&T) implementing the VES Event Listener. The fields in internalHeaderFields are not provided by any event source but instead are added by the VES Event Listener service itself as part of an event enrichment process necessary for efficient internal processing of events received by the VES Event Listener.

Best Practices for eventName

To prevent naming collisions, eventNames sent as part of the commonEventHeader, should conform to the following naming convention designed to summarize the purpose and type of the event, and to ensure the uniqueness of the eventName:

{DomainAbbreviation}_{PublisherName}_{Description}

Each underscore-separated subfield above should start with a capital letter and use camel-casing to separate words and acronyms. Acronyms should capitalize only the first letter of the acronym. Spaces and underscores should not appear within any subfield.

The DomainAbbreviation subfield derives from the ‘domain’ field in the commonEventHeader, as specified below:

  • ‘Fault’ for the fault domain

  • ‘Heartbeat’ for the heartbeat domain

  • ‘Measurement’ for the measurement domain

  • ‘MobileFlow’ for the mobileFlow domain

  • ‘Notification’ for the notification domain

  • ‘Other’ for the other domain

  • ‘Perf3gpp’ for the perf3gpp domain

  • ‘PnfReg’ for the pnfRegistration domain

  • ‘SipSignaling’ for the sipSignaling domain

  • ‘StateChange’ for the stateChange domain

  • ‘StndDefined’ for the stndDefined domain

  • ‘Syslog’ for the syslog domain

  • ‘Tca’ for the thresholdCrossingAlert domain

  • ‘VoiceQuality’ for the voiceQuality domain

The PublisherName subfield describes the vendor product or application publishing the event. This subfield conforms to the following conventions:

  • Vendor products are specified as: {productName}-{vendorName}

    For example: Visbc-Metaswitch or Vdbe-Juniper, where a hyphen is used to separate the productName and vendorName subfields. Note that the productName and vendorName subfields must not include hyphens themselves.

    Organizing the information in this way will cause an alphabetical listing of eventNames to sort similar network functions together, rather than to sort them by vendor.

    The productName subfield may describe a NF or a NFC. Where NFC names may be reused across different NF’s, they should be specified as:

    {NfName}:{NfcName}

    where a colon is used to separate the NfName and NfcName subfields. Note that the NfName and NfcName subfields must not include colons themselves.

    The productName may also describe other types of vendor modules or components such as a VM, application or hostname. As with NFs and NFCs, parent:child relationships may be communicated using colon as a subfield delimiter.

  • Service providers who adopt the VES Common Event Format for internal use, may provide PublisherName without the vendorName subfield. They would typically identify an application, system, service or microservice publishing the event (e.g., ‘Policy’, ‘So’, ‘MobileCallRecording’ or ‘Dkat’). As with NFs and NFCs, parent:child relationships may be communicated using colon as a subfield delimiter (e.g., ApplicationName:ApplicationComponent).

The final subfield of the eventName name should describe, in a compact camel case format the specific information being conveyed by the event. In some cases, this final subfield may not be required (e.g., in the case of certain heartbeats).

Examples of event names following the naming standards are provided below:

  • Tca_Vdbe-Ericsson_CpuThresholdExceeded

  • Heartbeat_Visbc:Mmc-Metaswitch

  • Syslog_Vdbe-Ericsson

  • Fault_MobileCallRecording_PilotNumberPoolExhaustion

  • Other_So:WanBonding_InstantiationPart1Complete

EventId Use Cases Examples

eventId Examples:

NOTE: Please note, the following are only examples, and other formats can be used provided they meet the requirement that the eventId is unique for all events or unique fault occurrence.

Example 1: assumes a unique key for each domain consisting of domain followed by an integer domain<n> or domainId<n>, where <n> is a positive integer, e.g. fault000001, heartbeat000001, measurement000005, notification3gppPerfFileReady0005

Example 2: assumes a unique integer key for all events across all domains <n>: 000000001, 00000002, 000000003

Rules:

  1. All domains except Fault: each time a subsequent event is sent the integer part of eventId will increment by 1. Repeat of eventId assumes duplicate event. Sequence number is set to 0 for all domains except fault.

  2. eventId construction for Fault Events:

    1. Most likely scenario

      • The sourceName on each Fault event is the NF Instance Name (pnf-name or vnf-name or vm-name) as entered in A&AI uniquely identifying this instance of the NF.

      • The eventId on Fault events is the same every time a given fault is raised (including onset and re-raise)

        1. The startEpochMicrosec value for the Fault event is the timestamp for when the fault onset occurs. Subsequent events for the same fault will keep the same startEpochMicrosec value.

        2. lastEpochMicrosec indicates the current event time. This value will be updated for each subsequent event for a given fault.

        3. The sequence number for each Fault event is set to 1 when the fault is raised and increments each time the same fault event is raised, until a clear is sent.

      • After the fault is cleared, a new eventId is used.

    _images/Use-Case-11.png
    1. Alternative Scenario: Network Function When Fault Event Status is Not Maintained.

      • The sourceName on each Fault event is the NF Instance Name (pnf-name or vnf-name or vm-name) as entered in A&AI uniquely identifying this instance of the NF.

      • The eventId on Fault events is the same every time a given fault is raised or cleared, even if it is re-raised after it had previously cleared. So, for example, if EMS loses contact with a particular device then a Fault event might be sent for a raise, re-raise (because EMS has re-tried and still can’t contact the device), clear (because EMS has re-tried and it can contact the device) and then raise again (because EMS has lost contact with the device again). The same eventId is used for all 4 of those Fault events.

      • The startEpochMicrosec value for each Fault event is the timestamp for when that event is generated, not when the fault first occurred. So all 4 of the Fault events in the previous bullet point would have a different timestamp.

      • lastEpochMicrosec indicates the current event time.

      • The sequence number for each Fault event is currently set to 0 on a raise and 1 on a clear. We could change that so that each Fault event is given a new monotonically increasing sequence number whether it is a raise or a clear if that is helpful (which is reset to 0 if the VM restarts) but they won’t be consecutive.

      • Normally, a clear is expected for each fault to be sent from a network function. However a few fault notification types will never be re-raised or cleared. In this case, general rules for VES events shall be followed with a new eventId for each event and sequence number set to 0.

    _images/Use-Case-21.png

Example 3: Exceptions from eventId uniqueness requirement: In certain scenarios such as restarts, the xNF might be unable to assure eventId uniqueness as information about the latest used eventID value might not have been persisted. When such eventId information is unavailable, the xNF should reset the eventID numbering following the EventId Use Cases Examples.

Technology Independent Datatypes
‘Fault’ Domain Datatypes
Datatype: faultFields

The faultFields datatype consists of the following fields:

Field

Type

Required?

Description

alarmAdditional Information

hashMap

No

Additional alarm information.

  • Note1: for SNMP mapping to VES, for hash key use OID of varbind, for value use incoming data for that varbind).

  • Note2: Alarm ID for 3GPP should be included (if applicable) in alarmAdditonalInformation as ‘alarmId’:’alarmIdValue’.

Could contain managed object instance as separate key:value; could add probable cause as separate key:value.

alarmCondition

string

Yes

Short name of the alarm condition/problem, such as a trap name. Should not have white space (e.g., tpLgCgiNotInConfig, BfdSessionDown, linkDown, etc…)

alarmInterfaceA

string

No

Card, port, channel or interface name of the device generating the alarm. This could reflect managed object.

eventCategory

string

No

Event category, for example: ‘license’, ‘link’, ‘routing’, ‘security’, ‘signaling’

eventSeverity

string

Yes

Event severity enumeration: ‘CRITICAL’, ‘MAJOR’, ‘MINOR’, ‘WARNING’, ‘NORMAL’. NORMAL is used to represent clear.

eventSourceType

string

Yes

Examples: ‘card’, ‘host’, ‘other’, ‘port’, ‘portThreshold’, ‘router’, ‘slotThreshold’, ‘switch’, ‘virtualMachine’, ‘virtualNetworkFunction’. This could be managed object class.

faultFieldsVersion

string

Yes

Version of the faultFields block as “#.#” where # is a digit; see section 1 for the correct digits to use.

specificProblem

string

Yes

Description of the alarm or problem (e.g., ‘eNodeB 155197 in PLMN 310-410 with eNodeB name KYL05197 is lost’). 3GPP probable cause would be included in this field.

vfStatus

string

Yes

Virtual function status enumeration: ‘Active’, ‘Idle’, ‘Preparing to terminate’, ‘Ready to terminate’, ‘Requesting Termination’

Heartbeat’ Domain Datatypes
Datatype: heartbeatFields

The heartbeatFields datatype is an optional field block for fields specific to heartbeat events; it consists of the following fields:

Field

Type

Required?

Description

additionalFields

hashMap

No

Additional expansion fields if needed

heartbeatFieldsVersion

string

Yes

Version of the heartbeatFields block as “#.#” where # is a digit; see section 1 for the correct digits to use.

heartbeatInterval

Integer

Yes

Current heartbeatInterval in seconds

‘Measurements’ Domain Datatypes

Note: NFs are required to report exactly one Measurement event per period per sourceName.

Datatype: codecsInUse

The codecsInUse datatype consists of the following fields describing the number of times an identified codec was used over the measurementInterval:

Field

Type

Required?

Description

codecIdentifer

string

Yes

Description of the codec

numberInUse

integer

Yes

Number of such codecs in use

Datatype: cpuUsage

The cpuUsage datatype defines the usage of an identifier CPU and consists of the following fields:

Field

Type

Required?

Description

cpuCapacityContention

number

No

The amount of time the CPU cannot run due to contention, in milliseconds over the measurementInterval

cpuDemandAvg

number

No

The total CPU time that the NF/NFC/VM could use if there was no contention, in milliseconds over the measurementInterval

cpuDemandMhz

number

No

CPU demand in MHz

cpuDemandPct

number

No

CPU demand as a percentage of the provisioned capacity

cpuIdentifier

string

Yes

CPU Identifier

cpuIdle

number

No

Percentage of CPU time spent in the idle task

cpuLatencyAvg

number

No

Percentage of time the VM is unable to run because it is contending for access to the physical CPUs

cpuOverheadAvg

number

No

The overhead demand above available allocations and reservations, in milliseconds over the measurementInterval

cpuSwapWaitTime

number

No

Swap wait time, in milliseconds over the measurementInterval

cpuUsageInterrupt

number

No

Percentage of time spent servicing interrupts

cpuUsageNice

number

No

Percentage of time spent running user space processes that have been niced

cpuUsageSoftIrq

number

No

Percentage of time spent handling soft irq interrupts

cpuUsageSteal

number

No

Percentage of time spent in involuntary wait which is neither user, system or idle time and is effectively time that went missing

cpuUsageSystem

number

No

Percentage of time spent on system tasks running the kernel

cpuUsageUser

number

No

Percentage of time spent running un-niced user space processes

cpuWait

number

No

Percentage of CPU time spent waiting for I/O operations to complete

percentUsage

number

Yes

Aggregate cpu usage of the virtual machine on which the xNFC reporting the event is running

Datatype: diskUsage

The diskUsage datatype defines the usage of a disk and consists of the following fields:

Field

Type

Required?

Description

diskBusResets

number

No

Number of bus resets over the measurementInterval

diskCommandsAborted

number

No

Number of disk commands aborted over the measurementInterval

diskCommandsAvg

number

No

Average number of commands per second over the measurementInterval

diskFlushRequests

number

No

Total flush requests of the disk cache over the measurementInterval

diskFlushTime

number

No

Milliseconds spent on disk cache flushing over the measurementInterval

diskIdentifier

string

Yes

Disk Identifier

diskIoTimeAvg

number

No

Milliseconds spent doing input/output operations over 1 sec; treat this metric as a device load percentage where 1000ms matches 100% load; provide the average over the measurement interval

diskIoTimeLast

number

No

Milliseconds spent doing input/output operations over 1 sec; treat this metric as a device load percentage where 1000ms matches 100% load; provide the last value measurement within the measurement interval

diskIoTimeMax

number

No

Milliseconds spent doing input/output operations over 1 sec; treat this metric as a device load percentage where 1000ms matches 100% load; provide the maximum value measurement within the measurement interval

diskIoTimeMin

number

No

Milliseconds spent doing input/output operations over 1 sec; treat this metric as a device load percentage where 1000ms matches 100% load; provide the minimum value measurement within the measurement interval

diskMergedReadAvg

number

No

Number of logical read operations that were merged into physical read operations, e.g., two logical reads were served by one physical disk access; provide the average measurement within the measurement interval

diskMergedReadLast

number

No

Number of logical read operations that were merged into physical read operations, e.g., two logical reads were served by one physical disk access; provide the last value measurement within the measurement interval

diskMergedReadMax

number

No

Number of logical read operations that were merged into physical read operations, e.g., two logical reads were served by one physical disk access; provide the maximum value measurement within the measurement interval

diskMergedReadMin

number

No

Number of logical read operations that were merged into physical read operations, e.g., two logical reads were served by one physical disk access; provide the minimum value measurement within the measurement interval

diskMergedWriteAvg

number

No

Number of logical write operations that were merged into physical write operations, e.g., two logical writes were served by one physical disk access; provide the average measurement within the measurement interval

diskMergedWriteLast

number

No

Number of logical write operations that were merged into physical write operations, e.g., two logical writes were served by one physical disk access; provide the last value measurement within the measurement interval

diskMergedWriteMax

number

No

Number of logical write operations that were merged into physical write operations, e.g., two logical writes were served by one physical disk access; provide the maximum value measurement within the measurement interval

diskMergedWriteMin

number

No

Number of logical write operations that were merged into physical write operations, e.g., two logical writes were served by one physical disk access; provide the minimum value measurement within the measurement interval

diskOctetsRead Avg

number

No

Number of octets per second read from a disk or partition; provide the average measurement within the measurement interval

diskOctetsRead

Last

number

No

Number of octets per second read from a disk or partition; provide the last measurement within the measurement interval

diskOctetsRead Max

number

No

Number of octets per second read from a disk or partition; provide the maximum measurement within the measurement interval

diskOctetsRead Min

number

No

Number of octets per second read from a disk or partition; provide the minimum measurement within the measurement interval

diskOctetsWrite Avg

number

No

Number of octets per second written to a disk or partition; provide the average measurement within the measurement interval

diskOctetsWrite Last

number

No

Number of octets per second written to a disk or partition; provide the last measurement within the measurement interval

diskOctetsWriteMax

number

No

Number of octets per second written to a disk or partition; provide the maximum measurement within the measurement interval

diskOctetsWriteMin

number

No

Number of octets per second written to a disk or partition; provide the minimum measurement within the measurement interval

diskOpsReadAvg

number

No

Number of read operations per second issued to the disk; provide the average measurement within the measurement interval

diskOpsReadLast

number

No

Number of read operations per second issued to the disk; provide the last measurement within the measurement interval

diskOpsReadMax

number

No

Number of read operations per second issued to the disk; provide the maximum measurement within the measurement interval

diskOpsReadMin

number

No

Number of read operations per second issued to the disk; provide the minimum measurement within the measurement interval

diskOpsWriteAvg

number

No

Number of write operations per second issued to the disk; provide the average measurement within the measurement interval

diskOpsWriteLast

number

No

Number of write operations per second issued to the disk; provide the last measurement within the measurement interval

diskOpsWrite Max

number

No

Number of write operations per second issued to the disk; provide the maximum measurement within the measurement interval

diskOpsWriteMin

number

No

Number of write operations per second issued to the disk; provide the minimum measurement within the measurement interval

diskPendingOperationsAvg

number

No

Queue size of pending I/O operations per second; provide the average measurement within the measurement interval

diskPendingOperationsLast

number

No

Queue size of pending I/O operations per second; provide the last measurement within the measurement interval

diskPendingOperationsMax

number

No

Queue size of pending I/O operations per second; provide the maximum measurement within the measurement interval

diskPendingOperationsMin

number

No

Queue size of pending I/O operations per second; provide the minimum measurement within the measurement interval

diskReadCommandsAvg

number

No

Average number of read commands issued per second to the disk over the measurementInterval

diskTime

number

No

Nanoseconds spent on disk cache reads/writes within the measurement interval

diskTimeReadAvg

number

No

Milliseconds a read operation took to complete; provide the average measurement within the measurement interval

diskTimeRead Last

number

No

Milliseconds a read operation took to complete; provide the last measurement within the measurement interval

diskTimeRead Max

number

No

Milliseconds a read operation took to complete; provide the maximum measurement within the measurement interval

diskTimeRead Min

number

No

Milliseconds a read operation took to complete; provide the minimum measurement within the measurement interval

diskTimeWrite Avg

number

No

Milliseconds a write operation took to complete; provide the average measurement within the measurement interval

diskTimeWrite Last

number

No

Milliseconds a write operation took to complete; provide the last measurement within the measurement interval

diskTimeWrite Max

number

No

Milliseconds a write operation took to complete; provide the maximum measurement within the measurement interval

diskTimeWrite Min

number

No

Milliseconds a write operation took to complete; provide the minimum measurement within the measurement interval

diskTotalReadLatencyAvg

number

No

Average read time from the perspective of a Guest OS: sum of the Kernel Read Latency and Physical Device Read Latency in milliseconds over the measurement interval

diskTotalWriteLatencyAvg

number

No

Average write time from the perspective of a Guest OS: sum of the Kernel Write Latency and Physical Device Write Latency in milliseconds over the measurement interval

diskWeightedIoTimeAvg

number

No

Measure in ms over 1 sec of both I/O completion time and the backlog that may be accumulating. Value is the average within the collection interval.

diskWeightedIoTimeLast

number

No

Measure in ms over 1 sec of both I/O completion time and the backlog that may be accumulating. Value is the last within the collection interval.

diskWeightedIoTimeMax

number

No

Measure in ms over 1 sec of both I/O completion time and the backlog that may be accumulating. Value is the maximum within the collection interval.

diskWeightedIoTimeMin

number

No

Measure in ms over 1 sec of both I/O completion time and the backlog that may be accumulating. Value is the minimum within the collection interval.

diskWriteCommandsAvg

number

No

Average number of write commands issued per second to the disk over the measurementInterval

Datatype: filesystemUsage

The filesystemUsage datatype consists of the following fields:

Field

Type

Required?

Description

filesystemName

string

Yes

File system name

blockConfigured

number

Yes

Configured block storage capacity in GB

blockIops

number

Yes

Block storage input-output operations per second

blockUsed

number

Yes

Used block storage capacity in GB

ephemeralConfigured

number

Yes

Configured ephemeral storage capacity in GB

ephemeralIops

number

Yes

Ephemeral storage input-output operations per second

ephemeralUsed

number

Yes

Used ephemeral storage capacity in GB

Datatype: hugePages

The hugePages datatype provides metrics on system hugePages; it consists of the following fields:

Field

Type

Required?

Description

bytesFree

number

No

Number of free hugePages in bytes

bytesUsed

number

No

Number of used hugePages in bytes

hugePagesIdentifier

string

Yes

HugePages identifier

percentFree

number

No

Number of free hugePages in percent

percentUsed

number

No

Number of used hugePages in percent

vmPageNumberFree

number

No

Number of free vmPages in numbers

vmPageNumberUsed

number

No

Number of used vmPages in numbers

Datatype: ipmi (Intelligent Platform Management Interface)

The ipmi datatype provides intelligent platform management interface metrics; it consists of the following fields:

Field

Type

Required?

Description

exitAirTemperature

number

No

System fan exit air flow temperature in Celsius

frontPanelTemperature

number

No

Front panel temp in Celsius

ioModuleTemperature

number

No

Io module temp in Celsius

ipmiBaseboardTemperatureArray

ipmiBaseboard Temperature [ ]

No

Array of ipmiBaseboard Temperature objects

ipmiBaseboardVoltageRegulator Array

ipmiBaseboard VoltageRegulator [ ]

No

Array of ipmiBaseboard VoltageRegulator objects

ipmiBatteryArray

ipmiBattery [ ]

No

Array of ipmiBattery objects

ipmiFanArray

ipmiFan [ ]

No

Array of ipmiFan objects

ipmiGlobalAggregateTemperatureMarginArray

ipmiGlobalAggregateTemperatureMargin []

No

ipmi global aggregate temperature margin

ipmiHsbpArray

ipmiHsbp [ ]

No

Array of ipmiHsbp objects

ipmiNicArray

ipmiNic [ ]

No

Array of ipmiNic objects

ipmiPowerSupplyArray

ipmiPowerSupply [ ]

No

Array of ipmiPowerSupply objects

ipmiProcessorArray

ipmiProcessor [ ]

No

Array of ipmiProcessor objects

systemAirflow

number

No

Airflow in cubic feet per minute (cfm)

Datatype: ipmiBaseboardTemperature

The ipmiBaseboardTemperature datatype consists of the following fields which describe ipmi baseboard temperature metrics:

Field

Type

Required?

Description

baseboardTemperature

number

No

Baseboard temperature in celsius

baseboardTemperatureIdentifier

string

Yes

Identifier for the location where the temperature is taken

Datatype: ipmiBaseboardVoltageRegulator

The ipmiBaseboardVoltageRegulator datatype consists of the following fields which describe ipmi baseboard voltage regulator metrics:

Field

Type

Required?

Description

baseboardVoltageRegulatorIdentifier

string

Yes

Identifier for the baseboard voltage regulator

voltageRegulatorTemperature

number

No

Voltage regulator temperature in celsius

Datatype: ipmiBattery

The ipmiBattery datatype consists of the following fields which describe ipmi battery metrics:

Field

Type

Required?

Description

batteryIdentifier

string

Yes

Identifier for the battery

batteryType

string

No

Type of battery

batteryVoltageLevel

number

No

Battery voltage level

Datatype: ipmiFan

The ipmiFan datatype consists of the following fields which describe ipmi fan metrics:

Field

Type

Required?

Description

fanIdentifier

string

Yes

Identifier for the fan

fanSpeed

number

No

Fan speed in revolutions per minute (rpm)

Datatype: ipmiGlobalAggregateTemperatureMargin

The ipmiGlobalAggregateTemperatureMargin datatype consists of the following fields:

Field

Type

Required?

Description

globalAggregateTemperatureMargin

number

No

Temperature margin in Celsius relative to a throttling thermal trip point

globalAggregateTemperatureMarginIdentifier

string

Yes

Identifier for the ipmi global aggregate temperature margin metrics

Datatype: ipmiHsbp

The ipmiHsbp datatype provides ipmi hot swap backplane power metrics; it consists of the following fields:

Field

Type

Required?

Description

hsbpIdentifier

string

Yes

Identifier for the hot swap backplane power unit

hsbpTemperature

number

No

Hot swap backplane power temperature in celsius

Datatype: ipmiNic

The ipmiNic datatype provides network interface control care metrics; it consists of the following fields:

Field

Type

Required?

Description

nicIdentifier

string

Yes

Identifier for the network interface control card

nicTemperature

number

No

nic temperature in Celsius

Datatype: ipmiPowerSupply

The ipmiPowerSupply datatype provides ipmi power supply metrics; it consists of the following fields:

Field

Type

Required?

Description

powerSupplyCurrentOutputPercent

number

No

Current output voltage as a percentage of the design specified level

powerSupplyIdentifier

string

Yes

Identifier for the power supply

powerSupplyInputPower

number

No

Input power in watts

powerSupplyTemperature

number

No

Power supply temperature in Celsius

Datatype: ipmiProcessor

The ipmiProcessor datatype provides ipmi processor metrics; it consists of the following fields:

Field

Type

Required?

Description

processorDimmAggregateThermalMarginArray

processorDimm AggregateThermal Margin [ ]

No

Array of processorDimmAggregate ThermalMargin objects

processorDtsThermalMargin

number

No

Front panel temperature in celsius

processorIdentifier

string

Yes

Identifier for the power supply

processorThermalControlPercent

number

No

Io module temperatue in celsius

Datatype: latencyBucketMeasure

The latencyBucketMeasure datatype consists of the following fields which describe the number of counts falling within a defined latency bucket:

Field

Type

Required?

Description

countsInTheBucket

number

Yes

Number of counts falling within a defined latency bucket

highEndOfLatencyBucket

number

No

High end of bucket range (typically in ms)

lowEndOfLatencyBucket

number

No

Low end of bucket range (typically in ms)

Datatype: load

The load datatype provides metrics on system cpu and io utilization obtained using /proc/loadavg; it consists of the following fields:

Field

Type

Required?

Description

longTerm

number

No

number of jobs in the run queue (state R, cpu utilization) or waiting for disk I/O (state D, io utilization) averaged over 15 minutes using /proc/loadavg

midTerm

number

No

number of jobs in the run queue (state R, cpu utilization) or waiting for disk I/O (state D, io utilization) averaged over 5 minutes using /proc/loadavg

shortTerm

number

No

number of jobs in the run queue (state R, cpu utilization) or waiting for disk I/O (state D, io utilization) averaged over 1 minute using /proc/loadavg

Datatype: machineCheckException

The machineCheckException datatype describes machine check exceptions; it consists of the following fields:

Field

Type

Required?

Description

correctedMemoryErrors

number

No

Total hardware errors that were corrected by the hardware (e.g. data corruption corrected via ECC) over the measurementInterval. These errors do not require immediate software actions, but are still reported for accounting and predictive failure analysis

correctedMemoryErrors In1Hr

number

No

Total hardware errors that were corrected by the hardware over the last one hour

uncorrectedMemoryErrors

number

No

Total uncorrected hardware errors that were detected by the hardware (e.g., causing data corruption) over the measurementInterval. These errors require a software response.

uncorrectedMemoryErrors In1Hr

number

No

Total uncorrected hardware errors that were detected by the hardware over the last one hour

vmIdentifier

string

Yes

Virtual machine identifier associated with the machine check exception

Datatype: measurementFields

The measurementFields datatype consists of the following fields:

Field

Type

Required?

Description

additionalFields

hashMap

No

Additional measurement fields if needed

additionalMeasurements

arrayOfNamedHashMap

No

Array of named hashMap if needed

additionalObjects

arrayOfJsonObject

No

Array of JSON objects described by name, schema and other meta-information, if needed

codecUsageArray

codecsInUse []

No

Array of codecs in use

concurrentSessions

integer

No

Peak concurrent sessions for the VM or xNF (depending on the context) over the measurementInterval

configuredEntities

integer

No

Depending on the context over the measurementInterval: peak total number of users, subscribers, devices, adjacencies, etc., for the VM, or peak total number of subscribers, devices, etc., for the xNF

cpuUsageArray

cpuUsage []

No

Usage of an array of CPUs

diskUsageArray

diskUsage []

No

Usage of an array of disks

featureUsageArray

hashMap

No

The hashMap key should identify the feature, while the value defines the number of times the identified feature was used

filesystemUsageArray

filesystemUsage [ ]

No

Filesystem usage of the VM on which the xNFC reporting the event is running

hugePagesArray

hugePages [ ]

No

Array of metrics on hugePages

ipmi

ipmi

No

Intelligent platform management interface metrics

latencyDistribution

latencyBucketMeasure [ ]

No

Array of integers representing counts of requests whose latency in milliseconds falls within per-xNF configured ranges; where latency is the duration between a service request and its fulfillment.

loadArray

load [ ]

No

Array of system load metrics

machineCheckExceptionArray

machineCheckException [ ]

No

Array of machine check exceptions

meanRequestLatency

number

No

Mean seconds required to respond to each request for the VM on which the xNFC reporting the event is running

measurementFieldsVersion

string

Yes

Version of the measurementFields block as “#.#” where # is a digit; see section 1 for the correct digits to use.

measurementInterval

number

Yes

Interval over which measurements are being reported in seconds

memoryUsageArray

memoryUsage []

No

Memory usage of an array of VMs

nfcScalingMetric

integer

No

Represents busy-ness of the network function from 0 to 100 as reported by the nfc

nicPerformanceArray

nicPerformance [ ]

No

Performance metrics of an array of network interface cards

numberOfMediaPortsInUse

integer

No

Number of media ports in use

processStatsArray

processStats [ ]

No

Array of metrics on system processes

requestRate

number

No

Peak rate of service requests per second to the xNF over the measurementInterval

Note on Measurement Expansion Fields

The measurementFields data type provides fields that can be used to pass additional data with the event. These fields are listed below and referred to as expansion fields:

  • additionalFields

  • additionalObjects

  • additionalMeasurements

When expansion fields are used, the goal is to avoid custom development by the service provider collecting the fields, since custom development adds obvious cost, delay and resource overhead. In the domain of measurements, it is expected that a high percentage of use cases for extensible fields can be satisfied by using the additionalMeasurements arrayOfNamedHashMap data structure in combination with a YAML registration file (provided at design time). The YAML registration file conveys metadata about the processing of additionalMeasurements. For more information, please see the VES Event Registration specification and in particular the aggregationRole, castTo, and isHomogeneous keywords.

Datatype: memoryUsage

The memoryUsage datatype defines the memory usage of a virtual machine and consists of the following fields:

Field

Type

Required?

Description

memoryBuffered

number

No

Kibibytes of temporary storage for raw disk blocks

memoryCached

number

No

Kibibytes of memory used for cache

memoryConfigured

number

No

Kibibytes of memory configured in the virtual machine on which the xNFC reporting the event is running

memoryDemand

number

No

Host demand in kibibytes

memoryFree

number

Yes

Kibibytes of physical RAM left unused by the system

memoryLatencyAvg

number

No

Percentage of time the VM is waiting to access swapped or compressed memory

memorySharedAvg

number

No

Shared memory in kilobytes

memorySlabRecl

number

No

The part of the slab that can be reclaimed such as caches measured in kibibytes

memorySlabUnrecl

number

No

The part of the slab that cannot be reclaimed even when lacking memory measure in kibibytes

memorySwapInAvg

number

No

Amount of memory swapped-in from host cache in kibibytes

memorySwapInRateAvg

number

No

Rate at which memory is swapped from disk into active memory during the interval in kilobytes per second

memorySwapOutAvg

number

No

Amount of memory swapped-out to host cache in kibibytes

memorySwapOutRateAvg

number

No

Rate at which memory is being swapped from active memory to disk during the current interval in kilobytes per second

memorySwapUsedAvg

number

No

Space used for caching swapped pages in the host cache in kibibytes

memoryUsed

number

Yes

Total memory minus the sum of free, buffered, cached and slab memory measured in kibibytes

percentMemoryUsage

number

No

Percentage of memory usage; value = (memoryUsed / (memoryUsed + memoryFree) x 100 if denomintor is nonzero, or 0, if otherwise.

vmIdentifier

string

Yes

Virtual Machine identifier associated with the memory metrics

Datatype: nicPerformance

The nicPerformance datatype consists of the following fields which describe the performance and errors of an of an identified virtual network interface card:

Field

Type

Required?

Description

administrativeState

string

No

Administrative state: enum: ‘inService’, ‘outOfService’

nicIdentifier

string

Yes

Network interface card identifier

operationalState

string

No

Operational state: enum: ‘inService’, ‘outOfService’

receivedBroadcastPacketsAccumulated

number

No

Cumulative count of broadcast packets received as read at the end of the measurement interval

receivedBroadcastPacketsDelta

number

No

Count of broadcast packets received within the measurement interval

receivedDiscardedPacketsAccumulated

number

No

Cumulative count of discarded packets received as read at the end of the measurement interval

receivedDiscardedPacketsDelta

number

No

Count of discarded packets received within the measurement interval

receivedErrorPacketsAccumulated

number

No

Cumulative count of error packets received as read at the end of the measurement interval

receivedErrorPacketsDelta

number

No

Count of error packets received within the measurement interval

receivedMulticastPacketsAccumulated

number

No

Cumulative count of multicast packets received as read at the end of the measurement interval

receivedMulticastPacketsDelta

number

No

Count of multicast packets received within the measurement interval

receivedOctetsAccumulated

number

No

Cumulative count of octets received as read at the end of the measurement interval

receivedOctetsDelta

number

No

Count of octets received within the measurement interval

receivedPercentDiscard

number

No

Percentage of discarded packets received; value = (receivedDiscardedPacketsDelta / receivedTotalPacketsDelta) x 100, if denominator is nonzero, or 0, if otherwise.

receivedPercentError

number

No

Percentage of error packets received; value = (receivedErrorPacketsDelta / receivedTotalPacketsDelta) x 100, if denominator is nonzero, or 0, if otherwise.

receivedTotalPacketsAccumulated

number

No

Cumulative count of all packets received as read at the end of the measurement interval

receivedTotalPacketsDelta

number

No

Count of all packets received within the measurement interval

receivedUnicastPacketsAccumulated

number

No

Cumulative count of unicast packets received as read at the end of the measurement interval

receivedUnicastPacketsDelta

number

No

Count of unicast packets received within the measurement interval

receivedUtilization

number

No

Percentage of utilization received; value = (receivedOctetsDelta / (speed x (lastEpochMicrosec - startEpochMicrosec) )) x 100, if denominator is nonzero, or 0, if otherwise.

speed

number

No

Speed configured in mbps.

transmittedBroadcastPacketsAccumulated

number

No

Cumulative count of broadcast packets transmitted as read at the end of the measurement interval

transmittedBroadcastPacketsDelta

number

No

Count of broadcast packets transmitted within the measurement interval

transmittedDiscardedPacketsAccumulated

number

No

Cumulative count of discarded packets transmitted as read at the end of the measurement interval

transmittedDiscardedPacketsDelta

number

No

Count of discarded packets transmitted within the measurement interval

transmittedErrorPacketsAccumulated

number

No

Cumulative count of error packets transmitted as read at the end of the measurement interval

transmittedErrorPacketsDelta

number

No

Count of error packets transmitted within the measurement interval

transmittedMulticastPacketsAccumulated

number

No

Cumulative count of multicast packets transmitted as read at the end of the measurement interval

transmittedMulticastPacketsDelta

number

No

Count of multicast packets transmitted within the measurement interval

transmittedOctetsAccumulated

number

No

Cumulative count of octets transmitted as read at the end of the measurement interval

transmittedOctetsDelta

number

No

Count of octets transmitted within the measurement interval

transmittedPercentDiscard

number

No

Percentage of discarded packets transmitted; value = (transmittedDiscardedPacketsDelta / transmittedTotalPacketsDelta) x 100, if denominator is nonzero, or 0, if otherwise.

transmittedPercentError

number

No

Percentage of error packets received; value = (transmittedErrorPacketsDelta / transmittedTotalPacketsDelta) x 100, if denominator is nonzero, or 0, if otherwise.

transmittedTotalPacketsAccumulated

number

No

Cumulative count of all packets transmitted as read at the end of the measurement interval

transmittedTotalPacketsDelta

number

No

Count of all packets transmitted within the measurement interval

transmittedUnicastPacketsAccumulated

number

No

Cumulative count of unicast packets transmitted as read at the end of the measurement interval

transmittedUnicastPacketsDelta

number

No

Count of unicast packets transmitted within the measurement interval

transmittedUtilization

number

No

Percentage of utilization transmitted; value = (transmittedOctetsDelta / (speed x (lastEpochMicrosec - startEpochMicrosec))) x 100, if denominator is nonzero, or 0, if otherwise.

valuesAreSuspect

string

Yes

Enumeration: ‘true’ or ‘false’. If ‘true’ then the vNicPerformance values are likely inaccurate due to counter overflow or other conditions.

Datatype: processorDimmAggregateThermalMargin

The processorDimmAggregateThermalMargin datatype provides intelligent platform management interface (ipmi) processor dual inline memory module aggregate thermal margin metrics; it consists of the following fields:

Field

Type

Required?

Description

processorDimmAggregateThermal MarginIdentifier

string

Yes

identifier for the aggregate thermal margin metrics from the processor dual inline memory module

thermalMargin

number

Yes

the difference between the DIMM’s current temperature, in celsius, and the DIMM’s throttling thermal trip

Datatype: processStats

The processStats datatype provides metrics on system processes; it consists of the following fields:

Field

Type

Required?

Description

forkRate

number

No

The number of threads created since the last reboot

processIdentifier

string

Yes

processIdentifier

psStateBlocked

number

No

The number of processes in a blocked state

psStatePaging

number

No

The number of processes in a paging state

psStateRunning

number

No

The number of processes in a running state

psStateSleeping

number

No

The number of processes in a sleeping state

psStateStopped

number

No

The number of processes in a stopped state

psStateZombie

number

No

The number of processes in a zombie state

‘Notification’ Domain Datatypes
Datatype: notificationFields

The notificationFields datatype consists of the following fields:

Field

Type

Required?

Description

additionalFields

hashMap

No

Additional notification fields if needed

arrayOfNamedHashMap

namedHashMap [ ]

No

Array of named hashMaps

changeContact

string

No

Identifier for a contact related to the change

changeIdentifier

string

Yes

System or session identifier associated with the change

changeType

string

Yes

Describes what has changed for the entity, for example: configuration changed, capability added, capability removed…

newState

string

No

New state of the entity, for example: ‘inService’, ‘maintenance’, ‘outOfService’

notificationFieldsVersion

string

Yes

Version of the notificationFields block as “#.#” where # is a digit; see section 1 for the correct digits to use.

oldState

string

No

Previous state of the entity, for example: ‘inService’, ‘maintenance’, ‘outOfService’

stateInterface

string

No

Card or port name of the entity that changed state

The fileReady notification event is used by 3GPP-compliant NFs to notify ONAP that a PM file is available for upload. The notificationFields are populated as follows:

arrayOfNamedHashMap: The array is named for the PM file as defined in 3GPP TS 28.550. The array contains the following key value pairs:

  • location in the form protocol://ipAddress:port/path/filename; e.g. “location” : “ftpes://135.3.1.44:21/pmfiles/A20180531.1030+0600-1045+0600A20000626.2315+0200-2330+0200_NodeBId.gz”

  • compression containing the compression type used for the PM file; e.g. “compression” : “gzip”

  • fileFormatType containing the format type of the PM file; e.g. “fileFormatType” : “org.3GPP.32.435#measCollec”

  • fileFormatVersion containing the format version of the PM file; e.g. “fileFormatVersion” : “V10”

  • other vendor-defined key-value pairs as needed

changeIdentifier: set to PM_MEAS_FILES

changeType: set to fileReady

Other notificationFields are not used for fileReady.

‘Other’ Domain Datatypes
Datatype: otherFields

The otherFields datatype defines fields for events belonging to the ‘other’ domain of the commonEventHeader domain enumeration; it consists of the following fields:

Field

Type

Required?

Description

arrayOfNamedHashMap

arrayOfNamedHashMap

No

Array of named hashMaps

hashMap

hashMap

No

Array of name-value pairs

jsonObjects

arrayOfJsonObject

No

Array of JSON objects described by name, schema and other meta-information

otherFieldsVersion

string

Yes

Version of the otherFields block as “#.#” where # is a digit; see section 1 for the correct digits to use.

‘perf3gpp’ Domain Datatypes
Datatype: measDataCollection

The measDataCollection datatype defines a 3GPP measurement collection structure aligned with the 3GPP PM format; it consists of the following fields:

Field

Type

Required?

Description

formatVersion

string

No

3GPP PM reporting file format version from pre-standard TS 28.550 v2.0.0

granularityPeriod

string

Yes

Granularity period for the PM report in seconds

measInfoList

measInfo [ ]

Yes

Array of measInfo measurements

measObjInstIdList

string [ ]

No

Array of monitored object local distinguished name ids per 3GPP TS 32.300

measuredEntityDn

string

Yes

Distinguished name per 3GPP TS 28.532

measuredEntitySoftwareVersion

string

No

Software version for the NF providing the PM data as specified in 3GPP TS 28.532

measuredEntityUserName

string

No

User Definable name for the measured object per 3GPP TS 28.532

Datatype: measInfo

The measInfo datatype provides measurement information; it consists of the following fields:

Field

Type

Required?

Description

jobId

string

No

Name of the measurement job

measInfoId

oneOf [ measInfoIdInteger , measInfoIdString ]

No

Measurement group Identifier

measTypes

oneOf [ measTypesInteger , measTypesString ]

Yes

Array of measurement identifiers associated with the measurement results expressed as integers for efficiency rather than strings

measValues

measValues [ ]

Yes

Array of measValues

Datatype: measInfoIdInteger

The measInfoIdInteger datatype provides an integer measurement group identifier; it consists of the following fields:

Field

Type

Required?

Description

iMeasInfoId

integer

Yes

Integer measurement group Identifier

Datatype: measInfoIdString

The measInfoIdString datatype provides a string measurement group identifier; it consists of the following fields:

Field

Type

Required?

Description

sMeasInfoId

integer

Yes

String measurement group Identifier

Datatype: measResultInteger

The measResultInteger datatype provides an integer 3GPP PM measurement result; it consists of the following fields:

Field

Type

Required?

Description

p

integer

Yes

Integer reference to the counter

iValue

integer

Yes

Integer counter value

Datatype: measResultNull

The measResultNull datatype provides a null 3GPP PM measurement result; it consists of the following fields:

Field

Type

Required?

Description

p

integer

Yes

Integer reference to the counter

isNull

string

Yes

Enumeration: ‘true’ or ‘false’

Datatype: measResultNumber

The measResultNumber datatype provides a number 3GPP PM measurement result; it consists of the following fields:

Field

Type

Required?

Description

p

integer

Yes

Integer reference to the counter

rValue

number

Yes

Number counter value

Datatype: measResultString

The measResultString datatype provides a string 3GPP PM measurement result; it consists of the following fields:

Field

Type

Required?

Description

p

integer

Yes

Integer reference to the counter

sValue

string

Yes

String counter value

Datatype: measTypesInteger

The measTypesInteger datatype provides an array of integer measurement identifiers associated with the measurement results; it consists of the following fields:

Field

Type

Required?

Description

iMeasTypesList

integer [ ]

Yes

Array of integer measurement identifiers associated with the measurement results

Datatype: measTypesString

The measTypesString datatype provides an array of string measurement identifiers associated with the measurement results; it consists of the following fields:

Field

Type

Required?

Description

sMeasTypesList

string [ ]

Yes

Array of string measurement identifiers associated with the measurement results

Datatype: measValues

The measValues datatype provides 3GPP measurement values; it consists of the following fields:

Field

Type

Required?

Description

measObjAddlFlds

hashMap

No

Additional key-value pairs if needed

measObjInstId

measDataCollection

Yes

Monitored object local distinguished name per 3GPP TS 32.300 and 3GPP TS 32.432

measResults

Array of items where each item is oneOf [ measResultInteger, measResultNull, measResultNumber, measResultString ]

Yes

Array of results

suspectFlag

string

No

Enumeration: ‘true’, ‘false’. Indicates if the values are suspect

Datatype: perf3gppFields

The perf3gppFields datatype defines fields for 3GPP PM format events, based on 3GPP TS 28.550, belonging to the ‘perf3gpp’ domain of the commonEventHeader domain enumeration; it consists of the following fields:

Field

Type

Required?

Description

eventAddlFields

hashMap

No

Additional key-value pairs if needed

measDataCollection

measData Collection

Yes

3GPP measurement collection structure

perf3gppFieldsVersion

string

Yes

Version of the perf3gpp event

‘pnfRegistration’ Domain Datatypes
Datatype: pnfRegistrationFields

The pnfRegistrationFields datatype defines fields for events belonging to the ‘pnfRegistration’ domain of the commonEventHeader domain enumeration; it consists of the following fields:

Field

Type

Required?

Description

additionalFields

hashMap

No

Additional pnfRegistration fields if needed

lastServiceDate

string

No

TS 32.692 dateOfLastService = date of last service; e.g. 15022017

macAddress

string

No

MAC address of OAM interface of the unit

manufactureDate

string

No

TS 32.692 dateOfManufacture = manufacture date of the unit; 24032016

modelNumber

string

No

TS 32.692 versionNumber = version of the unit from vendor; e.g. AJ02. Maps to AAI equip-model

oamV4IpAddress

string

No

IPv4 m-plane IP address to be used by the manager to contact the PNF

oamV6IpAddress

string

No

IPv6 m-plane IP address to be used by the manager to contact the PNF

pnfRegistrationFieldsVersion

string

Yes

Version of the pnfRegistrationFields block as “#.#” where # is a digit; see section 1 for the correct digits to use.

serialNumber

string

No

TS 32.692 serialNumber = serial number of the unit; e.g. 6061ZW3

softwareVersion

string

No

TS 32.692 swName = active SW running on the unit; e.g. 5gDUv18.05.201

unitFamily

string

No

TS 32.692 vendorUnitFamilyType = general type of HW unit; e.g. BBU

unitType

string

No

TS 32.692 vendorUnitTypeNumber = vendor name for the unit; e.g. Airscale

vendorName

string

No

TS 32.692 vendorName = name of manufacturer; e.g. Nokia. Maps to AAI equip-vendor

‘State Change’ Domain Datatypes
Datatype: stateChangeFields

The stateChangeFields datatype consists of the following fields:

Field

Type

Required?

Description

additionalFields

hashMap

No

Additional stateChange fields if needed

newState

string

Yes

New state of the entity: ‘inService’, ‘maintenance’, ‘outOfService’

oldState

string

Yes

Previous state of the entity: ‘inService’ , ‘maintenance’, ‘outOfService’

stateChangeFieldsVersion

string

Yes

Version of the stateChangeFields block as “#.#” where # is a digit; see section 1 for the correct digits to use.

stateInterface

string

Yes

Card or port name of the entity that changed state

‘StndDefined’ Domain Datatypes
Datatype: stndDefinedFields

The stndDefinedFields datatype consists of the following fields:

Field

Type

Required?

Description

data

object

Yes

Expected to contain a notification defined by relevant standards group/body Must be a JSON object.

schemaReference

string

No

A reference to standards defined schema, against which the contents of data property will be validated

stndDefinedFieldsVersion

string

Yes

Version of the stndDefinedFields block as “#.#” where # is a digit; see section 1 for the correct digits to use.

Additional rules, when using stndDefined domain

Following rules shall be followed, when using the StndDefined domain:

If the VNF or PNF is using VES StndDefined domain, then the VNF or PNF MUST fill the VES.commonEventHeader.stndDefinedNamespace with a value defined by relevant standards organization.

If the VNF or PNF is using VES StndDefined domain, then the VNF or PNF MAY fill the VES.stndDefinedFields.schemaReference property with a URI corresponding to the specific JSON schema object, against which validation of VES.stndDefinedFields.data will be executed.

If the VNF or PNF is using VES StndDefined domain and eventBatch is sent, then each and every event within eventBatch must have exactly the same VES.commonEventHeader.stndDefinedNamespace set.

‘Syslog’ Domain Datatypes
Datatype: syslogFields

The syslogFields datatype consists of the following fields:

Field

Type

Required?

Description

additionalFields

hashMap

No

Additional syslog fields if needed Ex: {“name1”: “value1”, “name2: “value2” … }

eventSourceHost

string

No

Hostname of the device

eventSourceType

string

Yes

Examples: ‘other’, ‘router’, ‘switch’, ‘host’, ‘card’, ‘port’, ‘slotThreshold’, ‘portThreshold’, ‘virtualMachine’, ‘virtualNetworkFunction’

syslogFacility

integer

No

Numeric code from 0 to 23 for facility:

0 kernel messages

1 user-level messages

2 mail system

3 system daemons

4 security/authorization messages

5 messages generated internally by syslogd

6 line printer subsystem

7 network news subsystem

8 UUCP subsystem

9 clock daemon

10 security/authorization messages

11 FTP daemon

12 NTP subsystem

13 log audit

14 log alert

15 clock daemon (note 2)

16 local use 0 (local0)

17 local use 1 (local1)

18 local use 2 (local2)

19 local use 3 (local3)

20 local use 4 (local4)

21 local use 5 (local5)

22 local use 6 (local6)

23 local use 7 (local7 )

syslogFieldsVersion

string

Yes

Version of the syslogFields block as “#.#” where # is a digit; see section 1 for the correct digits to use.

syslogMsg

string

Yes

Syslog message

syslogMsgHost

string

No

Hostname parsed from non-VES syslog message

syslogPri

integer

No

0-192

Combined Severity and Facility(see rfc5424)

syslogProc

string

No

Identifies the application that originated the message

syslogProcId

number

No

The process number assigned by the OS when the application was started

syslogSData

string

No

A <space> separated list of key=”value” pairs following the rfc5424 standard for SD-ELEMENT.

*Deprecated *

The entire rfc5424 syslogSData object, including square brackets [ ], SD-ID and list of SD-PARAMs

syslogSdId

string

No

0-32 char in format name@number,

i.e., ourSDID@32473

syslogSev

string

No

Level-of-severity text enumeration defined below:

Text Sev Description

Emergency 0 system is unusable

Alert 1 action must be taken immediately

Critical 2 critical conditions

Error 3 error conditions

Warning 4 warning conditions

Notice 5 normal but significant condition

Info 6 Informational messages

Debug 7 debug-level messages

syslogTag

string

Yes

Also known as MsgId. Brief non-spaced text indicating the type of message such as ‘TCPOUT’ or ‘BGP_STATUS_CHANGE’; ‘NILVALUE’ should be used when no other value can be provided

syslogTs

string

No

Timestamp parsed from non-VES syslog message

syslogVer

number

No

IANA assigned version of the syslog protocol specification:

0: VES

1: IANA RFC5424

Examples of syslogSData :

Preferred

ts=”1985-04-12T23:20:50.52Z” tag=”BGP_NEIGHBOR_DOWN” msg=”The BGP session to neighbor 10.10.10.10 is down”

Deprecated

[attinc@1234 ts=”1985-04-12T23:20:50.52Z” tag=”BGP_NEIGHBOR_DOWN” msg=”The BGP session to neighbor 10.10.10.10 is down”]

Syslog references:

https://tools.ietf.org/html/rfc5424#section-6

‘Threshold Crossing Alert’ Domain Datatypes
Datatype: counter

The counter datatype consists of the following fields:

Field

Type

Required?

Description

criticality

string

Yes

Enumeration: ‘CRIT’, ‘MAJ’

hashMap

hashMap

Yes

Key is the name of the counter and value is the current value of the counter

threshholdCrossed

string

Yes

Last threshold that was crossed

Datatype: thresholdCrossingAlertFields

The thresholdCrossingAlertFields datatype consists of the following fields:

Field

Type

Required?

Description

additionalFields

hashMap

No

Additional threshold crossing alert fields if needed

additionalParameters

counter [ ]

Yes

Array of performance counters

alertAction

string

Yes

Enumeration: ‘SET’, ‘CONT’, ‘CLEAR’

alertDescription

string

Yes

Unique short alert description (e.g., NE-CPUMEM)

alertType

string

Yes

Enumeration: ‘CARD-ANOMALY’, ‘INTERFACE-ANOMALY’, ELEMENT-ANOMALY’, ‘SERVICE-ANOMALY’

alertValue

string

No

Calculated API value (if applicable)

associatedAlertIdList

string [ ]

No

List of eventIds associated with the event being reported

collectionTimestamp

string

Yes

Time when the performance collector picked up the data; with RFC 2822 compliant format: ‘Sat, 13 Mar 2010 11:29:05 -0800’

dataCollector

string

No

Specific performance collector instance used

elementType

string

No

Type of network element (internal AT&T field)

eventSeverity

string

Yes

Event severity or priority enumeration: ‘CRITICAL’, ‘MAJOR’, ‘MINOR’, ‘WARNING’ , ‘NORMAL’

eventStartTimestamp

string

Yes

Time closest to when the measurement was made; with RFC 2822 compliant format: ‘Sat, 13 Mar 2010 11:29:05 -0800’

interfaceName

string

No

Physical or logical port or card (if applicable)

networkService

string

No

Network name (internal AT&T field)

possibleRootCause

string

No

Reserved for future use

thresholdCrossing FieldsVersion

string

Yes

Version of the thresholdCrossingAlertFields block as “#.#” where # is a digit; see section 1 for the correct digits to use.

Technology Specific Datatypes
Mobile Flow’ Domain Datatypes
Datatype: gtpPerFlowMetrics

The gtpPerFlowMetrics datatype consists of the following fields:

Field

Type

Required?

Description

avgBitErrorRate

number

Yes

Average bit error rate

avgPacketDelayVariation

number

Yes

Average packet delay variation or jitter in milliseconds for received packets: Average difference between the packet timestamp and time received for all pairs of consecutive packets

avgPacketLatency

number

Yes

Average delivery latency

avgReceiveThroughput

number

Yes

Average receive throughput

avgTransmitThroughput

number

Yes

Average transmit throughput

durConnectionFailedStatus

number

No

Duration of failed state in milliseconds , computed as the cumulative time between a failed echo request and the next following successful error request, over this reporting interval

durTunnelFailedStatus

number

No

Duration of errored state, computed as the cumulative time between a tunnel error indicator and the next following non-errored indicator, over this reporting interval

flowActivatedBy

string

No

Endpoint activating the flow

flowActivationEpoch

number

Yes

Time the connection is activated in the flow (connection) being reported on, or transmission time of the first packet if activation time is not available

flowActivationMicrosec

number

Yes

Integer microseconds for the start of the flow connection

flowActivationTime

string

No

Time the connection is activated in the flow being reported on, or transmission time of the first packet if activation time is not available; with RFC 2822 compliant format: ‘Sat, 13 Mar 2010 11:29:05 -0800’

flowDeactivatedBy

string

No

Endpoint deactivating the flow

flowDeactivationEpoch

number

Yes

Time for the start of the flow connection, in integer UTC epoch time aka UNIX time

flowDeactivationMicrosec

number

Yes

Integer microseconds for the start of the flow connection

flowDeactivationTime

string

Yes

Transmission time of the first packet in the flow connection being reported on; with RFC 2822 compliant format: ‘Sat, 13 Mar 2010 11:29:05 -0800’

flowStatus

string

Yes

Connection status at reporting time as a working / inactive / failed indicator value

gtpConnectionStatus

string

No

Current connection state at reporting time

gtpTunnelStatus

string

No

Current tunnel state at reporting time

ipTosCountList

hashMap

No

Array of key: value pairs where the keys are drawn from the IP Type-of-Service identifiers which range from ‘0’ to ‘255’, and the values are the count of packets that had those ToS identifiers in the flow

ipTosList

string

No

Array of unique IP Type-of-Service values observed in the flow where values range from ‘0’ to ‘255’

largePacketRtt

number

No

large packet round trip time

largePacketThreshold

number

No

large packet threshold being applied

maxPacketDelayVariation

number

Yes

Maximum packet delay variation or jitter in milliseconds for received packets: Maximum of the difference between the packet timestamp and time received for all pairs of consecutive packets

maxReceiveBitRate

number

No

maximum receive bit rate”

maxTransmitBitRate

number

No

maximum transmit bit rate

mobileQciCosCountList

hashMap

No

array of key: value pairs where the keys are drawn from LTE QCI or UMTS class of service strings, and the values are the count of packets that had those strings in the flow

mobileQciCosList

string

No

Array of unique LTE QCI or UMTS class-of-service values observed in the flow

numActivationFailures

number

Yes

Number of failed activation requests, as observed by the reporting node

numBitErrors

number

Yes

number of errored bits

numBytesReceived

number

Yes

number of bytes received, including retransmissions

numBytesTransmitted

number

Yes

number of bytes transmitted, including retransmissions

numDroppedPackets

number

Yes

number of received packets dropped due to errors per virtual interface

numGtpEchoFailures

number

No

Number of Echo request path failures where failed paths are defined in 3GPP TS 29.281 sec 7.2.1 and 3GPP TS 29.060 sec. 11.2

numGtpTunnelErrors

number

No

Number of tunnel error indications where errors are defined in 3GPP TS 29.281 sec 7.3.1 and 3GPP TS 29.060 sec. 11.1

numHttpErrors

number

No

Http error count

numL7BytesReceived

number

Yes

number of tunneled layer 7 bytes received, including retransmissions

numL7BytesTransmitted

number

Yes

number of tunneled layer 7 bytes transmitted, excluding retransmissions

numLostPackets

number

Yes

number of lost packets

numOutOfOrderPackets

number

Yes

number of out-of-order packets

numPacketErrors

number

Yes

number of errored packets

numPacketsReceivedExclRetrans

number

Yes

number of packets received, excluding retransmission

numPacketsReceivedInclRetrans

number

Yes

number of packets received, including retransmission

numPacketsTransmittedInclRetrans

number

Yes

number of packets transmitted, including retransmissions

numRetries

number

Yes

number of packet retrie

numTimeouts

number

Yes

number of packet timeouts

numTunneledL7BytesReceived

number

Yes

number of tunneled layer 7 bytes received, excluding retransmissions

roundTripTime

number

Yes

Round Trip time

tcpFlagCountList

hashMap

No

Array of key: value pairs where the keys are drawn from TCP Flags and the values are the count of packets that had that TCP Flag in the flow

tcpFlagList

string

No

Array of unique TCP Flags observed in the flow

timeToFirstByte

number

Yes

Time in milliseconds between the connection activation and first byte received

Datatype: mobileFlowFields

The mobileFlowFields datatype consists of the following fields:

Field

Type

Required?

Description

additionalFields

hashMap

No

Additional mobileFlow fields if needed

applicationType

string

No

Application type inferred

appProtocolType

string

No

Application protocol

appProtocolVersion

string

No

Application version

cid

string

No

Cell Id

connectionType

string

No

Abbreviation referencing a 3GPP reference point e.g., S1-U, S11, etc

ecgi

string

No

Evolved Cell Global Id

flowDirection

string

Yes

Flow direction, indicating if the reporting node is the source of the flow or destination for the flow

gtpPerFlowMetrics

gtpPer FlowMetrics

Yes

Mobility GTP Protocol per flow metrics

gtpProtocolType

string

No

GTP protocol

gtpVersion

string

No

GTP protocol version

httpHeader

string

No

HTTP request header, if the flow connects to a node referenced by HTTP

imei

string

No

IMEI for the subscriber UE used in this flow, if the flow connects to a mobile device

imsi

string

No

IMSI for the subscriber UE used in this flow, if the flow connects to a mobile device

ipProtocolType

string

Yes

IP protocol type e.g.,TCP, UDP, RTP…

ipVersion

string

Yes

IP protocol version e.g., IPv4, IPv6

lac

string

No

Location area code

mcc

string

No

Mobile country code

mnc

string

No

Mobile network code

mobileFlowFieldsVersion

string

Yes

Version of the mobileFlowFields block as “#.#” where # is a digit; see section 1 for the correct digits to use.

msisdn

string

No

MSISDN for the subscriber UE used in this flow, as an integer, if the flow connects to a mobile device

otherEndpointIpAddress

string

Yes

IP address for the other endpoint, as used for the flow being reported on

otherEndpointPort

integer

Yes

IP Port for the reporting entity, as used for the flow being reported on

otherFunctionalRole

string

No

Functional role of the other endpoint for the flow being reported on e.g., MME, S-GW, P-GW, PCRF…

rac

string

No

Routing area code

radioAccessTechnology

string

No

Radio Access Technology e.g., 2G, 3G, LTE

reportingEndpointIpAddr

string

Yes

IP address for the reporting entity, as used for the flow being reported on

reportingEndpointPort

integer

Yes

IP port for the reporting entity, as used for the flow being reported on

sac

string

No

Service area code

samplingAlgorithm

integer

No

Integer identifier for the sampling algorithm or rule being applied in calculating the flow metrics if metrics are calculated based on a sample of packets, or 0 if no sampling is applied

tac

string

No

Transport area code

tunnelId

string

No

Tunnel identifier

vlanId

string

No

VLAN identifier used by this flow

‘SipSignaling’ Domain Datatypes
Datatype: sipSignalingFields

The sipSignalingFields datatype communicates information about sip signaling messages, parameters and signaling state; it consists of the following fields:

Field

Type

Required?

Description

additionalInformation

hashMap

No

Additional sipSignaling fields

compressedSip

string

No

The full SIP request/response including headers and bodies

correlator

string

Yes

Constant across all events on this call

localIpAddress

string

Yes

Ip address on xNF

localPort

string

Yes

Port on xNF

remoteIpAddress

string

Yes

IP address of peer endpoint

remotePort

string

Yes

Port of peer endpoint

sipSignalingFieldsVersion

string

Yes

Version of the sipSignalingFields block as “#.#” where # is a digit; see section 1 for the correct digits to use.

summarySip

string

No

The SIP Method or Response (‘INVITE’, ‘200 OK’, ‘BYE’, etc)

vendorNfNameFields

vendorNf NameFields

Yes

Vendor, NF and nfModule names

‘Voice Quality’ Domain Datatypes
Datatype: endOfCallVqmSummaries

The endOfCallVqmSummaries datatype provides end of call voice quality metrics; it consists of the following fields:

Field

Type

Required?

Description

adjacencyName

string

Yes

Adjacency name

endpointAverageJitter

number

No

Endpoint average jitter

endpointDescription

string

Yes

Enumeration: ‘Caller’, ‘Callee’

endpointMaxJitter

number

No

Endpoint maximum jitter

endpointRtpOctetsDiscarded

number

No

Endpoint RTP octets discarded

endpointRtpOctetsLost

number

No

Endpoint RTP octets lost

endpointRtpOctetsReceived

number

No

Endpoint RTP octets received

endpointRtpOctetsSent

number

No

Endpoint RTP octets sent

endpointRtpPacketsDiscarded

number

No

Endpoint RTP packets discarded

endpointRtpPacketsLost

number

No

Endpoint RTP packets lost

endpointRtpPacketsReceived

number

No

Endpoint RTP packets received

endpointRtpPacketsSent

number

No

Endpoint RTP packets sent

localAverageJitter

number

No

Local average jitter

localAverageJitterBufferDelay

number

No

Local average jitter buffer delay

localMaxJitter

number

No

Local maximum jitter

localMaxJitterBufferDelay

number

No

Local max jitter buffer delay

localRtpOctetsDiscarded

number

No

Local RTP octets discarded

localRtpOctetsLost

number

No

Local RTP octets lost

localRtpOctetsReceived

number

No

Local RTP octets received

localRtpOctetsSent

number

No

Local RTP octets sent

localRtpPacketsDiscarded

number

No

Local RTP packets discarded

localRtpPacketsLost

number

No

Local RTP packets lost

localRtpPacketsReceived

number

No

Local RTP packets received

localRtpPacketsSent

number

No

Local RTP packets sent

mosCqe

number

No

Decimal range from 1 to 5(1 decimal place)

oneWayDelay

number

No

one-way path delay in milliseconds

packetLossPercent

number

No

Calculated percentage packet loss based on endpoint RTP packets lost (as reported in RTCP) and local RTP packets sent. Direction is based on endpoint description (Caller, Callee). Decimal (2 decimal places)

rFactor

number

No

rFactor from 0 to 100

roundTripDelay

number

No

Round trip delay in milliseconds

Datatype: voiceQualityFields

The voiceQualityFields datatype provides statistics related to customer facing voice products; consists of the following fields:

Field

Type

Required?

Description

additionalInformation

hashMap

No

Additional voice quality fields

calleeSideCodec

string

Yes

Callee codec for the call

callerSideCodec

string

Yes

Caller codec for the call

correlator

string

Yes

Constant across all events on this call

endOfCallVqmSummaries

endOfCallVqm Summaries

No

End of call voice quality metric summaries

phoneNumber

string

No

Phone number associated with the correlator

midCallRtcp

string

Yes

Base64 encoding of the binary RTCP data (excluding Eth/IP/UDP headers)

vendorNfNameFields

vendorNf NameFields

Yes

Vendor, NF and nfModule names

voiceQualityFieldsVersion

string

Yes

Version of the voiceQualityFields block as “#.#” where # is a digit; see section 1 for the correct digits to use.

RESTful Web Services Definition

Security

Event sources must identify themselves to the VES Event Listener.

There are 2 methods of HTTP authentication supported: Certificate Authentication and Basic Authentication.

Basic authentication is supported in VES Event Listener for backward compatibility for existing NFs that are already managed by ONAP. New NFs should support Certificate Authentication. Because the security is better, NFs may choose to only support Certificate Authentication and not support Basic Authentication.

Basic Authentication

When using Basic Authentication, the event source must not pass credentials on the query string. Credentials must be sent in an Authorization header as follows:

  1. The username and password are formed into one string as username:password

  2. The resulting string is Base64 encoded to produce the encoded credential.

  3. The encoded credential is communicated in the header after the string Authorization: Basic

Because the credentials are merely encoded but not encrypted, HTTPS (rather than HTTP) should be used. HTTPS will also encrypt and protect event contents.

Sample Request and Response
Sample Request
POST /eventListener/v7 HTTP/1.1
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
content-type: application/json
content-length: 12345
{
    "event": {
        "commonEventHeader": {
            "version": "4.1",
            "vesEventListenerVersion": "7.2.1",
            "domain": "heartbeat",
            "eventName": "Heartbeat_vIsbcMmc",
            "eventId": "heartbeat0000249",
            "sequence": 0,
            "priority": "Normal",
            "reportingEntityId": "cc305d54-75b4-431b-adb2-eb6b9e541234",
            "reportingEntityName": "ibcx0001vm002oam001",
            "sourceId": "de305d54-75b4-431b-adb2-eb6b9e546014",
            "sourceName": "ibcx0001vm002ssc001",
            "nfVendorName": "Ericsson",
            "nfNamingCode": "ibcx",
            "nfcNamingCode": "ssc",
            "startEpochMicrosec": 1413378172000000,
            "lastEpochMicrosec": 1413378172000000,
            "timeZoneOffset": "UTC-05:30"
        }
    }
}
Sample Success Response
HTTPS/1.1 202 Accepted
X-MinorVersion: 2
X-PatchVersion: 1
X-LatestVersion: 7.2.1
Mutual TLS Certificate Authentication

When using Certificate Authentication, the event source must initialize the HTTPS connection with TLS 1.2 or higher and execute mutual authentication procedures according to RFC5246. The event source must authenticate the VES Listener certificate and must provide its own X.509v3 end-entity certificate to the VES Listener for authentication. The Subject Name in the end-entity certificate must be used according to RFC5280. If a certificate is provided by the NF but it is invalid, the VES Listener is expected to reject the connection and not fall back to basic authentication.

Resource Structure

REST resources are defined with respect to a ServerRoot:

ServerRoot = https://{Domain|IP}:{Port}/{optionalRoutingPath}

The resource structure is provided below:

{ServerRoot}
    |
    |--- /eventListener/v{apiVersion}
             |
             |--- /eventBatch

Figure 1: REST Resource Structure

Exceptions
RESTful Web Services Exceptions

RESTful services generate and send exceptions to clients in response to invocation errors. Exceptions send HTTP status codes (specified later in this document for each operation). HTTP status codes may be followed by an optional JSON exception structure described below. Two types of exceptions may be defined: service exceptions and policy exceptions.

Field Name

Data Type

Required?

Description

messageId

xs:string

Yes

Unique message identifier of the format ‘ABCnnnn’ where ‘ABC’ is either ‘SVC’ for Service Exceptions or ‘POL’ for Policy Exception.

Exception numbers may be in the range of 0001 to 9999 where :

  • 0001 to 2999 are defined by OMA (see OMA’s Common_definitions for details)

  • 3000-9999 are available and undefined

text

xs:string

Yes

Message text, with replacement variables marked with %n, where n is an index into the list of <variables> elements, starting at 1

variables

xs:string [0..unbounded]

No

List of zero or more strings that represent the contents of the variables used by the message text

url

xs:anyUrl

No

Hyperlink to a detailed error resource (e.g., an HTML page for browser user agents).

Service Exceptions

When a service is not able to process a request, and retrying the request with the same information will also result in a failure, and the issue is not related to a service policy issue, then the service will issue a fault using the service exception fault message. Examples of service exceptions include invalid input, lack of availability of a required resource or a processing error.

A service exception uses the letters ‘SVC’ at the beginning of the message identifier. ‘SVC’ service exceptions used by the VES Event Listener API are defined below.

MessageId

Description / Comment

Text

Variables

Parent HTTP Code

SVC0001

General service error (see SVC2000)

<custom error message>

None

400

SVC0002

Bad parameter

Invalid input value for message part %1

%1: message part

400

SVC1000

No server resources

No server resources available to process the request

None

500

SVC2000

More elaborate version of SVC0001

The following service error occurred: %1.

Error code is %2.

%1: human readable description of the error

%2: error code

400

SVC2004

Invalid input value

Invalid input value for %1 %2: %3

%1: attribute

%2: event.commonEventHeader.stndDefinedNamespace

%3: Unable to route event

400

SVC2006

Mandatory input missing

Mandatory input %1 %2 is missing from request

%1: attribute

%2: event.commonEventHeader.stndDefinedNamespace

400

Table - Service Exceptions

Policy Exceptions

When a service is not able to complete because the request fails to meet a policy criteria, then the service will issue a fault using the policy exception fault message. To clarify how a policy exception differs from a service exception, consider that all the input to an operation may be valid as meeting the required input for the operation (thus no service exception), but using that input in the execution of the service may result in conditions that require the service not to complete. Examples of policy exceptions include privacy violations, requests not permitted under a governing service agreement or input content not acceptable to the service provider.

A Policy Exception uses the letters ‘POL’ at the beginning of the message identifier. ‘POL’ policy exceptions used by the VES Event Listener API are defined below.

MessageId

Description / Comment

Text

Variables

Parent HTTP Code

POL0001

General policy error (see POL2000)

A policy error occurred.

None

401

POL1009

User not provisioned for service

User has not been provisioned for service

None

401

POL1010

User suspended from service

User has been suspended from service

None

401

POL2000

More elaborate version of POL0001

The following policy error occurred: %1. Error code is %2.

%1: human readable description of the error

%2: error code

401

POL9003

Message size exceeds limit

Message content size exceeds the allowable limit

None

400

Table - Policy Exceptions

REST Operation Overview
REST Operation Summary

Operation Action

HTTP

Verb

Resource URL relative to {ServerRoot}, which is defined in section 3

publishAnyEvent

POST

/eventListener/v{apiVersion}

publishEventBatch

POST

/eventListener/v{apiVersion}/eventBatch

Table - REST Operation Summary

Api Versioning

apiVersion is used to describe the major version number of the event listener API (which is the same as the major version number of this specification). When this number changes, the implication is: the new major version will break clients of older major versions in some way, if they try to use the new API without modification (e.g., unmodified v1 clients would not be able to use v2 without error).

The Event Listener shall provide the following HTTP headers in response to all requests. Additionally, clients may populate these headers on requests to indicate the specific version they are interested in.

  • X-MinorVersion: 2

  • X-PatchVersion: 1

  • X-LatestVersion: 7.2.1

If a client requests major version 7 (per the REST resource URL) and does not specify the above headers, then they will be provided with the latest patch version of 7.0.x (which is 7.0.1). If the client wants a minor version of major version 7, then they need to supply the X-MinorVersion header with their request. For example, if they request major version 7 with X-MinorVersion: 1, they will get the latest patch version of 7.1, which is 7.1.1.

Message Size

The maximum allowed message size is 2 megabytes of uncompressed text. However, messages of this size have been known to cause performance and data loss. It is strongly recommended, that messages not exceed 1 megabyte. In a future version of the specification, a 1 megabyte limit will become a mandatory requirement.

Operation: publishAnyEvent
Functional Behavior

Allows authorized clients to publish any single event to the VES event listener.

  • Supports only HTTPS access.

  • Uses the HTTP verb POST

  • Supports JSON content types

  • Provides HTTP response codes as well as Service and Policy error messages

Call Flow

publishAnyEvent Call Flow

Input Parameters

Header Fields (note: all parameter names shall be treated as case-insensitive):

Parameter

Data Type

Required?

Brief description

Accept

string

No

Determines the format of the body of the response. Valid values are:

  • application/json

Authorization

string

No

The username and password are formed into one string as username:password. This string is then Base64 encoded to produce the encoded credential which is communicated in the header after the string “Authorization: Basic “. See examples below. If the Authorization header is missing, then an HTTP 400 Invalid Request message shall be returned. If the string supplied is invalid, then an HTTP 401 Unauthorized message shall be returned.

Content-length

integer

No

Note that content length is limited to 2 Megabyte (see Message Size)

Content-type

string

Yes

Must be set to one of the following values:

  • application/json

X-MinorVersion

integer

No

The minor version of the API requested by the client

X-PatchVersion

integer

No

The patch version of the API requested by the client

X-LatestVersion

string

No

The full version of the API requested by the client expressed as {major}.{minor}.{patch}

Body Fields:

Parameter

Data Type

Required?

Brief description

Event

event

Yes

Contains the JSON structure of the common event format.

Output Parameters

Header fields:

Parameter

Data Type

Required?

Brief description

Content-length

integer

No

Used only in error conditions

Content-type

string

No

Used only in error conditions

Date

datetime

No

Date time of the response in GMT

X-MinorVersion

integer

Yes

The minor version of the API service

X-PatchVersion

integer

Yes

The patch version of the API service

X-LatestVersion

string

Yes

The full version of the API service expressed as {major}. {minor}.{patch}

Body Fields (for success responses): no content is provided.

Body Fields (for error responses):

Parameter

Data Type

Required?

Brief description

requestError

requestError

Yes(for errors)

Used only in error conditions

HTTP Status Codes

Code

Reason Phrase

Description

202

Accepted

The request has been accepted for processing

400

Bad Request

Many possible reasons not specified by the other codes (e.g., missing required parameters or incorrect format) . The response body may include a further exception code and text. HTTP 400 errors may be mapped to SVC0001 (general service error), SVC0002 (bad parameter), SVC2004 (Invalid input value), SVC2006 (Mandatory input is missing from request), SVC2000 (general service error with details) or PO9003 (message content size exceeds the allowable limit).

401

Unauthorized

Authentication failed or was not provided. HTTP 401 errors may be mapped to POL0001 (general policy error) or POL2000 (general policy error with details).

404

Not Found

The server has not found anything matching the Request-URI. No indication is given of whether the condition is temporary or permanent.

405

Method Not Allowed

A request was made of a resource using a request method not supported by that resource (e.g., using PUT on a REST resource that only supports POST).

500

Internal Server Error

The server encountered an internal error or timed out; please retry (general catch-all server-side error).HTTP 500 errors may be mapped to SVC1000 (no server resources).

Sample Request and Response
Sample Request
POST  /eventListener/v7 HTTP/1.1
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
content-type: application/json
content-length: 12345
X-MinorVersion: 1

{
    "event": {
        "commonEventHeader": {
            "version": "4.1",
            "vesEventListenerVersion": "7.2.1",
            "domain": "fault",
            "eventName": "Fault_Vscf:Acs-Ericcson_PilotNumberPoolExhaustion",
            "eventId": "fault0000245",
            "sequence": 1,
            "priority": "High",
            "reportingEntityId": "cc305d54-75b4-431b-adb2-eb6b9e541234",
            "reportingEntityName": "ibcx0001vm002oam001",
            "sourceId": "de305d54-75b4-431b-adb2-eb6b9e546014",
            "sourceName": "scfx0001vm002cap001",
            "nfVendorName": "Ericsson",
            "nfNamingCode": "scfx",
            "nfcNamingCode": "ssc",
            "startEpochMicrosec": 1413378172000000,
            "lastEpochMicrosec": 1413378172000000,
            "timeZoneOffset": "UTC-05:30"
        },
        "faultFields": {
            "faultFieldsVersion": 4.0,
            "alarmCondition": "PilotNumberPoolExhaustion",
            "eventSourceType": "other",
            "specificProblem": "Calls cannot complete - pilot numbers are unavailable",
            "eventSeverity": "CRITICAL",
            "vfStatus": "Active",
            "alarmAdditionalInformation": {
                "PilotNumberPoolSize": "1000"
            }
        }
    }
}
Sample Success Response
HTTPS/1.1 202 Accepted
X-MinorVersion: 2
X-PatchVersion: 1
X-LatestVersion: 7.2.1
Sample Error Responses
Sample Policy Exception
HTTPS/1.1 400 Bad Request
content-type: application/json
content-length: 12345
Date: Thu, 04 Jun 2009 02:51:59 GMT
X-MinorVersion: 2
X-PatchVersion: 1
X-LatestVersion: 7.2.1

{
  "requestError": {
    "policyException": {
      "messageId": "POL9003",
      "text": "Message content size exceeds the allowable limit",
    }
  }
}
Sample Service Exception
HTTPS/1.1 400 Bad Request
content-type: application/json
content-length: 12345
Date: Thu, 04 Jun 2009 02:51:59 GMT
X-MinorVersion: 2
X-PatchVersion: 1
X-LatestVersion: 7.2.1

{
  "requestError": {
    "serviceException": {
      "messageId": "SVC2000",
      "text": "Missing Parameter: %1. Error code is %2"
      "variables": [
        "severity",
        "400"
      ]
    }
  }
}
Operation: publishEventBatch
Functional Behavior

Allows authorized clients to publish a batch of events to the VES event listener.

  • Supports only HTTPS access.

  • Uses the HTTP verb POST

  • Supports JSON content types

  • Provides HTTP response codes as well as Service and Policy error messages

publishEventBatch events are handled similarly to a single event. The acknowledgement from the VES Event Listener is for the publishEventBatch and not individual events within the publishEventBatch.

Call Flow

publishEventBatch Call Flow

Input Parameters

Header Fields (note: all parameter names shall be treated as case-insensitive):

Parameter

Data Type

Required?

Brief description

Accept

string

No

Determines the format of the body of the response. Valid values are:

  • application/json

Authorization

string

No

The username and password are formed into one string as “username:password” . This string is then Base64 encoded to produce the encoded credential which is communicated in the header after the string “Authorization: Basic”. See examples below. If the Authorization header is missing, then an HTTP 400 Invalid Request message shall be returned. If the string supplied is invalid, then an HTTP 401 Unauthorized message shall be returned.

Content-length

integer

No

Note that content length is limited to 2 megabyte (see Message Size).

Content-type

string

Yes

Must be set to one of the following values:

  • application/json

X-MinorVersion

integer

No

The minor version of the API requested by the client

X-PatchVersion

integer

No

The patch version of the API requested by the client

X-LatestVersion

string

No

The full version of the API requested by the client expressed as {major}.{minor}.{patch}

Body Fields:

Parameter

Data Type

Required?

Brief description

eventList

eventList

Yes

Array of events conforming to the common event format. All events must belong to a single domain. In case of stndDefined domain all events must have the same stndDefinedNamespace value set.

Output Parameters

Header fields:

Parameter

Data Type

Required?

Brief description

Content-length

integer

No

Used only in error conditions

Content-type

string

No

Used only in error conditions

Date

datetime

No

Date time of the response in GMT

X-MinorVersion

integer

Yes

The minor version of the API service

X-PatchVersion

integer

Yes

The patch version of the API service

X-LatestVersion

string

Yes

The full version of the API service expressed as {major}.{minor}.{patch}

Body Fields (for success responses: no content is provided.

Body Fields (for error responses):

Parameter

Data Type

Required?

Brief description

requestError

requestError

Yes(for errors)

Used only in error conditions

HTTP Status Codes

Code

Reason Phrase

Description

202

Accepted

The request has been accepted for processing

400

Bad Request

Many possible reasons not specified by the other codes (e.g., missing required parameters or incorrect format) . The response body may include a further exception code and text. HTTP 400 errors may be mapped to SVC0001 (general service error), SVC0002 (bad parameter), SVC2000 (general service error with details) or PO9003 (message content size exceeds the allowable limit).

401

Unauthorized

Authentication failed or was not provided. HTTP 401 errors may be mapped to POL0001 (general policy error) or POL2000 (general policy error with details).

404

Not Found

The server has not found anything matching the Request-URI. No indication is given of whether the condition is temporary or permanent.

405

Method Not Allowed

A request was made of a resource using a request method not supported by that resource (e.g., using PUT on a REST resource that only supports POST).

500

Internal Server Error

The server encountered an internal error or timed out; please retry (general catch-all server-side error).HTTP 500 errors may be mapped to SVC1000 (no server resources).

Sample Request and Response
Sample Request
POST /eventListener/v7/eventBatch HTTP/1.1
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
content-type: application/json
content-length: 12345
X-MinorVersion: 1

{
   "eventList": [
      {
         "commonEventHeader": {
            "version": "4.1",
            "vesEventListenerVersion": "7.2.1",
            "domain": "fault",
            "eventName": "Fault_Vscf:Acs-Ericcson_PilotNumberPoolExhaustion",
            "eventId": "fault0000250",
            "sequence": 1,
            "priority": "High",
            "reportingEntityId": "cc305d54-75b4-431b-adb2-eb6b9e541234",
            "reportingEntityName": "ibcx0001vm002oam0011234",
            "sourceId": "de305d54-75b4-431b-adb2-eb6b9e546014",
            "sourceName": "scfx0001vm002cap001",
            "nfVendorName": "Ericsson",
            "nfNamingCode": "scfx",
            "nfcNamingCode": "ssc",
            "startEpochMicrosec": 1413378172000000,
            "lastEpochMicrosec": 1413378172000000,
            "timeZoneOffset": "UTC-05:30"
         },
         "faultFields": {
            "faultFieldsVersion": 4.0,
            "alarmCondition": "PilotNumberPoolExhaustion",
            "eventSourceType": "other",
            "specificProblem": "Calls cannot complete - pilot numbers are unavailable",
            "eventSeverity": "CRITICAL",
            "vfStatus": "Active",
            "alarmAdditionalInformation": {
                "PilotNumberPoolSize": "1000"
            }
         }
      },
      {
         "commonEventHeader": {
            "version": "4.1",
            "vesEventListenerVersion": "7.2.1",
            "domain": "fault",
            "eventName": " Fault_Vscf:Acs-Ericcson_RecordingServerUnreachable",
            "eventId": "fault0000251",
            "sequence": 0,
            "priority": "High",
            "reportingEntityId": "cc305d54-75b4-431b-adb2-eb6b9e541234",
            "reportingEntityName": "ibcx0001vm002oam0011234",
            "sourceId": "de305d54-75b4-431b-adb2-eb6b9e546014",
            "sourceName": "scfx0001vm002cap001",
            "nfVendorName": "Ericsson",
            "nfNamingCode": "scfx",
            "nfcNamingCode": "ssc",
            "startEpochMicrosec": 1413378172000010,
            "lastEpochMicrosec": 1413378172000010,
            "timeZoneOffset": "UTC-05:30"
         },
         "faultFields": {
            "faultFieldsVersion": 4.0,
            "alarmCondition": "RecordingServerUnreachable",
            "eventSourceType": "other",
            "specificProblem": "Recording server unreachable",
            "eventSeverity": "CRITICAL",
            "vfStatus": "Active"
         }
      }
   ]
}
Sample Success Response
HTTPS/1.1 202 Accepted
X-MinorVersion: 2
X-PatchVersion: 1
X-LatestVersion: 7.2.1
Sample Error Responses
Sample Policy Exception
HTTPS/1.1 400 Bad Request
content-type: application/json
content-length: 12345
Date: Thu, 04 Jun 2009 02:51:59 GMT
X-MinorVersion: 2
X-PatchVersion: 1
X-LatestVersion: 7.2.1

{
  "requestError": {
    "policyException": {
      "messageId": "POL9003",
      "text": "Message content size exceeds the allowable limit",
    }
  }
}
Sample Service Exception
HTTPS/1.1 400 Bad Request
content-type: application/json
content-length: 12345
Date: Thu, 04 Jun 2009 02:51:59 GMT
X-MinorVersion: 2
X-PatchVersion: 1
X-LatestVersion: 7.2.1

{
  "requestError": {
    "serviceException": {
      "messageId": "SVC2000",
      "text": "Missing Parameter: %1. Error code is %2"
      "variables": [
        "severity",
        "400"
      ]
    }
  }
}

Terminology

Terminology used in this document is summarized below:

A&AI. Active & Available Inventory is the ONAP component that provides data views of Customer Subscriptions, Products, Services, Resources, and their relationships.

Alarm Condition. Short name of the alarm condition/problem, such as a trap name.

APPC (formerly APP-C). Application Controller. Handles the life cycle management of Virtual Network Functions (VNFs).

Common Event Format. A JSON schema describing events sent to the VES Event Listener.

Common Event Header. A component of the Common Event Format JSON structure. This datatype consists of fields common to all events.

DCAE. Data Collection Analysis and Events. DCAE is the ONAP subsystem that supports closed loop control and higher-level correlation for business and operations activities. DCAE collects performance, usage, and configuration data, provides computation of analytics, aids in trouble-shooting and management, and publishes event, data, and analytics to the rest of the ONAP system for FCAPS functionality.

DMaaP. Data Movement as a Platform. A set of common services provided by ONAP, including a Message Router, Data Router, and a Data Bus Controller.

Domain. In VES, an event ‘domain’ identifies a broad category of events (e.g., ‘fault’ or ‘measurement’), each of which is associated with a VES domain field block, which is sent with the commonEventHeader when events of that category are generated.

Epoch. The number of seconds that have elapsed since 00:00:00 Coordinated Universal Time (UTC), Thursday, 1 January 1970. Every day is treated as if it contains exactly 86400 seconds, so leap seconds are not applied to seconds since the Epoch. In VES Epoch times are measured in microseconds.

Event. A well-structured packet of network management information identified by an eventName which is asynchronously communicated to one or more instances of an Event Listener service to subscribers interested in that eventName. Events can convey measurements, faults, syslogs, threshold crossing alerts, and others types of information.

Event Id. Event key that is unique to the event source. The key must be unique within notification life cycle similar to EventID from 3GPP. It could be a sequential number, or a composite key formed from the event fields, such as sourceName_alarmCondition_startEpoch. The eventId should not include whitespace. For fault events, eventId is the eventId of the initial alarm; if the same alarm is raised again for changed, acknowledged or cleared cases, eventId must be the same as the initial alarm (along with the same startEpochMicrosec and an incremental sequence number.

Event Name. Identifier for specific types of events. Specific eventNames registered by the YAML may require that certain fields, which are optional in the Common Event Format, be present when events with that eventName are published.

Event Streaming. The delivery of network management event information in real time.

Extensible Data Structures. Data structures (e.g., hashMap) that allow event sources to send information not specifically identified in the VES schema.

Hash Map. A hash table, or data structure, used to implement an associative array, a structure than can map keys to values. In VES 6.0, all name-value pair structures were changed to hash maps (i.e., {‘name’: ‘keyName’, ‘value’: ‘keyValue’} was replaced with {‘keyName’: ‘keyValue’}).

IPMI. The Intelligent Platform Management Interface.

JSON. Java Script Object Notation. JSON is an open-standard file format that uses human-readable text to transmit data objects consisting of attribute–value pairs and array data types (or any other serializable value). It is a very common data format used for asynchronous browser–server communication.

NF. Network Function. Generalized name for a VNF or PNF.

NFC. Network Function Component. Generalized name for a VNFC or a component of a PNF.

ONAP. Open Network Automation Platform.

PNF. Physical Network Function.

Policy. Course of action for the management of the network. The ONAP Policy Framework is a comprehensive policy design, deployment, and execution environment. The Policy Framework is the *decision making* component in an ONAP system. It allows you to specify, deploy, and execute the governance of the features and functions in your ONAP system, be they closed loop, orchestration, or more traditional open loop use case implementations. The Policy Framework is the component that is the source of truth for all policy decisions.

Reporting Entity Name. Name of the entity reporting the event or detecting a problem in another vnf/vm or pnf which is experiencing the problem. May be the same as the sourceName. Not used for performance measurements currently.

SDC. Service Design and Creation Platform: The ONAP visual modeling and design tool. It creates internal metadata that describes assets used by all ONAP components, both at design time and run time. The SDC manages the content of a catalog, and assemblies of selected catalog to define how and when VNFs are realized in a target environment.

Source Name: Name of the entity experiencing the event issue, which may be detected and reported by a separate reporting entity. The sourceName identifies the device for which data is collected. A valid sourceName must be inventoried in A&AI.

Specific Problem. Description of the alarm or problem.

VES. Virtual Function Event Stream. In 6.0, the definition of VES was expanded to include event streaming for VNF, PNF and infrastructure. The VES Event Listener can receive any event sent in the VES Common Event Format.

VES Event Listener. A RESTful connectionless push event listener capable of receiving single events or batches of events sent in the Common Event Format.

VM. Virtual Machine.

VNF. Virtual Network Function. A VNF is a virtualized task formerly carried out by proprietary, dedicated network hardware. (Examples: virtual firewall, virtual DNS). A VNF can also be defined as a specific kind of Vendor Software Product.

YAML. A data serialization language and superset of JSON.

VNFC. Virtual Network Function Component. A VNFC is a part of a VNF. It is a stand-alone executable that is loosely-coupled, granular, re-usable, and responsible for a single capability.

Appendix: Historical Change Log

For the latest changes, see the Change Block just before the Table of Contents.

Date

Revision

Description

5/22/2015

0.1

Initial Release - Draft

5/29/2015

0.2

  • Introduction: removed all system names and references to internal AT&T components

  • Security: changed ‘event publisher’ to ‘event source’

  • Generic Event Format: updated the JSON schema per the below:

  • eventHeader: clarified the description of id, made sourceId a required field, changed the datatype of timestamps to timestamp [ ]

  • performanceFields: removed overflowFields

  • tmestamp: added a description of this datatype

  • Exceptions: fixed indentation of sections

  • Approvers: updated the list of approvers and added attuids

6/3/2015

0.3

  • Updated the security section to use HTTP Basic Authentication per AT&T REST standards. Updated the input parameters and messaging examples to use the new security scheme.

6/5/2015

0.4

  • Added otherFields sub section to the defined datatypes

  • Added locale field to the eventHeader.

6/5/2015

0.5

  • Updated the embedded event format json schema to match the changes made in v0.4

6/10/2015

0.6

  • Updated the {ServerRoot} format to contain an optional routing path (for D2 service modules).

7/7/2015

0.7

Common Event Format updates:

  • EventHeader: added ‘measurement’ to the ‘domain’ enumeration; changed ‘locale’ to ‘location’ and clarified in the description that this should be a clli code

  • Added a MeasurementFields datatype, which required the addition of the following datatypes: codecsInUse, cpuUsage, diskUsage, featuresInUse, memoryUsage

7/15/2015

1.0

  • Changed sourceInstance in the eventHeader to be an array of name value pairs

  • Changed the performanceFields block to thresholdCrossingAlertFields. Updated the domain field of the eventHeader to match.

7/23/2015

v1.1

Changes to eventHeader data format:

  • moved sourceInstance to internalHeaderFields

  • moved serviceInstanceId to internalHeaderFields

  • moved productId to internalHeaderFields

  • moved subscriberId to internalHeaderFields

  • moved location to internalHeaderFields

  • added the following new fields in internalHeaderFields: policyType, policyName, correlationEventType, correlationType, correlationName, correlationRootEventId

Changes to faultFields data format:

  • moved the eventSourceDeviceDescription to internalFaultFields and renamed it equipmentVendorModel

  • moved eventSourceHostname to internalFaultFields

  • changed alarmObjectInterface to alarmInterfaceA

  • changed alarmRemoteObject to alarmRemoteObjectZ and

    moved it to internalFaultFields

  • changed alarmRemoteObjectInterface to alarmInterfaceZ and moved it to internalFaultFields

Changes to thresholdCrossingFields data format:

  • changed several references from the old ‘performanceFields’ block to the new ‘thresholdCrossingFields’ block

Other:

  • Fixed several comma and colon syntax errors in the JSON schema as detected by a JSON schema syntax checker.

8/11/2015

v1.2

Timestamp format:

  • Section 4.18: added a note in the datetime field of the Timestamp datatype specifying the (GMT) format required

  • Updated the JSON schema with the same information

Event Header Severity Enumeration:

  • Section 4.8: modified the severity enumeration to remove the numbers in parentheses that followed the names. The names were not changed.

  • Updated the JSON schema with the same information.

8/20/2015

v1.3

JSON Schema rev’d to v9:

  • Alphabetized all fields in the JSON schema

  • Fixed the way arrays were specified (JSON schema syntax issue)

Sample Responses:

  • 2.1.1.1: alphabetized fields, fixed timestamps array depiction, fixed severity enum value to conform to latest format

  • 6.2.6.1: alphabetized fields, fixed timestamps array depiction, fixed severity enum value to conform to latest format

  • 6.3.6.1: alphabetized fields, fixed timestamps array depiction, fixed severity enum value to conform to latest format

  • 6.4.6.1: alphabetized fields, fixed timestamps array depiction, fixed eventList array depection, fixed severity enum value to conform to latest format

9/16/2015

v1.4

JSON Schema rev’d to v10:

  • Fixed an error in the way that the top level “event” object was specified in the v9 json schema. This was discovered when validating examples against the schema using this site: http://json-schema-validator.herokuapp.com/index.jsp

  • Changed the embedded json file in section 4

Sample Responses:

  • Removed an extra comma after the timestamp brace in section 6.2.6 and 6.3.6.

11/11/2015

v1.5

Section 4 was the only section changed: JSON Schema rev’d to v11 and Datatype tables were updated to match . Numerous data structure changes were made based on VNF vendor proof of concept feedback. Modified sample requests and responses to match.

11/12/2015

v1.6

  • The internalFaultFields were merged into the internalHeaderFields; then the internalFaultFields datatype was deleted.

  • Updated the JSON schema to v12.

  • Also corrected some background color issues in the sample requests and responses.

1/18/2016

v1.7

  • Section 2 changes: updated the sample request to conform with the changes below

  • Section 4 datatype changes:

  • Changed ‘eventHeader’ to ‘commonEventHeader’

  • Moved ‘eventSeverity’ from the ‘commonEventHeader’ to ‘faultFields’

  • Added ‘priority’ to ‘commonEventHeader’

  • moved ‘vFstatus’ to ‘faultFields’

  • removed ‘firstDateTime’ and ‘lastDateTime’ and changed ‘firstEpoch’ to ‘startEpochMicrosec’ and changed ‘lastEpoch’ to ‘lastEpochMicrosec’.

  • Added ‘functionalRole’ to the commonEventHeader

  • In the commonEventHeader, changed the ‘eventDomain’ enumeration to remove ‘measurements’ and add ‘measurementsForVfScaling’.

  • Changed the ‘measurementFields’ to ‘measurementsForVfScalingFields’

  • In the commonEventHeader, changed the following fields:

  • ‘eventDomain’ to ‘domain’

  • ‘eventSequence’ to ‘sequence’

  • ‘eventSourceId’ to ‘sourceId’

  • ‘eventSounceName’ to ‘sourceName’

  • Updated the JSON schema to v13

  • Section 6 changes: updated the input parameters and sample requests to conform to the changes above.

  • Section 7: changed the section from Approvers to Contributors.

1/22/2016

v1.8

  • Section 4: Added support for ‘mobileFlow’ in the commonEventHeader ‘domain’ enumeration. Added the mobileFlowFields datatype and the gtpPerFlowMetrics datatype referenced by that datatype.

  • Section 7: alphabetized the contributors

2/11/2016

v1.9

  • Added section 1.3: Naming Standard for Event Types

2/12/2016

v2.0

  • Updated request – response examples to reflect the naming standards for event types introduced in v1.9

  • Added a paragraph on use of Avro as a transport in section 1.4

3/11/2016

v2.1

  • Updated the embedded JSON schema to v15 to fix a typo in the required fields for the measurementsForVfScalingFields, namely, changed ‘configuredEntites’ to ‘configuredEntities’. Additionally, added an ‘Event Listener’ title block at the bottom of the file with a single required event object.

3/15/2016

v2.2

  • Added mobileFlowFields to the event datatype definition in section 4.7 and updated the embedded json schema at the top of section 4 to v16.

4/26/2016

v2.3

  • Generic Event Format updates: 1) made ‘priority’ lowercase in the Word doc table for commonEventHeader; 2) added ‘requestError’ data structure to the Word doc and JSON schema (which is now at v17)

4/27/2016

v2.4

  • JSON Schema: In the ‘event’ data structure, changed ‘thresholdCrossingFields’ to ‘thresholdCrossingAlertFields’ to product v18 of the schema.

  • ‘codecsInUse’ data structure: changed ‘numberInUse’

    to ‘codecUtilization’

5/26/2016

v2.5

  • Changed responses from ‘204 No Content’ to ‘202 Accepted’ and added a body to the response that enable AT&T to throttle the events being sent and/or to request the current state of throttling at the event source.

  • Added new datatypes to support the above: eventDomainThrottleSpecification, eventDomainThrottleSpecificationList, eventThrottlingState, suppressedNvPairs

  • Modifed the commonEventFormat json schema to v19

  • Note: for the VendorEventListener: added new licensing language on the back of the title page; added an “attCopyrightNotice” definition at the top of the commonEventFormat_Vendors.json file; also removed all references to internalHeaderFields from this file and from the VendorEventListener spec.

8/9/2016

v2.6

  • commonHeader: added a note on the description of sourceId and sourceName in the commonHeader: “use reportingEntity for domains that provide more detailed source info”

  • commonHeader: deleted the capacity, measurementsForVfScaling and usage domains in the domain enumeration

  • commonHeader: added the following domains to the domain enumeration: licensingKci, scalingKpi, stateChange

  • event: removed references to capacityFields, measurementsForVfScalingFields and usageFields and added references to licensingKciFields, scalingKpiFields, stateChangeFields

  • licensingKciFields: added this section along with ‘additionalMeasurements’, which is an optional list of measurementGroup structures. Changed the name of kciFieldsVersion to licensingKciFieldsVersion.

  • scalingKpiFields: added this section but changed measurementFieldsVersion to scalingKpiFieldsVersion

  • stateChangeFields: added this section along with ‘additionalFields’, which is an optional list of name-value pairs. Other fields included newState and oldState which were enumerations of the following possible states: ‘inService’, ‘maintenance’, ‘outOfService’

  • sysLogFields: added ‘additionalFields’, which is an optional list of name-value pairs

  • vNicUsage: added two required fields to the vNicUsage data structure: packetsIn and packetsOut

8/10/2016

v2.7

  • commonHeader: removed the note on the description of sourceId and sourceName in the commonHeader: “use reportingEntity for domains that provide more detailed source info”

  • commonHeader: added measurementsForVfScaling domain back and removed the licensingKci and scalingKpi domains

  • event: removed references to licensingKciFields and scalingKpiFields; added references to measurementsForVfScalingFields

  • measurementsForVfScalingFields: combined the kciDetail and kpiDetail structures into the measurementsForVfScalingFields structure; referenced the errors structure

  • errors: added a new structure to capture the receive and transmit errors for the measurements domain

  • removed the following structures: kci, kpi, scalingKpiFields and licensingKciFields

  • eventDomainThrottleSpecification: updated the reference to commonEventHeader domain field

  • faultFields: removed the numbers from the enumerated strings for eventSourceType

  • vNicUsage: made the broadcast, multicast and unicast fields optional

  • contributors: updated Alok’s organizational area

8/12/2016

v2.8

  • commonHeader: copied the descriptions of sourceId and sourceName from the JSON schema into the word document tables.

  • sample request examples: moved the reportingEntityId and reportingEntityNames to the same relative place in all sample requests in the document

  • Fixed the sample request shown for publishEventBatch to take an eventList as input.

  • Fixed the sample request shown for publishSpecificTopic to put the topic in the URL

  • errors: changed the receiveErrors and transmitErrors fields to be datatype number

  • codesInUse: changed ‘codecUtilization’ to ‘numberinUse’

  • vNicUsage: updated the description of the fields

8/27/2016

v2.9

  • Added a note “(currently: 1.1)” in the descriptions of the following fields: commonEventHeader:version, faultFields:faultFieldsVersion, measurementsForVfScalingFields:measurementsForVfScalingFieldsVersion, stateChangeFields:stateChangeFieldsVersion, sysLogFields:syslogFieldsVersion, thresholdCrossingAlertFields:thresholdCrossingFieldsVersion

  • stateChangeFields: made stateInterface mandatory

  • changed ‘enum’ to ‘enumeration’ throughout section 4 of the document (note: this can’t be done in the JSON schema).

  • measurementsForVfScalingFields: made the following fields optional: conurrentSessions, configuredEntitites, cpuUsageArray, fileSystemUsageArray, memoryConfigured, memoryUsed, requestRate, vNicUsageArray

  • measurementsForVfScalingFields: concurrentSessions and configuredEntities: changed the description to support both VMs and VNFs

  • measurementsFor VfScalingFields: clarified the descriptions of latencyDistribution, measurementInverval and requestRate

  • syslogFields: clarified the descriptions of syslogSData, syslogTag, syslogVer

  • thresholdCrossingAlertFields: made the following fields optional and clarified their descriptions: elementType, networkService

  • command and commandList: created a list of command structures to enable the event collector to request changes of event sources. Commands consist of a commandType along with optional fields (whose presence is indicated by the commandType). Three command types are currently supported: ‘measurementIntevalChange’, ‘provideThrottlingState’ and ‘throttlingSpecification’.

  • eventDomainThrottleSpecificationList: removed this and replaced it with commandList.

  • Operations and Sample Requests: modified the operations and samples to support the new command and commandList structures.

9/1/2016

v2.10

  • measurementsForVfScaling block: made the following fields optional: latencyDistribution (which is an array of latencyBucketMeasure structures) and meanRequestLatency. Updated the JSON schemas (now v24) to match.

9/16/2016

v2.11

  • 1 Introduction: updated the introduction to clarify the usage of eventTypes and the possibility of support for other protocols.

  • 6.1 REST Operation Overview: added two new subsections (6.1.2 and 6.1.3) discussing Api Version and Commands Toward Event Source Clients.

  • 6.2 publishAnyEvent: fixed the sample to conform to the latest changes

  • 6.3 publishSpecificTopic: fixed the sample to conform to the latest changes

  • 6.4 publishEventBatch: fixed the sample to conform to the latest changes

  • 6.5 provideThrottlingState operation: added the Input Parameters section heading back and fixed the sample request to provide eventThrottlingState (instead of eventThrottlingClientState).

  • The remaining bullets describe changes made to section 4 datatypes in alphabetical order:

  • command datatype: referenced the new section 6.1.3 which provides an explanation of command state expectations and requirements for a given eventSource:

  • commonEventHeader datatype:

    • made sourceId and reportingEntityId fields optional (although the internal Generic Event Listener spec indicates, in the field descriptions, that the AT&T enrichment process shall ensure that these fields are populated)

    • domain enumeration: changed measurementsForVfScalingFields to measurementsForVfScaling

  • eventDomainThrottleSpecificationList: added this array of eventDomainThrottleSpecification stuctures back to the schema because it is used by the provideThrottlingState operation.

  • eventList: added eventList back to the vendor version of the commonEventFormat. This is used by the publishEventBatch operation.

  • faultFields datatype:

    • eventSourceType: made this a string (and provided the previous enumerated values as examples)

  • filesystemUsage datatype:

    • changed vmIdentifier to filesystemName

  • gtpPerFlowMetrics datatype:

    • flowActivationTime: changed the format and description to be compliant with RFC 2822.

    • flowDeactivationTime: changed the format and description to be compliant with RFC 2822.

  • internalHeaderFields datatype:

    • Added the following optional fields: firstDateTime, lastDateTime compliant with RFC 2822. Noted in the description that these fields must be supplied for events in the following domains: fault, thresholdCrossingAlerts and measurementsForVfScaling.

    • ticketingTimestamp: changed the format and description to be compliant with RFC 2822.

  • syslogFields datatype:

    • eventSourceType: made this a string (and provided the previous enumerated values, without the numbers, as examples)

  • thresholdCrossingAlerts dataypte:

    • collectionTimestamp: changed the format and description to be compliant with RFC 2822.

    • eventStartTimestamp: changed the format and description to be compliant with RFC 2822.

    • added the same eventSeverity field as from the faultFields and made it required

9/23/2016

v2.12

  • Section 4 Datatypes: commonEventHeader: made reportingEntityName a required field (note: the JSON schema already had this field as required)

11/29/2016

v3.0

  • Introduction:

    • Introductory paragraph: changed ‘…Common Event Header Block followed by zero or more event domain blocks’ to ‘…Common Event Header Block accompanied by zero or more event domain blocks’ since the order of the blocks on the wire is not guaranteed.

    • Added Section 1.5 Versioning

  • Section 4: codec processing:

    • CommonEventFormat_Vendors schema only: codesInUse: changed required field from “codecUtilization” which was removed previously to “numberInUse” which is the new field name.

    • added ‘codecSelected’ datatype

    • added ‘codecSelectedTranscoding’ datatype

  • Section 4 and section 6: command processing:

    • Added commandListEntry which is an object that references the command object.

    • commandList: changed commandList to contain an array of commandListEntry objects.

    • Updated sample responses in section 6 where commands are used

  • Section 4: commonEventHeader:

    • Incremented version to 1.2

    • added two new values to the ‘domain’ enumeration: ‘serviceEvents’ and ‘signaling

  • Section 4: added endOfCallVqmSummaries datatype

  • Section 4: ‘event’: added two fields: ‘serviceEventsFields’ and ‘signalingFields’

  • Section 4: added ‘eventInstanceIdentifier’datatype

  • Section 4: CommonEventListener only: internalHeaderFields:

    • added ‘internalHeaderFieldsVersion’(initially set to 1.1)

    • added ‘correlationFirstEpoch’

    • added ‘closedLoopControlName’

    • added ‘closedLoopFlag’

    • added ‘collectorTimeStamp’

    • added ‘eventTag’

    • added ‘tenantName’

    • changed ‘operationalStatus’ to ‘inMaint’

    • added required fields in the schema to match the word doc: ‘equipmentNameCode’, ‘equipmentType’, ‘equipmentVendor’, ‘inMaint’, ‘provStatus’

  • Section 4: added ‘marker’datatype

  • Section 4: added ‘midCallRtcp’ datatype

  • Section 4: mobileFlowFields:

    • added ‘mobileFlowFieldsVersion’(initially set to 1.1)

  • Section 4: added ‘serviceEventsFields’datatype

  • Section 4: added ‘signalingFields’ datatype

  • Section 4: syslogFields:

    • Incremented syslogFieldsVersion to 1.2

    • added ‘syslogPri’

    • added ‘syslogSev’

    • added ‘syslogSdId’

  • Section 4: thresholdCrossingAlertFields:

    • Incremented thresholdCrossingFieldsVersion to 1.2

    • added ‘additionalFields’ which is an optional list of name value pairs.

  • Section 4: schema v26.0 embedded reflecting the above changes.

  • Section 6 and Section 2: changed all sample requests to use /v3 in the REST Resource URL.

12/1/2016

v3.1

  • Section 6: Updated the call flow diagrams to show ‘v3’

1/5/2017

v4.0

  • Combined the Generic Event Listener and Vendor Event Listener into a single API service specification with version 4.0.

  • Changed the title to VES (Virtual Function Event Streaming) Listener.

  • Changed references to ‘generic event’ to ‘common event’ or ‘VES event’ (depending on the context) throughout the document.

  • Used the Legal Disclaimer from the Vendor Event Listener on the back of the title page.

  • Section 1: Introduction changes:

    • modified wording to reference ‘VES’

    • removed the ‘Audience’ section, which described various AT&T groups the documented was intended for

    • tweaked the naming standards for event types to clarify the purpose of the naming conventions

  • Section 3: Resource Structure: added a sentence describing the FQDN and port used in the resource URL.

  • Section 4: Common Event Format changes:

    • renamed the section to ‘Common Event Format’ from ‘Generic Event Format’

    • reorganized the datatypes into separate sections ; sections were defined for each of the domains as well as for common event, common event header and command list processing

    • codecSelected datatype: removed this datatype

    • codecSelectedTranscoding datatype: removed this datatype

    • command datatype: added an enumerated value to commandType: ‘heartbeatIntervalChange’

    • commonEventHeader: added internalHeaderFields to the commonEventHeader, defined as “Fields (not supplied by event sources) that the VES Event Listener service can use to enrich the event if needed for efficient internal processing. This is an empty object which is intended to be defined separately by each provider implementing the VES Event Listener.”

    • commonEventHeader: removed two enumerated values , ‘serviceEvents’ and ‘signaling’ from the domain enumeration

    • commonEventHeader version: incremented the version to 2.0

    • endOfCallVqmSummaries datatype: removed this datatype

    • event: changed the description of the event datatype to: “fields which constitute the ‘root level’ of the common event format”

    • event: removed ‘serviceEventFields’ and ‘signalingFields’ from the definition

    • event: fixed a misspelling of ‘thresholdCrossingAlertFields’, which was only present in the Word document

    • eventInstanceIdentifier datatype: removed this datatype

    • internalHeaderFIelds datatype: defined this as follows: “The internalHeaderFields datatype is an undefined object which can contain arbitrarily complex JSON structures. It is intended to be defined separately by each provider implementing the VES Event Listener. The fields in internalHeaderFields are not provided by any event source but instead are added by the VES Event Listener service itself as part of an event enrichment process necessary for efficient internal processing of events received by the VES Event Listener”

    • marker datatype: removed this datatype

    • measurementsForVfScalingFields datatype: clarified that memoryConfigured and memoryUsed are measured in MB

    • midCallRtcp datatype: removed this datatype

    • mobileFlowFields datatype: added ‘additionalFields’

    • mobileFlowFields datatype: incremented the version number for this field block to 1.2

    • serviceEventsFields datatype: removed this datatype

    • signalingFields datatype: removed this datatype

    • syslogFields: added three fields to the schema that were previously described in the document but not incorporated into the schema: syslogPri, syslogSev, syslogSdId

    • syslogFields version: incremented the version to 2.0

  • Modified the Common Event Format JSON schema to v27.0 to incorporate the above changes. Also, added the AT&T Copyright Notice from the top of the retired CommonEventFormat_Vendors schema.

  • Section 6 and 2: changed all sample requests to use /v4 in the REST Resource URL and call flow diagrams

  • Section 6.1.3: added a row to the table in this section describing the ‘heartbeatIntervalChange’ command.

  • Section 6.1.4: added this new section describing expectations for buffering of events should all REST resource URL FQDNs be unreachable.

  • Section 6 Sample Requests: modified all sample requests showing the return of a commandList toward the event source to incorporate a heartbeatIntervalChange command; also corrected the spelling in the samples for the measurementIntervalChange command.

  • Section 7: Contributors: removed this section

3/21/2017

v4.1

  • JSON Schema changes to produce v27.2 (note: an earlier draft version of v27.1 had been distributed to a few individuals):

    • To support use of the schema with event batches, removed the following statement near the end of the schema file:

    “required”: [ “event” ]

  • Fixed the characters used in some of the quotes

  • Fixed some typos in the descriptions.

  • Removed the booleans, which were non-essential and which were causing problems across different implementations.

  • Section 4.5.7 measurementsForVfScalingFields:

    • Fixed the spelling of measurementsForVfScalingFields in the Word document

  • Section 2 and 6 sample requests and responses:

    • Removed quotes from numbers: sequence, and first/lastEpochMicrosec.

    • Fixed all quote characters, some of which were using unusual symbols that wouldn’t validate with the json-schema Python package.

  • Section 6.2.6.1, 6.3.6.1, 6.4.6.1 sample requests:

    • Added an alarmAdditionalInformation field array to the sample requests.

    • Added missing commas.

  • Section 6.5.6.1 provideThrottlingState sample requests:

    • Fixed the eventDomainThrottleSpecificationList to pass an array of anonymous eventDomainThrottleSpecification objects.

    • Added missing quotes.

  • Fixed the suppressedNvPairsList to pass an array of anonymous suppressedNvPairs objects.

4/14/2017

v5.0

  • Section 1 Introduction:

    • Clarified the Introduction (Section 1).

    • Changed Section 1.1 title from ‘Terminology’ to ‘Event Registration’ and referenced the YAML event registration format, defined in a separate document.

    • Clarified naming standards for eventName.

  • Section 3: updated the REST resource structure

  • Section 4.1 command list processing datatypes:

    • Got rid of commandListEntry and returned commandList to a simple array of commands.

    • Added heartbeatInterval to the command datatype.

    • Changed the datatype of measurementInterval from number to integer.

  • Section 4.2 common event datatypes:

    • event dataType: Added heartbeatFields, sipSignalingFields and voiceQualityFields to the event datatype as optional field blocks

    • Added jsonObject which provides a json object schema, name and other meta-information along with one or more object instances.

    • Added jsonObjectInstance which provides meta-information about an instance of a jsonObject along with the actual object instance

    • Added the ‘key’ datatype

    • Added the namedArrayOfFields datatype

    • Added vendorVnfNameFields

  • Section 4.3 common event header fields:

    • Add two new enumerations to domain: ‘sipSignaling’ and ‘voiceQuality’

    • Renamed eventType to eventName. Note that the original usage of eventType was formally described in the Introduction back on 2/11/2016 with v1.9.

    • Made eventName a required field

    • Created a new field called eventType with a meaning that is different than the old eventType

    • Removed functionalRole, which was replaced by the following two fields.

    • Added nfNamingCode

    • Added nfcNamingCode

    • Changed version to 3.0 (major version change) and made it a required field

  • Section 4.4: faultFields:

    • added one optional field: eventCategory

    • made faultFieldsVersion a required field

    • changed faultFieldsVersion to 2.0 (major version change)

    • fixed a typo on the spelling of alarmInterfaceA

    • clarified field descriptions

  • Section 4.5: added heartbeatFields datatype which can be used to communicate heartbeatInterval. Note: this change was previously made in v4.2

  • Section 4.6 measurements for vf scaling datatypes: changed the following datatypes from number to integer:

    • In measurementsForVfScalingFields: concurrentSessions, configuredEntities, numberOfMediaPortsInUse, vnfcScalingMetric

    • In codecsInUse: numberInUse

    • In featuresInUse: featureUtilization

  • Section 4.6.2 modified cpuUsage

  • Section 4.6.3 added diskUsage

  • Section 4.6.7 measurementsForVfScalingFields:

    • fixed the spelling of the measurementsForVfScalingFields in the Word document

    • added additionalFields, which is an array of fields (i.e., name-value pairs)

    • changed additionalMeasurements to reference the common datatype namedArrayOfFields (instead of referencing measurementGroup)

    • added additionalObjects which is an array of jsonObjects described by name, keys and schema

    • deleted aggregateCpuUsage

    • added diskUsageArray

    • deleted measurementGroup (which was replaced by the common datatype: namedArrayOfFields

    • added memoryUsageArray

    • deleted memoryConfigured and memoryUsed

    • deleted errors and vNicUsageArray

    • added vNicPerformanceArray

    • changed the measurementsForVfScalingVersion to 2.0 (major version change) and made it a required field. Also changed the name of this version field in the Word document to match that in the JSON schema.

  • Section 4.6.8 added memoryUsage

  • Section 4.6.9 vNicPerformance: replaced vNicUsage and errors with vNicPerformance

  • Section 4.7 mobile flow fields changes:

    • Made mobileFlowFieldsVersion a required field and changed the mobileFlowFieldsVersion to 2.0 (major version change).

    • Changed the datatype of flowActivationTime and flowDeactivationTime in the Word doc to string.

    • changed the following datatypes from number to integer: otherEndpointPort, reportingEndpointPort, samplingAlgorithm

  • Section 4.8: otherFields:

    • Added otherFieldsVersion (set at 1.1)

    • Added hashOfNameValuePairArrays

    • Added jsonObjects

    • Added nameValuePairs

  • Section 4.9: added sipSignaling domain datatypes with 4.8.1 sipSignalingFields. sipSignalingFieldsVersion is set at 1.0

  • Section 4.10 stateChangeFields: made stateChangeFieldsVersion a required field and set it to 2.0 (major version change).

  • Section 4.11 syslogFields:

    • Changed the following datatypes from number to integer: syslogFacility, syslogPri

    • Changed additionalFields from a field [ ] to a string which takes name=value pairs delimited by a pipe symbol.

    • Changed syslogFieldsVersion to 3.0 (major version change) and made it a required field

    • Made syslogSev an enumerated string (previously just a string)

  • Section 4.12 thresholdCrossingAlertFields: made thresholdCrossingFieldsVersion a required field and set it to 2.0 (major version change).

  • Section 4.132: added voice quality domain datatypes with 4.13.1 endOfCallVqmSummaries and 4.13.2 voiceQualityFields. voiceQualityFieldsVersion is set at 1.0

  • JSON Schema: changed the schema to v28.0 and incorporated all of the changes above.

  • Additional JSON Schema changes that are part of v28: Note: The following changes are provided relative to API Spec v4.0 (which embedded JSON schema v27.0), but they were also made in an interim release v4.1 (which embedded JSON schema v27.2):

    • To support use of the schema with event batches, removed the following statement near the end of the schema file:

    “required”: [ “event” ]

  • Fixed the characters used in some of the quotes

  • Fixed some typos in the descriptions.

  • Removed the booleans, which were non-essential and which were causing problems across different implementations.

  • Section 2 and 6 sample requests and responses (also incorporated in interim release 4.1):

    • Removed quotes from numbers: sequence, and first/lastEpochMicrosec.

    • Fixed all quote characters, some of which were using unusual symbols that wouldn’t validate with the json-schema Python package.

  • Section 2 and 6 sample requests and responses (only in v5.0):

    • Changed the version numbers in the URL string.

    • Added nfNamingCode and nfcNamingCode and removed functionalRole

  • Section 6 call flows: updated the version number (only in v5.0).

  • Section 6: removed the publishSpecificTopic operation

  • Section 6.1.4: Buffering: clarified event source expectations for buffering (only in v5.0).

  • Section 6.2.6.1, 6.3.6.1 sample requests (also incorporated in interim release 4.1):

    • Added an alarmAdditionalInformation field array to the sample requests.

    • Added missing commas.

  • Section 6.2.6.3, 6.3.6.3 commandList sample responses (only in v5.0):

    • Fixed the commandList sample responses to pass an array of anonymous command objects (rather than an array of commandListEntry objects).

    • Fixed the heartbeatIntervalChange commandType to pass a heartbeatInterval value instead of a measurementInterval value.

    • Removed quotes from the measurementInterval and heartbeatInterval values since they are numbers.

  • Section 6.4.6.1 provideThrottlingState sample requests(also incorporated in interim release 4.1):

    • Fixed the eventDomainThrottleSpecificationList to pass an array of anonymous eventDomainThrottleSpecification objects.

    • Added missing quotes.

    • Fixed the suppressedNvPairsList to pass an array of anonymous suppressedNvPairs objects (also incorporated in interim release 4.1).

5/22/2017

v5.1

  • Footers: removed proprietary markings and updated copyrights to 2017

  • Section 4.2.3: field:

    • Changed the API spec to make ‘name’ and ‘value’ start with lowercase letters. Note: this did not affect the schema, which already had them as lowercase.

  • JSON Schema:

    • measurementGroup: deleted this object since it was replaced with ‘namedArrayOfFields’ in v28.0 and was no longer being used.

    • namedArrayOfFields: Fixed an error in the specification of required fields: from ‘measurements’ to ‘arrayOfFields’.

  • Changed the version of the JSON schema to 28.1

6/14/2017

v5.2

  • JSON Schema: created v28.2 by changing the field descriptions in the memoryUsage object to refer to ‘kibibytes’ instead of ‘kilobytes’. There were no changes to the 28.1 structure.

  • Word Document: measurementsForVfScaling Domain: memoryUsage object: changed the field descriptions in this object to refer to ‘kibibytes’ instead of ‘kilobytes’. There were no changes to the memoryUsage structure.

  • Reorganized the Word document to group the data structures in Section 4 into three broad categories to better align with the VNF Guidelines documentation that has been prepared for vendors:

    • Common Event Datatypes:

      • Command List Processing Datatypes

      • Common Event Datatypes

      • Common Event Header Datatypes

    • Technology Independent Datatypes:

      • ‘Fault Domain Datatypes

      • ‘Heartbeat’ Domain Datatypes

      • ‘Measurements For Vf Scaling’ Domain Datatypes

      • ‘Other’ Domain Datatypes

      • ‘State Change’ Domain Datatypes

      • ‘Syslog’ Domain Datatypes

      • ‘Threshold Crossing Alert’ Domain Datatypes

    • Technology Specify Datatypes:

      • ‘Mobile Flow’ Domain Datatypes

      • ‘Sip Signaling’ Domain Datatypes

      • ‘Voice Quality’ Domain Datatypes

  • Section 6.1.3: Commands Toward Event Source Clients: Added a statement: “Note: Vendors are not currently required to implement support for command processing; in addition, command processing may be supported by an App-C interface in future.”

6/22/2017

v5.3

  • JSON Schema: created v28.3 by correcting an error in the sipSignalingFields: changed vnfVendorNameFields to vendorVnfNameFields. Embedded the new schema at the top of section 4.

9/12/2017

v5.4

  • Note: There no changes to any data structures or operations in this version.

  • JSON Schema: created v28.4 embedded at the top of section 4:

    • Added a reference to eventList in the properties defined under the schema title. This enables the schema to correctly validate event batches in addition to just events.

    • Moved the schema title to the top of the schema and changed the text from “Event Listener” to “VES Event Listener”

    • Added a schema header block under the title to clearly communicate the schema version, associated API and last-modified information

  • Changed the date in the copyright notice to 2017

9/19/2017

v5.4.1

  • Note: There no changes to any data structures or operations in this version.

  • Back of Cover Page: updated the license and copyright notice to comply with ONAP guidelines

  • JSON Schema: updated the JSON schema to v28.4.1: updated the copyright notice and license to comply with ONAP guidelines

6/28/2018

v6.0

  • Added contributors to the title page.

  • Updated references to ‘vnf’ ‘vnfc’ to either ‘nf’ and ‘nfc’ or ‘xNf’ and ‘xNfc’ to generalize support across both vnfs and pnfs.

  • Section 1:

    • clarified the meaning of the VES acronym

    • changed references from ASDC to SDC and from MSO to SO

    • clarified the requirements for eventNames.

    • Added a section of EventId use case examples

    • Added a new section on measurement expansion fields

    • Added a new section of syslogs

    • clarified the versioning section and referenced the new API Versioning section in section 6.

    • Added a list of all the latest field block version numbers in this version of the API spec.

  • Section 2: updated the sample to show use of new HTTP versioning headers. Added a note indicating that support for mutual SSL would be provided in future.

  • Section 3: updated the resource structure remove the clientThrottlingState resource.

  • Section 4: hashMaps. Changed all name-value pair structures to hashMaps causing the following data model and JSON schema (to v29.0) changes:

    • 4.1.1: Common Event Datatypes:

      • removed “field” and added “hashMap”

      • removed “namedArrayOfFields” and added “namedHashMap”

      • added arrayOfNamedHashMap

      • added arrayOfJsonObject

    • 4.2.1: Fault Domain Datatypes:

      • changed the faultFields version to 3.0 (major change)

      • changed faultFields.alarmAdditionalInformation to reference a hashMap

    • 4.2.2: Heartbeat Domain Datatypes:

      • changed the heartbeatFieldsVersion to 2.0 (major change)

      • changed heartbeatFields.additionalFields to reference a hashMap

    • 4.2.3: Measurement Domain Datatypes:

      • changed the measurementFieldsVersion to 3.0 (major change)

      • changed measurementFields.additionalFields to reference a hashMap

      • changed measurement.additionalMesurements to reference a namedHashMap [ ]

      • modified measurementFields.featureUsageArray to reference a hashmap and removed ‘featuresInUse’

      • added the following datatypes which are now referenced as items in arrays within measurementFields: hugePages, load, machineCheckException, processStats

    • 4.2.5: Other Domain Datatypes:

      • Change the otherFieldsVersion to 2.0 (major change)

      • changed otherFields.nameValuePairs to reference a hashMap and renamed it hashMap

      • changed otherFields.hashOfNameValuePairArrrays to reference a namedHashMap and renamed it arrayOfNamedHashMap

    • 4.2.7: State Change Domain Datatypes:

      • changed the stateChangeFiledsVersion to 3.0 (major change)

      • changed stateChangeFields.additionalFields to reference a hashMap

    • 4.2.9: Threshold Crossing Alert Domain Datatypes:

      • changed the thresholdCrossingAlertFieldsVersion to 3.0 (major change)

      • changed thresholdCrossingAlertFields.additionalFields to reference a hashMap

      • counter: removed name and value elements and replaced with a hashMap

    • 4.3.1: Mobile Flow Domain Datatypes:

      • changed the mobileFlowFieldsVersion to 3.0 (major change)

      • changed mobileFlowFields.additionalFields to reference a hashMap

      • gtpPerFlowMetrics: modified ipTosCountList to reference hashmap

      • gtpPerFlowMetrics: modified mobileQciCosCountList to reference hashmap

      • gtpPerFlowMetrics: modified tcpFlagCountList to reference hashmap

    • 4.3.2: Sip Signaling Domain Datatypes:

      • changed the sigSignalingFieldsVersion to 2.0 (major change)

      • changed sipSignalingFields.additionalInformation to reference a hashMap

    • 4.3.3: Voice Quality Domain Datatypes:

      • change the voiceQualityFieldsVersion to 2.0 (major change)

      • changed voiceQualityFields.additionalInformation to reference a hashMap

  • Section 4: added notes at the top of section 4 clarifying expectations and requirements for optional fields, extensible fields and keys sent through extensible fields.

  • Common Event Data Types: Section 4.1.1.9 Changed vendorVnfNameFields to vendorNfNameFields; updated Section 4.3.2 SipSignaling and 4.3.3 Voice Quality to refer to the renamed object

  • Common Event Header Section 4.1.2:

    • clarified the descriptions of eventId, reportingEntityName, sourceName and startEpochMicroseconds.

    • Added ‘notification’ and ‘pngRegistration’ to the domain enumeration.

    • added a new timeZoneOffsest field

  • Fault Domain Section 4.2.1: clarified the definitions of alarmCondition, eventSeverity and specificProblem

  • Measurements Domain Section 4.2.3: changed the name of this domain from ‘measurementsForVfScaling’ to ‘measurement’

    • measurementsForVfScaling measurement

    • measurementsForVfScalingFields measurementFields

    • measurementsForVfScalingVersion measurementFieldsVersion

    • the ‘mfvs’ abbreviation measurement

  • Measurements Domain Section 4.2.3 cpuUsage: added seven optional fields to this structure: cpuCapacityContention, cpuDemandAvg, cpuDemandMhz, cpuDemandPct, cpuLatencyAverage, cpuOverheadAvg, cpuSwapWaitTime

  • Measurements Domain Section 4.2.3 diskUsage: added ten optional fields to this structure: diskBusResets, diskCommandsAborted, diskCommandsAvg , diskFlushRequests, diskFlushTime, diskReadCommandsAvg, diskTime, diskTotalReadLatencyAvg, diskTotalWriteLatencyAvg, diskWriteCommandsAvg

  • Measurements Domain Section 4.2.3: added a new ‘ipmi’ datatype along with following ‘supporting’ datatypes: ipmiBaseboardTemperature, ipmiBaseboardVoltageRegulator, ipmiBattery, ipmiFan, ipmiGlobalAggregateTemperatureMargin, ipmiHsbp, ipmiNic, ipmiPowerSupply, ipmiProcessor, processorDimmAggregateThermalMargin

  • Measurements Domain Section 4.2.3: added a new ‘load’ datatype

  • Measurements Domain Section 4.2.3 memoryUsage: added eight optional fields to this structure: memoryDemand, memoryLatencyAvg, memorySharedAvg, memorySwapInAvg, memorySwapInRateAvg, memorySwapOutAvg, memorySwapOutRateAvg, memorySwapUsedAvg

  • Measurements Domain Section 4.2.3: modified measurementFields to include the following new fields: hugePagesArray, ipmi, loadArray, memoryErrors, processStatusArray, rdtArray

  • Measurements Domain Section 4.2.3 renamed vNicPerformance to nicPerformance and changed vNicIdentifer to nicIdentifier

  • Notification Domain Section 4.2.4: added notificationFields to support a new notification domain.

  • pnfRegistration Domain Section 4.2.7: added pnfRegistrationFields to support a new registration domain.

  • sysLog Domain Section 4.2.8: added two new fields: syslogMsgHost and syslogTs. Clarified field descriptions. Clarified syslogSData example.

  • endOfCallVqmSummaries Section 4.3.3.1:

    • converted endpointJitter into two fields: endpointAverageJitter and endpointMaxJitter

    • converted localJitter into two fields: localAverageJitter and localMaxJitter

    • added two fields: localAverageJitterBufferDelay and localMaxJitterBufferDelay

    • added endpointRtpOctetsLost and endpointRtpPacketsLost

    • added localRtpOctetsLost and localRtpPacketsLost

    • converted packetsLost into oneWayDelay

  • API Versioning:

    • Section 1.4: clarified the versioning section and linked it to the following new section 6.1.2

    • Section 6.1.2: Added requirements for HTTP headers communicating minor, patch and latest version information.

    • Section 2 and 6 sample messages: clarified examples to use the new HTTP headers

  • Section 6.1.4: Added a section specifying message size limits.

  • Section2 6.2.6.1 and 6.3.6.1: corrected additionalInformation examples to use hashMap instead of name-value pair fields.

  • Section 7: Added a section on Terminology.

  • Command List Processing: removed command list processing from the document and schema:

    • Modified the Section 3 resource structure to align with these changes.

    • Removed Section 4 Datatypes: command, commandList, eventDomainThrottleSpecification, eventDomainThrottleSpecificationList, eventThrottlingState, suppressedNvPairs

    • Removed Section 6.1 description of commands toward event source clients

  • Removed Section 6.4 operation: provideThrottlingState

7/30/2018

v7.0

  • General:

    • Fixed typos throughout

    • Changed example versions to v7

  • Section1:

    • Clarified casing and use of dashes versus colons in eventName examples

    • Updated all field block versions

  • Section 2: added a note clarifying that TLS 1.2 or higher must be used for HTTPS connections.

  • Section 4 embedded schema changed to v30:

    • Added ” ‘additionalProperties’: false ” to objects to reject events that attempt to send properties that are not listed in the ‘properties’ keyword. Note: does not affect hashmap extensible fields.

    • Changed all versions in all field blocks from number to string enum with the version number fixed by the enum so the schema can validate events that attempt to send non-standard field blocks.

    • Changed syslog additionalFields to a hashMap

  • Section 4:

    • Fixed section heading numbers that were the same

    • 4.1.1: jsonObjectInstance: added an optional recursive jsonObject and removed all required fields from this object

    • 4.1.2: commonEventHeader:

      • nfVendorName: added this optional field

      • timeZoneOffset: changed from number to string with a particular format specified

      • version was changed from number to string (as were all the version fields of all the field blocks)

      • vesCommonEventListenerVersion: added this required field as a string enumeration

    • 4.2.3: Measurements Domain:

      • Added a note clarifying that NFs are required to report exactly one Measurement event per period per sourceName

      • diskUsage: added four new optional fields: diskWeightedIoTimeAve, diskWeightedIoTimeLast , diskWeightedIoTimeMax, diskWeightedIoTimeMin

      • memoryUsage: add one new optional field: percentMemoryUsage

      • nicPerformance: added nine new optional fields: administrativeState, operationalState , receivedPercentDiscard, receivedPercentError, receivedUtilization, speed, transmittedPercentDiscard, transmittedPercentError, transmittedUtilization

      • processorDimmAggregateThermalMargin: make the thermalMargin field required

    • 4.2.8: Syslog Domain:

  • Corrected the example at the end of the section

7/31/2018

v7.0.1

  • Section 4: The schema embedded at the top of section 4 was patched to correct a header field name error—the schema version moves from 30 to 30.0.1:

    • Changed commonEventHeader field: ‘vesCommonEventFormatVersion’ field to ‘vesEventListenerVersion’ and set the enum to 7.0.1

    • Also changed the commonEventHeader ‘required’ array to reflect use the corrected field name: ‘vesEventListenerVersion’

    • Changed the commonEventHeader ‘version’ field enumeration to 4.0.1

  • Section1:

    • Changed the field block versions for the common header for ‘vesEventListenerVersion’ (to 7.0.1) and ‘version’ (to 4.0.1).

  • Sections 2 and 6:

    • Changed the commonEventHeader version fields above, in the sample message requests and responses; also updated the faultFieldsVersion to 4.0

  • Section 6.1.2: Changed the X-LatestVersion to 7.0.1 and the X-PatchVersion to 1

12/10/2018

v7.1

  • Section 1.2: Added Notification domain Perf3gpp domain and changed a reference from ‘measurements domain’ to ‘measurement domain’.

  • Section 1.7.1: Field Block Versions: added ‘perf3gppFields’ version at 1.0 and changed the following version enumerations so that existing clients of major version 7 would not be broken by this VES minor version change, in accordance with semantic versioning definitions:

    • commonEventHeader: changed to ‘vesEventListenerVersion’ enum to accept either 7.0 or 7.0.1 or 7.1.

    • commonEventHeader: changed ‘version’ enum to accept either 4.0 or 4.0.1 or 4.1

  • Section 2:

    • changed sample request and responses to reference 7.1 instead of 7.0.1 (and version 4.1 of the commonEventHeader version, instead of v4.0.1)

    • added a sub section on service provider support for mutual ssl certificate authentication

  • Section 4.1.2.1:

    • CommonEventHeader timeZoneOffset changed description from ‘UTC+/-hh.mm’ to ‘UTC+/-hh:mm’

    • Added ‘perf3gpp’ to the domain enumeration

  • Section 4.2.3: Measurement Domain Datatypes:

    • In ‘MeasurementFields’: Changed ‘ipmiArray’ to ‘ipmi’ and made the type ‘object’

    • ‘ipmiProcessor’: changed ‘pprocessorThermalControl’ to ‘processorThermalControl’

    • ‘machineCheckException’: changed ‘processIdentifier’ to ‘vmIdentifier’

  • Section 4.2.6: added the perf3gpp domain

  • Section 4 embedded schema:

    • Changed the schema version from 30.0.1 to 30.1 as a result of the changes below:

    • commonEventHeader: changed to ‘vesEventListenerVersion’ enum to accept either 7.0, 7.0.1 or 7.1

    • commonEventHeader: changed the ‘version’ field enumeration to accept either 4.0, 4.0.1 or 4.1

    • commonEventHeader: changed the ‘domain’ enumeration to add support for the perf3gpp domain.

    • ‘event’: added a reference to ‘perf3gppFields’

    • ‘hugePages’: changed the type of hugePagesIdentifier from number to string

    • ‘ipmiGlobalAggregateTemperatureMargin’: changed ‘pmiGlobalAggregateTemperatureMarginIdentifier’ to ‘globalAggregateTemperatureMarginIdentifier’

    • ‘perf3gppFields’: added this object

  • Section 6: changed references throughout from v7.0.1 to v7.1 and v4.0.1 (of the commonEventHeader version) to v4.1

  • Changed the location of the doc to VNF Requirements and changed the formatting

1/28/2020

v7.1.1

  • Changed event sizes from 2Mb to 1Mb

  • Configuration Requirement comments addressed

  • Changed DCAE Collector to VES Event Listener

  • Replaced VNF with NF where appropriate

  • Updated publishAnyEvent and publishBatchEvent to clarify both one way and mutual TLS are supported

  • Changed authorization for publishEventBatch because certification authorization is also supported

  • Updated fault use case in EventId Use Case Examples based on Ericsson feedback

  • Added new Configuration Requirements section

  • Added new Event Domain Requirements section

  • Updated security requirements based on agreements in ONAP Security Committee with details on 2-way certificate support

  • Provided clarifications on event buffering

  • Added Event Handling Requirements for publishEventFlow

  • Updated Field Block Versions to support existing clients of major version 7

  • Updated sample request and response schemas

  • Updated embedded schema as follows:

    • Changed schema version to 30.1.1

    • Changed measValues to measValuesList and similar changes throughout

    • Changed iMeasTypesList to sMeasTypesList

  • Corrected publishEventBatch call flow diagram

  • Changed AuthorizationHeader to Required? = NO for publishAnyEvent operation

  • Relaxed various requirements related to camel casing of values from ‘must’ to ‘should’

5/27/2020

v7.2

  • Re-organized sections to flow more logically

  • Moved NF requirements to VNF Requirements

  • Changed DCAE Collector to VES Event Listener

  • Added StndDefined domain datatypes

  • Added eventCommonHeader field stndDefinedNamespace

  • Updated SVC exceptions with SVC2004 and SVC2006

  • Updated links to OMA

  • Updated publishEventBatch to support stndDefined

01/16/2021

v7.2.1

  • updated to reference CommonEventFormat_30.2.1_ONAP

  • added eventId use-case example, where eventID uniqueness cannot be assured

OPNFV Verfied Program Badging for VNFs

OPNFV Verified Program Overview

The OPNFV Verified Program (OVP) is

an open source, community-led compliance and verification program to demonstrate the readiness and availability of commercial NFV products and services, including NFVI and VNFs, using OPNFV and ONAP components.

—Source: OVP

The program currently offers verification badges for NFVI, VNFs, and Labs. The VNF badge aims to verify that a given VNF is compatible and interoperable with a given release of ONAP and an ONAP-compatible NFVI.

Relationship to ONAP

The ONAP VNF Requirements project defines the mandatory and recommended requirements for a VNF to be successfully orchestrated by ONAP. At this time, the OPNFV VNF badge automates the verification of a subset of these requirements with plans to expand the scope over verified requirements over time.

Currently, the OPNFV VNF badge covers the following:

  • Compliance checks of the contents of a VNF onboarding package for Heat-based or TOSCA-based VNFs.

    • Validation of the packages are, respectively, performed by the ONAP VVP and ONAP VNFSDK projects.

  • Validation that the package can be onboarded, modeled, configured, deployed, and instantiated on an ONAP-compatible NFVI (currently OpenStack)

How to Receive a ONPFV VNF Badge

The ONAP platform includes a set of automated tests that can be setup and executed for a given VNF to verify its compliance with the in-scope VNF Requirements. This test suite will produce a result file that is compatible for submission to the OPNFV Verified Program. Please refer to the OPNFV VNF Portal for more details on registering for the program and submitting your results.

The following section will describe how to setup and execute the tests.

Executing the OPNFV Verified Compliance and Validation Tests

The instructions related to setting up and executing the tests vary based on whether the VNF is modeled in OpenStack Heat or in TOSCA. Please refer to the appropriate section based on your VNF.

Heat-based VNF Validation
Instructions

The instructions for setting up and running the validation scripts can be found on the VVP Test Engine GitHub site.

Reporting Results

Once the test suite passes, the results tarball can be submitted to the OPNFV Verification Program VNF Portal.

Additional Resources
TOSCA-based VNF Testing

VNF Test Platform (VTP) provides an platform to on-board different test cases required for OVP for various VNF testing provided by VNFSDK (for TOSCA) projects in ONAP. And it generates the test case outputs which would be uploaded into OVP portal for VNF badging.

TOSCA VNF Test Environment

As pre-requestsite steps, it is assumed that, successful ONAP, Vendor VNFM and OpenStack cloud are already available. Below installation steps help to setup VTP components and CLI.

_images/tosca_vnf_test_environment.png
Installation

Clone the VNFSDK repo.

git clone --depth 1 --branch elalto https://git.onap.org/vnfsdk/refrepo

Install the VTP by using script refrepo/vnfmarket-be/deployment/install/vtp_install.sh

Follow the steps as below (in sequence):

  • vtp_install.sh --download: It will download all required artifacts into /opt/vtp_stage

  • vtp_install.sh --install: It will install VTP (/opt/controller) and CLI (/opt/oclip)

  • vtp_install.sh --start: It will start VTP controller as Tomcat service and CLI as oclip service

  • vtp_install.sh --verify: It will verify the setup is done properly by running some test cases.

Last step (verify) would check the health of VTP components and TOSCA VNF compliance and validation test cases.

Check Available Test Cases

VTP supports to check the compliance of VNF and PNF based on ONAP VNFRQTS.

To check:

  • Go to command console

  • Run command oclip

  • Now it will provide a command prompt:

oclip:open-cli>

Now run command as below and check the supported compliance test cases for VNFRQTS.

  • csar-validate - Helps to validate given VNF CSAR for all configured VNFRQTS.

  • csar-validate-rxxx - Helps to validate given VNF CSAR for a given VNFRQTS requirement number.

oclip:open-cli>schema-list --product onap-dublin --service vnf-compliance
+--------------+----------------+------------------------+--------------+----------+------+
|product       |service         |command                 |ocs-version   |enabled   |rpc   |
+--------------+----------------+------------------------+--------------+----------+------+
|onap-dublin   |vnf-compliance  |csar-validate-r10087    |1.0           |true      |      |
+--------------+----------------+------------------------+--------------+----------+------+
|onap-dublin   |vnf-compliance  |csar-validate           |1.0           |true      |      |
+--------------+----------------+------------------------+--------------+----------+------+
|onap-dublin   |vnf-compliance  |csar-validate-r26885    |1.0           |true      |      |
+--------------+----------------+------------------------+--------------+----------+------+
|onap-dublin   |vnf-compliance  |csar-validate-r54356    |1.0           |true      |      |
...

To know the details of each VNFRQTS, run as below.

oclip:open-cli>use onap-dublin
oclip:onap-dublin>csar-validate-r54356 --help
usage: oclip csar-validate-r54356

Data types used by NFV node and is based on TOSCA/YAML constructs specified in draft GS NFV-SOL 001.
The node data definitions/attributes used in VNFD MUST comply.

Now run command as below and check the supported validation testcases

oclip:onap-dublin>use open-cli
oclip:open-cli>schema-list --product onap-dublin --service vnf-validation
+--------------+----------------+----------------------+--------------+----------+------+
|product       |service         |command               |ocs-version   |enabled   |rpc   |
+--------------+----------------+----------------------+--------------+----------+------+
|onap-dublin   |vnf-validation  |vnf-tosca-provision   |1.0           |true      |      |
+--------------+----------------+----------------------+--------------+----------+------+
Configure ONAP with required VNFM and cloud details

1. Setup the OCOMP profile onap-dublin

Run following command to configure the ONAP service URL and credentials as given below, which will be used by VTP while executing the test cases

oclip:open-cli>use onap-dublin
oclip:onap-dublin>profile onap-dublin
oclip:onap-dublin>set sdc.onboarding:host-url=http://159.138.8.8:30280
oclip:onap-dublin>set sdc.onboarding:host-username=cs0008
oclip:onap-dublin>set sdc.onboarding:host-password=demo123456!
oclip:onap-dublin>set sdc.catalog:host-url=http://159.138.8.8:30205
oclip:onap-dublin>set sdc.catalog:host-password=demo123456\!
oclip:onap-dublin>set sdc.catalog:host-username=cs0008
oclip:onap-dublin>set sdc.catalog:service-model-approve:host-username=gv0001
oclip:onap-dublin>set sdc.catalog:service-model-distribute:host-username=op0001
oclip:onap-dublin>set sdc.catalog:service-model-test-start:host-username=jm0007
oclip:onap-dublin>set sdc.catalog:service-model-test-accept:host-username=jm0007
oclip:onap-dublin>set sdc.catalog:service-model-add-artifact:host-username=ocomp
oclip:onap-dublin>set sdc.catalog:vf-model-add-artifact:host-username=ocomp
oclip:onap-dublin>set aai:host-url=https://159.138.8.8:30233
oclip:onap-dublin>set aai:host-username=AAI
oclip:onap-dublin>set aai:host-password=AAI
oclip:onap-dublin>set vfc:host-url=http://159.138.8.8:30280
oclip:onap-dublin>set multicloud:host-url=http://159.138.8.8:30280

NOTE: Mostly all above entries value would be same except the IP address used in the URL, which would be ONAP Kubernetes cluster IP.

By default, SDC onboarding service does not provide node port, which is available to access from external ONAP network. To enable for external access, register the SDC onboarding service into MSB and use MSB url for sdc.onboarding:host-url.

oclip:onap-dublin> microservice-create --service-name sdcob --service-version v1.0 --service-url /onboarding-api/v1.0 --path /onboarding-api/v1.0 --node-ip 172.16.1.0 --node-port 8081

NOTE: To find the node-ip and node-port, use the following steps.

Find out SDC onboarding service IP and port details as given here:

[root@onap-dublin-vfw-93996-50c1z ~]# kubectl get pods -n onap -o wide | grep sdc-onboarding-be
dev-sdc-sdc-onboarding-be-5564b877c8-vpwr5 2/2 Running 0 29d 172.16.1.0 192.168.2.163 <none> <none>
dev-sdc-sdc-onboarding-be-cassandra-init-mtvz6 0/1 Completed 0 29d 172.16.0.220 192.168.2.163 <none> <none>
[root@onap-dublin-vfw-93996-50c1z ~]#

Note down the IP address for sdc-onboarding-be 172.16.1.0

[root@onap-dublin-vfw-93996-50c1z ~]# kubectl get services -n onap -o wide | grep sdc-onboarding-be
sdc-onboarding-be ClusterIP 10.247.198.92 <none> 8445/TCP,8081/TCP 29d app=sdc-onboarding-be,release=dev-sdc
[root@onap-dublin-vfw-93996-50c1z ~]#

Note down the port for sdc-onboarding-be 8445 8081

Similarly, other service IP and Port could be discovered like above, in case not know earlier :)

Verify these details once by typing ‘set’

oclip:onap-dublin> set

This profile would be used by user while running the test cases with ONAP setup configured in it, as below oclip –profile onap-dublin vnf-tosca-provision ….

2. Setup SDC consumer

SDC uses consumer concept to configure required VN model and service model artifacts. So following commands required to run, which will create consumer named ocomp, which is already configured in onap-dublin profile created in above steps.

oclip --product onap-dublin --profile onap-dublin sdc-consumer-create --consumer-name ocomp

NOTE: command oclip could be used in scripting mode as above or in interactive mode as used in earlier steps

3. Update the cloud and vnfm driver details

In the configuration file /opt/oclip/conf/vnf-tosca-provision.json, update the cloud and VNFM details.

{ "cloud": {
        "identity-url": "http://10.12.11.1:5000/v3",
        "username": "admin",
        "password": "password",
        "region": "RegionOVP",
        "version": "ocata",
        "tenant": "ocomp"
    },
    "vnfm":{
        "hwvnfmdriver":{
            "version": "v1.0",
            "url": "http://159.138.8.8:38088",
            "username": "admin",
            "password": "xxxx"
        },
        "gvnfmdriver":{
            "version": "v1.0",
            "url": "http://159.138.8.8:30280"
        }
    }
}

4.Configure the decided VNFRES (optional) VTP allows to configure the set of VNFRQTS to be considered while running the VNF compliance test cases in the configuration file /opt/oclip/conf/VNFRQTS.properties.

If not available, please create this file with following entries:

VNFRQTS.enabled=r02454,r04298,r07879,r09467,r13390,r23823,r26881,r27310,r35851,r40293,r43958,r66070,r77707,r77786,r87234,r10087,r21322,r26885,r40820,r35854,r65486,r17852,r46527,r15837,r54356,r67895,r95321,r32155,r01123,r51347,r787965,r130206
pnfreqs.enabled=r10087,r87234,r35854,r15837,r17852,r293901,r146092,r57019,r787965,r130206
# ignored all chef and ansible related tests
vnferrors.ignored=
pnferrors.ignored=
Running the TOSCA VNF Test

Every test provided in VTP is given with guidelines on how to use it. On every execution of test cases, use the following additional arguments based on requirements

  • --product onap-dublin - It helps VTP choose the test cases written for onap-dublin version

  • --profile onap-dublin - It helps VTP to use the profile settings provided by admin (optional)

  • --request-id - It helps VTP to track the progress of the test cases execution and user could use this id for same. (optional)

So, final test case execution would be as below. To find the test case arguments details, run second command below.

oclip --product onap-dublin --profile onap-dublin --request-id req-1 <test case name> <test case arguments>
oclip --product onap-dublin <test case name> --help
Running TOSCA VNF Compliance Testing

To run compliance test as below with given CSAR file

It will produce the result format as below:

{
    "date": "Fri Sep 20 17:34:24 CST 2019",
    "criteria": "PASS",
    "contact": "ONAP VTP Team onap-discuss@lists.onap.org",
    "results": [
    {
        "description": "V2.4.1 (2018-02)",
        "passed": true,
        "vnfreqName": "SOL004",
        "errors": []
    },
    {
        "description": "If the VNF or PNF CSAR Package utilizes Option 2 for package security, then the complete CSAR file MUST be digitally signed with the VNF or PNF provider private key. The VNF or PNF provider delivers one zip file consisting of the CSAR file, a signature file and a certificate file that includes the VNF or PNF provider public key. The certificate may also be included in the signature container, if the signature format allows that. The VNF or PNF provider creates a zip file consisting of the CSAR file with .csar extension, signature and certificate files. The signature and certificate files must be siblings of the CSAR file with extensions .cms and .cert respectively.\n",
        "passed": true,
        "vnfreqName": "r787965",
        "errors": []
    }
    ],
    "platform": "VNFSDK - VNF Test Platform (VTP) 1.0",
    "vnf": {
    "mode": "WITH_TOSCA_META_DIR",
    "vendor": "ONAP",
    "name": null,
    "type": "TOSCA",
    "version": null
    }
}

In case of errors, the errors section will have list of details as below. Each error block, will be given with error code and error details. Error code would be very useful to provide the troubleshooting guide in future. Note, to generate the test result in OVP archieve format, its recommended to run this compliance test with request-id similar to running validation test as below.

[
{
    "vnfreqNo": "R66070",
    "code": "0x1000",
    "message": "MissinEntry-Definitions file",
    "lineNumber": -1
}
]
Running TOSCA VNF Validation Testing

VTP provides validation test case with following modes:

_images/tosca_vnf_test_flow.png
  • setup: Create requires Vendor, Service Subscription and VNF cloud in ONAP

  • standup: From the given VSP csar, VNF csar and NS csar, it creates VF Model, NS Model and NS service

  • cleanup: Remove those entries created during provision

  • provision: Runs setup -> standup

  • validate: Runs setup -> standup -> cleanup

  • checkup: mode helps to verify automation is deployed properly.

For OVP badging, validate mode would be used as below:

oclip --request-id WkVVu9fD--product onap-dublin --profile onap-dublin vnf-tosca-provision --vsp <vsp csar> --vnf-csar <v

Validation testing would take for a while to complete the test execution, so user could use the above given request-id, to tracking the progress as below:

oclip execution-list --request-id WkVVu9fD
+------------+------------------------+--------------+------------------+------------------------------+--------------+------------+--------------------------+--------------------------+
|request-id  |execution-id            |product       |service           |command                       |profile       |status      |start-time                |end-time                  |
+------------+------------------------+--------------+------------------+------------------------------+--------------+------------+--------------------------+--------------------------+
|WkVVu9fD    |WkVVu9fD-1568731678753  |onap-dublin   |vnf-validation    |vnf-tosca-provision           |              |in-progress |2019-09-17T14:47:58.000   |                        |
+------------+------------------------+--------------+------------------+------------------------------+--------------+------------+--------------------------+--------------------------+
|WkVVu9fD    |WkVVu9fD-1568731876397  |onap-dublin   |sdc.catalog       |service-model-test-request    |onap-dublin   |in-progress |2019-09-17T14:51:16.000   |                          |
+------------+------------------------+--------------+------------------+------------------------------+--------------+------------+--------------------------+--------------------------+
|WkVVu9fD    |WkVVu9fD-1568731966966  |onap-dublin   |sdc.onboarding    |vsp-archive                   |onap-dublin   |completed   |2019-09-17T14:52:46.000   |2019-09-17T14:52:47.000   |
+------------+------------------------+--------------+------------------+------------------------------+--------------+------------+--------------------------+--------------------------+
|WkVVu9fD    |WkVVu9fD-1568731976982  |onap-dublin   |aai               |subscription-delete           |onap-dublin   |completed   |2019-09-17T14:52:56.000   |2019-09-17T14:52:57.000   |
+------------+------------------------+--------------+------------------+------------------------------+--------------+------------+--------------------------+--------------------------+
|WkVVu9fD    |WkVVu9fD-1568731785780  |onap-dublin   |aai               |vnfm-create                   |onap-dublin   |completed   |2019-09-17T14:49:45.000   |2019-09-17T14:49:46.000   |
......

While executing the test cases, VTP provides unique execution-id (2nd column) for each step. As you note in the example above, some steps are in-progress, while others are completed already. If there is error then status will be set to failed.

To find out the foot-print of each step, following commands are available:

oclip execution-show-out --execution-id WkVVu9fD-1568731785780       - Reports the standard output logs
oclip execution-show-err --execution-id WkVVu9fD-1568731785780        - Reports the standard error logs
oclip execution-show-debug --execution-id WkVVu9fD-1568731785780  - Reports the debug details like HTTP request and responseoclip execution-show --execution-id WkVVu9fD-1568731785780              - Reports the complete foot-print of inputs, outputs of steps

Track the progress of the vnf-tosca-provision test cases until its completed. Then the out of the validation test cases could be retrieved as below:

oclip execution-show --execution-id WkVVu9fD-1568731678753              - use vnf tosca test case execution id here

It will provides the output format as below:

{
"output": {
    "ns-id": null,
    "vnf-id": "",
    "vnfm-driver": "hwvnfmdriver",
    "vnf-vendor-name": "huawei",
    "onap-objects": {
    "ns_instance_id": null,
    "tenant_version": null,
    "service_type_id": null,
    "tenant_id": null,
    "subscription_version": null,
    "esr_vnfm_id": null,
    "location_id": null,
    "ns_version": null,
    "vnf_status": "active",
    "entitlement_id": null,
    "ns_id": null,
    "cloud_version": null,
    "cloud_id": null,
    "vlm_version": null,
    "esr_vnfm_version": null,
    "vlm_id": null,
    "vsp_id": null,
    "vf_id": null,
    "ns_instance_status": "active",
    "service_type_version": null,
    "ns_uuid": null,
    "location_version": null,
    "feature_group_id": null,
    "vf_version": null,
    "vsp_version": null,
    "agreement_id": null,
    "vf_uuid": null,
    "ns_vf_resource_id": null,
    "vsp_version_id": null,
    "customer_version": null,
    "vf_inputs": null,
    "customer_id": null,
    "key_group_id": null,
    },
    "vnf-status": "active",
    "vnf-name": "vgw",
    "ns-status": "active"
},
"input": {
    "mode": "validate",
    "vsp": "/tmp/data/vtp-tmp-files/1568731645518.csar",
    "vnfm-driver": "hwvnfmdriver",
    "config-json": "/opt/oclip/conf/vnf-tosca-provision.json",
    "vnf-vendor-name": "huawei",
    "ns-csar": "/tmp/data/vtp-tmp-files/1568731660745.csar",
    "onap-objects": "{}",
    "timeout": "600000",
    "vnf-name": "vgw",
    "vnf-csar": "/tmp/data/vtp-tmp-files/1568731655310.csar"
},
"product": "onap-dublin",
"start-time": "2019-09-17T14:47:58.000",
"service": "vnf-validation",
"end-time": "2019-09-17T14:53:46.000",
"request-id": "WkVVu9fD-1568731678753",
"command": "vnf-tosca-provision",
"status": "completed"
}
Reporting Results

VTP provides translation tool to migrate the VTP result into OVP portal format and generates the tar file for the given test case execution. Please refer https://github.com/onap/vnfsdk-refrepo/tree/master/vnfmarket-be/deployment/vtp2ovp for more details.

Once tar is generated, it can be used to submit into OVP portal https://vnf-verified.lfnetworking.org/

Requirement List

This appendix provides a consolidated list of requirements that can be searched and exported in a variety of formats.

Additionally, a JSON version of the requirements can be downloaded here.

ID

Content

Target

Keyword

Section Name

R-00011

A VNF's Heat Orchestration Template's parameter defined in a nested YAML file **SHOULD NOT** have a parameter constraint defined.

VNF

SHOULD NOT

constraints

R-00068

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.

VNF or PNF DOCUMENTATION PACKAGE

MUST

Resource Description

R-00098

The VNF **MUST NOT** impact the ability of the VNF to provide service/function due to a single container restart.

VNF

MUST NOT

All Layer Redundancy

R-00156

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

VNF or PNF DOCUMENTATION PACKAGE

MUST

Resource Description

R-00228

A VNF's Heat Orchestration Template **MAY** reference the nested heat statically by repeated definition.

VNF

MAY

Nested Heat Template Requirements

R-00606

A VNF **MAY** be connected to zero, one or more than one ONAP external network.

VNF

MAY

External Networks

R-00977

A VNF's Heat Orchestration Template's ``{network-role}`` **MUST NOT** be a substring of ``{vm-type}``.

VNF

MUST NOT

{network-role}

R-01101

A VNF's Heat Orchestration Template **MAY** reference the nested heat dynamically using the resource ``OS::Heat::ResourceGroup``.

VNF

MAY

Nested Heat Template Requirements

R-01123

The VNF or PNF CSAR package Manifest file **MUST** contain: VNF or PNF package meta-data, a list of all artifacts (both internal and external) entry's including their respected URI's, as specified in ETSI GS NFV-SOL 004

VNF or PNF CSAR PACKAGE

MUST

VNF or PNF Package Contents

R-01334

The VNF or PNF **MAY** conform to the NETCONF RFC 5717, "Partial Lock Remote Procedure Call".

VNF or PNF

MAY

NETCONF Server Requirements

R-01359

A VNF's Heat Orchestration Template that contains an ``OS::Nova:Server`` resource **MAY** define a parameter for the property ``availability_zone`` that is not utilized in any ``OS::Nova::Server`` resources in the Heat Orchestration Template.

VNF

MAY

Property: availability_zone

R-01382

The VNF or PNF **MUST** allow the entire configuration of the VNF or PNF to be retrieved via NETCONF's <get-config> and <edit-config>, independently of whether it was configured via NETCONF or other mechanisms.

VNF or PNF

MUST

NETCONF Server Requirements

R-01455

When a VNF's Heat Orchestration Template creates a Virtual Machine (i.e., ``OS::Nova::Server``), each "class" of VMs **MUST** be assigned a VNF unique ``{vm-type}``; where "class" defines VMs that **MUST** have the following identical characteristics: 1.) ``OS::Nova::Server`` resource property ``flavor`` value 2.) ``OS::Nova::Server`` resource property ``image`` value 3.) Cinder Volume attachments - Each VM in the "class" **MUST** have the identical Cinder Volume configuration 4.) Network attachments and IP address requirements - Each VM in the "class" **MUST** have the identical number of ports connecting to the identical networks and requiring the identical IP address configuration.

VNF

MUST

{vm-type}

R-01478

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.

VNF or PNF DOCUMENTATION PACKAGE

MUST

Resource Control Loop

R-01556

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.

VNF or PNF DOCUMENTATION PACKAGE

MUST

Resource Control Loop

R-01896

A VNF's Heat Orchestration Template's parameter values that are constant across all deployments **MUST** be declared in a Heat Orchestration Template Environment File.

VNF

MUST

Scope of a Heat Orchestration Template

R-02164

When a VNF's Heat Orchestration Template's Contrail resource ``OS::ContrailV2::InstanceIp`` and/or ``OS::ContrailV2::VirtualMachineInterface`` contains the property ``virtual_network_refs`` that references an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), the property value **MUST** be obtained by a ``get_param`` and the property parameter * **MUST** follow the format ``{network-role}_net_fqdn`` * **MUST** be declared as type ``string``

VNF

MUST

ONAP External Networks

R-02170

The VNF **MUST** use, whenever possible, standard implementations of security applications, protocols, and formats, e.g., S/MIME, TLS, SSH, IPSec, X.509 digital certificates for cryptographic implementations. These implementations must be purchased from reputable vendors or obtained from reputable open source communities and must not be developed in-house.

VNF

MUST

VNF Data Protection Requirements

R-02360

The VNFC **MUST** be designed as a standalone, executable process.

VNF

MUST

VNF Design

R-02454

The VNF **MUST** support the existence of multiple major/minor versions of the VNF software and/or sub-components and interfaces that support both forward and backward compatibility to be transparent to the Service Provider usage.

VNF

MUST

Deployment Optimization

R-025941

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.

VNF or PNF PROVIDER

MUST

Resource Description

R-02597

The VNF or PNF **MUST** implement the protocol operation: ``lock(target)`` - Lock the configuration data store target.

VNF or PNF

MUST

NETCONF Server Requirements

R-02651

The VNF or PNF Provider's Ansible playbooks **SHOULD** use available backup capabilities 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.

VNF or PNF PROVIDER

SHOULD

Ansible Playbook Requirements

R-02691

A VNF's Heat Orchestration Template's ``OS::Nova::Server`` resource property ``metadata`` key/value pair ``workload_context`` parameter ``workload_context`` **MUST NOT** be enumerated in the Heat Orchestration Template's environment file.

VNF

MUST NOT

workload_context

R-02997

The VNF **MUST** preserve their persistent data. Running VMs will not be backed up in the Network Cloud infrastructure.

VNF

MUST

VNF Devops

R-03251

A VNF's Heat Orchestration Template's Resource ``OS::Cinder::Volume`` **MAY** be defined in a Cinder Volume Module.

VNF

MAY

ONAP VNF Modularity Overview

R-03324

A VNF's Heat Orchestration template's Environment File **MUST** contain the ``parameters:`` section.

VNF

MUST

Environment File Format

R-03465

The VNF or PNF **MUST** release locks to prevent permanent lock-outs when the corresponding <partial-unlock> operation succeeds if ":partial-lock" is supported.

VNF or PNF

MUST

NETCONF Server Requirements

R-03595

A VNF's Heat Orchestration Template's Resource ``OS::Neutron::SecurityGroup`` that is applicable to more than one ``{vm-type}`` and one ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), the ``OS::Neutron::SecurityGroup`` Resource ID **SHOULD** use the naming convention * ``{network-role}_security_group`` where * ``{network-role}`` is the network-role of the ONAP external network

VNF

SHOULD

OS::Neutron::SecurityGroup

R-03656

A VNF's Heat Orchestration Template's Resource ``OS::Heat::SoftwareConfig`` Resource ID **MAY** use the naming convention * ``{vm-type}_RSC`` where * ``{vm-type}`` is the vm-type * ``RSC`` signifies that it is the Resource Software Config

VNF

MAY

OS::Heat::SoftwareConfig

R-03954

The VNF **MUST** survive any single points of failure within the Network Cloud (e.g., virtual NIC, VM, disk failure).

VNF

MUST

All Layer Redundancy

R-04158

The VNF or PNF **MUST** conform to the NETCONF RFC 4742, "Using the NETCONF Configuration Protocol over Secure Shell (SSH)".

VNF or PNF

MUST

NETCONF Server Requirements

R-04298

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

VNF

MUST

Testing

R-04344

A VNF's Nested YAML file **MAY** be invoked by more than one of a VNF's Heat Orchestration Templates (when the VNF is composed of two or more Heat Orchestration Templates).

VNF

MAY

Nested Heat Template Requirements

R-04492

The VNF **MUST** generate security audit logs that can be sent to Security Analytics Tools for analysis.

VNF

MUST

VNF Security Analytics Requirements

R-04697

When the VNF's Heat Orchestration Template's Resource ``OS::Neutron::Port`` is attaching to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), and an IPv4 address is assigned using the property ``fixed_ips`` map property ``ip_address`` and the parameter type is defined as a ``comma_delimited_list``, the parameter name **MUST** follow the naming convention * ``{vm-type}_{network-role}_ips`` where * ``{vm-type}`` is the {vm-type} associated with the ``OS::Nova::Server`` * ``{network-role}`` is the {network-role} of the ONAP external network

VNF

MUST

Property: fixed_ips, Map Property: ip_address

R-04747

A VNF's Heat Orchestration Template's Resource ``OS::Heat::CloudConfig`` Resource ID **MUST** contain the ``{vm-type}``.

VNF

MUST

OS::Heat::CloudConfig

R-04982

The VNF **MUST NOT** include an authentication credential, e.g., password, in the security audit logs, even if encrypted.

VNF

MUST NOT

VNF Security Analytics Requirements

R-05050

A VNF's Heat Orchestration Templates intrinsic function ``get_file`` <content key> **MAY** be used: * more than once in a VNF's Heat Orchestration Template * in two or more of a VNF's Heat Orchestration Templates * in a VNF's Heat Orchestration Templates nested YAML file

VNF

MAY

Heat Files Support (get_file)

R-05201

When a VNF connects to two or more unique networks, each network **MUST** be assigned a unique ``{network-role}`` in the context of the VNF for use in the VNF's Heat Orchestration Template.

VNF

MUST

{network-role}

R-05257

A VNF's Heat Orchestration Template's **MUST NOT** contain the Resource ``OS::Neutron::FloatingIP``.

VNF

MUST NOT

VIP Assignment, ONAP External Networks

R-06327

The VNF **MUST** respond to a "drain VNFC" [#4.5.2]_ command against a specific VNFC, preventing new session from reaching the targeted VNFC, with no disruption to active sessions on the impacted VNFC, if a VNF provides a load balancing function across multiple instances of its VNFCs. This is used to support scenarios such as proactive maintenance with no user impact.

VNF

MUST

VNF Devops

R-06413

The VNF **MUST** log the field "service or program used for access" in the security audit logs.

VNF

MUST

VNF Security Analytics Requirements

R-06613

A VNF's Heat Orchestration Template's parameter defined in a non-nested YAML file as type ``boolean`` **MAY** have a parameter constraint defined.

VNF

MAY

constraints

R-06668

The VNF **MUST** handle the start or restart of VNFC instances in any order with each VNFC instance establishing or re-establishing required connections or relationships with other VNFC instances and/or VNFs required to perform the VNF function/role without requiring VNFC instance(s) to be started/restarted in a particular order.

VNF

MUST

Application Resilient Error Handling

R-06885

The VNF **SHOULD** support the ability to scale down a VNFC pool without jeopardizing active sessions. Ideally, an active session should not be tied to any particular VNFC instance.

VNF

SHOULD

System Resource Optimization

R-06924

The VNF or PNF producing VES events **MUST** deliver VES events as it becomes available or according to the configured measurement interval.

VNF or PNF

MUST

Event Delivery Requirements

R-07251

The VNF or PNF **MUST** support APPC/SDN-C ``ResumeTraffic`` command.

VNF or PNF

MUST

Lifecycle Management Related Commands

R-07443

A VNF's Heat Orchestration Templates' Cinder Volume Module Output Parameter's name and type **MUST** match the input parameter name and type in the corresponding Base Module or Incremental Module.

VNF

MUST

ONAP Volume Module Output Parameters

R-07507

A VNF's Heat Orchestration Template's ``OS::Nova::Server`` resource property ``metadata`` key/value pair ``vnf_id`` parameter **MUST** be declared as ``vnf_id`` and the parameter **MUST** be defined as type: ``string``.

VNF

MUST

vnf_id

R-07545

The VNF or PNF **MUST** support all operations, administration and management (OAM) functions available from the supplier for VNFs or PNFs using the supplied YANG code and associated NETCONF servers.

VNF or PNF

MUST

NETCONF Server Requirements

R-07617

The VNF **MUST** log success and unsuccessful creation, removal, or change to the inherent privilege level of users.

VNF

MUST

VNF Security Analytics Requirements

R-08315

The VNF **SHOULD** use redundant connection pooling to connect to any backend data source that can be switched between pools in an automated/scripted fashion to ensure high availability of the connection to the data source.

VNF

SHOULD

Intelligent Transaction Distribution & Management

R-08775

A VNF's Heat Orchestration Template's Resource ``OS::Neutron::SecurityGroup`` that is applicable to one ``{vm-type}`` and more than one network (ONAP internal network and/or ONAP external network), the ``OS::Neutron::SecurityGroup`` Resource ID **SHOULD** use the naming convention * ``{vm-type}_security_group`` where * ``{vm-type}`` is the vm-type

VNF

SHOULD

OS::Neutron::SecurityGroup

R-08975

A VNF's Heat Orchestration Template's Resource ``OS::Heat::SoftwareConfig`` Resource ID **MUST** contain the ``{vm-type}``.

VNF

MUST

OS::Heat::SoftwareConfig

R-09209

The VNF or PNF Provider's Ansible playbooks **MUST** store any playbook configuration data that requires encryption (passwords, secrets, etc.) in a JSON (.json), YAML (.yaml|.yml) or INI (.ini) file, which will be placed in ``<VNF type>/<Version>/ansible/vars`` directory.

VNF or PNF PROVIDER

MUST

Ansible Playbook Requirements

R-09467

The VNF **MUST** utilize only NCSP standard compute flavors. [#4.5.1]_

VNF

MUST

VNF Devops

R-09811

A VNF's Heat Orchestration Template's ``OS::Nova::Server`` resource property ``metadata`` key/value pair ``vf_module_index`` **MUST NOT** have parameter constraints defined.

VNF

MUST NOT

vf_module_index

R-100000

The VNF's Heat Orchestration Template's resource ``OS::ContrailV2::InstanceIp`` property ``instance_ip_address`` parameter **MUST** be declared as either type ``string`` or type ``comma_delimited_list``.

VNF

MUST

Resource OS::ContrailV2::InstanceIp Property instance_ip_address

R-100010

When the VNF's Heat Orchestration Template's Resource ``OS::ContrailV2::InstanceIp`` is assigning an IP address to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), and an IPv4 address is assigned using the property ``instance_ip_address`` and the parameter type is defined as a string, the parameter name **MUST** follow the naming convention * ``{vm-type}_{network-role}_ip_{index}`` where * ``{vm-type}`` is the {vm-type} associated with the ``OS::Nova::Server`` * ``{network-role}`` is the {network-role} of the ONAP external network * ``{index}`` is a numeric value that **MUST** start at zero in a VNF's Heat Orchestration Template and **MUST** increment by one

VNF

MUST

Resource OS::ContrailV2::InstanceIp Property instance_ip_address

R-100020

The VNF's Heat Orchestration Template's Resource ``OS::ContrailV2::InstanceIp`` property ``instance_ip_address`` parameter ``{vm-type}_{network-role}_ip_{index}`` **MUST NOT** be enumerated in the VNF's Heat Orchestration Template's Environment File.

VNF

MUST NOT

Resource OS::ContrailV2::InstanceIp Property instance_ip_address

R-100030

When the VNF's Heat Orchestration Template's Resource ``OS::ContrailV2::InstanceIp`` is assigning an IP address to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), and an IPv4 address is assigned using the property ``instance_ip_address`` and the parameter type is defined as a ``comma_delimited_list``, the parameter name **MUST** follow the naming convention * ``{vm-type}_{network-role}_ips`` where * ``{vm-type}`` is the {vm-type} associated with the ``OS::Nova::Server`` * ``{network-role}`` is the {network-role} of the ONAP external network

VNF

MUST

Resource OS::ContrailV2::InstanceIp Property instance_ip_address

R-100040

The VNF's Heat Orchestration Template's Resource ``OS::ContrailV2::InstanceIp`` property ``instance_ip_address`` parameter ``{vm-type}_{network-role}_ips`` **MUST NOT** be enumerated in the VNF's Heat Orchestration Template's Environment File.

VNF

MUST NOT

Resource OS::ContrailV2::InstanceIp Property instance_ip_address

R-100050

When the VNF's Heat Orchestration Template's Resource ``OS::ContrailV2::InstanceIp`` is assigning an IP address to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), and an IPv6 address is assigned using the property ``instance_ip_address`` and the parameter type is defined as a string, the parameter name **MUST** follow the naming convention * ``{vm-type}_{network-role}_v6_ip_{index}`` where * ``{vm-type}`` is the {vm-type} associated with the ``OS::Nova::Server`` * ``{network-role}`` is the {network-role} of the ONAP external network * ``{index}`` is a numeric value that **MUST** start at zero in a VNF's Heat Orchestration Template and **MUST** increment by one

VNF

MUST

Resource OS::ContrailV2::InstanceIp Property instance_ip_address

R-100060

The VNF's Heat Orchestration Template's Resource ``OS::ContrailV2::InstanceIp`` property ``instance_ip_address`` parameter ``{vm-type}_{network-role}_v6_ip_{index}`` **MUST NOT** be enumerated in the VNF's Heat Orchestration Template's Environment File.

VNF

MUST NOT

Resource OS::ContrailV2::InstanceIp Property instance_ip_address

R-100070

When the VNF's Heat Orchestration Template's Resource ``OS::ContrailV2::InstanceIp`` is assigning an IP address to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), and an IPv6 address is assigned using the property ``instance_ip_address`` and the parameter type is defined as a ``comma_delimited_list``, the parameter name **MUST** follow the naming convention * ``{vm-type}_{network-role}_v6_ips`` where * ``{vm-type}`` is the {vm-type} associated with the OS::Nova::Server * ``{network-role}`` is the {network-role} of the ONAP external network

VNF

MUST

Resource OS::ContrailV2::InstanceIp Property instance_ip_address

R-100080

The VNF's Heat Orchestration Template's Resource ``OS::ContrailV2::InstanceIp`` property ``instance_ip_address`` parameter ``{vm-type}_{network-role}_v6_ips`` **MUST NOT** be enumerated in the VNF's Heat Orchestration Template's Environment File.

VNF

MUST NOT

Resource OS::ContrailV2::InstanceIp Property instance_ip_address

R-100090

When the VNF's Heat Orchestration Template's Resource ``OS::ContrailV2::InstanceIp`` is assigning an IP address to an ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666), and an IPv4 address is assigned using the property ``instance_ip_address`` and the parameter type is defined as a ``string``, the parameter name **MUST** follow the naming convention * ``{vm-type}_int_{network-role}_ip_{index}`` where * ``{vm-type}`` is the {vm-type} associated with the ``OS::Nova::Server`` * ``{network-role}`` is the {network-role} of the ONAP internal network * ``{index}`` is a numeric value that **MUST** start at zero in a VNF's Heat Orchestration Template and **MUST** increment by one

VNF

MUST

Resource OS::ContrailV2::InstanceIp Property instance_ip_address

R-100100

The VNF's Heat Orchestration Template's Resource ``OS::ContrailV2::InstanceIp`` property ``instance_ip_address`` parameter ``{vm-type}_int_{network-role}_ip_{index}`` **MUST** be enumerated in the VNF's Heat Orchestration Template's Environment File.

VNF

MUST

Resource OS::ContrailV2::InstanceIp Property instance_ip_address

R-100110

When the VNF's Heat Orchestration Template's Resource ``OS::ContrailV2::InstanceIp`` is assigning an IP address to an ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666), and an IPv4 address is assigned using the property ``instance_ip_address`` and the parameter type is defined as a ``comma_delimited_list``, the parameter name **MUST** follow the naming convention * ``{vm-type}_int_{network-role}_ips`` where * ``{vm-type}`` is the {vm-type} associated with the ``OS::Nova::Server`` * ``{network-role}`` is the {network-role} of the ONAP internal network

VNF

MUST

Resource OS::ContrailV2::InstanceIp Property instance_ip_address

R-100120

The VNF's Heat Orchestration Template's Resource ``OS::ContrailV2::InstanceIp`` property ``instance_ip_address`` parameter ``{vm-type}_int_{network-role}_int_ips`` **MUST** be enumerated in the VNF's Heat Orchestration Template's Environment File.

VNF

MUST

Resource OS::ContrailV2::InstanceIp Property instance_ip_address

R-100130

When the VNF's Heat Orchestration Template's Resource ``OS::ContrailV2::InstanceIp`` is assigning an IP address to an ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666), and an IPv6 address is assigned using the property ``instance_ip_address`` and the parameter type is defined as a ``string``, the parameter name **MUST** follow the naming convention * ``{vm-type}_int_{network-role}_v6_ip_{index}`` where * ``{vm-type}`` is the {vm-type} associated with the ``OS::Nova::Server`` * ``{network-role}`` is the {network-role} of the ONAP internal network * ``{index}`` is a numeric value that **MUST** start at zero in a VNF's Heat Orchestration Template and **MUST** increment by one

VNF

MUST

Resource OS::ContrailV2::InstanceIp Property instance_ip_address

R-100140

The VNF's Heat Orchestration Template's Resource ``OS::ContrailV2::InstanceIp`` property ``instance_ip_address`` parameter ``{vm-type}_int_{network-role}_v6_ip_{index}`` **MUST** be enumerated in the VNF's Heat Orchestration Template's Environment File.

VNF

MUST

Resource OS::ContrailV2::InstanceIp Property instance_ip_address

R-100150

When the VNF's Heat Orchestration Template's Resource ``OS::ContrailV2::InstanceIp`` is assigning an IP address to an ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666), and an IPv6 address is assigned using the property ``instance_ip_address`` and the parameter type is defined as a ``comma_delimited_list``, the parameter name **MUST** follow the naming convention * ``{vm-type}_int_{network-role}_v6_ips`` where * ``{vm-type}`` is the {vm-type} associated with the ``OS::Nova::Server`` * ``{network-role}`` is the {network-role} of the ONAP internal network

VNF

MUST

Resource OS::ContrailV2::InstanceIp Property instance_ip_address

R-100160

The VNF's Heat Orchestration Template's Resource ``OS::ContrailV2::InstanceIp`` property ``instance_ip_address`` map property ``ip_address`` parameter ``{vm-type}_int_{network-role}_v6_ips`` **MUST** be enumerated in the VNF's Heat Orchestration Template's Environment File.

VNF

MUST

Resource OS::ContrailV2::InstanceIp Property instance_ip_address

R-100170

The VNF's Heat Orchestration Template's Resource ``OS::ContrailV2::InstanceIp`` property ``instance_ip_address`` parameter associated with an ONAP external network, i.e., * ``{vm-type}_{network-role}_ip_{index}`` * ``{vm-type}_{network-role}_v6_ip_{index}`` * ``{vm-type}_{network-role}_ips`` * ``{vm-type}_{network-role}_v6_ips`` **MUST NOT** be enumerated in the Heat Orchestration Template's Environment File. ONAP provides the IP address assignments at orchestration time.

VNF

MUST NOT

Resource OS::ContrailV2::InstanceIp Property instance_ip_address

R-100180

The VNF's Heat Orchestration Template's Resource ``OS::ContrailV2::InstanceIp`` property ``instance_ip_address`` parameter associated with an ONAP internal network, i.e., * ``{vm-type}_int_{network-role}_ip_{index}`` * ``{vm-type}_int_{network-role}_v6_ip_{index}`` * ``{vm-type}_int_{network-role}_ips`` * ``{vm-type}_int_{network-role}_v6_ips`` **MUST** be enumerated in the Heat Orchestration Template's Environment File and IP addresses **MUST** be assigned.

VNF

MUST

Resource OS::ContrailV2::InstanceIp Property instance_ip_address

R-100190

The VNF's Heat Orchestration Template's resource ``OS::ContrailV2::InstanceIp`` property ``subnet_uuid`` parameter **MUST** be declared type ``string``.

VNF

MUST

Resource OS::ContrailV2::InstanceIp Property subnet_uuid

R-100200

When the VNF's Heat Orchestration Template's resource ``OS::ContrailV2::InstanceIp`` is assigning an IP address to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), and an IPv4 address is being cloud assigned by OpenStack's DHCP Service and the ONAP external network IPv4 subnet is to be specified using the property ``subnet_uuid``, the parameter **MUST** follow the naming convention * ``{network-role}_subnet_id`` where * ``{network-role}`` is the network role of the ONAP external network.

VNF

MUST

Resource OS::ContrailV2::InstanceIp Property subnet_uuid

R-100210

The VNF's Heat Orchestration Template's Resource ``OS::ContrailV2::InstanceIp`` property ``subnet_uuid`` parameter ``{network-role}_subnet_id`` **MUST NOT** be enumerated in the VNF's Heat Orchestration Template's Environment File.

VNF

MUST NOT

Resource OS::ContrailV2::InstanceIp Property subnet_uuid

R-100220

When the VNF's Heat Orchestration Template's resource ``OS::ContrailV2::InstanceIp`` is assigning an IP address to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), and an IPv6 address is being cloud assigned by OpenStack's DHCP Service and the ONAP external network IPv6 subnet is to be specified using the property ``subnet_uuid``, the parameter **MUST** follow the naming convention * ``{network-role}_v6_subnet_id`` where * ``{network-role}`` is the network role of the ONAP external network.

VNF

MUST

Resource OS::ContrailV2::InstanceIp Property subnet_uuid

R-100230

The VNF's Heat Orchestration Template's Resource ``OS::ContrailV2::InstanceIp`` property ``subnet_uuid`` parameter ``{network-role}_v6_subnet_id`` **MUST NOT** be enumerated in the VNF's Heat Orchestration Template's Environment File.

VNF

MUST NOT

Resource OS::ContrailV2::InstanceIp Property subnet_uuid

R-100240

When * the VNF's Heat Orchestration Template's resource ``OS::ContrailV2::InstanceIp`` in an Incremental Module is assigning an IP address to an ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666) that is created in the Base Module, AND * an IPv4 address is being cloud assigned by OpenStack's DHCP Service AND * the ONAP internal network IPv4 subnet is to be specified using the property ``subnet_uuid``, the parameter **MUST** follow the naming convention * ``int_{network-role}_subnet_id`` where * ``{network-role}`` is the network role of the ONAP internal network Note that the parameter **MUST** be defined as an ``output`` parameter in the base module.

VNF

MUST

Resource OS::ContrailV2::InstanceIp Property subnet_uuid

R-100250

The VNF's Heat Orchestration Template's Resource ``OS::ContrailV2::InstanceIp`` property ``subnet_uuid`` parameter ``int_{network-role}_subnet_id`` **MUST NOT** be enumerated in the VNF's Heat Orchestration Template's Environment File.

VNF

MUST NOT

Resource OS::ContrailV2::InstanceIp Property subnet_uuid

R-100260

When * the VNF's Heat Orchestration Template's resource ``OS::ContrailV2::InstanceIp`` in an Incremental Module is attaching to an ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666) that is created in the Base Module, AND * an IPv6 address is being cloud assigned by OpenStack's DHCP Service AND * the ONAP internal network IPv6 subnet is to be specified using the property ``subnet_uuid``, the parameter **MUST** follow the naming convention * ``int_{network-role}_v6_subnet_id`` where ``{network-role}`` is the network role of the ONAP internal network. Note that the parameter **MUST** be defined as an ``output`` parameter in the base module.

VNF

MUST

Resource OS::ContrailV2::InstanceIp Property subnet_uuid

R-100270

The VNF's Heat Orchestration Template's Resource ``OS::ContrailV2::InstanceIp`` property ``subnet_uuid`` parameter ``int_{network-role}_v6_subnet_id`` **MUST NOT** be enumerated in the VNF's Heat Orchestration Template's Environment File.

VNF

MUST NOT

Resource OS::ContrailV2::InstanceIp Property subnet_uuid

R-100280

If a VNF's Heat Orchestration Template's resource ``OS::ContrailV2::VirtualMachineInterface`` is attaching to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), the map property ``virtual_machine_interface_allowed_address_pairs``, ``virtual_machine_interface_allowed_address_pairs_allowed_address_pair``, ``virtual_machine_interface_allowed_address_pairs_allowed_address_pair_ip``, ``virtual_machine_interface_allowed_address_pairs_allowed_address_pair_ip_ip_prefix`` parameter **MUST NOT** be enumerated in the VNF's Heat Orchestration Template's Environment File.

VNF

MUST NOT

ONAP External Networks

R-100310

When the VNF's Heat Orchestration Template's resource ``OS::ContrailV2::VirtualMachineInterface`` is attaching to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), and an IPv4 Virtual IP (VIP) is required to be supported by the ONAP data model, the map property ``virtual_machine_interface_allowed_address_pairs``, ``virtual_machine_interface_allowed_address_pairs_allowed_address_pair``, ``virtual_machine_interface_allowed_address_pairs_allowed_address_pair_ip``, ``virtual_machine_interface_allowed_address_pairs_allowed_address_pair_ip_ip_prefix`` parameter name **MUST** follow the naming convention * ``{vm-type}_{network-role}_floating_ip`` where * ``{vm-type}`` is the {vm-type} associated with the ``OS::Nova::Server`` * ``{network-role}`` is the {network-role} of the ONAP external network And the parameter **MUST** be declared as type ``string``. The ONAP data model can only support one IPv4 VIP address.

VNF

MUST

ONAP External Networks

R-100330

When the VNF's Heat Orchestration Template's resource ``OS::ContrailV2::VirtualMachineInterface`` is attaching to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), and an IPv6 Virtual IP (VIP) is required to be supported by the ONAP data model, the map property ``virtual_machine_interface_allowed_address_pairs``, ``virtual_machine_interface_allowed_address_pairs_allowed_address_pair``, ``virtual_machine_interface_allowed_address_pairs_allowed_address_pair_ip``, ``virtual_machine_interface_allowed_address_pairs_allowed_address_pair_ip_ip_prefix`` parameter name **MUST** follow the naming convention * ``{vm-type}_{network-role}_floating_v6_ip`` where * ``{vm-type}`` is the {vm-type} associated with the ``OS::Nova::Server`` * ``{network-role}`` is the {network-role} of the ONAP external network And the parameter **MUST** be declared as type ``string``. The ONAP data model can only support one IPv6 VIP address.

VNF

MUST

ONAP External Networks

R-100350

When the VNF's Heat Orchestration Template's resource ``OS::ContrailV2::VirtualMachineInterface`` is attaching to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), and the IPv4 VIP address and/or IPv6 VIP address is **not** supported by the ONAP data model, the map property ``virtual_machine_interface_allowed_address_pairs``, ``virtual_machine_interface_allowed_address_pairs_allowed_address_pair``, ``virtual_machine_interface_allowed_address_pairs_allowed_address_pair_ip``, ``virtual_machine_interface_allowed_address_pairs_allowed_address_pair_ip_ip_prefix`` * Parameter name **MAY** use any naming convention. That is, there is no ONAP mandatory parameter naming convention. * Parameter **MAY** be declared as type ``string`` or type ``comma_delimited_list``. And the ``OS::ContrailV2::VirtualMachineInterface`` resource **MUST** contain resource-level ``metadata`` (not property-level). And the ``metadata`` format **MUST** must contain the key value ``aap_exempt`` with a list of all map property ``virtual_machine_interface_allowed_address_pairs``, ``virtual_machine_interface_allowed_address_pairs_allowed_address_pair``, ``virtual_machine_interface_allowed_address_pairs_allowed_address_pair_ip``, ``virtual_machine_interface_allowed_address_pairs_allowed_address_pair_ip_ip_prefix`` parameters **not** supported by the ONAP data model.

VNF

MUST

ONAP External Networks

R-100360

When the VNF's Heat Orchestration Template's Resource ``OS::ContrailV2::VirtualMachineInterface`` is attaching to an ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666), and an IPv4 Virtual IP (VIP) address is assigned using the map property, ``virtual_machine_interface_allowed_address_pairs, virtual_machine_interface_allowed_address_pairs_allowed_address_pair, virtual_machine_interface_allowed_address_pairs_allowed_address_pair_ip, virtual_machine_interface_allowed_address_pairs_allowed_address_pair_ip_ip_prefix`` , the parameter name **MUST** follow the naming convention * ``{vm-type}_int_{network-role}_floating_ip`` where * ``{vm-type}`` is the {vm-type} associated with the OS::Nova::Server * ``{network-role}`` is the {network-role} of the ONAP internal network And the parameter **MUST** be declared as ``type: string`` and **MUST** be enumerated in the environment file. OR the parameter name **MUST** follow the naming convention * ``{vm-type}_int_{network-role}_floating_ips`` where * ``{vm-type}`` is the {vm-type} associated with the OS::Nova::Server * ``{network-role}`` is the {network-role} of the ONAP internal network And the parameter **MUST** be declared as ``type: comma_delimited_list`` and **MUST** be enumerated in the environment file.

VNF

MUST

ONAP Internal Networks

R-100370

When the VNF's Heat Orchestration Template's Resource ``OS::ContrailV2::VirtualMachineInterface`` is attaching to an ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666), and an IPv6 Virtual IP (VIP) address is assigned using the map property, ``virtual_machine_interface_allowed_address_pairs, virtual_machine_interface_allowed_address_pairs_allowed_address_pair, virtual_machine_interface_allowed_address_pairs_allowed_address_pair_ip, virtual_machine_interface_allowed_address_pairs_allowed_address_pair_ip_ip_prefix`` , the parameter name **MUST** follow the naming convention * ``{vm-type}_int_{network-role}_floating_v6_ip`` where * ``{vm-type}`` is the {vm-type} associated with the OS::Nova::Server * ``{network-role}`` is the {network-role} of the ONAP internal network And the parameter **MUST** be declared as ``type: string`` and **MUST** be enumerated in the environment file OR the parameter name **MUST** follow the naming convention * ``{vm-type}_int_{network-role}_floating_v6_ips`` where * ``{vm-type}`` is the {vm-type} associated with the OS::Nova::Server * ``{network-role}`` is the {network-role} of the ONAP internal network And the parameter **MUST** be declared as ``type: comma_delimited_list`` and **MUST** be enumerated in the environment file.

VNF

MUST

ONAP Internal Networks

R-100380

If a VNF requires the use of an SSH key created by OpenStack, the VNF Heat Orchestration Template **SHOULD** create the ``OS::Nova::Keypair`` in the base module, and expose the public key as an output value. This allows re-use of the key by ONAP when triggering scale out, recovery, or other day 1 operations.

VNF

SHOULD

Key Pairs

R-100400

A VNF's Heat Orchestration Template's ``OS::Nova::Server`` resource property metadata **SHOULD** contain the key/value pair ``vf_module_name``.

VNF

SHOULD

vf_module_name

R-100410

A VNF's Heat Orchestration Template's ``OS::Nova::Server`` resource property ``metadata`` **MAY** contain the key/value pair ``vf_module_index``.

VNF

MAY

vf_module_index

R-10087

The VNF or PNF CSAR package **MUST** include all artifacts required by ETSI GS NFV-SOL004 including Manifest file, VNFD or PNFD (or Main TOSCA/YAML based Service Template) and other optional artifacts.

VNF or PNF CSAR PACKAGE

MUST

VNF or PNF Package Contents

R-10129

The VNF or PNF **SHOULD** conform its YANG model to RFC 7223, "A YANG Data Model for Interface Management".

VNF or PNF

SHOULD

NETCONF Server Requirements

R-10173

The VNF or PNF **MUST** allow another NETCONF session to be able to initiate the release of the lock by killing the session owning the lock, using the <kill-session> operation to guard against hung NETCONF sessions.

VNF or PNF

MUST

NETCONF Server Requirements

R-103464

A VNF or PNF producing VES events that is buffering events due to an unavailable VES Event Listener **MAY** leverage to ``publishEventBatch`` operation to redeliver buffered events. Please note this can only be used when all buffered events belong to the same domain due to the restrictions in place for the operation.

VNF or PNF

MAY

Buffering and Redelivery

R-10353

The VNF or PNF **MUST** conform its YANG model to RFC 6244, "An Architecture for Network Management Using NETCONF and YANG".

VNF or PNF

MUST

NETCONF Server Requirements

R-106240

A PNF **MUST** support the pnfRegistration VES event which is required to integrate with ONAP’s PNF Plug and Play capabilities.

PNF

MUST

PNF Plug and Play

R-10834

A VNF's Heat Orchestration Template resource attribute ``property:`` **MUST NOT** use more than two levels of nested ``get_param`` intrinsic functions when deriving a property value. SDC does not support nested ``get_param`` with recursive lists (i.e., a list inside list). The second ``get_param`` in a nested lookup must directly derive its value without further calls to ``get_param`` functions. * Example of valid nesting: * ``name: {get_param: [ {vm-type}_names, {get_param : index } ] }`` * Examples of invalid nesting. SDC will not support these examples since there is an array inside array. * ``name: {get_param: [ {vm-type}_names, { get_param: [ indexlist, 0 ] } ] }`` * ``name: {get_param: [ {vm-type}_names, { get_param: [ indexlist1, { get_param: indexlist2 } ] } ] }``

VNF

MUST NOT

properties

R-11041

All parameters defined in a VNFs Nested YAML file **MUST** be passed in as properties of the resource calling the nested yaml file.

VNF

MUST

Nested Heat Template Requirements

R-11168

A VNF's Heat Orchestration Template's Resource ID that is associated with an ONAP external network **MUST** include the ``{network-role}`` as part of the resource ID.

VNF

MUST

{network-role}

R-11200

A VNF's Cinder Volume Module, when it exists, **MUST** be 1:1 with a Base module or Incremental module.

VNF

MUST

ONAP VNF Modularity Overview

R-11235

The VNF or PNF **MUST** implement the protocol operation: ``kill-session(session``- Force the termination of **session**.

VNF or PNF

MUST

NETCONF Server Requirements

R-11441

A VNF's Heat Orchestration Template's parameter type **MUST** be one of the following values: * ``string`` * ``number`` * ``json`` * ``comma_delimited_list`` * ``boolean``

VNF

MUST

type

R-11499

The VNF or PNF **MAY** fully support the XPath 1.0 specification for filtered retrieval of configuration and other database contents. The 'type' attribute within the <filter> parameter for <get> and <get-config> 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.

VNF or PNF

MAY

NETCONF Server Requirements

R-11690

When a VNF's Heat Orchestration Template's Resource ID contains an ``{index}``, the ``{index}`` is a numeric value that **MUST** start at zero and **MUST** increment by one. As stated in R-16447, *a VNF's <resource ID> MUST be unique across all Heat Orchestration Templates and all HEAT Orchestration Template Nested YAML files that are used to create the VNF*. While the ``{index}`` will start at zero in the VNF, the ``{index}`` may not start at zero in a given Heat Orchestration Template or HEAT Orchestration Template Nested YAML file.

VNF

MUST

Resource IDs

R-11790

The VNF **MUST** support ONAP Controller's **Restart (stop/start or reboot)** command.

VNF

MUST

Virtual Function - Container Recovery Requirements

R-118669

Login access (e.g., shell access) to the operating system layer, whether interactive or as part of an automated process, **MUST** be through an encrypted protocol such as SSH or TLS.

VNF

MUST

VNF General Security Requirements

R-120182

A VNF or PNF Provider utilizing VES **MUST** indicate specific conditions that may arise, and recommend actions that may be taken at specific thresholds, or if specific conditions repeat within a specified time interval, using the semantics and syntax described by the :ref:`VES Event Registration specification <ves_event_registration_3_2>`. **NOTE:** The Service Provider may override VNF or PNF provider Event Registrations using the ONAP SDC Design Studio to finalizes Service Provider engineering rules for the processing of the VNF or PNF events. These changes may modify any of the following: * Threshold levels * Specified actions related to conditions

VNF or PNF PROVIDER

MUST

Event Definition and Registration

R-12110

The VNF **MUST NOT** use keys generated or derived from predictable functions or values, e.g., values considered predictable include user identity information, time of day, stored/transmitted data.

VNF

MUST NOT

VNF Data Protection Requirements

R-12271

The VNF or PNF **SHOULD** conform its YANG model to RFC 7223, "IANA Interface Type YANG Module".

VNF or PNF

SHOULD

NETCONF Server Requirements

R-123044

The VNF or PNF Provider **MAY** require that specific events, identified by their ``eventName``, require that certain fields, which are optional in the common event format, must be present when they are published.

VNF or PNF PROVIDER

MAY

Event Definition and Registration

R-12467

The VNF **MUST NOT** use compromised encryption algorithms. For example, SHA, DSS, MD5, SHA-1 and Skipjack algorithms. Acceptable algorithms can be found in the NIST FIPS publications (https://csrc.nist.gov/publications/fips) and in the NIST Special Publications (https://csrc.nist.gov/publications/sp).

VNF

MUST NOT

VNF Data Protection Requirements

R-12538

The VNF **SHOULD** support load balancing and discovery mechanisms in resource pools containing VNFC instances.

VNF

SHOULD

System Resource Optimization

R-12678

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.

VNF or PNF DOCUMENTATION PACKAGE

MUST

Resource Description

R-12706

The VNF or PNF **MUST** support APPC/SDN-C ``QuiesceTraffic`` command.

VNF or PNF

MUST

Lifecycle Management Related Commands

R-12709

The VNFC **SHOULD** be independently deployed, configured, upgraded, scaled, monitored, and administered by ONAP.

VNF

SHOULD

VNF Design

R-130206

If the VNF or PNF CSAR Package utilizes Option 1 for package security, then the complete CSAR file **MUST** contain a Digest (a.k.a. hash) for each of the components of the VNF or PNF package. The table of hashes is included in the package manifest file, which is signed with the VNF or PNF provider private key. In addition, the VNF or PNF provider MUST include a signing certificate that includes the VNF or PNF provider public key, following a TOSCA pre-defined naming convention and located either at the root of the archive or in a predefined location specified by the TOSCA.meta file with the corresponding entry named "ETSI-Entry-Certificate".

VNF or PNF CSAR PACKAGE

MUST

VNF or PNF Package Authenticity and Integrity

R-130645

The VNF or PNF **MUST** respect the Time To Live provided by the DNS for the VES Event Listener FQDN.

VNF or PNF

MUST

VES Listener Endpoint and DNS Resolution

R-13151

The VNF **SHOULD** disable the paging of the data requiring encryption, if possible, where the encryption of non-transient data is required on a device for which the operating system performs paging to virtual memory. If not possible to disable the paging of the data requiring encryption, the virtual memory should be encrypted.

VNF

SHOULD

VNF Data Protection Requirements

R-13194

A VNF's Heat Orchestration Template's ``OS::Nova::Server`` resource property ``metadata`` key/value pair ``environment_context`` **MUST NOT** be enumerated in the Heat Orchestration Template's environment file.

VNF

MUST NOT

environment_context

R-13196

A VNF **MAY** be composed of zero to many Incremental Modules.

VNF

MAY

ONAP VNF Modularity Overview

R-13344

The VNF **MUST** log starting and stopping of security logging.

VNF

MUST

VNF Security Analytics Requirements

R-13390

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

VNF or PNF

MUST

Configuration Management via Chef

R-13613

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

VNF

MUST

Licensing Requirements

R-13627

The VNF **MUST** monitor API invocation patterns to detect anomalous access patterns that may represent fraudulent access or other types of attacks, or integrate with tools that implement anomaly and abuse detection.

VNF

MUST

VNF Security Analytics Requirements

R-14198

A VNF's Heat Orchestration Template's Resource ``OS::Neutron::SecurityGroup`` that is applicable to one {vm-type} and one ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666), the ``OS::Neutron::SecurityGroup`` Resource ID **SHOULD** use the naming convention * ``{vm-type}_int_{network-role}_security_group`` where * ``{vm-type}`` is the vm-type * ``{network-role}`` is the network-role of the ONAP internal network

VNF

SHOULD

OS::Neutron::SecurityGroup

R-14447

A VNF's Heat Orchestration Template's Resource ``OS::ContrailV2::ServiceTemplate`` Resource ID **MAY** use the naming convention * ``{vm-type}_RST_{index}`` where * ``{vm-type}`` is the vm-type * ``RST`` signifies that it is the Resource Service Template * ``{index}`` is the index. The ``{index}`` starts at zero and increments by one (as described in R-11690).

VNF

MAY

OS::ContrailV2::ServiceTemplate

R-146092

If one or more non-MANO artifact(s) is included in the VNF or PNF CSAR package, the Manifest file in this CSAR package **MUST** contain one or more of the following ONAP non-MANO artifact set identifier(s): - onap_ves_events: contains VES registration files - onap_pm_dictionary: contains the PM dictionary files - onap_yang_modules: contains Yang module files for configurations - onap_ansible_playbooks: contains any ansible_playbooks - onap_pnf_sw_information: contains the PNF software information file - onap_others: contains any other non_MANO artifacts, e.g. informational documents *NOTE: According to ETSI SOL004 v.2.6.1, every non-MANO artifact set shall be identified by a non-MANO artifact set identifier which shall be registered in the ETSI registry. Approved ONAP non-MANO artifact set identifiers are documented in the following page* https://wiki.onap.org/display/DW/ONAP+Non-MANO+Artifacts+Set+Identifiers

VNF or PNF CSAR PACKAGE

MUST

VNF or PNF Package Contents

R-14853

The VNF **MUST** respond to a "move traffic" [#4.5.2]_ command against a specific VNFC, moving all existing session elsewhere with minimal disruption if a VNF provides a load balancing function across multiple instances of its VNFCs. Note: Individual VNF performance aspects (e.g., move duration or disruption scope) may require further constraints.

VNF

MUST

VNF Devops

R-15189

A VNF's Heat Orchestration Template's Resource ``OS::Nova::ServerGroup`` Resource ID **MAY** use the naming convention * ``{vm-type}_RSG`` or * ``{vm-type}_Server_Grp`` or * ``{vm-type}_ServerGroup`` or * ``{vm-type}_servergroup``

VNF

MAY

OS::Nova::ServerGroup

R-15287

When the VNF's Heat Orchestration Template's resource ``OS::Neutron::Port`` is attaching to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), and an IPv6 address is being cloud assigned by OpenStack's DHCP Service and the ONAP external network IPv6 subnet is to be specified using the property ``fixed_ips`` map property ``subnet``, the parameter **MUST** follow the naming convention * ``{network-role}_v6_subnet_id`` where * ``{network-role}`` is the network role of the ONAP external network.

VNF

MUST

Property: fixed_ips, Map Property: subnet

R-15325

The VNF **MUST** log the field "success/failure" in the security audit logs.

VNF

MUST

VNF Security Analytics Requirements

R-15480

A VNF's Heat Orchestration Template's ``OS::Nova::Server`` resource property ``metadata`` key/value pair ``vf_module_name`` parameter ``vf_module_name`` **MUST NOT** have parameter constraints defined.

VNF

MUST NOT

vf_module_name

R-15837

The following table defines the major TOSCA Types specified in ETSI NFV-SOL001 standard draft. The VNFD provided by a VNF vendor **MUST** comply with the below definitions:

VNF

MUST

General

R-15884

The VNF **MUST** include the field "date" in the Security alarms (where applicable and technically feasible).

VNF

MUST

VNF Security Analytics Requirements

R-15885

The VNF or PNF **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 VNF or PNF action, it should reflect this status on the Chef Server regardless of whether the Callback succeeded or not.

VNF or PNF

MUST

Chef Roles/Requirements

R-16039

The VNF **SHOULD** test for adherence to the defined resiliency rating recommendation at each layer, during each delivery cycle so that the resiliency rating is measured and feedback is provided where software resiliency requirements are not met.

VNF

SHOULD

Deployment Optimization

R-16065

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

VNF or PNF

MUST

Configuration Management via Ansible

R-16241

A VNF's ONAP internal network **MUST** have one subnet. A VNF's ONAP internal network **MAY** have more than one subnet.

VNF

MUST

Internal Networks

R-16437

A VNF's Heat Orchestration Template's Resource ``OS::ContrailV2::ServiceTemplate`` Resource ID **MUST** contain the ``{vm-type}``.

VNF

MUST

OS::ContrailV2::ServiceTemplate

R-16447

A VNF's <resource ID> **MUST** be unique across all Heat Orchestration Templates and all HEAT Orchestration Template Nested YAML files that are used to create the VNF.

VNF

MUST

resource ID

R-16496

The VNF **MUST** enable instantiating only the functionality that is needed for the decomposed VNF (e.g., if transcoding is not needed it should not be instantiated).

VNF

MUST

VNF Design

R-16560

The VNF **SHOULD** conduct a resiliency impact assessment for all inter/intra-connectivity points in the VNF to provide an overall resiliency rating for the VNF to be incorporated into the software design and development of the VNF.

VNF

SHOULD

Monitoring & Dashboard

R-16777

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.

VNF or PNF

MUST

Configuration Management via Ansible

R-16875

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.

VNF or PNF DOCUMENTATION PACKAGE

MUST

Resource Control Loop

R-16968

A VNF's Heat Orchestration Templates **MUST NOT** include heat resources to create an ONAP external network. An ONAP external network **MUST** be instantiated by using VID or by invoking SO directly.

VNF

MUST NOT

External Networks

R-17334

A VNF's Heat Orchestration Template's Resource ``OS::Neutron::SecurityGroup`` that is applicable to one ``{vm-type}`` and one ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), the ``OS::Neutron::SecurityGroup`` Resource ID **SHOULD** use the naming convention * ``{vm-type}_{network-role}_security_group`` where * ``{vm-type}`` is the vm-type * ``{network-role}`` is the network-role of the ONAP external network

VNF

SHOULD

OS::Neutron::SecurityGroup

R-17528

A VNF's Heat Orchestration Template's first level Nested YAML file **MUST NOT** contain more than one ``OS::Nova::Server`` resource. A VNF's Heat Orchestration Template's second level Nested YAML file **MUST NOT** contain any heat resources.

VNF

MUST NOT

Nested Heat Template Requirements

R-17624

The PNF **MAY** support the optional parameters for Service Configuration Parameters. Note: These are detailed in the Stage 5 PnP Note: These parameters are optional, and not all PNFs will support any or all of these parameters, it is up to the vendor and service provider to ascertain which ones are supported up to an including all of the ones that have been defined. Note: It is expected that there will be a growing list of supported configuration parameters in future releases of ONAP.

PNF

MAY

PNF Plug and Play

R-176945

The VNF or PNF producing VES events **SHOULD NOT** send syslog events to the VES Event Listener during debug mode, but rather store syslog events locally for access or possible file transfer.

VNF or PNF

SHOULD NOT

Event Delivery Requirements

R-177937

The PNFD provided by a PNF vendor **MUST** comply with the following Capabilities Types as specified in ETSI NFV-SOL001 standard: - tosca.capabilities.nfv.VirtualLinkable

PNF

MUST

Capability Types

R-17852

The VNFD **MAY** include TOSCA/YAML definitions that are not part of NFV Profile. If provided, these definitions MUST comply with TOSCA Simple Profile in YAML v.1.2.

VNF

MAY

General

R-18001

If the VNF's ports connected to a unique ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666) and the port's IP addresses are statically assigned IP addresses, the IPv4 addresses **MAY** be from different subnets and the IPv6 addresses **MAY** be from different subnets.

VNF

MAY

Items to Note

R-18008

The VNF's Heat Orchestration Template's Resource ``OS::Neutron::Port`` property ``network`` parameter **MUST** be declared as type: ``string``.

VNF

MUST

Property: network

R-18202

A VNF's Heat Orchestration Template's Resource ``OS::Heat::MultipartMime`` Resource ID **MAY** use the naming convention * ``{vm-type}_RMM`` where * ``{vm-type}`` is the vm-type * ``RMM`` signifies that it is the Resource Multipart Mime

VNF

MAY

OS::Heat::MultipartMime

R-18525

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.

VNF or PNF

MUST

Configuration Management via Chef

R-18683

If a VNF has one IPv4 OAM Management IP Address and the IP Address needs to be inventoried in ONAP's A&AI database, an output parameter **MUST** be declared in only one of the VNF's Heat Orchestration Templates and the parameter **MUST** be named ``oam_management_v4_address``.

VNF

MUST

OAM Management IP Addresses

R-18725

The VNF **MUST** handle the restart of a single VNFC instance without requiring all VNFC instances to be restarted.

VNF

MUST

Application Resilient Error Handling

R-18733

The VNF or PNF **MUST** implement the protocol operation: ``discard-changes()`` - Revert the candidate configuration data store to the running configuration if ":candidate" is supported.

VNF or PNF

MUST

NETCONF Server Requirements

R-18864

The VNF **MUST NOT** use technologies that bypass virtualization layers (such as SR-IOV) unless approved by the NCSP (e.g., if necessary to meet functional or performance requirements).

VNF

MUST NOT

VNF Design

R-19082

The VNF **MUST** not contain undocumented functionality.

VNF

MUST

VNF General Security Requirements

R-19366

The VNF or PNF **MUST** support APPC ``ConfigModify`` command.

VNF or PNF

MUST

Configuration Commands

R-195620

The VNF or PNF Provider's Ansible playbooks **SHOULD** compare the version(s) of Ansible that the VNF Provider developed and tested against to the ``ansible_version.full`` value during playbook execution, and issue a ``WARNING`` message if the operator version is not one of the tested versions.

VNF or PNF PROVIDER

SHOULD

Ansible Playbook Requirements

R-19756

If a VNF's Heat Orchestration Template ``OS::ContrailV2::InterfaceRouteTable`` resource ``interface_route_table_routes`` property ``interface_route_table_routes_route`` map property parameter ``{vm-type}_{network-role}_route_prefixes`` **MUST** be defined as type ``json``.

VNF

MUST

Interface Route Table Prefixes for Contrail InterfaceRoute Table

R-19768

The VNF **SHOULD** support the separation of (1) signaling and payload traffic (i.e., customer facing traffic), (2) operations, administration and management traffic, and (3) internal VNF traffic (i.e., east-west traffic such as storage access) using technologies such as VPN and VLAN.

VNF

SHOULD

VNF General Security Requirements

R-19922

The VNF or PNF **MUST** support APPC/SDN-C ``UpgradePrecheck`` command.

VNF or PNF

MUST

Lifecycle Management Related Commands

R-20065

A VNF's Heat Orchestration Template's Resource ``OS::ContrailV2::PortTuple`` Resource ID **MUST** contain the ``{vm-type}``.

VNF

MUST

OS::ContrailV2::PortTuple

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.

VNF

MUST

Compute, Network, and Storage Requirements

R-20308

A VNF's Heat Orchestration Template's ``OS::Nova::Server`` resource property ``metadata`` key/value pair ``environment_context`` parameter **MUST** be declared as ``environment_context`` and the parameter type **MUST** be defined as type: ``string``.

VNF

MUST

environment_context

R-20319

A VNF's Heat Orchestration Template's Resource ``OS::Heat::CloudConfig`` Resource ID **MAY** use the naming convention * ``{vm-type}_RCC`` where * ``{vm-type}`` is the vm-type * ``RCC`` signifies that it is the Resource Cloud Config

VNF

MAY

OS::Heat::CloudConfig

R-20353

The VNF or PNF **MUST** implement at least one of ``:candidate`` and ``:writable-running`` capabilities. When both ``:candidate`` and ``:writable-running`` are provided then two locks should be supported.

VNF or PNF

MUST

NETCONF Server Requirements

R-20453

A VNF's Heat Orchestration Template's Resource ``OS::Neutron::Port`` that is attaching to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), the ``OS::Neutron::Port`` Resource ID **MUST** use the naming convention * ``{vm-type}_{vm-type_index}_{network-role}_port_{port-index}`` where * ``{vm-type}`` is the vm-type * ``{vm-type_index}`` references the instance of the ``{vm-type}`` in the VNF. The ``{vm-type_index}`` is a numeric value that **MUST** start at zero in the VNF and **MUST** increment by one each time a new instance of a ``{vm-type}`` is referenced. * ``{network-role}`` is the network-role of the ONAP external network that the port is attached to * ``{port_index}`` references the instance of the port on the ``{vm-type}`` attached to ``{network-role}`` network. The ``{port_index}`` is a numeric value that **MUST** start at zero on an instance of a ``{vm-type}`` and **MUST** increment by one each time a new port is defined on the instance of the ``{vm-type}`` attached to ``{network-role}`` network.

VNF

MUST

OS::Neutron::Port

R-20547

When an ONAP Volume Module Output Parameter is declared as an input parameter in a base or an incremental module Heat Orchestration Template, parameter constraints **SHOULD NOT** be declared.

VNF

SHOULD NOT

ONAP Volume Module Output Parameters

R-20741

The VNF or PNF **MUST** support APPC/SDN-C ``Configure`` command.

VNF or PNF

MUST

Configuration Commands

R-20856

A VNF's Heat Orchestration Template's ``OS::Nova::Server`` resource property ``metadata`` key/value pair ``vnf_id`` parameter ``vnf_id`` **MUST NOT** be enumerated in the Heat Orchestration Template's environment file.

VNF

MUST NOT

vnf_id

R-20860

The VNF **MUST** be agnostic to the underlying infrastructure (such as hardware, host OS, Hypervisor), any requirements should be provided as specification to be fulfilled by any hardware.

VNF

MUST

VNF Devops

R-209104

The VNF or PNF producing VES syslog events **SHOULD** restrict these events to those that convey significant errors or warnings needed to support the operation or troubleshooting of the VNF or PNF. It is expected the volume of such events would be lower (e.g. less than 2000 per day) than more detailed events produced in the course of normal operations.

VNF or PNF

SHOULD

Monitoring and Fault Protocol Selection

R-20988

The VNF or PNF Provider's Ansible playbooks **MUST** not log or display passwords and other attributes that must remain secret when running playbook in debug mode. NOTE: Use ``no_log: True``

VNF or PNF PROVIDER

MUST

Ansible Playbook Requirements

R-21210

The VNF **MUST** implement the following input validation control on APIs: Validate that any input file has a correct and valid Multipurpose Internet Mail Extensions (MIME) type. Input files should be tested for spoofed MIME types.

VNF

MUST

VNF API Security Requirements

R-21322

The VNF provider **MUST** provide their testing scripts to support testing as specified in ETSI NFV-SOL004 - Testing directory in CSAR

VNF CSAR PACKAGE

MUST

VNF or PNF Package Contents

R-21330

A VNF's Heat Orchestration Template's Resource property parameter that is associated with an ONAP external network **MUST** include the ``{network-role}`` as part of the parameter name.

VNF

MUST

{network-role}

R-21511

A VNF's Heat Orchestration Template's use of ``{network-role}`` in all Resource IDs **MUST** be the same case.

VNF

MUST

{network-role}

R-21558

The VNF **SHOULD** use intelligent routing by having knowledge of multiple downstream/upstream endpoints that are exposed to it, to ensure there is no dependency on external services (such as load balancers) to switch to alternate endpoints.

VNF

SHOULD

Intelligent Transaction Distribution & Management

R-21652

The VNF **MUST** implement the following input validation control: Check the size (length) of all input. Do not permit an amount of input so great that it would cause the VNF to fail. Where the input may be a file, the VNF API must enforce a size limit.

VNF

MUST

VNF API Security Requirements

R-21819

VNFs that are subject to regulatory requirements **MUST** provide functionality that enables the Operator to comply with ETSI TC LI requirements, and, optionally, other relevant national equivalents.

VNF

MUST

VNF General Security Requirements

R-22059

The VNF **MUST NOT** execute long running tasks (e.g., IO, database, network operations, service calls) in a critical section of code, so as to minimize blocking of other operations and increase concurrent throughput.

VNF

MUST NOT

System Resource Optimization

R-221914

The VNF or PNF CSAR package **MUST** contain a human-readable change log text file. The Change Log file keeps a history describing any changes in the VNF or PNF package. The Change Log file is kept up to date continuously from the creation of the CSAR package.

VNF or PNF CSAR PACKAGE

MUST

VNF or PNF Package Contents

R-22288

The VNF's Heat Orchestration Template's Resource ``OS::Neutron::Port`` property ``fixed_ips`` map property ``subnet`` parameter ``int_{network-role}_v6_subnet_id`` **MUST NOT** be enumerated in the VNF's Heat Orchestration Template's Environment File.

VNF

MUST NOT

Property: fixed_ips, Map Property: subnet

R-22346

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.

VNF or PNF PROVIDER

MUST

Resource Description

R-22367

The VNF **MUST** support detection of malformed packets due to software misconfiguration or software vulnerability, and generate an error to the syslog console facility.

VNF

MUST

VNF Security Analytics Requirements

R-22589

A VNF's Heat Orchestration Template parameter declaration **MAY** contain the attribute ``immutable:``.

VNF

MAY

immutable

R-225891

A VNF's Heat Orchestration Template parameter declaration **MAY** contain the attribute ``tags:``.

VNF

MAY

tags

R-22608

When a VNF's Heat Orchestration Template's Base Module's output parameter is declared as an input parameter in an Incremental Module, the parameter attribute ``constraints:`` **SHOULD NOT** be declared.

VNF

SHOULD NOT

ONAP Base Module Output Parameters

R-22680

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.

VNF or PNF DOCUMENTATION PACKAGE

MUST

Resource Control Loop

R-22688

When a VNF's Heat Orchestration Template creates an ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666) and the ONAP internal network needs to be shared between modules within a VNF, the ONAP internal network **MUST** be created either in the * the base module * a nested YAML file invoked by the base module and the base module **MUST** contain an output parameter that provides either the network UUID or network name. * If the network UUID value is used to reference the network, the output parameter name in the base module **MUST** follow the naming convention ``int_{network-role}_net_id`` * If the network name in is used to reference the network, the output parameter name in the base template **MUST** follow the naming convention ``int_{network-role}_net_name`` The ``{network-role}`` **MUST** be the network-role of the ONAP internal network created in the Base Module. The Base Module Output Parameter MUST be declared in the ``parameters:`` section of the Incremental Module(s) where the ``OS::Neutron::Port`` resource(s) is attaching to the ONAP internal network.

VNF

MUST

Internal Networks

R-22838

The VNF's Heat Orchestration Template's Resource ``OS::Nova::Server`` property ``name`` parameter **MUST NOT** be enumerated in the Heat Orchestration Template's Environment File.

VNF

MUST NOT

Property: Name

R-22888

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.

VNF or PNF DOCUMENTATION PACKAGE

MUST

Resource Control Loop

R-22946

The VNF or PNF **SHOULD** conform its YANG model to RFC 8341, "NETCONF Access Control Model".

VNF or PNF

SHOULD

NETCONF Server Requirements

R-23035

The VNF **MUST** be designed to scale horizontally (more instances of a VNF or VNFC) and not vertically (moving the existing instances to larger VMs or increasing the resources within a VM) to achieve effective utilization of cloud resources.

VNF

MUST

VNF Design

R-23135

The VNF **MUST**, if not integrated with the Operator's identity and access management system, authenticate all access to protected resources.

VNF

MUST

VNF Identity and Access Management Requirements

R-231402

The VNF **MUST** provide a means to explicitly logout, thus ending that session.

VNF

MUST

VNF Identity and Access Management Requirements

R-23311

The VNF's Heat Orchestration Template's base module or incremental module resource ``OS::Nova::Server`` property ``availability_zone`` parameter **MUST** be declared as type: ``string``.

VNF

MUST

Property: availability_zone

R-233922

If the VNF or PNF is using SNMP, then the VNF or PNF Provider **SHOULD** provide examples of all SNMP alarms.

VNF or PNF

SHOULD

SNMP Monitoring Requirements

R-23475

VNFCs **SHOULD** be agnostic to the details of the Network Cloud (such as hardware, host OS, Hypervisor or container technology) and must run on the Network Cloud with acknowledgement to the paradigm that the Network Cloud will continue to rapidly evolve and the underlying components of the platform will change regularly.

VNF

SHOULD

VNF Devops

R-23503

When the VNF's Heat Orchestration Template's Resource ``OS::Neutron::Port`` is attaching to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), and an IPv6 address is assigned using the property ``fixed_ips`` map property ``ip_address`` and the parameter type is defined as a ``comma_delimited_list``, the parameter name **MUST** follow the naming convention * ``{vm-type}_{network-role}_v6_ips`` where * ``{vm-type}`` is the {vm-type} associated with the OS::Nova::Server * ``{network-role}`` is the {network-role} of the ONAP external network

VNF

MUST

Property: fixed_ips, Map Property: ip_address

R-23663

A VNF's Heat Orchestration template's base module **MAY** (or **MAY NOT**) contain the section ``resources:``.

VNF

MAY

resources

R-23664

A VNF's Heat Orchestration template's incremental module and volume module **MUST** contain the section ``resources:``.

VNF

MUST

resources

R-23740

The VNF **MUST** implement and enforce the principle of least privilege on all protected interfaces.

VNF

MUST

VNF General Security Requirements

R-23957

The VNF **MUST** include the field "time" in the Security alarms (where applicable and technically feasible).

VNF

MUST

VNF Security Analytics Requirements

R-240760

The VNF **MUST NOT** contain any backdoors.

VNF

MUST NOT

VNF General Security Requirements

R-24189

The VNF or PNF Provider **MUST** deliver a new set of Ansible playbooks that includes all updated and unchanged playbooks for any new revision to an existing set of playbooks.

VNF or PNF PROVIDER

MUST

Ansible Playbook Requirements

R-24269

The VNF or PNF **SHOULD** conform its YANG model to RFC 7407, "A YANG Data Model for SNMP Configuration", if Netconf used to configure SNMP engine.

VNF or PNF

SHOULD

NETCONF Server Requirements

R-24359

The VNF **MUST** provide the capability of testing the validity of a digital certificate by validating the date the certificate is being used is within the validity period for the certificate.

VNF

MUST

VNF Cryptography Requirements

R-24482

The VNF or PNF Provider's Ansible playbooks **MUST** be designed to run using an inventory hosts file in a supported format; with site group that shall be used to add site specific configurations to the target VNF or PNF VM(s) as needed.

VNF or PNF PROVIDER

MUST

Ansible Client Requirements

R-24632

The PNF Descriptor (PNFD) provided by PNF vendor **MUST** comply with TOSCA/YAML based Service template for PNF descriptor specified in ETSI NFV-SOL001.

PNF

MUST

General

R-246519

As alternative to Ansible, Chef or REST, a VNF or PNF **MAY** support YANG models allowing execution of standard controller LCM operations including HealthCheck. Note: To support vendor YANG models for LCM operations, the controller is responsible for performing VNF/PNF specific translation of north-bound API requests into one or more south-bound NETCONF requests.

VNF or PNF

MAY

LCM Operations via NETCONF

R-24893

A VNF's Heat Orchestration template's Environment File's **MAY** contain the ``event_sinks:`` section.

VNF

MAY

Environment File Format

R-24997

A VNF's Heat Orchestration Template's Resource ``OS::Nova::Keypair`` that applies to one ``{vm-type}``, the ``OS::Nova::Keypair`` Resource ID **SHOULD** use the naming convention * ``{vm-type}_keypair_{index}`` where * ``{vm-type}`` is the vm-type of the ``OS::Nova::Server`` * ``{index}`` is the ``{index}`` of the keypair. The ``{index}`` starts at zero and increments by one (as described in R-11690).

VNF

SHOULD

OS::Nova::Keypair

R-251639

The VNF **MUST** provide explicit confirmation of a session termination such as a message, new page, or rerouting to a login page.

VNF

MUST

VNF Identity and Access Management Requirements

R-25190

A VNF's Heat Orchestration Template's Resource ``OS::Cinder::Volume`` **SHOULD NOT** declare the property ``availability_zone``.

VNF

SHOULD NOT

Optional Property availability_zone

R-25238

The VNF or PNF PACKAGE **MUST** validated YANG code using the open source pyang [#7.3.1]_ program using the following commands: .. code-block:: text $ pyang --verbose --strict <YANG-file-name(s)> $ echo $! The VNF or PNF **MUST** have the echo command return a zero value otherwise the validation has failed.

VNF or PNF

MUST

NETCONF Server Requirements

R-25401

The VNF **MUST** use asymmetric keys of at least 2048 bits in length.

VNF

MUST

VNF Cryptography Requirements

R-25547

The VNF **MUST** log the field "protocol" in the security audit logs.

VNF

MUST

VNF Security Analytics Requirements

R-256267

If SNMP is utilized, the VNF **MUST** support at least SNMPv3 with message authentication.

VNF

MUST

VNF General Security Requirements

R-256347

The PNF **MUST** support one of the protocols for a Service Configuration message exchange between the PNF and PNF Controller (in ONAP): a) Netconf/YANG, b) Chef, or c) Ansible. Note: The PNF Controller may be VF-C, APP-C or SDN-C based on the PNF and PNF domain.

PNF

MUST

PNF Plug and Play

R-256790

A VNF's Heat Orchestration Template's Resource ``OS::Nova::Server`` property ``availability_zone`` parameter name **MAY** change when past into a nested YAML file.

VNF

MAY

Property: availability_zone

R-25720

A VNF's Heat Orchestration Template's Resource ``OS::Neutron::Net`` Resource ID **MUST** use the naming convention * ``int_{network-role}_network`` VNF Heat Orchestration Templates can only create ONAP internal networks (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666). There is no ``{index}`` after ``{network-role}`` because ``{network-role}`` **MUST** be unique in the scope of the VNF's Heat Orchestration Template.

VNF

MUST

OS::Neutron::Net

R-258352

The PNF **MUST** support & accept the provisioning of an ONAP contact IP address (in IPv4 or IPv6 format). Note: For example, it a possibility is that an external EMS would configure & provision the ONAP contact IP address to the PNF (in either IPv4 or IPv6 format). For the PNF Plug and Play Use Case, this IP address is the service provider's "point of entry" to the DCAE VES Listener. Note: different service provider's network architecture may also require special setup to allow an external PNF to contact the ONAP installation. For example, in the AT&T network, a maintenance tunnel is used to access ONAP.

PNF

MUST

PNF Plug and Play

R-258686

The VNF application processes **SHOULD NOT** run as root. If a VNF application process must run as root, the technical reason must be documented.

VNF

SHOULD NOT

VNF General Security Requirements

R-25877

A VNF's Heat Orchestration Template's parameter name (i.e., <param name>) **MUST** contain only alphanumeric characters and underscores ('_').

VNF

MUST

<param name>

R-26115

The VNF or PNF **MUST** follow the data model update rules defined in [RFC6020] section 10 for YANG 1.0 modules, and [RFC7950] section 11 for YANG 1.1 modules. All deviations from the aforementioned update rules shall be handled by a built-in automatic upgrade mechanism.

VNF or PNF

MUST

NETCONF Server Requirements

R-26124

If a VNF Heat Orchestration Template parameter has a default value, it **MUST** be enumerated in the environment file.

VNF

MUST

default

R-261501

If the VNF or PNF is using SNMP, then the VNF or PNF Provider **MUST** provide a Management Information Base (MIB) file that uniquely identifies and describes all SNMP events exposed by the network function.

VNF or PNF

MUST

SNMP Monitoring Requirements

R-26351

A VNF's Heat Orchestration Template's Resource ``OS::Neutron::Port`` that is attaching to an ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666), the ``OS::Neutron::Port`` Resource ID **MUST** use the naming convention * ``{vm-type}_{vm-type_index}_int_{network-role}_port_{port-index}`` where * ``{vm-type}`` is the vm-type * ``{vm-type_index}`` references the instance of the ``{vm-type}`` in the VNF. The ``{vm-type_index}`` is a numeric value that **MUST** start at zero in the VNF and **MUST** increment by one each time a new instance of a ``{vm-type}`` is referenced. * ``{network-role}`` is the network-role of the ONAP internal network that the port is attached to * ``{port_index}`` references the instance of the port on the ``{vm-type}`` attached to ``{network-role}`` network. The ``{port_index}`` is a numeric value that **MUST** start at zero on an instance of a ``{vm-type}`` and **MUST** increment by one each time a new port is defined on the instance of the ``{vm-type}`` attached to ``{network-role}`` network.

VNF

MUST

OS::Neutron::Port

R-26371

The VNF **MUST** detect communication failure for inter VNFC instance and intra/inter VNF and re-establish communication automatically to maintain the VNF without manual intervention to provide service continuity.

VNF

MUST

Application Resilient Error Handling

R-26506

A VNF's Heat Orchestration Template's ``{network-role}`` **MUST** contain only alphanumeric characters and/or underscores '_' and * **MUST NOT** contain any of the following strings: ``_int`` or ``int_`` or ``_int_`` * **MUST NOT** end in the string: ``_v6`` * **MUST NOT** contain the strings ``_#_``, where ``#`` is a number * **MUST NOT** end in the string: ``_#``, where ``#`` is a number

VNF

MUST NOT

{network-role}

R-26508

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

VNF or PNF

MUST

NETCONF Server Requirements

R-26567

The VNF or PNF Package **MUST** include a run list of roles/cookbooks/recipes, for each supported VNF or PNF action, that will perform the desired VNF or PNF action in its entirety as specified by ONAP (see Section 7.c, APPC/SDN-C APIs and Behavior, for list of VNF or PNF actions and requirements), when triggered by a chef-client run list in JSON file.

VNF or PNF

MUST

Chef Roles/Requirements

R-26881

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

VNF

MUST

Compute, Network, and Storage Requirements

R-270358

A VNF's Heat Orchestration Template's Cinder Volume Template **MUST** contain either * An ``OS::Cinder::Volume`` resource * An ``OS::Heat::ResourceGroup`` resource that references a Nested YAML file that contains an ``OS::Cinder::Volume`` resource * A resource that defines the property ``type`` as a Nested YAML file (i.e., static nesting) and the Nested YAML contains an ``OS::Cinder::Volume`` resource

VNF

MUST

ONAP Heat Cinder Volumes

R-27078

A VNF's Heat Orchestration template **MUST** contain the section ``heat_template_version:``.

VNF

MUST

heat_template_version

R-27310

The VNF or PNF Package **MUST** include all relevant Chef artifacts (roles/cookbooks/recipes) required to execute VNF or PNF actions requested by ONAP for loading on appropriate Chef Server.

VNF or PNF

MUST

Chef Roles/Requirements

R-27469

A VNF's Heat Orchestration Template's Resource ``OS::Neutron::Port`` that is creating a *Reserve Port* with an IPv4 address, the ``OS::Neutron::Port`` Resource ID **SHOULD** use the naming convention * ``reserve_port_{vm-type}_{network-role}_floating_ip_{index}`` where * ``{vm-type}`` is the vm-type * ``{network-role}`` is the network-role of the ONAP external network that the port is attached to * ``{index}`` is the instance of the IPv4 *Reserve Port* for the vm-type attached to the network of ``{network-role}``. The ``{index}`` starts at zero and increments by one (as described in R-11690).

VNF

SHOULD

OS::Neutron::Port

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.

VNF

MUST

Licensing Requirements

R-27818

When the VNF's Heat Orchestration Template's Resource ``OS::Neutron::Port`` is attaching to an ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666), and an IPv6 address is assigned using the property ``fixed_ips`` map property ``ip_address`` and the parameter type is defined as a ``string``, the parameter name **MUST** follow the naming convention * ``{vm-type}_int_{network-role}_v6_ip_{index}`` where * ``{vm-type}`` is the {vm-type} associated with the ``OS::Nova::Server`` * ``{network-role}`` is the {network-role} of the ONAP internal network * ``{index}`` is a numeric value that **MUST** start at zero in a VNF's Heat Orchestration Template and **MUST** increment by one

VNF

MUST

Property: fixed_ips, Map Property: ip_address

R-27970

When a VNF's Heat Orchestration Template's resource is associated with more than one ``{vm-type}`` and/or more than one ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666) and/or ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), the Resource ID **MAY** contain the term ``shared`` and/or **MAY** contain text that identifies the VNF.

VNF

MAY

Resource IDs

R-27995

The VNF **SHOULD** include control loop mechanisms to notify the consumer of the VNF of their exceeding SLA thresholds so the consumer is able to control its load against the VNF.

VNF

SHOULD

Intelligent Transaction Distribution & Management

R-28168

The VNF **SHOULD** use an appropriately configured logging level that can be changed dynamically, so as to not cause performance degradation of the VNF due to excessive logging.

VNF

SHOULD

Monitoring & Dashboard

R-28189

A VNF's Heat Orchestration Template's Resource ``OS::ContrailV2::InterfaceRouteTable`` Resource ID **MAY** use the naming convention * ``{network-role}_RIRT`` where * ``{network-role}`` is the network-role * ``RIRT`` signifies that it is the Resource Interface Route Table

VNF

MAY

OS::ContrailV2::InterfaceRouteTable

R-28222

If a VNF's Heat Orchestration Template ``OS::ContrailV2::InterfaceRouteTable`` resource ``interface_route_table_routes`` property ``interface_route_table_routes_route`` map property parameter name **MUST** follow the format * ``{vm-type}_{network-role}_route_prefixes``

VNF

MUST

Interface Route Table Prefixes for Contrail InterfaceRoute Table

R-283988

A VNF or PNF producing VES events **MUST NOT** send information through extensible structures if the event specification has explicitly defined fields for that information.

VNF or PNF

MUST NOT

Event Formatting and Usage

R-284934

If the PNF encounters an error authenticating, reaching the ONAP DCAE VES Event listener or recieves an error response from sending the pnfRegistration VES Event, it **MAY** log the error, and notify the operator. Note: the design of how errors are logged, retrieved and reported will be a vendor-specific architecture. Reporting faults and errors is also a vendor specific design. It is expected that the PNF shall have a means to log an error and notify a user when a fault condition occurs in trying to contact ONAP, authenticate or send a pnfRegistration event.

PNF

MAY

PNF Plug and Play

R-28756

The VNF or PNF **MAY** 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 <running> configuration at the same time.

VNF or PNF

MAY

NETCONF Server Requirements

R-28795

The VNF's Heat Orchestration Template's Resource ``OS::Neutron::Port`` property ``fixed_ips`` map property ``ip_address`` parameter ``{vm-type}_int_{network-role}_ip_{index}`` **MUST** be enumerated in the VNF's Heat Orchestration Template's Environment File.

VNF

MUST

Property: fixed_ips, Map Property: ip_address

R-28980

A VNF's incremental module **MAY** be used for initial VNF deployment only.

VNF

MAY

ONAP VNF Modularity Overview

R-29324

The VNF or PNF **SHOULD** implement the protocol operation: ``copy-config(target, source)`` - Copy the content of the configuration data store source to the configuration data store target.

VNF or PNF

SHOULD

NETCONF Server Requirements

R-293901

The VNF or PNF CSAR PACKAGE with TOSCA-Metadata **MUST** include following additional keywords pointing to TOSCA files: - ETSI-Entry-Manifest - ETSI-Entry-Change-Log Note: For a CSAR containing a TOSCA-Metadata directory, which includes the TOSCA.meta metadata file. The TOSCA.meta metadata file includes block_0 with the Entry-Definitions keyword pointing to a TOSCA definitions YAML file used as entry for parsing the contents of the overall CSAR archive.

VNF or PNF CSAR PACKAGE

MUST

VNF or PNF Package Contents

R-29488

The VNF or PNF **MUST** implement the protocol operation: ``get-config(source, filter`` - Retrieve a (filtered subset of a) configuration from the configuration data store source.

VNF or PNF

MUST

NETCONF Server Requirements

R-29495

The VNF or PNF **MUST** support locking if a common object is being manipulated by two simultaneous NETCONF configuration operations on the same VNF or PNF 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).

VNF or PNF

MUST

NETCONF Server Requirements

R-29705

The VNF **MUST** restrict changing the criticality level of a system security alarm to users with administrative privileges.

VNF

MUST

VNF Security Analytics Requirements

R-29751

A VNF's Heat Orchestration Template's Resource ``OS::Nova::Server`` Resource ID **MUST** use the naming convention * ``{vm-type}_server_{index}`` where * ``{vm-type}`` is the vm-type * ``{index}`` is the index. The ``{index}`` **MUST** starts at zero and increment by one as described in R-11690.

VNF

MUST

OS::Nova::Server

R-29760

The VNFC **MUST** be installed on non-root file systems, unless software is specifically included with the operating system distribution of the guest image.

VNF

MUST

VNF Devops

R-29765

When the VNF's Heat Orchestration Template's Resource ``OS::Neutron::Port`` is attaching to an ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666), and an IPv6 address is assigned using the property ``fixed_ips`` map property ``ip_address`` and the parameter type is defined as a ``comma_delimited_list``, the parameter name **MUST** follow the naming convention * ``{vm-type}_int_{network-role}_v6_ips`` where * ``{vm-type}`` is the {vm-type} associated with the ``OS::Nova::Server`` * ``{network-role}`` is the {network-role} of the ONAP internal network

VNF

MUST

Property: fixed_ips, Map Property: ip_address

R-29872

The VNF's Heat Orchestration Template's Resource ``OS::Neutron::Port`` property ``network`` parameter **MUST NOT** be enumerated in the Heat Orchestration Template's Environment File.

VNF

MUST NOT

Property: network

R-29977

The VNF **MUST** provide the capability of testing the validity of a digital certificate by validating the CA signature on the certificate.

VNF

MUST

VNF Cryptography Requirements

R-30005

A VNF's Heat Orchestration Template's Resource ``OS::Neutron::SecurityGroup`` that is applicable to more than one ``{vm-type}`` and more than one network (internal and/or external), the ``OS::Neutron::SecurityGroup`` Resource ID **MAY** use the naming convention * ``shared_security_group`` or * ``{vnf-type}_security_group`` where * ``{vnf-type}`` describes the VNF

VNF

MAY

OS::Neutron::SecurityGroup

R-30278

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

VNF or PNF PROVIDER

SHOULD

Configuration Management via NETCONF/YANG

R-303569

The VNF **MUST** log the Source IP address in the security audit logs.

VNF

MUST

VNF Security Analytics Requirements

R-30395

A VNF's Cinder Volume Module **MAY** utilize nested heat.

VNF

MAY

Nested Heat Orchestration Templates Overview

R-304011

A VNF's Heat Orchestration Template's ``OS::Nova::Server`` resource's * Resource ID (defined in R-29751) * property ``image`` parameter name (defined in R-58670) * property ``flavor`` parameter name (defined in R-45188) * property ``name`` parameter name (defined in R-54171 & R-87817) * property ``networks`` map property ``port`` value which is a ``OS::Neutron::Port`` Resource ID (defined in R-20453) referenced using the intrinsic function ``get_attr`` **MUST** contain the identical ``{vm-type}`` and **MUST** follow the naming conventions defined in R-58670, R-45188, R-54171, R-87817, and R-29751. And the ``{index}`` in the ``OS::Nova::Server`` Resource ID (defined in R-29751) **MUST** match the ``{vm-type_index}`` defined in the ``OS::Nova::Server`` property ``networks`` map property ``port`` referenced ``OS::Neutron::Port`` Resource ID (defined in R-20453).

VNF

MUST

Resource: OS::Nova::Server - Parameters

R-305645

The VNF or PNF **MUST** support configuration management including life cycle management (LCM) using at least one of the following protocols a)NETCONF/YANG, b)Ansible and c)Chef.

VNF or PNF

MUST

Configuration Management

R-30650

The VNF **MUST** utilize cloud provided infrastructure and VNFs (e.g., virtualized Local Load Balancer) as part of the VNF so that the cloud can manage and provide a consistent service resiliency and methods across all VNF's.

VNF

MUST

VNF Design

R-30654

The VNF or PNF 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 VNF or PNF (e.g., configure).

VNF or PNF

MUST

Chef Roles/Requirements

R-30753

A VNF's Heat Orchestration Template's Resource ``OS::ContrailV2::NetworkIpam`` Resource ID **MUST** contain the ``{network-role}`` of the ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666) that the resource is associated with.

VNF

MUST

OS::ContrailV2::NetworkIpam

R-30804

A VNF's Heat Orchestration Template's Resource ``OS::Heat::MultipartMime`` Resource ID **MUST** contain the ``{vm-type}``.

VNF

MUST

OS::Heat::MultipartMime

R-30932

The VNF **MUST** log successful and unsuccessful access to VNF resources, including data.

VNF

MUST

VNF Security Analytics Requirements

R-31141

VNF Heat Orchestration Template's Cinder Volume Module's Environment File **MUST** be named identical to the VNF Heat Orchestration Template's Cinder Volume Module with ``.y[a]ml`` replaced with ``.env``.

VNF

MUST

Cinder Volume Modules

R-31614

The VNF **MUST** log the field "event type" in the security audit logs.

VNF

MUST

VNF Security Analytics Requirements

R-31809

The VNF or PNF **MUST** support the HealthCheck RPC. The HealthCheck RPC executes a VNF or PNF Provider-defined VNF or PNF HealthCheck over the scope of the entire VNF or PNF (e.g., if there are multiple VNFCs, then run a health check, as appropriate, for all VNFCs). It returns a 200 OK if the test completes. A JSON object is returned indicating state (healthy, unhealthy), scope identifier, time-stamp and one or more blocks containing info and fault information. If the VNF or PNF is unable to run the HealthCheck, return a standard http error code and message.

VNF or PNF

MUST

REST APIs

R-32094

A VNF's Heat Orchestration Template parameter declaration **MAY** contain the attribute ``label:``.

VNF

MAY

label

R-32155

The VNFD provided by VNF vendor may use the below described TOSCA interface types. An on-boarding entity (ONAP SDC) **MUST** support them. **tosca.interfaces.nfv.vnf.lifecycle.Nfv** supports LCM operations

VNF

MUST

Interface Types

R-32217

The VNF or PNF **MUST** have routable management IP addresses or FQDNs that are reachable via the Ansible Server for the endpoints (VMs) of a VNF or PNF that playbooks will target. ONAP will initiate requests to the Ansible Server for invocation of playbooks against these end points [#7.3.3]_.

VNF or PNF

MUST

Ansible Client Requirements

R-32394

A VNF's Heat Orchestration Template's use of ``{vm-type}`` in all Resource property parameter names **MUST** be the same case.

VNF

MUST

{vm-type}

R-32557

A VNF's Heat Orchestration Template parameter declaration **MAY** contain the attribute ``hidden:``.

VNF

MAY

hidden

R-32636

The VNF **MUST** support API-based monitoring to take care of the scenarios where the control interfaces are not exposed, or are optimized and proprietary in nature.

VNF

MUST

VNF Security Analytics Requirements

R-32641

The VNF **MUST** provide the capability to encrypt data on non-volatile memory.Non-volative memory is storage that is capable of retaining data without electrical power, e.g. Complementary metal-oxide-semiconductor (CMOS) or hard drives.

VNF

MUST

VNF Data Protection Requirements

R-32695

The VNF **MUST** provide the ability to modify the number of retries, the time between retries and the behavior/action taken after the retries have been exhausted for exception handling to allow the NCSP to control that behavior, where the interface and/or functional specification allows for altering behaviour.

VNF

MUST

Application Resilient Error Handling

R-328086

The VNF or PNF **MUST**, if serving as a distribution point or anchor point for steering point from source to destination, support the ONAP Controller's ``DistributeTraffic`` command.

VNF or PNF

MUST

Lifecycle Management Related Commands

R-32981

The VNF or PNF **MUST** support APPC ``ConfigBackup`` command.

VNF or PNF

MUST

Configuration Commands

R-33132

A VNF's Heat Orchestration Template **MAY** be 1.) Base Module Heat Orchestration Template (also referred to as a Base Module), 2.) Incremental Module Heat Orchestration Template (referred to as an Incremental Module), or 3.) a Cinder Volume Module Heat Orchestration Template (referred to as Cinder Volume Module).

VNF

MAY

ONAP VNF Modularity Overview

R-332680

The VNF or PNF producing VES events **SHOULD** deliver syslog messages that meet the criteria in R-209104 to the VES Event Listener using the ``syslog`` VES domain.

VNF or PNF

SHOULD

Monitoring and Fault Protocol Selection

R-33280

The VNF or PNF Provider's Ansible playbooks **MUST NOT** contain instance specific values that can not be provided by a parameter to the playbook.

VNF or PNF PROVIDER

MUST NOT

Ansible Playbook Requirements

R-33488

The VNF **MUST** protect against all denial of service attacks, both volumetric and non-volumetric, or integrate with external denial of service protection tools.

VNF

MUST

VNF Security Analytics Requirements

R-33694

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

VNF or PNF

MUST

Resource Control Loop

R-33846

The VNF **MUST** install the NCSP required software on Guest OS images when not using the NCSP provided Guest OS images. [#4.5.1]_

VNF

MUST

VNF Devops

R-33878

The VNF or PNF **MUST** utilize one of the authentication methods prescribed by the relevant VES Event Listener specification.

VNF or PNF

MUST

Security

R-33904

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

VNF or PNF

MUST

Resource Control Loop

R-33946

The VNF or PNF **MUST** conform to the NETCONF RFC 4741, "NETCONF Configuration Protocol".

VNF or PNF

MUST

NETCONF Server Requirements

R-33955

The VNF or PNF **SHOULD** conform its YANG model to RFC 6991, "Common YANG Data Types".

VNF or PNF

SHOULD

NETCONF Server Requirements

R-34037

The VNF's Heat Orchestration Template's resource ``OS::Neutron::Port`` property ``fixed_ips`` map property ``ip_address`` parameter **MUST** be declared as either type ``string`` or type ``comma_delimited_list``.

VNF

MUST

Property: fixed_ips, Map Property: ip_address

R-34055

A VNF's Heat Orchestration Template's ``OS::Nova::Server`` resource property ``metadata`` key/value pair ``workload_context`` parameter ``workload_context`` **MUST NOT** have parameter constraints defined.

VNF

MUST NOT

workload_context

R-34484

The VNF **SHOULD** create a single component VNF for VNFCs that can be used by other VNFs.

VNF

SHOULD

VNF Design

R-34552

The VNF **MUST** be implemented so that it is not vulnerable to OWASP Top 10 web application security risks.

VNF

MUST

VNF Security Analytics Requirements

R-346137

A VNF or PNF producing VES events that is buffering events per R-658596 **MUST** store in-scope events even when the maximum capacity of the buffer (defined in R-636251) has been reached. To make room for new events in this situation, hte oldest event in the buffer shall be removed as necessary. (i.e. First In First Out)

VNF or PNF

MUST

Buffering and Redelivery

R-348813

The VNF's Heat Orchestration Template's ZIP file **MUST NOT** include a binary image file.

VNF HEAT PACKAGE

MUST NOT

ONAP VNF On-Boarding

R-34957

The VNF **MUST** provide a method of metrics gathering for each layer's performance to identify variances in the allocations so they can be addressed.

VNF

MUST

Monitoring & Dashboard

R-35291

The VNF **MUST** support the ability to failover a VNFC automatically to other geographically redundant sites if not deployed active-active to increase the overall resiliency of the VNF.

VNF

MUST

All Layer Redundancy

R-353637

Containerized components of VNFs **SHOULD** follow the recommendations for Container Base Images and Build File Configuration in the latest available version of the CIS Docker Community Edition Benchmarks to ensure that containerized VNFs are secure. All non-compliances with the benchmarks MUST be documented.

VNF

SHOULD

VNF General Security Requirements

R-35401

The VNF or PNF **MUST** support SSH and allow SSH access by the Ansible server to the endpoint VM(s) and comply with the Network Cloud Service Provider guidelines for authentication and access.

VNF or PNF

MUST

Ansible Client Requirements

R-35414

A VNF Heat Orchestration's template **MUST** contain the section ``parameters:`` with at least one parameter defined.

VNF

MUST

parameters

R-35532

The VNF **SHOULD** release and clear all shared assets (memory, database operations, connections, locks, etc.) as soon as possible, especially before long running sync and asynchronous operations, so as to not prevent use of these assets by other entities.

VNF

SHOULD

System Resource Optimization

R-35666

If a VNF has an ONAP internal network, the VNF's Heat Orchestration Template **MUST** include the heat resources to create the ONAP internal network. A VNF's ONAP internal network is created using Neutron Heat Resources (e.g., ``OS::Neutron::Net``, ``OS::Neutron::Subnet``, ``OS::Neutron::ProviderNet``) and/or Contrail Heat Resources (e.g., ``OS::ContrailV2::VirtualNetwork``, ``OS::ContrailV2::NetworkIpam``).

VNF

MUST

Internal Networks

R-35735

When the VNF's Heat Orchestration Template's resource ``OS::Neutron::Port`` is attaching to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), and the IPv6 VIP is required to be supported by the ONAP data model, the property ``allowed_address_pairs`` map property ``ip_address`` parameter name **MUST** follow the naming convention * ``{vm-type}_{network-role}_floating_v6_ip`` where * ``{vm-type}`` is the {vm-type} associated with the ``OS::Nova::Server`` * ``{network-role}`` is the {network-role} of the ONAP external network And the parameter **MUST** be declared as type ``string``. As noted in the introduction to this section, the ONAP data model can only support one IPv6 VIP address.

VNF

MUST

VIP Assignment, ONAP External Networks

R-35851

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.

VNF HEAT PACKAGE

MUST

Compute, Network, and Storage Requirements

R-35854

The VNF Descriptor (VNFD) provided by VNF vendor **MUST** comply with TOSCA/YAML based Service template for VNF descriptor specified in ETSI NFV-SOL001. **Note**: As the ETSI NFV-SOL001 is work in progress the below tables summarizes the TOSCA definitions agreed to be part of current version of NFV profile and that VNFD MUST comply with in ONAP Release 2+ Requirements.

VNF

MUST

General

R-358699

The VNF **MUST** support at least the following roles: system administrator, application administrator, network function O&M.

VNF

MUST

VNF Identity and Access Management Requirements

R-35960

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.

VNF or PNF

MUST

Resource Control Loop

R-36280

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.

VNF or PNF DOCUMENTATION PACKAGE

MUST

Resource Description

R-36542

A VNF's Heat Orchestration Template's ``OS::Nova::Server`` resource property ``metadata`` key/value pair ``vnf_name`` parameter ``vnf_name`` **MUST NOT** be enumerated in the Heat Orchestration Template's environment file.

VNF

MUST NOT

vnf_name

R-36582

A VNF's Base Module **MAY** utilize nested heat.

VNF

MAY

Nested Heat Orchestration Templates Overview

R-36687

A VNF's Heat Orchestration Template's ``{vm-type}`` case in Resource property parameter names **SHOULD** match the case of ``{vm-type}`` in Resource IDs and vice versa.

VNF

SHOULD

{vm-type}

R-36772

A VNF's Heat Orchestration Template's parameter **MUST** include the attribute ``type:``.

VNF

MUST

type

R-36792

The VNF **MUST** automatically retry/resubmit failed requests made by the software to its downstream system to increase the success rate.

VNF

MUST

Application Resilient Error Handling

R-36843

The VNF **MUST** support the ability of the VNFC to be deployable in multi-zoned cloud sites to allow for site support in the event of cloud zone failure or upgrades.

VNF

MUST

All Layer Redundancy

R-36982

A VNF's Heat Orchestration template **MAY** contain the ``outputs:`` section.

VNF

MAY

outputs

R-37028

A VNF **MUST** be composed of one Base Module

VNF

MUST

ONAP VNF Modularity Overview

R-37039

A VNF's Heat Orchestration Template's ``OS::Nova::Server`` resource property ``metadata`` key/value pair ``vf_module_index`` parameter ``vf_module_index`` **MUST NOT** be enumerated in the Heat Orchestration Template's environment file.

VNF

MUST NOT

vf_module_index

R-373737

The VNF **MUST**, if not integrated with the operator's IAM system, provide a mechanism for assigning roles and/or permissions to an identity.

VNF

MUST

VNF Identity and Access Management Requirements

R-37437

A VNF's Heat Orchestration Template's ``OS::Nova::Server`` resource property ``metadata`` **MUST** contain the key/value pair ``vnf_id`` and the value **MUST** be obtained via a ``get_param``.

VNF

MUST

vnf_id

R-37692

The VNFC **MUST** provide API versioning to allow for independent upgrades of VNFC.

VNF

MUST

VNF Design

R-378131

(Error Case) - If an error is encountered by the PNF during a Service Configuration exchange with ONAP, the PNF **MAY** log the error and notify an operator.

PNF

MAY

PNF Plug and Play

R-37929

The VNF or PNF **MUST** accept all necessary instance specific data from the environment or node object attributes for the VNF or PNF in roles/cookbooks/recipes invoked for a VNF or PNF action.

VNF or PNF

MUST

Chef Roles/Requirements

R-379523

A VNF or PNF producing VES events that is buffering events due to an unavailable VES Event Listener **MUST** redeliver all buffered events according to the following rules when the VNF or PNF detects the VES Event Listener has become available: * Deliver all previously buffered events before sending new events * Deliver buffered events in the order they were received

VNF or PNF

MUST

Buffering and Redelivery

R-38001

The VNF **MUST** support ONAP Controller's **Rebuild** command.

VNF

MUST

Virtual Function - Container Recovery Requirements

R-381623

Containerized components of VNFs **SHOULD** execute in a Docker run-time environment that follows the Container Runtime Configuration in the latest available version of the CIS Docker Community Edition Benchmarks to ensure that containerized VNFs are secure. All non-compliances with the benchmarks MUST be documented.

VNF

SHOULD

VNF General Security Requirements

R-38236

The VNF's Heat Orchestration Template's resource ``OS::Neutron::Port`` property ``fixed_ips`` map property ``subnet`` parameter **MUST** be declared type ``string``.

VNF

MUST

Property: fixed_ips, Map Property: subnet

R-384337

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

VNF DOCUMENTATION PACKAGE

MUST

Resource Description

R-38474

A VNF's Base Module **MUST** have a corresponding Environment File.

VNF

MUST

ONAP VNF Modularity Overview

R-39003

The VNF or PNF Provider's Ansible playbooks **MUST** store passwords and other attributes that must remain secret in JSON, YAML or INI files that can be encrypted/decrypted using Ansible Vault capabilities.

VNF or PNF PROVIDER

MUST

Ansible Playbook Requirements

R-39067

A VNF's Heat Orchestration Template's ``OS::Nova::Server`` resource property ``metadata`` key/value pair ``vf_module_name`` parameter **MUST** be declared as ``vf_module_name`` and the parameter **MUST** be defined as type: ``string``.

VNF

MUST

vf_module_name

R-39349

A VNF Heat Orchestration Template **MUST NOT** be designed to utilize the OpenStack ``heat stack-update`` command for scaling (growth/de-growth).

VNF

MUST NOT

Support of heat stack update

R-39402

A VNF's Heat Orchestration Template **MUST** contain the section ``description:``.

VNF

MUST

description

R-39562

The VNF **MUST** disable unnecessary or vulnerable cgi-bin programs.

VNF

MUST

VNF Identity and Access Management Requirements

R-39604

The VNF **MUST** provide the capability of testing the validity of a digital certificate by checking the Certificate Revocation List (CRL) for the certificates of that type to ensure that the certificate has not been revoked.

VNF

MUST

VNF Cryptography Requirements

R-39650

The VNF **SHOULD** provide the ability to test incremental growth of the VNF.

VNF

SHOULD

VNF Devops

R-39841

The VNF's Heat Orchestration Template's Resource ``OS::Neutron::Port`` property ``fixed_ips`` map property ``ip_address`` parameter ``{vm-type}_{network-role}_ip_{index}`` **MUST NOT** be enumerated in the VNF's Heat Orchestration Template's Environment File.

VNF

MUST NOT

Property: fixed_ips, Map Property: ip_address

R-40499

Each VNF's Heat Orchestration Template's ``{vm-type}`` **MUST** have a unique parameter name for the ``OS::Nova::Server`` property ``flavor`` even if more than one ``{vm-type}`` shares the same flavor.

VNF

MUST

Property: flavor

R-40518

A VNF's Heat Orchestration Template's parameter defined in a non-nested YAML file as type ``string`` **MAY** have a parameter constraint defined.

VNF

MAY

constraints

R-40551

A VNF's Heat Orchestration Template's Nested YAML files **MAY** (or **MAY NOT**) contain the section ``resources:``.

VNF

MAY

resources

R-40820

The VNF CSAR PACKAGE **MUST** enumerate all of the open source licenses their VNF(s) incorporate. CSAR License directory as per ETSI SOL004. for example ROOT\\Licenses\\ **License_term.txt**

VNF CSAR PACKAGE

MUST

VNF or PNF Package Contents

R-40827

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

VNF or PNF

MUST

Licensing Requirements

R-408813

A VNF or PNF producing VES events **MUST** pass all information it is able to collect even if the information field is identified as optional. However, if the data cannot be collected, then optional fields can be omitted.

VNF or PNF

MUST

Event Formatting and Usage

R-408814

The VNF or a PNF producing VES stndDefined domain events to report standards-organization defined events to ONAP, **MUST** set the event.stndDefinedNamespace property. By default, ONAP ships with support for the following: * 3GPP-Provisioning * 3GPP-Heartbeat * 3GPP-FaultSupervision * 3GPP-PerformanceAssurance Another namespace, outside of the list provided, needs to registered in ONAP in coordination with the operator before it can be used.

VNF or PNF

MUST

Event Formatting and Usage

R-408815

If the VNF or PNF producing VES stndDefined domain events provides the event.stndDefinedFields.schemaReference then it **MUST** set its value to the publicUrl value in DCAE's VES Collector `etc/externalRepo/schema-map.json <https://github.com/onap/dcaegen2-collectors-ves/blob/guilin/etc/externalRepo/schema-map.json/>`_ that describes the data being sent in event.stndDefinedFields.data.

VNF or PNF

MUST

Event Formatting and Usage

R-408816

If the VNF or PNF producing VES stndDefined domain events provides the event.stndDefinedFields.schemaReference then it **MUST** only pass events that conform to schema references previously registered with DCAE otherwise the event will be rejected. By default, ONAP ships with support for schemas found in DCAE's VES Collector `etc/externalRepo/schema-map.json <https://github.com/onap/dcaegen2-collectors-ves/blob/guilin/etc/externalRepo/schema-map.json/>`_.

VNF or PNF

MUST

Event Formatting and Usage

R-408817

The VNF or PNF Provider producing stndDefined events **MUST** coordinate with the operator, willing to validate stndDefined events, to configure DCAE to accept any new event schema prior to sending those events or the events will be rejected.

VNF or PNF

MUST

Event Formatting and Usage

R-408818

If the VNF or PNF producing VES stndDefined domain events provides the event.stndDefinedFields.schemaReference then it **MUST** set the event.stndDefined.schemaReference property to an exact structure, from supported schemaReference, describing the notification within an openAPI specification, using JSON Pointer as URI fragment e.g. “https://forge.3gpp.org/.../faultMnS.yaml#/components/schemas/notifyNewAlarm"

VNF or PNF

MUST

Event Formatting and Usage

R-40971

When the VNF's Heat Orchestration Template's Resource ``OS::Neutron::Port`` is attaching to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), and an IPv4 address is assigned using the property ``fixed_ips`` map property ``ip_address`` and the parameter type is defined as a string, the parameter name **MUST** follow the naming convention * ``{vm-type}_{network-role}_ip_{index}`` where * ``{vm-type}`` is the {vm-type} associated with the ``OS::Nova::Server`` * ``{network-role}`` is the {network-role} of the ONAP external network * ``{index}`` is a numeric value that **MUST** start at zero in a VNF's Heat Orchestration Template and **MUST** increment by one

VNF

MUST

Property: fixed_ips, Map Property: ip_address

R-41159

The VNF **MUST** deliver any and all functionality from any VNFC in the pool (where pooling is the most suitable solution). The VNFC pool member should be transparent to the client. Upstream and downstream clients should only recognize the function being performed, not the member performing it.

VNF

MUST

System Resource Optimization

R-41215

The VNF **MAY** have zero to many "incremental" modules.

VNF

MAY

ONAP VNF Modularity Overview

R-41252

The VNF **MUST** support the capability of online storage of security audit logs.

VNF

MUST

VNF Security Analytics Requirements

R-41430

The VNF or PNF **MUST** support APPC/SDN-C ``HealthCheck`` command.

VNF or PNF

MUST

HealthCheck and Failure Related Commands

R-41492

When the VNF's Heat Orchestration Template's resource ``OS::Neutron::Port`` is attaching to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), and the IPv4 VIP is required to be supported by the ONAP data model, the property ``allowed_address_pairs`` map property ``ip_address`` parameter name **MUST** follow the naming convention * ``{vm-type}_{network-role}_floating_ip`` where * ``{vm-type}`` is the {vm-type} associated with the ``OS::Nova::Server`` * ``{network-role}`` is the {network-role} of the ONAP external network And the parameter **MUST** be declared as type ``string``. As noted in the introduction to this section, the ONAP data model can only support one IPv4 VIP address.

VNF

MUST

VIP Assignment, ONAP External Networks

R-41493

When the VNF's Heat Orchestration Template's resource ``OS::Neutron::Port`` is attaching to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), and the IPv4 VIP address and/or IPv6 VIP address is **not** supported by the ONAP data model, the property ``allowed_address_pairs`` map property ``ip_address`` * Parameter name **MAY** use any naming convention. That is, there is no ONAP mandatory parameter naming convention. * Parameter **MAY** be declared as type ``string`` or type ``comma_delimited_list``. And the ``OS::Neutron::Port`` resource **MUST** contain resource-level ``metadata`` (not property-level). And the ``metadata`` format **MUST** must contain the key value ``aap_exempt`` with a list of all ``allowed_address_pairs`` map property ``ip_address`` parameters **not** supported by the ONAP data model.

VNF

MUST

VIP Assignment, ONAP External Networks

R-41825

The VNF **MUST** activate security alarms automatically when a configurable number of consecutive unsuccessful login attempts is reached.

VNF

MUST

VNF Security Analytics Requirements

R-41829

The VNF or PNF **MUST** be able to specify the granularity of the lock via a restricted or full XPath expression if ":partial-lock" is supported.

VNF or PNF

MUST

NETCONF Server Requirements

R-41888

A VNF's Heat Orchestration Template intrinsic function ``get_file`` **MUST NOT** utilize URL-based file retrieval.

VNF

MUST NOT

Heat Files Support (get_file)

R-41994

The VNF **MUST** support the use of X.509 certificates issued from any Certificate Authority (CA) that is compliant with RFC5280, e.g., a public CA such as DigiCert or Let's Encrypt, or an RFC5280 compliant Operator CA. Note: The VNF provider cannot require the use of self-signed certificates in an Operator's run time environment.

VNF

MUST

VNF Cryptography Requirements

R-42018

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.

VNF or PNF

MUST

Resource Control Loop

R-42207

The VNF **MUST** design resiliency into a VNF such that the resiliency deployment model (e.g., active-active) can be chosen at run-time.

VNF

MUST

All Layer Redundancy

R-42333

The VNF or PNF Provider's Ansible playbooks that target a subset of VMs (or servers/blades) part of a VNF (or PNF) instance **MUST** be designed to use the VNF or PNF inventory host file and to use a parameter named ``target_vm_list`` to provide the subset of VMs in the VNF instance specifically targeted by the playbook. NOTE: Example of such playbooks would be playbooks used to configure VMs added to a VNF instance as part of a scale-out/up or scale-in/down operation. Such playbook is expected to also need to perform configuration/reconfiguration tasks part of the base VNF instance build.

VNF or PNF PROVIDER

MUST

Ansible Playbook Requirements

R-42685

A VNF's Heat Orchestration template's Environment File's **MAY** contain the ``parameter_merge_strategies:`` section.

VNF

MAY

Environment File Format

R-42874

The VNF **MUST** allow the Operator to restrict access to protected resources based on the assigned permissions associated with an ID in order to support Least Privilege (no more privilege than required to perform job functions).

VNF

MUST

VNF Identity and Access Management Requirements

R-43253

The VNF or PNF Provider's Ansible playbooks **MUST** be 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).

VNF or PNF PROVIDER

MUST

Ansible Playbook Requirements

R-43332

The VNF **MUST** activate security alarms automatically when it detects the successful modification of a critical system or application file.

VNF

MUST

VNF Security Analytics Requirements

R-43353

The VNF or PNF Provider's Ansible playbooks **MUST** return control only after all tasks performed by playbook 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.

VNF or PNF PROVIDER

MUST

Ansible Playbook Requirements

R-43413

A VNF **MUST** utilize a modular Heat Orchestration Template design to support scaling (growth/de-growth).

VNF

MUST

Support of heat stack update

R-43740

VNF's Heat Orchestration Template's Resource **MAY** declare the attribute ``deletion_policy:``.

VNF

MAY

deletion_policy

R-43884

The VNF **SHOULD** integrate with the Operator's authentication and authorization services (e.g., IDAM).

VNF

SHOULD

VNF API Security Requirements

R-43958

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

VNF DOCUMENTATION PACKAGE

MUST

Testing

R-44001

A VNF's Heat Orchestration Template parameter declaration **MUST** contain the attribute ``description``.

VNF

MUST

description

R-44013

The VNF or PNF **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 VNF or PNF action requires the output of a chef-client run be made available (e.g., get running configuration).

VNF or PNF

MUST

Chef Roles/Requirements

R-440220

The VNF or PNF **SHOULD** support File transferring protocol, such as FTPES or SFTP, when supporting the event-driven bulk transfer of monitoring data.

VNF or PNF

SHOULD

Bulk Performance Measurement

R-44271

The VNF's Heat Orchestration Template's Resource ``OS::Nova::Server`` property ``name`` parameter value **SHOULD NOT** contain special characters since the Contrail GUI has a limitation displaying special characters. However, if special characters must be used, the only special characters supported are: --- \" ! $ ' (\ \ ) = ~ ^ | @ ` { } [ ] > , . _

VNF

SHOULD NOT

Contrail Issue with Values for OS::Nova::Server Property Name

R-44281

The VNF or PNF **MUST** implement the protocol operation: ``edit-config(target, default-operation, test-option, error-option, config)`` - Edit the target configuration data store by merging, replacing, creating, or deleting new config elements.

VNF or PNF

MUST

NETCONF Server Requirements

R-44318

A VNF's Heat Orchestration Template's ``OS::Nova::Server`` resource property ``metadata`` key/value pair ``vnf_name`` parameter ``vnf_name`` **MUST NOT** have parameter constraints defined.

VNF

MUST NOT

vnf_name

R-444446

The VNF or PNF Provider's Ansible playbooks **SHOULD** issue log messages in the same format as Ansible's default messages: ``[<Log Level>]: <message>`` Example: ``[WARNING]: Ansible version 2.9.3 does not match a known, tested version: 2.8.1, 2.8.2``

VNF or PNF PROVIDER

SHOULD

Ansible Playbook Requirements

R-44569

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.

VNF or PNF

MUST NOT

Licensing Requirements

R-44723

The VNF **MUST** use symmetric keys of at least 112 bits in length.

VNF

MUST

VNF Cryptography Requirements

R-44896

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

VNF

MUST

Compute, Network, and Storage Requirements

R-45188

The VNF's Heat Orchestration Template's Resource 'OS::Nova::Server' property ``flavor`` parameter name **MUST** follow the naming convention ``{vm-type}_flavor_name``.

VNF

MUST

Property: flavor

R-45197

The VNF or PNF **MUST** define the "from=" clause to provide the list of IP addresses of the Ansible Servers in the Cluster, separated by coma, to restrict use of the SSH key pair to elements that are part of the Ansible Cluster owner of the issued and assigned mechanized user ID.

VNF or PNF

MUST

Ansible Client Requirements

R-45602

If a VNF's Port is attached to a network (internal or external) and the port's IP addresses are cloud assigned by OpenStack's DHCP Service, the ``OS::Neutron::Port`` Resource's * property ``fixed_ips`` map property ``ip_address`` **MUST NOT** be used * property ``fixed_ips`` map property ``subnet`` **MAY** be used

VNF

MUST NOT

Items to Note

R-45719

The VNF **MUST**, if not integrated with the Operator's Identity and Access Management system, enforce a configurable "terminate idle sessions" policy by terminating the session after a configurable period of inactivity.

VNF

MUST

VNF Identity and Access Management Requirements

R-45856

The VNF or PNF **MUST** support APPC/SDN-C ``UpgradePostCheck`` command.

VNF or PNF

MUST

Lifecycle Management Related Commands

R-460012

The VNF or PNF producing VES events **MUST** allow the configuration of the attributes defined in Table 1 and utilize the provided default value (where applicable) when the configuration value is not provided by the Service Provider.

VNF or PNF

MUST

Configuration Requirements

R-46096

A VNF's Heat Orchestration template's Environment File's **MAY** contain the ``encrypted_parameters:`` section.

VNF

MAY

Environment File Format

R-46119

A VNF's Heat Orchestration Template's Resource ``OS::Cinder::Volume`` **MAY** be defined in a Base Module.

VNF

MAY

ONAP VNF Modularity Overview

R-46128

A VNF's Heat Orchestration Template's Resource ``OS::ContrailV2::InstanceIp`` Resource ID that is configuring an IPv6 Address on a virtual machine interface (i.e., OS::ContrailV2::VirtualMachineInterface) attached to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968) **MUST** use the naming convention * ``{vm-type}_{vm-type_index}_{network-role}_vmi_{vmi_index}_v6_IP_{index}`` where * ``{vm-type}`` is the vm-type * ``{vm-type_index}`` references the instance of the ``{vm-type}`` in the VNF. The ``{vm-type_index}`` is a numeric value that **MUST** start at zero in the VNF and **MUST** increment by one each time a new instance of a ``{vm-type}`` is referenced. * ``{network-role}`` is the network-role of the ONAP external network that the port is attached to * ``{vmi_index}`` references the instance of the virtual machine interface on the ``{vm-type}`` attached to ``{network-role}`` network. The ``{vmi_index}`` is a numeric value that **MUST** start at zero on an instance of a ``{vm-type}`` and **MUST** increment by one each time a new virtual machine interface is defined on the instance of the ``{vm-type}`` attached to ``{network-role}`` network. * ``v6_IP`` signifies that an IPv6 address is being configured * ``{index}`` references the instance of the IPv6 address configured on the virtual machine interface. The ``{index}`` is a numeric value that **MUST** start at zero on an instance of a virtual machine interface and **MUST** increment by one each time a new IPv6 address is configured on the virtual machine interface.

VNF

MUST

OS::ContrailV2::InstanceIp

R-46461

A VNF's port connected to an ONAP internal network **MUST NOT** use the port for the purpose of reaching VMs in another VNF and/or an external gateway and/or external router.

VNF

MUST NOT

Internal Networks

R-465236

The VNF **SHOULD** provide the capability of maintaining the integrity of its static files using a cryptographic method.

VNF

SHOULD

VNF Security Analytics Requirements

R-46527

A VNFD is a deployment template which describes a VNF in terms of deployment and operational behavior requirements. It contains virtualized resources (nodes) requirements as well as connectivity and interfaces requirements and **MUST** comply with info elements specified in ETSI GS NFV-IFA 011. The main parts of the VNFD are the following: - VNF topology: it is modeled in a cloud agnostic way using virtualized containers and their connectivity. Virtual Deployment Units (VDU) describe the capabilities of the virtualized containers, such as virtual CPU, RAM, disks; their connectivity is modeled with VDU Connection Point Descriptors (VduCpd), Virtual Link Descriptors (VnfVld) and VNF External Connection Point Descriptors (VnfExternalCpd); - VNF deployment aspects: they are described in one or more deployment flavours, including configurable parameters, instantiation levels, placement constraints (affinity / antiaffinity), minimum and maximum VDU instance numbers. Horizontal scaling is modeled with scaling aspects and the respective scaling levels in the deployment flavours; **Note**: The deployment aspects (deployment flavour etc.) are postponed for future ONAP releases. - VNF lifecycle management (LCM) operations: describes the LCM operations supported per deployment flavour, and their input parameters; Note, thatthe actual LCM implementation resides in a different layer, namely referring to additional template artifacts.

VNF

MUST

General

R-46567

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

VNF or PNF

MUST

Configuration Management via Ansible

R-46823

The VNF or PNF Provider's Ansible playbooks **MUST** store passwords and other attributes that must remain secret in JSON, YAML or INI with differentiated names when passwords and secrets vary from environment to environment. Example, name must include <Mechanized user ID>_...json or <Mechanized user ID>_...xml when labs and production use different passwords and/or secrets. The <Mechanized user ID> is discovered from the environment ``/etc/ansible/ansible.cfg`` where the playbook runs.

VNF or PNF PROVIDER

MUST

Ansible Playbook Requirements

R-46839

A VNF's Heat Orchestration Template's use of ``{vm-type}`` in all Resource IDs **MUST** be the same case.

VNF

MUST

{vm-type}

R-46851

The VNF **MUST** support ONAP Controller's Evacuate command.

VNF

MUST

Virtual Function - Container Recovery Requirements

R-46908

The VNF **MUST**, if not integrated with the Operator's Identity and Access Management system, comply with "password complexity" policy. When passwords are used, they shall be complex and shall at least meet the following password construction requirements: (1) be a minimum configurable number of characters in length, (2) include 3 of the 4 following types of characters: upper-case alphabetic, lower-case alphabetic, numeric, and special, (3) not be the same as the UserID with which they are associated or other common strings as specified by the environment, (4) not contain repeating or sequential characters or numbers, (5) not to use special characters that may have command functions, and (6) new passwords must not contain sequences of three or more characters from the previous password.

VNF

MUST

VNF Identity and Access Management Requirements

R-46960

NCSPs **MAY** operate a limited set of Guest OS and CPU architectures and families, virtual machines, etc.

VNF

MAY

VNF Devops

R-46968

VNF's Heat Orchestration Template's Resource **MAY** declare the attribute ``depends_on:``.

VNF

MAY

depends_on

R-46986

The VNF provider **MUST** follow GSMA vendor practices and SEI CERT Coding Standards when developing the VNF in order to minimize the risk of vulnerabilities. See GSMA NESAS Network Equipment Security Assurance Scheme – Development and Lifecycle Security Requirements Version 1.0 (https://www.gsma.com/ security/wp-content/uploads/2019/11/FS.16-NESAS-Development-and-Lifecycle-Security- Requirements-v1.0.pdf) and SEI CERT Coding Standards (https://wiki.sei.cmu.edu/ confluence/display/seccode/SEI+CERT+Coding+Standards).

VNF

MUST

VNF General Security Requirements

R-47061

A VNF's Heat Orchestration Template's OS::Nova::Server Resource **SHOULD** contain the metadata map value parameter 'workload_context'.

VNF

SHOULD

workload_context

R-47068

The VNF or PNF **MAY** expose a single endpoint that is responsible for all functionality.

VNF or PNF

MAY

Chef Client Requirements

R-470963

A VNF or PNF producing VES events **SHOULD** leverage camel case to separate words and acronyms used as keys that will be sent through extensible fields. When an acronym is used as the key, then only the first letter shall be capitalized.

VNF or PNF

SHOULD

Event Formatting and Usage

R-47204

The VNF **MUST** be capable of protecting the confidentiality and integrity of data at rest and in transit from unauthorized access and modification.

VNF

MUST

VNF Data Protection Requirements

R-47849

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.

VNF or PNF

MUST

Licensing Requirements

R-47874

A VNF **MAY** have * Only an IPv4 OAM Management IP Address * Only an IPv6 OAM Management IP Address * Both a IPv4 and IPv6 OAM Management IP Addresses

VNF

MAY

OAM Management IP Addresses

R-479386

The VNF **MUST** provide the capability of setting a configurable message to be displayed after successful login. It MAY provide a list of supported character sets.

VNF

MUST

VNF Identity and Access Management Requirements

R-48067

A VNF's Heat Orchestration Template's ``{vm-type}`` **MUST NOT** be a substring of ``{network-role}``.

VNF

MUST NOT

{vm-type}

R-48080

The VNF **SHOULD** support an automated certificate management protocol such as CMPv2, Simple Certificate Enrollment Protocol (SCEP) or Automated Certificate Management Environment (ACME).

VNF

SHOULD

VNF Cryptography Requirements

R-481670

The VNF's Heat Orchestration Template's Resource ``OS::Nova::Server`` property ``flavor`` value **MUST** be be obtained via a ``get_param``.

VNF

MUST

Property: flavor

R-48247

The VNF or PNF **MUST** support APPC ``ConfigRestore`` command.

VNF or PNF

MUST

Configuration Commands

R-48356

The VNF **MUST** fully exploit exception handling to the extent that resources (e.g., threads and memory) are released when no longer needed regardless of programming language.

VNF

MUST

Application Resilient Error Handling

R-48470

The VNF **MUST** support Real-time detection and notification of security events.

VNF

MUST

VNF Security Analytics Requirements

R-484843

The PNFD provided by a PNF vendor **MUST** comply with the following Data Types as specified in ETSI NFV-SOL001 standard: - tosca.datatypes.nfv.CpProtocolData - tosca.datatypes.nfv.AddressData - tosca.datatypes.nfv.L2AddressData - tosca.datatypes.nfv.L3AddressData - tosca.datatypes.nfv.LocationInfo - tosca.datatypes.nfv.CivicAddressElement

PNF

MUST

Data Types

R-48596

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

VNF or PNF DOCUMENTATION PACKAGE

MUST

Resource Control Loop

R-48698

The VNF or PNF Provider's Ansible playbooks **MUST** utilize information from key value pairs that will be provided by the Ansible Server as ``extra-vars`` during invocation to execute the desired VNF or PNF action. The "extra-vars" attribute-value pairs are passed to the Ansible Server by an APPC/SDN-C as part of the Rest API request. 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. Any files containing instance specific info (attribute-value pairs), not obtainable from any ONAP inventory databases or other sources, referenced and used as input by playbooks, shall be provisioned (and distributed) in advance of use, e.g., VNF or PNF instantiation. Recommendation is to avoid these instance specific, manually created in advance of instantiation, files.

VNF or PNF PROVIDER

MUST

Ansible Playbook Requirements

R-48761

The VNF **MUST** support ONAP Controller's Snapshot command.

VNF

MUST

Virtual Function - Container Recovery Requirements

R-48880

If a VNF's Port is attached to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968) and the port's IP addresses are assigned by ONAP's SDN-Controller, the ``OS::Neutron::Port`` Resource's * property ``fixed_ips`` map property ``ip_address`` **MUST** be used * property ``fixed_ips`` map property ``subnet`` **MUST NOT** be used

VNF

MUST

Items to Note

R-48917

The VNF **MUST** monitor for and alert on (both sender and receiver) errant, running longer than expected and missing file transfers, so as to minimize the impact due to file transfer errors.

VNF

MUST

Monitoring & Dashboard

R-48987

If the VNF's OAM Management IP Address is cloud assigned and and the OAM IP Address is required to be inventoried in ONAP A&AI, then the parameter **MUST** be obtained by the resource ``OS::Neutron::Port`` attribute ``ip_address``.

VNF

MUST

OAM Management IP Addresses

R-49036

The VNF or PNF **SHOULD** conform its YANG model to RFC 7277, "A YANG Data Model for IP Management".

VNF or PNF

SHOULD

NETCONF Server Requirements

R-49109

The VNF or PNF **MUST** support HTTPS using TLS v1.2 or higher with strong cryptographic ciphers.

VNF or PNF

MUST

VNF Cryptography Requirements

R-49145

The VNF or PNF **MUST** implement ``:confirmed-commit`` If ``:candidate`` is supported.

VNF or PNF

MUST

NETCONF Server Requirements

R-49224

The VNF **MUST** provide unique traceability of a transaction through its life cycle to ensure quick and efficient troubleshooting.

VNF

MUST

Monitoring & Dashboard

R-49308

The VNF **SHOULD** test for adherence to the defined resiliency rating recommendation at each layer, during each delivery cycle with delivered results, so that the resiliency rating is measured and the code is adjusted to meet software resiliency requirements.

VNF

SHOULD

Deployment Optimization

R-49396

The VNF or PNF Provider's Ansible playbooks **MUST** support each APPC/SDN-C VNF or PNF action by invocation of **one** playbook [#7.3.4]_. The playbook will be responsible for executing all necessary tasks (as well as calling other playbooks) to complete the request.

VNF or PNF PROVIDER

MUST

Ansible Playbook Requirements

R-49466

The VNF or PNF **MUST** support APPC/SDN-C ``UpgradeSoftware`` command.

VNF or PNF

MUST

Lifecycle Management Related Commands

R-498679

A VNF or PNF producing VES events **MAY** discard buffered events older than a maximum retention period, not less than 1 hour, even if the event was never successfully delivered to the event listener. While discarding based on this retention period is supported for backwards compatibility, it is recommended to retain events until the maximum buffer size is reached per R-346137 as that will maximize the number of events delivered.

VNF or PNF

MAY

Buffering and Redelivery

R-49911

The VNF or PNF Provider **MUST** assign a new point release to the updated Ansible playbook set. The functionality of a new playbook set must be tested before it is deployed to the production.

VNF or PNF PROVIDER

MUST

Ansible Playbook Requirements

R-50011

A VNF's Heat Orchestration Template's ``OS::Heat::ResourceGroup`` property ``count`` **MUST** be enumerated in the VNF's Heat Orchestration Template's Environment File and **MUST** be assigned a value.

VNF

MUST

OS::Heat::ResourceGroup Property count

R-50252

The VNF or PNF Provider's Ansible playbooks **MUST** write to a response file in JSON format that will be retrieved and made available by the Ansible Server if, as part of a VNF or PNF action (e.g., audit), a playbook is required to return any VNF or PNF information/response. The text files must be written in the main playbook home directory, in JSON format. The JSON file must be created for the VNF or PNF with the name '<VNF or PNF name>_results.txt'. All playbook output results, for all VNF VMS or PNF Server/Blades, to be provided as a response to the request, must be written to this response file.

VNF or PNF PROVIDER

MUST

Ansible Playbook Requirements

R-50436

The VNF's Heat Orchestration Template's Resource ``OS::Nova::Server`` property ``flavor`` parameter **MUST** be declared as type: ``string``.

VNF

MUST

Property: flavor

R-50468

A VNF's Heat Orchestration Template's Resource ``OS::ContrailV2::VirtualMachineInterface`` Resource ID that is attaching to an ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666) **MUST** use the naming convention * ``{vm-type}_{vm-type_index}_int_{network-role}_vmi_{vmi_index}`` where * ``{vm-type}`` is the vm-type * ``{vm-type_index}`` references the instance of the ``{vm-type}`` in the VNF. The ``{vm-type_index}`` is a numeric value that **MUST** start at zero in the VNF and **MUST** increment by one each time a new instance of a ``{vm-type}`` is referenced. * ``{network-role}`` is the network-role of the ONAP internal network that the port (i.e. virtual machine interface) is attached to * ``{vmi_index}`` references the instance of the virtual machine interface on the ``{vm-type}`` attached to ``{network-role}`` network. The ``{vmi_index}`` is a numeric value that **MUST** start at zero on an instance of a ``{vm-type}`` and **MUST** increment by one each time a new virtual machine interface is defined on the instance of the ``{vm-type}`` attached to ``{network-role}`` network.

VNF

MUST

OS::ContrailV2::VirtualMachineInterface

R-506221

The VNF or PNF CSAR file **MUST** be a zip file with .csar extension.

VNF or PNF CSAR PACKAGE

MUST

VNF or PNF Package Structure and Format

R-50816

A VNF's Heat Orchestration Template's ``OS::Nova::Server`` resource property ``metadata`` key/value pair ``vf_module_index`` value **MUST** be obtained via a ``get_param``.

VNF

MUST

vf_module_index

R-511776

When a VNF's Heat Orchestration Template is ready to be on-boarded to ONAP, all files composing the VNF Heat Orchestration Template **MUST** be placed in a flat (i.e., non-hierarchical) directory and archived using ZIP. The resulting ZIP file is uploaded into ONAP.

VNF

MUST

ONAP VNF On-Boarding

R-51347

The VNF or PNF CSAR package **MUST** be arranged as a CSAR archive as specified in TOSCA Simple Profile in YAML 1.2.

VNF or PNF CSAR PACKAGE

MUST

VNF or PNF Package Structure and Format

R-51430

The VNF's Heat Orchestration Template's Resource ``OS::Nova::Server`` property ``name`` parameter **MUST** be declared as either type ``string`` or type ``comma_delimited_list``.

VNF

MUST

Property: Name

R-51442

The VNF or PNF Provider's Ansible playbooks **SHOULD** be designed to automatically 'rollback' to the original state in case of any errors for actions that change state of the VNF or PNF (e.g., configure). **Note**: In case rollback at the playbook level is not supported or possible, the VNF or PNF provider shall provide alternative rollback mechanism (e.g., for a small VNF or PNF the rollback mechanism may rely on workflow to terminate and re-instantiate VNF VMs and then re-run playbook(s)). Backing up updated files is also recommended to support rollback when soft rollback is feasible.

VNF or PNF PROVIDER

SHOULD

Ansible Playbook Requirements

R-52060

The VNF **MUST** provide the capability to configure encryption algorithms or devices so that they comply with the laws of the jurisdiction in which there are plans to use data encryption.

VNF

MUST

VNF Cryptography Requirements

R-520802

If the VNF or PNF is using VES, then the VNF or PNF Provider **MUST** provide a YAML file formatted in adherence with the :ref:`VES Event Registration specification <ves_event_registration_3_2>` that defines the following information for each event produced by the VNF: * ``eventName`` * Required fields * Optional fields * Any special handling to be performed for that event

VNF or PNF PROVIDER

MUST

Event Definition and Registration

R-52425

A VNF's port connected to an ONAP internal network **MUST** use the port for the purpose of reaching VMs in the same VNF.

VNF

MUST

Internal Networks

R-52499

The VNF **MUST** meet their own resiliency goals and not rely on the Network Cloud.

VNF

MUST

All Layer Redundancy

R-52753

VNF's Heat Orchestration Template's Base Module's output parameter's name and type **MUST** match the VNF's Heat Orchestration Template's incremental Module's name and type.

VNF

MUST

ONAP Base Module Output Parameters

R-52870

The VNF **MUST** provide a method of metrics gathering and analysis to evaluate the resiliency of the software from both a granular as well as a holistic standpoint. This includes, but is not limited to thread utilization, errors, timeouts, and retries.

VNF

MUST

Monitoring & Dashboard

R-528866

The VES events produced by the VNF or PNF **MUST** conform to the schema and other formatting requirements specified in the relevant VES Event Listener specification.

VNF or PNF

MUST

Event Formatting and Usage

R-53015

The VNF or PNF **MUST** apply locking based on the sequence of NETCONF operations, with the first configuration operation locking out all others until completed.

VNF or PNF

MUST

NETCONF Server Requirements

R-53245

The VNF or PNF Provider's Ansible playbooks **MUST NOT** require passwords or secrets to be passed in clear text in the command line or Rest API request to run the playbook.

VNF or PNF PROVIDER

MUST NOT

Ansible Playbook Requirements

R-53310

A VNF's Heat Orchestration Template's Resource ``OS::ContrailV2::InstanceIp`` Resource ID that is configuring an IPv4 Address on a virtual machine interface (i.e., OS::ContrailV2::VirtualMachineInterface) attached to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968) **MUST** use the naming convention * ``{vm-type}_{vm-type_index}_{network-role}_vmi_{vmi_index}_IP_{index}`` where * ``{vm-type}`` is the vm-type * ``{vm-type_index}`` references the instance of the ``{vm-type}`` in the VNF. The ``{vm-type_index}`` is a numeric value that **MUST** start at zero in the VNF and **MUST** increment by one each time a new instance of a ``{vm-type}`` is referenced. * ``{network-role}`` is the network-role of the ONAP external network that the virtual machine interface is attached to * ``{vmi_index}`` references the instance of the virtual machine interface on the ``{vm-type}`` attached to ``{network-role}`` network. The ``{vmi_index}`` is a numeric value that **MUST** start at zero on an instance of a ``{vm-type}`` and **MUST** increment by one each time a new virtual machine interface is defined on the instance of the ``{vm-type}`` attached to ``{network-role}`` network. * ``IP`` signifies that an IPv4 address is being configured * ``{index}`` references the instance of the IPv4 address configured on the virtual machine interface. The ``{index}`` is a numeric value that **MUST** start at zero on an instance of a virtual machine interface and **MUST** increment by one each time a new IPv4 address is configured on the virtual machine interface.

VNF

MUST

OS::ContrailV2::InstanceIp

R-53317

The VNF or PNF **SHOULD** conform its YANG model to RFC 8407, "Guidelines for Authors and Reviewers of YANG Data Model specification".

VNF or PNF

SHOULD

NETCONF Server Requirements

R-53433

A VNF's Cinder Volume Module **MUST** have a corresponding environment file

VNF

MUST

ONAP VNF Modularity Overview

R-535009

The PNFD provided by a PNF vendor **MUST** comply with the following Node Types as specified in ETSI NFV-SOL001 standard: - tosca.nodes.nfv.PNF - tosca.nodes.nfv.PnfExtCp - tosca.nodes.nfv.Cp

PNF

MUST

Node Types

R-53598

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.

VNF or PNF DOCUMENTATION PACKAGE

MUST

Resource Control Loop

R-53952

A VNF's Heat Orchestration Template's Resource **MUST NOT** reference a HTTP-based resource definitions.

VNF

MUST NOT

type

R-54171

When the VNF's Heat Orchestration Template's Resource ``OS::Nova::Server`` property ``name`` parameter is defined as a ``string``, the parameter name **MUST** follow the naming convention * ``{vm-type}_name_{index}`` where ``{index}`` is a numeric value that **MUST** start at zero in a VNF's Heat Orchestration Template and **MUST** increment by one.

VNF

MUST

Property: Name

R-54190

The VNF or PNF **MUST** release locks to prevent permanent lock-outs when/if a session applying the lock is terminated (e.g., SSH session is terminated).

VNF or PNF

MUST

NETCONF Server Requirements

R-54340

A VNF's Heat Orchestration Template's ``OS::Nova::Server`` resource property ``metadata`` key/value pair ``vf_module_index`` parameter **MUST** be declared as ``vf_module_index`` and the parameter **MUST** be defined as type: ``number``.

VNF

MUST

vf_module_index

R-54356

The below table includes the data types used by NFV node and is based on TOSCA/YAML constructs specified in draft GS NFV-SOL 001. The node data definitions/attributes used in VNFD **MUST** comply with the below table.

VNF

MUST

Data Types

R-54373

The VNF or PNF Provider **MUST** provide Ansible playbooks that are compatible with the Operator’s deployed versions of Ansible and Python. As the Ansible runtime itself is not deployed as part of ONAP, the ONAP project cannot dictate the specific versions supported.

VNF or PNF

MUST

Ansible Client Requirements

R-54430

The VNF **MUST** use the NCSP's supported library and compute flavor that supports DPDK to optimize network efficiency if using DPDK. [#4.1.1]_

VNF

MUST

VNF Design

R-54517

When a VNF's Heat Orchestration Template's resource is associated with a single ``{vm-type}``, the Resource ID **MUST** contain the ``{vm-type}``.

VNF

MUST

Resource IDs

R-54520

The VNF **MUST** log successful and unsuccessful authentication attempts, e.g., authentication associated with a transaction, authentication to create a session, authentication to assume elevated privilege.

VNF

MUST

VNF Security Analytics Requirements

R-54816

The VNF **MUST** support the storage of security audit logs for a configurable period of time.

VNF

MUST

VNF Security Analytics Requirements

R-54876

The below table describes the data types used for LCM configuration and is based on TOSCA constructs specified in draft GS NFV-SOL 001. The LCM configuration data elements used in VNFD **MUST** comply with the below table.

VNF

MUST

Data Types

R-54930

The VNF **MUST** implement the following input validation controls: Do not permit input that contains content or characters inappropriate to the input expected by the design. Inappropriate input, such as SQL expressions, may cause the system to execute undesirable and unauthorized transactions against the database or allow other inappropriate access to the internal network (injection attacks).

VNF

MUST

VNF API Security Requirements

R-55218

A VNF's Heat Orchestration Template's ``OS::Nova::Server`` resource property ``metadata`` key/value pair ``vnf_id`` parameter ``vnf_id`` **MUST NOT** have parameter constraints defined.

VNF

MUST NOT

vnf_id

R-55306

A VNF's Heat Orchestration Template's ``OS::Nova::Server`` resource property ``metadata`` key/value pair ``vf_module_index`` **MUST NOT** be used in a ``OS::Cinder::Volume`` resource and **MUST NOT** be used in VNF's Volume template; it is not supported.

VNF

MUST NOT

vf_module_index

R-55307

A VNF's Heat Orchestration Template's parameter ``vf_module_index`` **MUST NOT** be used for indexing an: - ``OS::Nova::Server`` property ``name`` parameter (when defined as a ``comma_delimited_list``). - ``OS::Neutron::Port`` property ``fixed_ips`` map property ``ip_address`` parameter (when defined as a ``comma_delimited_list``) when the port is attaching to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968) - ``OS::ContrailV2::InstanceIp`` property ``instance_ip_address`` parameter (when defined as a ``comma_delimited_list``) when the port (i.e, ``OS::ContrailV2::VirtualMachineInterface``) is attaching to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968)

VNF

MUST NOT

vf_module_index

R-55345

The VNF **SHOULD** use techniques such as "lazy loading" when initialization includes loading catalogues and/or lists which can grow over time, so that the VNF startup time does not grow at a rate proportional to that of the list.

VNF

SHOULD

System Resource Optimization

R-55478

The VNF **MUST** log logoffs.

VNF

MUST

VNF Security Analytics Requirements

R-554966

The VNF or PNF **MUST** report performance metrics using :ref:`Virtual Function Event Streaming (VES) <ves_monitoring_requirements>` or :ref:`bulk_performance_measurement`.

VNF or PNF

MUST

Monitoring and Fault Protocol Selection

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

VNF

MUST

Compute, Network, and Storage Requirements

R-56183

A VNF's Heat Orchestration Template's ``OS::Nova::Server`` resource property ``metadata``key/value pair ``environment_context`` parameter ``environment_context`` **MUST NOT** have parameter constraints defined.

VNF

MUST NOT

environment_context

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.

VNF

MUST

Virtual Function - Container Recovery Requirements

R-56287

If the VNF's OAM Management IP Address is assigned by ONAP SDN-C and assigned in the VNF's Heat Orchestration Template's via a heat resource ``OS::Neutron::Port`` property ``fixed_ips`` map property ``ip_adress`` parameter (e.g., ``{vm-type}_{network-role}_ip_{index}``, ``{vm-type}_{network-role}_v6_ip_{index}``) and the OAM IP Address is required to be inventoried in ONAP A&AI, then the parameter **MUST** be echoed in an output statement. .. code-block:: yaml outputs: oam_management_v4_address: value: {get_param: {vm-type}_{network-role}_ip_{index} } oam_management_v6_address: value: {get_param: {vm-type}_{network-role}_v6_ip_{index} }

VNF

MUST

OAM Management IP Addresses

R-56385

The VNF or PNF **MUST** support APPC ``Audit`` command.

VNF or PNF

MUST

Configuration Commands

R-56438

A VNF's Heat Orchestration Template's Nested YAML file extension **MUST** be in the lower case format ``.yaml`` or ``.yml``.

VNF

MUST

ONAP Heat Orchestration Template Filenames

R-56718

The PNF Vendor **MAY** provide software version(s) to be supported by PNF for SDC Design Studio PNF Model. This is set in the PNF Model property software_versions.

PNF

MAY

PNF Plug and Play

R-56721

A VNF's Incremental Module **MAY** utilize nested heat.

VNF

MAY

Nested Heat Orchestration Templates Overview

R-56793

The VNF **MUST** test for adherence to the defined performance budgets at each layer, during each delivery cycle with delivered results, so that the performance budget is measured and the code is adjusted to meet performance budget.

VNF

MUST

Deployment Optimization

R-56815

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

VNF or PNF DOCUMENTATION PACKAGE

MUST

Resource Control Loop

R-56904

The VNF **MUST** interoperate with the ONAP (SDN) Controller so that it can dynamically modify the firewall rules, ACL rules, QoS rules, virtual routing and forwarding rules. This does not preclude the VNF providing other interfaces for modifying rules.

VNF

MUST

VNF General Security Requirements

R-56920

The VNF **MUST** protect all security audit logs (including API, OS and application-generated logs), security audit software, data, and associated documentation from modification, or unauthorized viewing, by standard OS access control mechanisms, by sending to a remote system, or by encryption.

VNF

MUST

VNF Security Analytics Requirements

R-56988

The VNF or PNF Provider's Ansible playbooks **MUST** load any configuration data that requires encryption (passwords, secrets, etc.) in a JSON (.json), YAML (.yaml|.yml) or INI (.ini) file, from the ``<VNF type>/<Version>/ansible/vars`` directory.

VNF or PNF PROVIDER

MUST

Ansible Playbook Requirements

R-570134

The VES events produced by the VNF or PNF **MUST** be compliant with the common event formats defined in one of the following specifications: * :ref:`VES Event Listener 5.4.1<ves_event_listener_5_4_1>` * :ref:`VES Event Listener 7.1.1<ves_event_listener_7_1>` * :ref:`VES Event Listener 7.2<ves_event_listener_7_2>` The latest version (7.2) should be preferred. Earlier versions are provided for backwards compatibility.

VNF or PNF

MUST

Event Formatting and Usage

R-57019

The PNF CSAR PACKAGE Manifest file **MUST** start with the PNF package metadata in the form of a name-value pairs. Each pair shall appear on a different line. The name is specified as following: - pnfd_provider - pnfd_name - pnfd_release_date_time - pnfd_archive_version

PNF CSAR PACKAGE

MUST

VNF or PNF Package Contents

R-57282

Each VNF's Heat Orchestration Template's ``{vm-type}`` **MUST** have a unique parameter name for the ``OS::Nova::Server`` property ``image`` even if more than one ``{vm-type}`` shares the same image.

VNF

MUST

Property: image

R-57424

A VNF's port connected to an ONAP external network **MAY** use the port for the purpose of - Connecting a VM in the VNF to VMs in another VNF and/or - Connecting a VM in the VNF to an external gateway or external router and/or - Connecting a VM in the VNF to other VMs in the same VNF

VNF

MAY

External Networks

R-57617

The VNF **MUST** include the field "success/failure" in the Security alarms (where applicable and technically feasible).

VNF

MUST

VNF Security Analytics Requirements

R-57855

The VNF **MUST** support hitless staggered/rolling deployments between its redundant instances to allow "soak-time/burn in/slow roll" which can enable the support of low traffic loads to validate the deployment prior to supporting full traffic loads.

VNF

MUST

Deployment Optimization

R-581188

The VNF **MUST NOT** identify the reason for a failed authentication, only that the authentication failed.

VNF

MUST NOT

VNF Identity and Access Management Requirements

R-58301

The VNF or PNF Provider's Ansible playbooks **SHOULD NOT** 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 Playbook related artifacts. **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 APPC/SDN-C. There are policies, as part of Control Loop models, that send remediation action requests to an APPC/SDN-C; these are triggered as a response to an event or correlated events published to Event Bus.

VNF or PNF PROVIDER

SHOULD NOT

Ansible Playbook Requirements

R-58358

The VNF or PNF **MAY** implement the ``:with-defaults`` capability [RFC6243].

VNF or PNF

MAY

NETCONF Server Requirements

R-58370

The VNF **SHOULD** operate with anti-virus software which produces alarms every time a virus is detected.

VNF

SHOULD

VNF Security Analytics Requirements

R-58421

The VNF **SHOULD** be decomposed into granular re-usable VNFCs.

VNF

SHOULD

VNF Design

R-58424

A VNF's Heat Orchestration Template's use of ``{network-role}`` in all Resource property parameter names **MUST** be the same case.

VNF

MUST

{network-role}

R-58670

The VNF's Heat Orchestration Template's Resource ``OS::Nova::Server`` property ``image`` parameter name **MUST** follow the naming convention ``{vm-type}_image_name``.

VNF

MUST

Property: image

R-58775

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.

VNF

MUST

Testing

R-589037

A VNF Heat Orchestration Template's Cinder Volume Module ``resources:`` section **MUST** only be defined using one of the following: * one of more ``OS::Cinder::Volume`` resources * one or more ``OS::Heat::ResourceGroup`` resources that call a nested YAML file that contains only ``OS::Cinder::Volume`` resources * a resource that calls a nested YAML file (static nesting) that contains only ``OS::Cinder::Volume`` resources

VNF

MUST

Cinder Volume Modules

R-58964

The VNF **MUST** provide the capability to restrict read and write access to data handled by the VNF.

VNF

MUST

VNF Data Protection Requirements

R-59391

The VNF **MUST NOT** allow the assumption of the permissions of another account to mask individual accountability. For example, use SUDO when a user requires elevated permissions such as root or admin.

VNF

MUST NOT

VNF Identity and Access Management Requirements

R-59434

A VNF's Heat Orchestration Template's Resource ``OS::Neutron::Subnet`` Resource ID **SHOULD** use the naming convention * ``int_{network-role}_subnet_{index}`` where * ``{network-role}`` is the network-role of the ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666). * ``{index}`` is the ``{index}`` of the subnet of the ONAP internal network. The ``{index}`` starts at zero and increments by one (as described in R-11690).

VNF

SHOULD

OS::Neutron::Subnet

R-59482

A VNF's Heat Orchestration Template **MUST NOT** be VNF instance specific or cloud site specific.

VNF

MUST NOT

Scope of a Heat Orchestration Template

R-59568

The VNF's Heat Orchestration Template's Resource ``OS::Nova::Server`` property ``availability_zone`` parameter **MUST NOT** be enumerated in the Heat Orchestration Template's Environment File.

VNF

MUST NOT

Property: availability_zone

R-596064

The PNFD provided by a PNF vendor **MUST** comply with the following Policy Types as specified in ETSI NFV-SOL001 standard: - tosca.policies.nfv.SecurityGroupRule

PNF

MUST

Policy Types

R-59610

The VNF or PNF **MUST** implement the data model discovery and download as defined in [RFC6022].

VNF or PNF

MUST

NETCONF Server Requirements

R-59930

A VNF's Heat Orchestration template's Environment File's **MAY** contain the ``parameter_defaults:`` section.

VNF

MAY

Environment File Format

R-599443

A parameter enumerated in a VNF's Heat Orchestration Template's environment file **MUST** be declared in the corresponding VNF's Heat Orchestration Template's YAML file's ``parameters:`` section.

VNF

MUST

ONAP Heat Support of Environment Files

R-60011

A VNF's Heat Orchestration Template **MUST** have no more than two levels of nesting.

VNF

MUST

Nested Heat Template Requirements

R-60106

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

VNF or PNF

MUST

NETCONF Server Requirements

R-60656

The VNF or PNF **MUST** support sub tree filtering.

VNF or PNF

MUST

NETCONF Server Requirements

R-61001

A shared Heat Orchestration Template resource is a resource that **MUST** be defined in the base module and will be referenced by one or more resources in one or more incremental modules. The UUID of the shared resource (created in the base module) **MUST** be exposed by declaring a parameter in the ``outputs`` section of the base module. For ONAP to provided the UUID value of the shared resource to the incremental module, the parameter name defined in the ``outputs`` section of the base module **MUST** be defined as a parameter in the ``parameters`` section of the incremental module. ONAP will capture the output parameter name and value in the base module and provide the value to the corresponding parameter(s) in the incremental module(s).

VNF

MUST

ONAP Heat VNF Modularity

R-610010

A VNF's Heat Orchestration Template's Base Module **MAY** declare zero, one, or more than one ``OS::Nova::Server`` resource. A ``OS::Nova::Server`` **MAY** be created in the base module or a nested yaml file invoked by the base module.

VNF

MAY

ONAP Heat VNF Modularity

R-610020

If a VNF's Heat Orchestration Template's Base Module contains two or more ``OS::Nova::Server`` resources (created in the base module itself and/or in a nested yaml file invoked by the base module), the ``OS::Nova::Server`` resources **MAY** define the same ``{vm-type}`` (as defined in R-01455) or **MAY** define different ``{vm-type}``. Note that - there is no constraint on the number of unique ``{vm-type}`` defined in the base module. - there is no constraint on the number of ``OS::Nova::Server`` resources that define the same ``{vm-type}`` in the base module. - if an ``OS::Nova::Server`` is created in a nested yaml file invoked by the base module, the nested yaml file **MUST NOT** contain more than one ``OS::Nova::Server`` resource (as defined in R-17528).

VNF

MAY

ONAP Heat VNF Modularity

R-610030

A VNF's Heat Orchestration Template's Incremental Module **MUST** declare - one or more ``OS::Nova::Server`` resources OR - one or more ``OS::Cinder::Volume`` resources. An ``OS::Nova::Server`` **MAY** be created in the incremental module or a nested yaml file invoked by the incremental module. An ``OS::Cinder::Volume`` **MAY** be created in the incremental module or a nested yaml file invoked by the incremental module.

VNF

MUST

ONAP Heat VNF Modularity

R-610040

If a VNF's Heat Orchestration Template's Incremental Module contains two or more ``OS::Nova::Server`` resources, the ``OS::Nova::Server`` resources **MAY** define the same ``{vm-type}`` (as defined in R-01455) or **MAY** define different ``{vm-type}``. Note that - there is no constraint on the number of unique ``{vm-type}`` defined in the incremental module. - there is no constraint on the number of ``OS::Nova::Server`` resources that define the same ``{vm-type}`` in the incremental module. - if an ``OS::Nova::Server`` is created in a nested yaml file invoked by the incremental module, the nested yaml file **MUST NOT** contain more than one ``OS::Nova::Server`` resource (as defined in R-17528).

VNF

MAY

ONAP Heat VNF Modularity

R-610050

The same ``{vm-type}`` for a VNF's Heat Orchestration Template's ``OS::Nova::Server`` resource (as defined in R-01455) **MAY** exist in the VNF's Heat Orchestration Template's Base Module (or invoked nested yaml file) and/or one or more of the VNF's Heat Orchestration Template's Incremental Modules (or invoked nested yaml file).

VNF

MAY

ONAP Heat VNF Modularity

R-61354

The VNF **MUST** provide a mechanism (e.g., access control list) to permit and/or restrict access to services on the VNF by source, destination, protocol, and/or port.

VNF

MUST

VNF General Security Requirements

R-62170

The VNF or PNF **MUST** over-ride any default values for configurable parameters that can be set by ONAP in the roles, cookbooks and recipes.

VNF or PNF

MUST

Chef Roles/Requirements

R-62187

A VNF's Heat Orchestration Template's Resource ``OS::ContrailV2::InstanceIp`` Resource ID that is configuring an IPv4 Address on a virtual machine interface (i.e., OS::ContrailV2::VirtualMachineInterface) attached to an ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666) **MUST** use the naming convention * ``{vm-type}_{vm-type_index}_int_{network-role}_vmi_{vmi_index}_IP_{index}`` where * ``{vm-type}`` is the vm-type * ``{vm-type_index}`` references the instance of the ``{vm-type}`` in the VNF. The ``{vm-type_index}`` is a numeric value that **MUST** start at zero in the VNF and **MUST** increment by one each time a new instance of a ``{vm-type}`` is referenced. * ``{network-role}`` is the network-role of the ONAP internal network that the port is attached to * ``{vmi_index}`` references the instance of the virtual machine interface on the ``{vm-type}`` attached to ``{network-role}`` network. The ``{vmi_index}`` is a numeric value that **MUST** start at zero on an instance of a ``{vm-type}`` and **MUST** increment by one each time a new virtual machine interface is defined on the instance of the ``{vm-type}`` attached to ``{network-role}`` network. * ``IP`` signifies that an IPv4 address is being configured * ``{index}`` references the instance of the IPv4 address configured on the virtual machine interface. The ``{index}`` is a numeric value that **MUST** start at zero on an instance of a virtual machine interface and **MUST** increment by one each time a new IPv4 address is configured on the virtual machine interface.

VNF

MUST

OS::ContrailV2::InstanceIp

R-62428

A VNF's Heat Orchestration Template's ``OS::Nova::Server`` resource property ``metadata`` key/value pair ``vnf_name`` parameter **MUST** be declared as ``vnf_name`` and the parameter **MUST** be defined as type: ``string``.

VNF

MUST

vnf_name

R-62468

The VNF or PNF **MUST** allow all configuration data to be edited through a NETCONF <edit-config> operation. Proprietary NETCONF RPCs that make configuration changes are not sufficient.

VNF or PNF

MUST

NETCONF Server Requirements

R-62498

The VNF **MUST** support only encrypted access protocols, e.g., TLS, SSH, SFTP.

VNF

MUST

VNF General Security Requirements

R-62590

The VNF's Heat Orchestration Template's Resource ``OS::Neutron::Port`` property ``fixed_ips`` map property ``ip_address`` parameter associated with an ONAP external network, i.e., * ``{vm-type}_{network-role}_ip_{index}`` * ``{vm-type}_{network-role}_v6_ip_{index}`` * ``{vm-type}_{network-role}_ips`` * ``{vm-type}_{network-role}_v6_ips`` **MUST NOT** be enumerated in the Heat Orchestration Template's Environment File. ONAP provides the IP address assignments at orchestration time.

VNF

MUST NOT

Property: fixed_ips, Map Property: ip_address

R-62802

When the VNF's Heat Orchestration Template's resource ``OS::Neutron::Port`` is attaching to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), and an IPv4 address is being cloud assigned by OpenStack's DHCP Service and the ONAP external network IPv4 subnet is to be specified using the property ``fixed_ips`` map property ``subnet``, the parameter **MUST** follow the naming convention * ``{network-role}_subnet_id`` where * ``{network-role}`` is the network role of the ONAP external network.

VNF

MUST

Property: fixed_ips, Map Property: subnet

R-629534

The VNF **MUST** be capable of automatically synchronizing the system clock daily with the Operator's trusted time source, to assure accurate time reporting in log files. It is recommended that Coordinated Universal Time (UTC) be used where possible, so as to eliminate ambiguity owing to daylight savings time.

VNF

MUST

VNF Security Analytics Requirements

R-62983

When the VNF's Heat Orchestration Template's Resource ``OS::Neutron::Port`` is attaching to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), the ``network`` parameter name **MUST** * follow the naming convention ``{network-role}_net_id`` if the Neutron network UUID value is used to reference the network * follow the naming convention ``{network-role}_net_name`` if the OpenStack network name is used to reference the network. where ``{network-role}`` is the network-role of the ONAP external network and a ``get_param`` **MUST** be used as the intrinsic function.

VNF

MUST

Property: network

R-63105

The VNF or PNF **MAY** produce telemetry data using the :doc:`RESTConf Collector <dcae:sections/services/restconf/index>`, but this requires additional coordination with the operator to appropriately map the data internally to a VES-like structure used within ONAP. If this option is needed, then the VNF or PNF Provider must coordinate with with the Operator for the data to be successfully collected and processed by DCAE.

VNF or PNF

MAY

Monitoring and Fault Protocol Selection

R-63137

VNF's Heat Orchestration Template's Resource **MAY** declare the attribute ``update_policy:``.

VNF

MAY

update_policy

R-63330

The VNF **MUST** detect when its security audit log storage medium is approaching capacity (configurable) and issue an alarm.

VNF

MUST

VNF Security Analytics Requirements

R-63473

The VNF **MUST** automatically advertise newly scaled components so there is no manual intervention required.

VNF

MUST

System Resource Optimization

R-636251

A VNF or PNF producing VES events **MUST** size the event buffer referenced in R-658596 such that it can buffer a minimum of 1 hours of events under nominal load.

VNF or PNF

MUST

Buffering and Redelivery

R-638216

(Error Case) - The PNF **MUST** support a configurable timer to stop the periodicity sending of the pnfRegistration VES event. If this timer expires during a Service Configuration exchange between the PNF and ONAP, it MAY log a time-out error and notify an operator. Note: It is expected that each vendor will enforce and define a PNF service configuration timeout period. This is because the PNF cannot wait indefinitely as there may also be a technician on-site trying to complete installation & commissioning. The management of the VES event exchange is also a requirement on the PNF to be developed by the PNF vendor.

PNF

MUST

PNF Plug and Play

R-638682

The VNF **MUST** log any security event required by the VNF Requirements to Syslog using LOG_AUTHPRIV for any event that would contain sensitive information and LOG_AUTH for all other relevant events.

VNF

MUST

VNF General Security Requirements

R-63935

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

VNF or PNF

MUST

NETCONF Server Requirements

R-63956

If the VNF's ports connected to a unique ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968) and the port's IP addresses are ONAP SDN-C assigned IP addresses, the IPv4 addresses **MAY** be from different subnets and the IPv6 addresses **MAY** be from different subnets.

VNF

MAY

Items to Note

R-64064

The PNFD provided by a PNF vendor **MUST** comply with the following Relationship Types as specified in ETSI NFV-SOL001 standard: - tosca.relations.nfv.VirtualLinksTo

PNF

MUST

Relationship Types

R-64445

The VNF **MUST** support the ability of a requestor of the service to determine the version (and therefore capabilities) of the service so that Network Cloud Service Provider can understand the capabilities of the service.

VNF

MUST

Deployment Optimization

R-64713

The VNF **SHOULD** support a software promotion methodology from dev/test -> pre-prod -> production in software, development & testing and operations.

VNF

SHOULD

VNF Devops

R-64768

The VNF **MUST** limit the size of application data packets to no larger than 9000 bytes for SDN network-based tunneling when guest data packets are transported between tunnel endpoints that support guest logical networks.

VNF

MUST

VNF Design

R-65134

The VNF **SHOULD** maintain state in a geographically redundant datastore that may, in fact, be its own VNFC.

VNF

SHOULD

VNF Design

R-65486

The VNFD **MUST** comply with ETSI GS NFV-SOL001 specification endorsing the above mentioned NFV Profile and maintaining the gaps with the requirements specified in ETSI GS NFV-IFA011 standard.

VNF

MUST

General

R-65515

The VNF **MUST** provide a mechanism and tool to start VNF containers (VMs) without impacting service or service quality assuming another VNF in same or other geographical location is processing service requests.

VNF

MUST

Application Resilient Error Handling

R-65516

A VNF's Heat Orchestration Template's Resource ``OS::Nova::Keypair`` that applies to all Virtual Machines in the VNF, the ``OS::Nova::Keypair`` Resource ID **SHOULD** use the naming convention * ``{vnf-type}_keypair`` where * ``{vnf-type}`` describes the VNF

VNF

SHOULD

OS::Nova::Keypair

R-655209

The VNF or PNF producing VES events **MUST** respect the configured VES Timeout Value when delivering VES events, and abort any call where the VES Event Listener does not successfully acknowledge the delivery of event(s) within the Timeout Value. These failed transactions should be buffered and retried in accordance with the :ref:`ves_buffering_requirements` Requirements.

VNF or PNF

MUST

Event Delivery Requirements

R-65618

A VNF's Heat Orchestration Template's Resource ``OS::ContrailV2::ServiceHealthCheck`` Resource ID **MAY** use the naming convention * ``{vm-type}_RSHC_{LEFT|RIGHT}`` where * ``{vm-type}`` is the vm-type * ``RSHC`` signifies that it is the Resource Service Health Check * ``LEFT`` is used if the Service Health Check is on the left interface * ``RIGHT`` is used if the Service Health Check is on the right interface

VNF

MAY

OS::ContrailV2::ServiceHealthCheck

R-65641

The VNF or PNF **MUST** support APPC/SDN-C ``UpgradeBackOut`` command.

VNF or PNF

MUST

Lifecycle Management Related Commands

R-65755

The VNF or PNF **SHOULD** support callback URLs to return information to ONAP upon completion of the chef-client run for any chef-client run associated with a VNF or PNF 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.

VNF or PNF

SHOULD

Chef Roles/Requirements

R-658596

A VNF or PNF producing VES events **MUST** buffer events that meet the following criteria if the VES Event Listener is unreachable or the request encounters a timeout. * Faults with eventSeverity of ``MINOR``, ``MAJOR``, ``NORMAL``, or ``CRITICAL`` * Syslog with syslogSev of ``Emergency``, ``Alert``, ``Critical``, ``Error``, or ``Warning`` * All measurement events

VNF or PNF

MUST

Buffering and Redelivery

R-66070

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.

VNF HEAT PACKAGE

MUST

Resource Description

R-663631

The VNF's Heat Orchestration Template's Resource ``OS::Nova::Server`` property ``name`` value **MUST** be be obtained via a ``get_param``.

VNF

MUST

Property: Name

R-66793

The VNF or PNF **MUST** guarantee the VNF or PNF 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 VNF or PNF without locking either configuration method out).

VNF or PNF

MUST

NETCONF Server Requirements

R-67114

The VNF or PNF **MUST** be installed with Chef-Client >= 12.0 and Chef push jobs client >= 2.0.

VNF

MUST

Chef Client Requirements

R-67124

The VNF or PNF Provider's Ansible playbooks **MUST** be designed to run using an inventory hosts file in a supported format; with group names matching VNFC 3-character string adding "vip" for groups with virtual IP addresses shared by multiple VMs as seen in examples provided in Appendix.

VNF or PNF PROVIDER

MUST

Ansible Client Requirements

R-67231

A VNF's Heat Orchestration template's Environment File's **MUST NOT** contain the ``resource_registry:`` section.

VNF

MUST NOT

Environment File Format

R-67386

A VNF's Heat Orchestration Template's Resource **MAY** declare the attribute ``metadata``.

VNF

MAY

metadata

R-67597

A VNF's Heat Orchestration Template's ``OS::Nova::Server`` resource property ``metadata`` key/value pair ``vm_role`` parameter ``vm_role`` **MUST NOT** have parameter constraints defined.

VNF

MUST NOT

vm_role

R-67709

The VNF **MUST** be designed, built and packaged to enable deployment across multiple fault zones (e.g., VNFCs deployed in different servers, racks, OpenStack regions, geographies) so that in the event of a planned/unplanned downtime of a fault zone, the overall operation/throughput of the VNF is maintained.

VNF

MUST

All Layer Redundancy

R-67793

When a VNF's Heat Orchestration Template's resource is associated with more than one ``{vm-type}`` and/or more than one ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666) and/or ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), the Resource ID **MUST NOT** contain the ``{vm-type}`` and/or ``{network-role}``/``int_{network-role}``.

VNF

MUST NOT

Resource IDs

R-67895

The VNFD provided by VNF vendor may use the below described TOSCA capabilities. An on-boarding entity (ONAP SDC) **MUST** support them. **tosca.capabilities.nfv.VirtualBindable** A node type that includes the VirtualBindable capability indicates that it can be pointed by **tosca.relationships.nfv.VirtualBindsTo** relationship type. **tosca.capabilities.nfv.VirtualLinkable** A node type that includes the VirtualLinkable capability indicates that it can be pointed by **tosca.relationships.nfv.VirtualLinksTo** relationship. **tosca.capabilities.nfv.ExtVirtualLinkable** A node type that includes the ExtVirtualLinkable capability indicates that it can be pointed by **tosca.relationships.nfv.VirtualLinksTo** relationship. **Note**: This capability type is used in Casablanca how it does not exist in the last SOL001 draft **tosca.capabilities.nfv.VirtualCompute** and **tosca.capabilities.nfv.VirtualStorage** includes flavours of VDU

VNF

MUST

Capability Types

R-67918

The VNF **MUST** handle replication race conditions both locally and geo-located in the event of a data base instance failure to maintain service continuity.

VNF

MUST

Application Resilient Error Handling

R-68023

A VNF's Heat Orchestration Template's ``OS::Nova::Server`` resource property ``metadata`` key/value pair ``vf_module_name`` value **MUST** be obtained via a ``get_param``.

VNF

MUST

vf_module_name

R-68122

A VNF's incremental module **MAY** be deployed more than once, either during initial VNF deployment and/or scale out.

VNF

MAY

ONAP VNF Modularity Overview

R-68165

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

VNF or PNF

MUST

Security

R-681859

A VNF's Heat Orchestration Template's ``OS::Neutron::Port`` resource's * Resource ID (defined in R-20453) * property ``network`` parameter name (defined in R-62983 and R-86182) * property ``fixed_ips``, map property ``ip_address`` parameter name (defined in R-40971, R-04697, R-71577, R-23503, R-78380, R-85235, R-27818, and R-29765) * property ``fixed_ips``, map property ``subnet`` parameter name (defined in R-62802, R-15287, R-84123, R-76160) * property ``allowed_address_pairs`` parameter name (defined in R-41492 and R-83418) **MUST** contain the identical ``{network-role}``.

VNF

MUST

Items to Note

R-68198

A VNF's Heat Orchestration template's Environment File's ``parameters:`` section **MAY** (or **MAY NOT**) enumerate parameters.

VNF

MAY

Environment File Format

R-68200

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

VNF or PNF

MAY

NETCONF Server Requirements

R-68520

A VNF's Heat Orchestration Template's Resource ``OS::Neutron::Port`` that is creating a *Reserve Port* with an IPv6 address, the ``OS::Neutron::Port`` Resource ID **SHOULD** use the naming convention * ``reserve_port_{vm-type}_{network-role}_floating_v6_ip_{index}`` where * ``{vm-type}`` is the vm-type * ``{network-role}`` is the network-role of the ONAP external network that the port is attached to * ``{index}`` is the instance of the IPv6 *Reserve Port* for the vm-type attached to the network of ``{network-role}``. The ``{index}`` starts at zero and increments by one (as described in R-11690).

VNF

SHOULD

OS::Neutron::Port

R-686466

The PNF **MUST** support sending a pnfRegistration VES event.

PNF

MUST

PNF Plug and Play

R-68990

The VNF or PNF **MAY** support the ``:startup`` capability. It will allow the running configuration to be copied to this special database. It can also be locked and unlocked.

VNF or PNF

MAY

NETCONF Server Requirements

R-69014

When a VNF's port connects to an ONAP internal network or ONAP external network, a network role, referred to as the ``{network-role}`` **MUST** be assigned to the network for use in the VNF's Heat Orchestration Template. The ``{network-role}`` is used in the VNF's Heat Orchestration Template's resource IDs and resource property parameter names.

VNF

MUST

{network-role}

R-69111

The VNF or PNF **MUST** report application logs using either :ref:`Virtual Function Event Streaming (VES) <ves_monitoring_requirements>` or Syslog in compliance with `RFC 5424 <https://tools.ietf.org/html/rfc5424>`__ .

VNF or PNF

MUST

Monitoring and Fault Protocol Selection

R-69431

The VNF's Heat Orchestration Template's Resource ``OS::Nova::Server`` property ``flavor`` parameter **MUST** be enumerated in the Heat Orchestration Template's Environment File and a value **MUST** be assigned.

VNF

MUST

Property: flavor

R-69565

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.

VNF or PNF DOCUMENTATION PACKAGE

MUST

Resource Description

R-69588

When a VNF's Heat Orchestration Template's Virtual Machine (i.e., ``OS::Nova::Server`` Resource) boots from Cinder Volume, the ``OS::Nova::Server`` resource property ``block_device_mapping`` or ``block_device_mapping_v2`` **MUST** be used.

VNF

MUST

Boot Options

R-69610

The VNF **MUST** provide the capability of using X.509 certificates issued by an external Certificate Authority.

VNF

MUST

VNF Data Protection Requirements

R-69634

The VNF's Heat Orchestration Template's Resource ``OS::Neutron::Port`` property ``fixed_ips`` map property ``subnet`` parameter ``int_{network-role}_subnet_id`` **MUST NOT** be enumerated in the VNF's Heat Orchestration Template's Environment File.

VNF

MUST NOT

Property: fixed_ips, Map Property: subnet

R-69649

The VNF Provider **MUST** have patches available for vulnerabilities in the VNF as soon as possible. Patching shall be controlled via change control process with vulnerabilities disclosed along with mitigation recommendations.

VNF

MUST

VNF General Security Requirements

R-69663

A VNF **MAY** be composed from one or more Heat Orchestration Templates, each of which represents a subset of the overall VNF.

VNF

MAY

ONAP VNF Modularity Overview

R-697654

The VNF or PNF **MAY** leverage ONAP's High Volume VNF Event Streaming (HV-VES) when there is a need to deliver large volumes of real-time performance management metrics. See :doc:`HV-VES collector <dcae:sections/services/ves-hv/index>` service details for more information.

VNF or PNF

MAY

Monitoring and Fault Protocol Selection

R-69877

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.

VNF or PNF

MUST

Resource Control Loop

R-70013

The VNF **MUST NOT** require any manual steps to get it ready for service after a container rebuild.

VNF

MUST NOT

Application Resilient Error Handling

R-70276

A VNF HEAT's Orchestration Nested Template's YAML file name **MUST NOT** be in the format ``{vm-type}.y[a]ml`` where ``{vm-type}`` is defined in the Heat Orchestration Template.

VNF

MUST NOT

Nested Heat file

R-703767

The VNF **MUST** have the capability to securely transmit the security logs and security events to a remote system before they are purged from the system.

VNF

MUST

VNF Security Analytics Requirements

R-70492

The VNF or PNF **MUST** support DNS resolution of the VES Listener Endpoint if a Fully Qualified Domain Name (FQDN) is provided.

VNF or PNF

MUST

VES Listener Endpoint and DNS Resolution

R-70496

The VNF or PNF **MUST** implement the protocol operation: ``commit(confirmed, confirm-timeout)`` - Commit candidate configuration data store to the running configuration if ":candidate" is supported.

VNF or PNF

MUST

NETCONF Server Requirements

R-707977

When the PNF receives a Service configuration from ONAP, the PNF **MUST** cease sending the pnfRegistration VES Event.

PNF

MUST

PNF Plug and Play

R-708564

If a VNF's Heat Orchestration Template's resource invokes a nested YAML file, either statically or dynamically (via ``OS::Heat::ResourceGroup``), the names of the parameters associated with the following resource properties **MUST NOT** change. * ``OS::Nova::Server`` property ``flavor`` * ``OS::Nova::Server`` property ``image`` * ``OS::Nova::Server`` property ``name`` * ``OS::Nova::Server`` property metadata key value ``vnf_id`` * ``OS::Nova::Server`` property metadata key value ``vf_module_id`` * ``OS::Nova::Server`` property metadata key value ``vnf_name`` * ``OS::Nova::Server`` property metadata key value ``vf_module_name`` * ``OS::Nova::Server`` property metadata key value ``vm_role`` * ``OS::Nova::Server`` property metadata key value ``vf_module_index`` * ``OS::Nova::Server`` property metadata key value ``workload_context`` * ``OS::Nova::Server`` property metadata key value ``environment_context`` * ``OS::Neutron::Port`` property ``fixed_ips``, map property ``ip_address`` * ``OS::Neutron::Port`` property ``fixed_ips``, map property ``subnet`` * ``OS::Neutron::Port`` property ``allowed_address_pairs``, map property ``ip_address`` * ``OS::Neutron::Port`` property ``network`` * ``OS::ContrailV2::VirtualMachineInterface`` property ``virtual_network_refs`` * ``OS::ContrailV2::VirtualMachineInterface`` property ``virtual_machine_interface_allowed_address_pairs``, map property ``virtual_machine_interface_allowed_address_pairs_allowed_address_pair``, ``virtual_machine_interface_allowed_address_pairs_allowed_address_pair_ip`` , ``virtual_machine_interface_allowed_address_pairs_allowed_address_pair_ip_ip_prefix`` * ``OS::ContrailV2::InstanceIP`` property ``instance_ip_address`` * ``OS::ContrailV2::InstanceIP`` property ``subnet_uuid``

VNF

MUST NOT

Nested Heat Template Requirements

R-70933

The VNF **MUST** provide the ability to migrate to newer versions of cryptographic algorithms and protocols with minimal impact.

VNF

MUST

VNF Data Protection Requirements

R-70964

If a VNF's Port is attached to an ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666) and the port's IP addresses are statically assigned by the VNF's Heat Orchestration Template (i.e., enumerated in the Heat Orchestration Template's environment file), the ``OS::Neutron::Port`` Resource's * property ``fixed_ips`` map property ``ip_address`` **MUST** be used * property ``fixed_ips`` map property ``subnet`` **MUST NOT** be used

VNF

MUST NOT

Items to Note

R-71152

The VNF's Heat Orchestration Template's Resource ``OS::Nova::Server`` property ``image`` parameter **MUST** be declared as type: ``string``.

VNF

MUST

Property: image

R-71493

A VNF's Heat Orchestration Template's ``OS::Nova::Server`` resource property ``metadata`` **MUST** contain the key/value pair ``vf_module_id`` and the value MUST be obtained via a ``get_param``.

VNF

MUST

vf_module_id

R-71577

When the VNF's Heat Orchestration Template's Resource ``OS::Neutron::Port`` is attaching to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), and an IPv6 address is assigned using the property ``fixed_ips`` map property ``ip_address`` and the parameter type is defined as a string, the parameter name **MUST** follow the naming convention * ``{vm-type}_{network-role}_v6_ip_{index}`` where * ``{vm-type}`` is the {vm-type} associated with the ``OS::Nova::Server`` * ``{network-role}`` is the {network-role} of the ONAP external network * ``{index}`` is a numeric value that **MUST** start at zero in a VNF's Heat Orchestration Template and **MUST** increment by one

VNF

MUST

Property: fixed_ips, Map Property: ip_address

R-71699

A VNF's Heat Orchestration Template's Resource **MUST NOT** reference a HTTP-based Nested YAML file.

VNF

MUST NOT

type

R-717227

When the VNF's Heat Orchestration Template's Resource ``OS::Neutron::Port`` is attaching to an ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666), and an IPv4 Virtual IP (VIP) address is assigned using the property ``allowed_address_pairs`` map property ``ip_address``, the parameter name **MUST** follow the naming convention - ``{vm-type}_int_{network-role}_floating_ip`` where - ``{vm-type}`` is the {vm-type} associated with the OS::Nova::Server - ``{network-role}`` is the {network-role} of the ONAP internal network And the parameter **MUST** be declared as ``type: string`` and **MUST** be enumerated in the environment file. OR the parameter name **MUST** follow the naming convention - ``{vm-type}_int_{network-role}_floating_ips`` where - ``{vm-type}`` is the {vm-type} associated with the OS::Nova::Server - ``{network-role}`` is the {network-role} of the ONAP internal network And the parameter **MUST** be declared as ``type: comma_delimited_list`` and **MUST** be enumerated in the environment file.

VNF

MUST

VIP Assignment, ONAP Internal Networks

R-71842

The VNF **MUST** include the field "service or program used for access" in the Security alarms (where applicable and technically feasible).

VNF

MUST

VNF Security Analytics Requirements

R-72184

The VNF or PNF **MUST** have routable FQDNs for all the endpoints (VMs) of a VNF or PNF that contain chef-clients which are used to register with the Chef Server. As part of invoking VNF or PNF actions, ONAP will trigger push jobs against FQDNs of endpoints for a VNF or PNF, if required.

VNF or PNF

MUST

Chef Client Requirements

R-72483

A VNF's Heat Orchestration Template's ``OS::Nova::Server`` resource property ``metadata`` **MUST** contain the key/value pair ``vnf_name`` and the value **MUST** be obtained via a ``get_param``.

VNF

MUST

vnf_name

R-72871

A VNF's Heat Orchestration Template's ``OS::Nova::Server`` resource property ``metadata`` key/value pair ``vf_module_id`` parameter ``vf_module_id`` **MUST NOT** be enumerated in the Heat Orchestration Template's environment file.

VNF

MUST NOT

vf_module_id

R-73067

The VNF **MUST** use NIST and industry standard cryptographic algorithms and standard modes of operations when implementing cryptography.

VNF

MUST

VNF Data Protection Requirements

R-73213

A VNF's Heat Orchestration Template's Resource ``OS::Neutron::SecurityGroup`` that is applicable to more than one ``{vm-type}`` and one ONAP internal network, (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666), the ``OS::Neutron::SecurityGroup`` Resource ID **SHOULD** use the naming convention * ``int_{network-role}_security_group`` where * ``{network-role}`` is the network-role of the ONAP internal network

VNF

SHOULD

OS::Neutron::SecurityGroup

R-73223

The VNF **MUST** support proactive monitoring to detect and report the attacks on resources so that the VNFs and associated VMs can be isolated, such as detection techniques for resource exhaustion, namely OS resource attacks, CPU attacks, consumption of kernel memory, local storage attacks.

VNF

MUST

VNF Security Analytics Requirements

R-73364

The VNF **MUST** support at least two major versions of the VNF software and/or sub-components to co-exist within production environments at any time so that upgrades can be applied across multiple systems in a staggered manner.

VNF

MUST

Deployment Optimization

R-73459

The VNF or PNF **MUST** provide the ability to include a "from=" clause in SSH public keys associated with mechanized user IDs created for an Ansible Server cluster to use for VNF or PNF VM authentication.

VNF or PNF

MUST

Ansible Client Requirements

R-73468

The VNF **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 if VNF is heat based.

VNF

MUST

NETCONF Server Requirements

R-73560

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

VNF or PNF

MUST

Resource Control Loop

R-73583

The VNF **MUST** allow changes of configuration parameters to be consumed by the VNF without requiring the VNF or its sub-components to be bounced so that the VNF availability is not effected.

VNF

MUST

Application Configuration Management

R-74304

A VNF's Heat Orchestration Template's Environment file extension **MUST** be in the lower case format ``.env``.

VNF

MUST

ONAP Heat Orchestration Template Filenames

R-74481

The VNF **MUST NOT** require the use of a dynamic routing protocol unless necessary to meet functional requirements.

VNF

MUST NOT

VNF Design

R-74712

The VNF **MUST** utilize FQDNs (and not IP address) for both Service Chaining and scaling.

VNF

MUST

System Resource Optimization

R-74958

The VNF **MUST** activate security alarms automatically when it detects an unsuccessful attempt to gain permissions or assume the identity of another user.

VNF

MUST

VNF Security Analytics Requirements

R-74978

A VNF's Heat Orchestration Template's ``OS::Nova::Server`` resource property ``metadata`` key/value pair ``workload_context`` parameter **MUST** be declared as ``workload_context`` and the parameter **MUST** be defined as type: ``string``.

VNF

MUST

workload_context

R-75041

The VNF **MUST**, if not integrated with the Operator's Identity and Access Management system, support configurable password expiration.

VNF

MUST

VNF Identity and Access Management Requirements

R-75141

A VNF's Heat Orchestration Template's resource name (i.e., <resource ID>) **MUST** only contain alphanumeric characters and underscores ('_').

VNF

MUST

resource ID

R-75343

The VNF **MUST** provide the capability of testing the validity of a digital certificate by recognizing the identity represented by the certificate - the "distinguished name".

VNF

MUST

VNF Cryptography Requirements

R-75608

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

VNF or PNF

MUST

Configuration Management via Ansible

R-756950

The VNF **MUST** be operable without the use of Network File System (NFS).

VNF

MUST

VNF General Security Requirements

R-75850

The VNF **SHOULD** decouple persistent data from the VNFC and keep it in its own datastore that can be reached by all instances of the VNFC requiring the data.

VNF

SHOULD

VNF Design

R-75943

The VNF or PNF **SHOULD** support the data schema defined in 3GPP TS 32.435 or 3GPP TS 28.532, when supporting the event-driven bulk transfer of monitoring data.

VNF or PNF

SHOULD

Bulk Performance Measurement

R-76014

A VNF's Heat Orchestration Template's Resource ``OS::ContrailV2::ServiceHealthCheck`` Resource ID **MUST** contain the ``{vm-type}``.

VNF

MUST

OS::ContrailV2::ServiceHealthCheck

R-76057

VNF Heat Orchestration Template's Nested YAML file name **MUST** contain only alphanumeric characters and underscores '_' and **MUST NOT** contain the case insensitive string ``base``.

VNF

MUST

Nested Heat file

R-76160

When * the VNF's Heat Orchestration Template's resource ``OS::Neutron::Port`` in an Incremental Module is attaching to an ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666) that is created in the Base Module, AND * an IPv6 address is being cloud assigned by OpenStack's DHCP Service AND * the ONAP internal network IPv6 subnet is to be specified using the property ``fixed_ips`` map property ``subnet``, the parameter **MUST** follow the naming convention * ``int_{network-role}_v6_subnet_id`` where ``{network-role}`` is the network role of the ONAP internal network. Note that the parameter **MUST** be defined as an ``output`` parameter in the base module.

VNF

MUST

Property: fixed_ips, Map Property: subnet

R-763774

The VNF or PNF **MUST** support a HTTPS connection to the DCAE VES Event Listener.

VNF or PNF

MUST

PNF Plug and Play

R-76449

A VNF's Heat Orchestration Template's **MUST NOT** contain the Resource ``OS::Neutron::FloatingIPAssociation``.

VNF

MUST NOT

VIP Assignment, ONAP External Networks

R-76682

If a VNF's Heat Orchestration Template ``OS::ContrailV2::InterfaceRouteTable`` resource ``interface_route_table_routes`` property ``interface_route_table_routes_route`` map property parameter ``{vm-type}_{network-role}_route_prefixes`` **MUST NOT** be enumerated in the VNF's Heat Orchestration Template's Environment File.

VNF

MUST NOT

Interface Route Table Prefixes for Contrail InterfaceRoute Table

R-76718

If a VNF's Heat Orchestration Template uses the intrinsic function ``get_file``, the ``get_file`` target **MUST** be referenced in the Heat Orchestration Template by file name.

VNF

MUST

Heat Files Support (get_file)

R-76901

The VNF **MUST** support a container rebuild mechanism based on existing image (e.g. Glance image in Openstack environment) or a snapshot.

VNF

MUST

Virtual Function - Container Recovery Requirements

R-77334

The VNF **MUST** allow configurations and configuration parameters to be managed under version control to ensure consistent configuration deployment, traceability and rollback.

VNF

MUST

Application Configuration Management

R-77667

The VNF **MUST** test for adherence to the defined performance budget at each layer, during each delivery cycle so that the performance budget is measured and feedback is provided where the performance budget is not met.

VNF

MUST

Deployment Optimization

R-78010

The VNF **MUST** support LDAP in order to integrate with an external identity and access manage system. It MAY support other identity and access management protocols.

VNF

MUST

VNF Identity and Access Management Requirements

R-78116

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

VNF or PNF

MUST

Chef Roles/Requirements

R-78282

The VNF or PNF **MUST** conform to the NETCONF RFC 6242, "Using the Network Configuration Protocol over Secure Shell".

VNF or PNF

MUST

NETCONF Server Requirements

R-78380

When the VNF's Heat Orchestration Template's Resource ``OS::Neutron::Port`` is attaching to an ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666), and an IPv4 address is assigned using the property ``fixed_ips`` map property ``ip_address`` and the parameter type is defined as a ``string``, the parameter name **MUST** follow the naming convention * ``{vm-type}_int_{network-role}_ip_{index}`` where * ``{vm-type}`` is the {vm-type} associated with the ``OS::Nova::Server`` * ``{network-role}`` is the {network-role} of the ONAP internal network * ``{index}`` is a numeric value that **MUST** start at zero in a VNF's Heat Orchestration Template and **MUST** increment by one

VNF

MUST

Property: fixed_ips, Map Property: ip_address

R-78569

VNF's Heat Orchestration Template's Resource **MAY** declare the attribute ``external_id:``.

VNF

MAY

external_id

R-78640

The VNF or PNF Provider's Ansible playbooks **SHOULD** provide a single YAML or JSON file with all the passwords and secrets to reduce the number of files to be decrypted/encrypted before on-boarding into the central repository.

VNF or PNF PROVIDER

SHOULD

Ansible Playbook Requirements

R-787965

If the VNF or PNF CSAR Package utilizes Option 2 for package security, then the complete CSAR file **MUST** be digitally signed with the VNF or PNF provider private key. The VNF or PNF provider delivers one zip file consisting of the CSAR file, a signature file and a certificate file that includes the VNF or PNF provider public key. The certificate may also be included in the signature container, if the signature format allows that. The VNF or PNF provider creates a zip file consisting of the CSAR file with .csar extension, signature and certificate files. The signature and certificate files must be siblings of the CSAR file with extensions .cms and .cert respectively.

VNF or PNF CSAR PACKAGE

MUST

VNF or PNF Package Authenticity and Integrity

R-79107

The VNF **MUST**, if not integrated with the Operator’s Identity and Access Management system, support the ability to lock out the userID after a configurable number of consecutive unsuccessful authentication attempts using the same userID. The locking mechanism must be reversible by an administrator and should be reversible after a configurable time period.

VNF

MUST

VNF Identity and Access Management Requirements

R-79224

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

VNF or PNF

MUST

Chef Client Requirements

R-793716

The PNF **MUST** have "ONAP Aware" software which is capable of performing PNF PnP registration with ONAP. The "ONAP Aware" software is capable of performing the PNF PnP Registration with ONAP MUST either be loaded separately or integrated into the PNF software upon physical delivery and installation of the PNF. Note: It is up to the specific vendor to design the software management functions.

PNF

MUST

PNF Plug and Play

R-795126

The VNF CSAR package Manifest file **MUST** start with the VNF package metadata in the form of a name-value pairs. Each pair shall appear on a different line. The name is specified as following: - vnf_provider_id - vnf_product_name - vnf_release_date_time - vnf_package_version

VNF CSAR PACKAGE

MUST

VNF or PNF Package Contents

R-79817

A VNF's Heat Orchestration Template's parameter defined in a non-nested YAML file as type ``comma_delimited_list`` **MAY** have a parameter constraint defined.

VNF

MAY

constraints

R-79952

The VNF **SHOULD** support container snapshots if not for rebuild and evacuate for rollback or back out mechanism.

VNF

SHOULD

All Layer Redundancy

R-80070

The VNF **MUST** handle errors and exceptions so that they do not interrupt processing of incoming VNF requests to maintain service continuity (where the error is not directly impacting the software handling the incoming request).

VNF

MUST

Application Resilient Error Handling

R-80335

For all GUI and command-line interfaces, the VNF **MUST** provide the ability to present a warning notice that is set by the Operator. A warning notice is a formal statement of resource intent presented to everyone who accesses the system.

VNF

MUST

VNF General Security Requirements

R-80374

A VNF's Heat Orchestration Template's ``OS::Nova::Server`` resource property ``metadata`` key/value pair ``vf_module_name`` parameter ``vf_module_name`` **MUST NOT** be enumerated in the Heat Orchestration Template's environment file.

VNF

MUST NOT

vf_module_name

R-805572

When the VNF's Heat Orchestration Template's Resource ``OS::Neutron::Port`` is attaching to an ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666), and an IPv6 Virtual IP (VIP) address is assigned using the property ``allowed_address_pairs`` map property ``ip_address``, the parameter name **MUST** follow the naming convention - ``{vm-type}_int_{network-role}_floating_v6_ip`` where - ``{vm-type}`` is the {vm-type} associated with the OS::Nova::Server - ``{network-role}`` is the {network-role} of the ONAP internal network And the parameter **MUST** be declared as ``type: string`` and **MUST** be enumerated in the environment file OR the parameter name **MUST** follow the naming convention - ``{vm-type}_int_{network-role}_floating_v6_ips`` where - ``{vm-type}`` is the {vm-type} associated with the OS::Nova::Server - ``{network-role}`` is the {network-role} of the ONAP internal network And the parameter **MUST** be declared as ``type: comma_delimited_list`` and **MUST** be enumerated in the environment file.

VNF

MUST

VIP Assignment, ONAP Internal Networks

R-807129

The VNF or PNF **SHOULD** report the files in FileReady for as long as they are available at VNF or PNF. Note: Recommended period is at least 24 hours.

VNF or PNF

SHOULD

Bulk Performance Measurement

R-80829

The VNF's Heat Orchestration Template's Resource ``OS::Neutron::Port`` property ``fixed_ips`` map property ``subnet`` parameter ``{network-role}_v6_subnet_id`` **MUST NOT** be enumerated in the VNF's Heat Orchestration Template's Environment File.

VNF

MUST NOT

Property: fixed_ips, Map Property: subnet

R-80898

TThe VNF or PNF **MUST** support heartbeat via a <get> with null filter.

VNF or PNF

MUST

NETCONF Server Requirements

R-809261

The PNF **MUST** use a IP address to contact ONAP. Note: it is expected that an ONAP operator can ascertain the ONAP IP address or the security gateway to reach ONAP on the VID or ONAP portal GUI. Note: The ONAP contact IP address has been previously configured and provisioned prior to this step. Note: The ONAP IP address could be provisioned or resolved through FQDN & DNS.

PNF

MUST

PNF Plug and Play

R-81147

The VNF **MUST**, if not integrated with the Operator’s Identity and Access Management system, support multifactor authentication on all protected interfaces exposed by the VNF for use by human users.

VNF

MUST

VNF Identity and Access Management Requirements

R-81214

A VNF's Heat Orchestration Template's Resource ``OS::ContrailV2::InterfaceRouteTable`` Resource ID **MUST** contain the ``{network-role}``.

VNF

MUST

OS::ContrailV2::InterfaceRouteTable

R-81339

A VNF Heat Orchestration Template's Base Module file name **MUST** include case insensitive 'base' in the filename and **MUST** match one of the following four formats: 1.) ``base_<text>.y[a]ml`` 2.) ``<text>_base.y[a]ml`` 3.) ``base.y[a]ml`` 4.) ``<text>_base_<text>``.y[a]ml where ``<text>`` **MUST** contain only alphanumeric characters and underscores '_' and **MUST NOT** contain the case insensitive string ``base`` or ``volume``.

VNF

MUST

Base Modules

R-814377

The VNF **MUST** have the capability of allowing the Operator to create, manage, and automatically provision user accounts using one of the protocols specified in Chapter 7.

VNF

MUST

VNF Identity and Access Management Requirements

R-816745

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.

VNF or PNF PROVIDER

MUST

Resource Description

R-81725

A VNF's Incremental Module **MUST** have a corresponding Environment File

VNF

MUST

ONAP VNF Modularity Overview

R-818859

The VNF or PNF producing VES events **MUST** not allow an unavailable or timing out VES Event Listener to impact the performance, stability, or correct execution of network function.

VNF or PNF

MUST

Buffering and Redelivery

R-81979

A VNF's Heat Orchestration Template's Resource ``OS::ContrailV2::NetworkIpam`` Resource ID **MAY** use the naming convention * ``{network-role}_RNI`` where * ``{network-role}`` is the network-role * ``RNI`` signifies that it is the Resource Network IPAM

VNF

MAY

OS::ContrailV2::NetworkIpam

R-82018

The VNF or PNF **MUST** load the Ansible Server SSH public key onto VNF or PNF VM(s) /root/.ssh/authorized_keys as part of instantiation. Alternative, is for Ansible Server SSH public key to be loaded onto VNF or PNF under /home/<Mechanized user ID>/.ssh/authorized_keys as part of instantiation, when a Mechanized user ID is created during instantiation, and Configure and all playbooks are designed to use a mechanized user ID only for authentication (never using root authentication during Configure playbook run). This will allow the Ansible Server to authenticate to perform post-instantiation configuration without manual intervention and without requiring specific VNF or PNF login IDs and passwords. *CAUTION*: For VNFs or PNFs 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.

VNF or PNF

MUST

Ansible Client Requirements

R-82115

When a VNF's Heat Orchestration Template's resource is associated with a single ``{vm-type}`` and a single ONAP external network, the Resource ID text **MUST** contain both the ``{vm-type}`` and the ``{network-role}`` - the ``{vm-type}`` **MUST** appear before the ``{network-role}`` and **MUST** be separated by an underscore '_' - e.g., ``{vm-type}_{network-role}``, ``{vm-type}_{index}_{network-role}`` - note that an ``{index}`` value **MAY** separate the ``{vm-type}`` and the ``{network-role}`` and when this occurs underscores **MUST** separate the three values. (e.g., ``{vm-type}_{index}_{network-role}``).

VNF

MUST

Resource IDs

R-82134

A VNF's Heat Orchestration Template's ``OS::Nova::Server`` resource property ``metadata`` key/value pair ``vf_module_id`` parameter **MUST** be declared as ``vf_module_id`` and the parameter **MUST** be defined as type: ``string``.

VNF

MUST

vf_module_id

R-82223

The VNF **MUST** be decomposed if the functions have significantly different scaling characteristics (e.g., signaling versus media functions, control versus data plane functions).

VNF

MUST

VNF Design

R-82551

When a VNF's Heat Orchestration Template's resource is associated with a single ``{vm-type}`` and a single ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666), the Resource ID **MUST** contain both the ``{vm-type}`` and the ``int_{network-role}`` and - the ``{vm-type}`` **MUST** appear before the ``int_{network-role}`` and **MUST** be separated by an underscore '_' - (e.g., ``{vm-type}_int_{network-role}``, ``{vm-type}_{index}_int_{network-role}``) - note that an ``{index}`` value **MAY** separate the ``{vm-type}`` and the ``int_{network-role}`` and when this occurs underscores **MUST** separate the three values. (e.g., ``{vm-type}_{index}_int_{network-role}``).

VNF

MUST

Resource IDs

R-82732

A VNF Heat Orchestration Template's Cinder Volume Module **MUST** be named identical to the base or incremental module it is supporting with ``_volume`` appended.

VNF

MUST

Cinder Volume Modules

R-82811

The VNF or PNF **MUST** support APPC ``StartApplication`` command.

VNF or PNF

MUST

Lifecycle Management Related Commands

R-82909

The VNF or PNF **MUST** report faults and alarms using either :ref:`Virtual Function Event Streaming (VES) <ves_monitoring_requirements>` or :ref:`SNMP <snmp_monitoring_requirements>`. (NOTE: See relevant sections for more detailed requirements)

VNF or PNF

MUST

Monitoring and Fault Protocol Selection

R-83092

The VNF or PNF Provider's Ansible playbooks **MUST** load passwords and other attributes that must remain secret from JSON, YAML or INI files that can be encrypted/decrypted using Ansible Vault capabilities.

VNF or PNF PROVIDER

MUST

Ansible Playbook Requirements

R-83146

The VNF or PNF **MUST** support APPC ``StopApplication`` command.

VNF or PNF

MUST

Lifecycle Management Related Commands

R-83227

The VNF **MUST** Provide the capability to encrypt data in transit on a physical or virtual network.

VNF

MUST

VNF Data Protection Requirements

R-83412

If a VNF's Heat Orchestration Template's resource ``OS::Neutron::Port`` is attaching to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968), the property ``allowed_address_pairs`` map property ``ip_address`` parameter(s) **MUST NOT** be enumerated in the VNF's Heat Orchestration Template's Environment File.

VNF

MUST NOT

VIP Assignment, ONAP External Networks

R-83500

The VNF **MUST** provide the capability of allowing certificate renewal and revocation.

VNF

MUST

VNF Cryptography Requirements

R-83677

The VNF's Heat Orchestration Template's Resource ``OS::Neutron::Port`` property ``fixed_ips`` map property ``subnet`` parameter ``{network-role}_subnet_id`` **MUST NOT** be enumerated in the VNF's Heat Orchestration Template's Environment File.

VNF

MUST NOT

Property: fixed_ips, Map Property: subnet

R-83706

When a VNF's Heat Orchestration Template's Virtual Machine (i.e., ``OS::Nova::Server`` resource) boots from an image, the ``OS::Nova::Server`` resource property ``image`` **MUST** be used.

VNF

MUST

Boot Options

R-83790

The VNF or PNF **MAY** implement the ``:validate`` capability.

VNF or PNF

MAY

NETCONF Server Requirements

R-83873

The VNF or PNF **MUST** support ``:rollback-on-error`` value for the <error-option> parameter to the <edit-config> 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 <edit-config> request.

VNF or PNF

MUST

NETCONF Server Requirements

R-84123

When * the VNF's Heat Orchestration Template's resource ``OS::Neutron::Port`` in an Incremental Module is attaching to an ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666) that is created in the Base Module, AND * an IPv4 address is being cloud assigned by OpenStack's DHCP Service AND * the internal network IPv4 subnet is to be specified using the property ``fixed_ips`` map property ``subnet``, the parameter **MUST** follow the naming convention * ``int_{network-role}_subnet_id`` where * ``{network-role}`` is the network role of the ONAP internal network Note that the parameter **MUST** be defined as an ``output`` parameter in the base module.

VNF

MUST

Property: fixed_ips, Map Property: subnet

R-84160

The VNF **MUST** have security logging for VNFs and their OSs be active from initialization. Audit logging includes automatic routines to maintain activity records and cleanup programs to ensure the integrity of the audit/logging systems.

VNF

MUST

VNF Security Analytics Requirements

R-841740

The VNF or PNF **SHOULD** support FileReady VES event for event-driven bulk transfer of monitoring data.

VNF or PNF

SHOULD

Bulk Performance Measurement

R-842258

The VNF **MUST** include a configuration (e.g. a heat template or CSAR package) that specifies the targeted parameters (e.g. a limited set of ports) over which the VNF will communicate; including internal, external and management communication.

VNF

MUST

VNF General Security Requirements

R-84322

A VNF's Heat Orchestration Template's Resource property parameter that is associated with an ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666) **MUST** include ``int_{network-role}`` as part of the parameter name, where ``int_`` is a hard coded string.

VNF

MUST

{network-role}

R-84366

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.

VNF or PNF DOCUMENTATION PACKAGE

MUST

Resource Description

R-844011

The VNF **MUST** not store authentication credentials to itself in clear text or any reversible form and must use salting.

VNF

MUST

VNF Identity and Access Management Requirements

R-84457

A VNF's Heat Orchestration Template's Resource ``OS::ContrailV2::PortTuple`` Resource ID **MAY** use the naming convention * ``{vm-type}_RPT`` where * ``{vm-type}`` is the vm-type * ``RPT`` signifies that it is the Resource Port Tuple

VNF

MAY

OS::ContrailV2::PortTuple

R-84473

The VNF **MUST** enable DPDK in the guest OS for VNF's requiring high packets/sec performance. High packet throughput is defined as greater than 500K packets/sec.

VNF

MUST

VNF Design

R-84517

The Contrail GUI has a limitation displaying special characters. The issue is documented in https://bugs.launchpad.net/juniperopenstack/+bug/1590710. It is recommended that special **SHOULD** characters be avoided. However, if special characters must be used, note that for the following resources: * Virtual Machine * Virtual Network * Port * Security Group * Policies * IPAM Creation the only special characters supported are - \" ! $\ \ ' ( ) = ~ ^ | @ ` { } [ ] > , . _"

VNF

SHOULD

Contrail Issue with Values for the Property Name

R-85235

When the VNF's Heat Orchestration Template's Resource ``OS::Neutron::Port`` is attaching to an ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666), and an IPv4 address is assigned using the property ``fixed_ips`` map property ``ip_address`` and the parameter type is defined as a ``comma_delimited_list``, the parameter name **MUST** follow the naming convention * ``{vm-type}_int_{network-role}_ips`` where * ``{vm-type}`` is the {vm-type} associated with the ``OS::Nova::Server`` * ``{network-role}`` is the {network-role} of the ONAP internal network

VNF

MUST

Property: fixed_ips, Map Property: ip_address

R-85328

A VNF's Heat Orchestration Template's ``OS::Nova::Server`` resource property ``metadata`` **MAY** contain the key/value pair ``vm_role`` and the value **MUST** be obtained either via - ``get_param`` - hard coded in the key/value pair ``vm_role``.

VNF

MAY

vm_role

R-85653

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.

VNF or PNF

MUST

Licensing Requirements

R-85734

If a VNF's Heat Orchestration Template contains the property ``name`` for a non ``OS::Nova::Server`` resource, the intrinsic function ``str_replace`` **MUST** be used in conjunction with the ONAP supplied metadata parameter ``vnf_name`` to generate a unique value. Additional data **MAY** be used in the ``str_replace`` construct to generate a unique value.

VNF

MUST

Resource Property “name”

R-857511

VNF or PNF Provider **MUST** have agreement with the Service Provider before utilizing the :doc:`HV-VES option <dcae:sections/services/ves-hv/index>` for monitoring as this option does not fully integrate with the ONAP's DCAE event processing capabilities.

VNF or PNF PROVIDER

MUST

Monitoring and Fault Protocol Selection

R-859208

The VNF **MUST** log automated remote activities performed with elevated privileges.

VNF

MUST

VNF Security Analytics Requirements

R-85959

The VNF **SHOULD** automatically enable/disable added/removed sub-components or component so there is no manual intervention required.

VNF

SHOULD

System Resource Optimization

R-85991

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.

VNF or PNF PROVIDER

MUST

Licensing Requirements

R-86182

When the VNF's Heat Orchestration Template's Resource ``OS::Neutron::Port`` is in an incremental module and is attaching to an ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666), the ``network`` parameter name **MUST** * follow the naming convention ``int_{network-role}_net_id`` if the network UUID value is used to reference the network * follow the naming convention ``int_{network-role}_net_name`` if the network name in is used to reference the network. where ``{network-role}`` is the network-role of the ONAP internal network and a ``get_param`` **MUST** be used as the intrinsic function.

VNF

MUST

Property: network

R-86235

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.

VNF or PNF

MUST

Resource Control Loop

R-86261

The VNF **MUST** be able to authenticate and authorize all remote access.

VNF

MUST

VNF General Security Requirements

R-86285

A VNF's Heat Orchestration template **MUST** have a corresponding environment file.

VNF

MUST

Environment File Format

R-86476

A VNF's Heat Orchestration Template's ``OS::Nova::Server`` resource property ``metadata`` key/value pair ``vm_role`` value **MUST** only contain alphanumeric characters and underscores (i.e., '_').

VNF

MUST

vm_role

R-86497

A VNF's Heat Orchestration Template's Resource ``OS::Cinder::VolumeAttachment`` Resource ID **SHOULD** use the naming convention * ``{vm-type}_volume_attachment_{index}`` where * ``{vm-type}`` is the vm-type * ``{index}`` starts at zero and increments by one (as described in R-11690)

VNF

SHOULD

OS::Cinder::VolumeAttachment

R-86585

The VNFC **SHOULD** minimize the use of state within a VNFC to facilitate the movement of traffic from one instance to another.

VNF

SHOULD

VNF Design

R-86588

A VNF's Heat Orchestration Template's ``{network-role}`` case in Resource property parameter names **SHOULD** match the case of ``{network-role}`` in Resource IDs and vice versa.

VNF

SHOULD

{network-role}

R-86758

The VNF **SHOULD** provide an automated test suite to validate every new version of the software on the target environment(s). The tests should be of sufficient granularity to independently test various representative VNF use cases throughout its lifecycle. Operations might choose to invoke these tests either on a scheduled basis or on demand to support various operations functions including test, turn-up and troubleshooting.

VNF

SHOULD

VNF Devops

R-86835

The VNF **MUST** set the default settings for user access to deny authorization, except for a super user type of account.

VNF

MUST

VNF Identity and Access Management Requirements

R-86926

A VNF's incremental module **MAY** be used for scale out only.

VNF

MAY

ONAP VNF Modularity Overview

R-86972

A VNF **SHOULD** create the ONAP internal network in the VNF's Heat Orchestration Template's Base Module.

VNF

SHOULD

Internal Networks

R-87004

A VNF's Heat Orchestration Template's Resource ``OS::Cinder::Volume`` Resource ID **SHOULD** use the naming convention * ``{vm-type}_volume_{index}`` where * ``{vm-type}`` is the vm-type * ``{index}`` starts at zero and increments by one (as described in R-11690)

VNF

SHOULD

OS::Cinder::Volume

R-87096

A VNF **MAY** contain zero, one or more than one ONAP internal network.

VNF

MAY

Internal Networks

R-87123

The VNF's Heat Orchestration Template's Resource ``OS::Neutron::Port`` property ``fixed_ips`` map property ``ip_address`` parameter ``{vm-type}_{network-role}_v6_ip_{index}`` **MUST NOT** be enumerated in the VNF's Heat Orchestration Template's Environment File.

VNF

MUST NOT

Property: fixed_ips, Map Property: ip_address

R-87234

The VNF or PNF CSAR package provided by a VNF or PNF vendor **MUST** be with TOSCA-Metadata directory (CSAR Option 1) as specified in ETSI GS NFV-SOL004. **Note:** SDC supports only the CSAR Option 1 in Dublin. The Option 2 will be considered in future ONAP releases.

VNF or PNF CSAR PACKAGE

MUST

VNF or PNF Package Structure and Format

R-87247

VNF Heat Orchestration Template's Incremental Module file name **MUST** contain only alphanumeric characters and underscores '_' and **MUST NOT** contain the case insensitive string ``base``.

VNF

MUST

Incremental Modules

R-872986

The VNF **MUST** store Authentication Credentials used to authenticate to other systems encrypted except where there is a technical need to store the password unencrypted in which case it must be protected using other security techniques that include the use of file and directory permissions. Ideally, credentials SHOULD rely on a HW Root of Trust, such as a TPM or HSM.

VNF

MUST

VNF General Security Requirements

R-87352

The VNF **SHOULD** utilize Cloud health checks, when available from the Network Cloud, from inside the application through APIs to check the network connectivity, dropped packets rate, injection, and auto failover to alternate sites if needed.

VNF

SHOULD

Monitoring & Dashboard

R-87485

A VNF's Heat Orchestration Template's file extension **MUST** be in the lower case format ``.yaml`` or ``.yml``.

VNF

MUST

ONAP Heat Orchestration Template Filenames

R-87563

A VNF's Heat Orchestration Template's Resource ``OS::ContrailV2::InstanceIp`` Resource ID that is configuring an IPv6 Address on a virtual machine interface (i.e., OS::ContrailV2::VirtualMachineInterface) attached to an ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666) **MUST** use the naming convention * ``{vm-type}_{vm-type_index}_int_{network-role}_vmi_{vmi_index}_v6_IP_{index}`` where * ``{vm-type}`` is the vm-type * ``{vm-type_index}`` references the instance of the ``{vm-type}`` in the VNF. The ``{vm-type_index}`` is a numeric value that **MUST** start at zero in the VNF and **MUST** increment by one each time a new instance of a ``{vm-type}`` is referenced. * ``{network-role}`` is the network-role of the ONAP internal network that the port is attached to * ``{vmi_index}`` references the instance of the virtual machine interface on the ``{vm-type}`` attached to ``{network-role}`` network. The ``{vmi_index}`` is a numeric value that **MUST** start at zero on an instance of a ``{vm-type}`` and **MUST** increment by one each time a new virtual machine interface is defined on the instance of the ``{vm-type}`` attached to ``{network-role}`` network. * ``v6_IP`` signifies that an IPv6 address is being configured * ``{index}`` references the instance of the IPv6 address configured on the virtual machine interface. The ``{index}`` is a numeric value that **MUST** start at zero on an instance of a virtual machine interface and **MUST** increment by one each time a new IPv6 address is configured on the virtual machine interface.

VNF

MUST

OS::ContrailV2::InstanceIp

R-87564

The VNF or PNF **SHOULD** conform its YANG model to RFC 7317, "A YANG Data Model for System Management".

VNF or PNF

SHOULD

NETCONF Server Requirements

R-87817

When the VNF's Heat Orchestration Template's Resource ``OS::Nova::Server`` property ``name`` parameter is defined as a ``comma_delimited_list``, the parameter name **MUST** follow the naming convention ``{vm-type}_names``.

VNF

MUST

Property: Name

R-88002

The VNF or PNF Provider **MUST** use a pre-agreed upon password to encrypt the Ansible Vault file, or provide the vault password used to encrypt the file to the customer, in a secure manner, to allow the customer to decrypt/encrypt (rekey) Ansible Vault files before they are checked into the central repository for distribution.

VNF or PNF PROVIDER

MUST

Ansible Playbook Requirements

R-88026

The VNF or PNF **MUST** include a NETCONF server enabling runtime configuration and lifecycle management capabilities.

VNF or PNF

MUST

Configuration Management

R-88031

The VNF or PNF **SHOULD** implement the protocol operation: ``delete-config(target)`` - Delete the named configuration data store target.

VNF or PNF

SHOULD

NETCONF Server Requirements

R-88199

The VNF **MUST** utilize a persistent datastore service that can meet the data performance/latency requirements. (For example: Datastore service could be a VNFC in VNF or a DBaaS in the Cloud execution environment)

VNF

MUST

VNF Design

R-88524

A VNF's Heat Orchestration Template's Volume Template Output Parameter names **MUST** contain ``{vm-type}`` when appropriate.

VNF

MUST

ONAP Volume Template Output Parameters:

R-88536

A VNF's Heat Orchestration Template's OS::Nova::Server Resource **SHOULD** contain the metadata map value parameter 'environment_context'.

VNF

SHOULD

environment_context

R-88786

The VNF or PNF Provider's Ansible playbooks **SHOULD** place the passwords and secrets to be edited at the top of the single YAML or JSON file with all the secrets, and the (default) ones that are to remain unchanged ' towards the bottom, with commentary separating them.

VNF or PNF PROVIDER

SHOULD

Ansible Playbook Requirements

R-88863

A VNF's Heat Orchestration Template's parameter defined in a non-nested YAML file as type ``number`` **MAY** have a parameter constraint defined.

VNF

MAY

constraints

R-89010

The VNF **MUST** survive any single points of software failure internal to the VNF (e.g., in memory structures, JMS message queues).

VNF

MUST

All Layer Redundancy

R-89474

The VNF **MUST** log the field "Login ID" in the security audit logs.

VNF

MUST

VNF Security Analytics Requirements

R-89571

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.

VNF or PNF PROVIDER

MUST

Resource Configuration

R-89800

The VNF **MUST NOT** require Hypervisor-level customization from the cloud provider.

VNF

MUST NOT

VNF Devops

R-89913

A VNF's Heat Orchestration Template's Cinder Volume Module Output Parameter(s) **MUST** include the UUID(s) of the Cinder Volumes created in template.

VNF

MUST

ONAP Volume Module Output Parameters

R-90007

The VNF or PNF **MUST** implement the protocol operation: ``close-session()`` - Gracefully close the current session.

VNF or PNF

MUST

NETCONF Server Requirements

R-90022

A VNF's Nested YAML file **MAY** be invoked more than once by a VNF's Heat Orchestration Template.

VNF

MAY

Nested Heat Template Requirements

R-901331

The VNF's Heat Orchestration Template's Resource ``OS::Nova::Server`` property ``image`` value **MUST** be be obtained via a ``get_param``.

VNF

MUST

Property: image

R-90152

A VNF's Heat Orchestration Template's ``resources:`` section **MUST** contain the declaration of at least one resource.

VNF

MUST

resources

R-90206

The VNF's Heat Orchestration Template's Resource ``OS::Neutron::Port`` property ``fixed_ips`` map property ``ip_address`` parameter ``{vm-type}_int_{network-role}_int_ips`` **MUST** be enumerated in the VNF's Heat Orchestration Template's Environment File.

VNF

MUST

Property: fixed_ips, Map Property: ip_address

R-90279

A VNF Heat Orchestration's template's parameter **MUST** be used - in a resource AND/OR - in a output parameter (in the outputs section) with the exception of the parameters for the ``OS::Nova::Server`` resource property ``availability_zone`` which is defined in R-98450.

VNF

MUST

parameters

R-90526

A VNF Heat Orchestration Template parameter declaration **MUST NOT** contain the ``default`` attribute.

VNF

MUST NOT

default

R-90632

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.

VNF

MUST

Resource Control Loop

R-90748

A VNF's Heat Orchestration Template's Resource ``OS::Cinder::Volume`` **MAY** be defined in an Incremental Module.

VNF

MAY

ONAP VNF Modularity Overview

R-908291

The VNF or PNF **MAY** leverage a bulk VNF or PNF telemetry transmission mechanism in instances where other transmission methods are not practical or advisable. NOTE: For additional information and use cases for the Bulk Telemetry Transmission Mechanism, please refer to the :ref:`bulk_performance_measurement` requirements and the `5G - Bulk PM ONAP Development <https://wiki.onap.org/display/DW/5G+-+Bulk+PM>`__ Wiki page.

VNF or PNF

MAY

Monitoring and Fault Protocol Selection

R-91125

The VNF's Heat Orchestration Template's Resource ``OS::Nova::Server`` property ``image`` parameter **MUST** be enumerated in the Heat Orchestration Template's Environment File and a value **MUST** be assigned.

VNF

MUST

Property: image

R-91273

A VNF Heat Orchestration's template's parameter for the ``OS::Nova::Server`` resource property ``availability_zone`` **MAY NOT** be used in any ``OS::Nova::Server``.

VNF

MAY NOT

parameters

R-91342

A VNF Heat Orchestration Template's Base Module's Environment File **MUST** be named identical to the VNF Heat Orchestration Template's Base Module with ``.y[a]ml`` replaced with ``.env``.

VNF

MUST

Base Modules

R-91497

A VNF's incremental module **MAY** be used for both deployment and scale out.

VNF

MAY

ONAP VNF Modularity Overview

R-91745

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

VNF or PNF

MUST

Ansible Client Requirements

R-918136

The VNF or PNF Provider's Ansible playbooks **MUST NOT** fail due to a mismatched version check as specified in R-918136. The warning message should be issued, and the playbook execution should continue as normal.

VNF or PNF PROVIDER

MUST NOT

Ansible Playbook Requirements

R-92193

A VNF's Heat Orchestration Template's Contrail resource ``OS::ContrailV2::InstanceIp`` and/or ``OS::ContrailV2::VirtualMachineInterface`` property ``virtual_network_refs`` parameter ``{network-role}_net_fqdn`` **MUST NOT** be enumerated in the VNF's Heat Orchestration Template's Environment File.

VNF

MUST NOT

ONAP External Networks

R-92207

The VNF **SHOULD** provide a mechanism that enables the operators to perform automated system configuration auditing at configurable time intervals.

VNF

SHOULD

VNF General Security Requirements

R-92571

The VNF **MUST** provide operational instrumentation such as logging, so as to facilitate quick resolution of issues with the VNF to provide service continuity.

VNF

MUST

Monitoring & Dashboard

R-92635

A VNF's Heat Orchestration Template **MUST** be compliant with the OpenStack Template Guide.

VNF

MUST

ONAP Heat Orchestration Template Format

R-92866

The VNF or PNF Provider **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 creating Mechanized user ID(s) used by the Ansible Server(s) on VNF VM(s) and uploading and installing new SSH keys used by the mechanized use ID(s).

VNF or PNF PROVIDER

MUST

Ansible Client Requirements

R-92935

The VNF **SHOULD** minimize the propagation of state information across multiple data centers to avoid cross data center traffic.

VNF

SHOULD

Minimize Cross Data-Center Traffic

R-93030

The VNF's Heat Orchestration Template's Resource ``OS::Neutron::Port`` property ``fixed_ips`` map property ``ip_address`` parameter ``{vm-type}_{network-role}_v6_ips`` **MUST NOT** be enumerated in the VNF's Heat Orchestration Template's Environment File.

VNF

MUST NOT

Property: fixed_ips, Map Property: ip_address

R-931076

The VNF **MUST** support account names that contain at least A-Z, a-z, and 0-9 character sets and be at least 6 characters in length.

VNF

MUST

VNF Identity and Access Management Requirements

R-93443

The VNF or PNF **MUST** define all data models in YANG 1.0 [RFC6020] or YANG 1.1 [RFC7950]. A combination of YANG 1.0 and YANG 1.1 modules is allowed subject to the rules in [RFC7950] section 12. The mapping to NETCONF shall follow the rules defined in this RFC.

VNF or PNF

MUST

NETCONF Server Requirements

R-93496

The VNF's Heat Orchestration Template's Resource ``OS::Neutron::Port`` property ``fixed_ips`` map property ``ip_address`` parameter associated with an ONAP internal network, i.e., * ``{vm-type}_int_{network-role}_ip_{index}`` * ``{vm-type}_int_{network-role}_v6_ip_{index}`` * ``{vm-type}_int_{network-role}_ips`` * ``{vm-type}_int_{network-role}_v6_ips`` **MUST** be enumerated in the Heat Orchestration Template's Environment File and IP addresses **MUST** be assigned.

VNF

MUST

Property: fixed_ips, Map Property: ip_address

R-935717

The VNF or PNF **MUST** report heartbeats using :ref:`Virtual Function Event Streaming (VES) <ves_monitoring_requirements>`.

VNF or PNF

MUST

Monitoring and Fault Protocol Selection

R-93860

The VNF **SHOULD** provide the capability to integrate with an external encryption service.

VNF

SHOULD

VNF Cryptography Requirements

R-940591

A VNF or PNF producing VES events **SHOULD** use the recommended parameter name for the configurable value from Table 1.

VNF or PNF

SHOULD

Configuration Requirements

R-94084

The VNF or PNF **MUST** support APPC/SDN-C ``ConfigScaleOut`` command.

VNF or PNF

MUST

Configuration Commands

R-94509

A VNF Heat Orchestration Template's Incremental Module's Environment File **MUST** be named identical to the VNF Heat Orchestration Template's Incremental Module with ``.y[a]ml`` replaced with ``.env``.

VNF

MUST

Incremental Modules

R-94525

The VNF **MUST** log connections to the network listeners of the resource.

VNF

MUST

VNF Security Analytics Requirements

R-94567

The VNF or PNF Provider's Ansible playbooks **MUST** be designed to run using an inventory hosts file in a supported format with only IP addresses or IP addresses and VM/VNF or PNF names.

VNF or PNF PROVIDER

MUST

Ansible Client Requirements

R-94669

If a VNF has one IPv6 OAM Management IP Address and the IP Address needs to be inventoried in ONAP's A&AI database, an output parameter **MUST** be declared in only one of the VNF's Heat Orchestration Templates and the parameter **MUST** be named ``oam_management_v6_address``.

VNF

MUST

OAM Management IP Addresses

R-94978

The VNF **MUST** provide a mechanism and tool to perform a graceful shutdown of all the containers (VMs) in the VNF without impacting service or service quality assuming another VNF in same or other geographical location can take over traffic and process service requests.

VNF

MUST

Application Resilient Error Handling

R-952314

If the PNF set up a TLS connection and mutual (two-way) authentication is being used, then the PNF **MUST** provide its own X.509v3 Certificate to the DCAE VES Collector for authentication. Note: This allows TLS authentication by DCAE VES Collector. Note: The PNF got its X.509 certificate through Enrollment with an operator certificate authority or a X.509 vendor certificate from the vendor factory CA. Note: In R3 three authentication options are supported: (1) HTTP with Username & Password and no TLS. (2) HTTP with Username & Password & TLS with two-way certificate authentication. (3) HTTP with Username & Password & TLS with server-side certificate authentication.

PNF

MUST

PNF Plug and Play

R-95303

A VNF's Heat Orchestration Template **MUST** be defined using valid YAML.

VNF

MUST

YAML Format

R-95321

The VNFD provided by VNF vendor may use the below described TOSCA relationships. An on-boarding entity (ONAP SDC) **MUST** support them. **tosca.relationships.nfv.VirtualBindsTo** This relationship type represents an association relationship between VDU and CP node types. **tosca.relationships.nfv.VirtualLinksTo** This relationship type represents an association relationship between the VduCpd's and VirtualLinkDesc node types.

VNF

MUST

Relationship Types

R-95430

If a VNF's Heat Orchestration Template's ``OS::Nova::Server`` resource property ``metadata`` key/value pair ``vm_role`` value is obtained via ``get_param``, the parameter **MAY** be declared as * ``vm_role`` and the parameter defined as ``type: string``. * ``vm_roles`` and the parameter defined as ``type: comma_delimited_list``. * ``{vm-type}_vm_role`` and the parameter defined as ``type: string``.

VNF

MAY

vm_role

R-95864

The VNF **MUST** support digital certificates that comply with X.509 standards.

VNF

MUST

VNF Data Protection Requirements

R-95950

The VNF or PNF **MUST** provide a NETCONF interface fully defined by supplied YANG models for the embedded NETCONF server.

VNF or PNF

MUST

Configuration Management

R-96227

A VNF's Heat Orchestration Template's parameter defined in a non-nested YAML file as type ``json`` **MAY** have a parameter constraint defined.

VNF

MAY

constraints

R-96253

A VNF's Heat Orchestration Template's Resource ``OS::ContrailV2::VirtualMachineInterface`` Resource ID that is attaching to an ONAP external network (per the ONAP definition, see Requirement R-57424 and R-16968) **MUST** use the naming convention * ``{vm-type}_{vm-type_index}_{network-role}_vmi_{vmi_index}`` where * ``{vm-type}`` is the vm-type * ``{vm-type_index}`` references the instance of the ``{vm-type}`` in the VNF. The ``{vm-type_index}`` is a numeric value that **MUST** start at zero in the VNF and **MUST** increment by one each time a new instance of a ``{vm-type}`` is referenced. * ``{network-role}`` is the network-role of the ONAP external network that the port (i.e. virtual machine interface) is attached to * ``{vmi_index}`` references the instance of the virtual machine interface on the ``{vm-type}`` attached to ``{network-role}`` network. The ``{vmi_index}`` is a numeric value that **MUST** start at zero on an instance of a ``{vm-type}`` and **MUST** increment by one each time a new virtual machine interface is defined on the instance of the ``{vm-type}`` attached to ``{network-role}`` network.

VNF

MUST

OS::ContrailV2::VirtualMachineInterface

R-96482

When a VNF's Heat Orchestration Template's resource is associated with a single ONAP external network, the Resource ID **MUST** contain the text ``{network-role}``.

VNF

MUST

Resource IDs

R-96554

The VNF or PNF **MUST** implement the protocol operation: ``unlock(target)`` - Unlock the configuration data store target.

VNF or PNF

MUST

NETCONF Server Requirements

R-96634

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.

VNF or PNF PROVIDER

MUST

Compute, Network, and Storage Requirements

R-96983

A VNF's Heat Orchestration Template's Resource ID that is associated with an ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666) **MUST** include ``int_{network-role}`` as part of the Resource ID, where ``int_`` is a hard coded string.

VNF

MUST

{network-role}

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.

VNF

MUST

Compute, Network, and Storage Requirements

R-97201

The VNF's Heat Orchestration Template's Resource ``OS::Neutron::Port`` property ``fixed_ips`` map property ``ip_address`` parameter ``{vm-type}_int_{network-role}_v6_ip_{index}`` **MUST** be enumerated in the VNF's Heat Orchestration Template's Environment File.

VNF

MUST

Property: fixed_ips, Map Property: ip_address

R-972082

If the Manifest file in the PNF CSAR package includes "onap_pnf_sw_information" as a non-MANO artifact set identifiers, then the PNF software information file is included in the package and it **MUST** be compliant to: - The file extension which contains the PNF software version must be .yaml - The PNF software version information must be specified as following: .. code-block:: yaml pnf_software_information: - pnf_software_version: "<version>"

PNF CSAR PACKAGE

MUST

VNF or PNF Package Contents

R-97343

The VNF or PNF **MUST** support APPC/SDN-C ``UpgradeBackup`` command.

VNF or PNF

MUST

Lifecycle Management Related Commands

R-97345

The VNF or PNF **MUST** permit authentication, using root account, only right after instantiation and until post-instantiation configuration is completed.

VNF or PNF

MUST

Ansible Client Requirements

R-97445

The VNF **MUST** log the field "date/time" in the security audit logs.

VNF

MUST

VNF Security Analytics Requirements

R-97451

The VNF or PNF **MUST** provide the ability to remove root access once post-instantiation configuration (Configure) is completed.

VNF or PNF

MUST

Ansible Client Requirements

R-97529

The VNF or PNF **SHOULD** implement the protocol operation: ``get-schema(identifier, version, format)`` - Retrieve the YANG schema.

VNF or PNF

SHOULD

NETCONF Server Requirements

R-97726

A VNF's Heat Orchestration Template's Base Module Output Parameter names **MUST** contain ``{vm-type}`` and/or ``{network-role}`` when appropriate.

VNF

MUST

ONAP Base Module Output Parameters:

R-980039

The PNF **MUST** send the pnfRegistration VES event periodically.

PNF

MUST

PNF Plug and Play

R-98138

When a VNF's Heat Orchestration Template's resource is associated with a single ONAP internal network (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666), the Resource ID **MUST** contain the text ``int_{network-role}``.

VNF

MUST

Resource IDs

R-981585

The pnfRegistration VES event periodicity **MUST** be configurable. Note: The PNF uses the service configuration request as a semaphore to stop sending the pnfRegistration sent. See the requirement PNP-5360 requirement.

PNF

MUST

PNF Plug and Play

R-98374

A VNF's Heat Orchestration Template's ``OS::Nova::Server`` resource property ``metadata`` key/value pair ``vf_module_id`` parameter ``vf_module_id`` **MUST NOT** have parameter constraints defined.

VNF

MUST NOT

vf_module_id

R-98407

A VNF's Heat Orchestration Template's ``{vm-type}`` **MUST** contain only alphanumeric characters and/or underscores '_' and **MUST NOT** contain any of the following strings: ``_int`` or ``int_`` or ``_int_``.

VNF

MUST NOT

{vm-type}

R-98450

A VNF's Heat Orchestration Template's base module or incremental module resource ``OS::Nova::Server`` property ``availability_zone`` parameter **MUST** follow the naming convention * ``availability_zone_{index}`` where ``{index}`` is a numeric value that **MUST** start at zero in a VNF's Heat Orchestration Templates and **MUST** increment by one.

VNF

MUST

Property: availability_zone

R-98569

The VNF's Heat Orchestration Template's Resource ``OS::Neutron::Port`` property ``fixed_ips`` map property ``ip_address`` parameter ``{vm-type}_int_{network-role}_v6_ips`` **MUST** be enumerated in the VNF's Heat Orchestration Template's Environment File.

VNF

MUST

Property: fixed_ips, Map Property: ip_address

R-98617

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

VNF PROVIDER

MUST

Resource Description

R-98905

The VNF's Heat Orchestration Template's Resource ``OS::Neutron::Port`` property ``fixed_ips`` map property ``ip_address`` parameter ``{vm-type}_{network-role}_ips`` **MUST NOT** be enumerated in the VNF's Heat Orchestration Template's Environment File.

VNF

MUST NOT

Property: fixed_ips, Map Property: ip_address

R-98911

The VNF or PNF **MUST NOT** use any instance specific parameters for the VNF or PNF in roles/cookbooks/recipes invoked for a VNF or PNF action.

VNF or PNF

MUST NOT

Chef Roles/Requirements

R-98989

The VNF **SHOULD** utilize resource pooling (threads, connections, etc.) within the VNF application so that resources are not being created and destroyed resulting in resource management overhead.

VNF

SHOULD

System Resource Optimization

R-99110

A VNF's Heat Orchestration Template's Resource ``OS::ContrailV2::VirtualNetwork`` Resource ID **MUST** use the naming convention * ``int_{network-role}_network`` VNF Heat Orchestration Templates can only create ONAP internal networks (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666). There is no ``{index}`` after ``{network-role}`` because ``{network-role}`` **MUST** be unique in the scope of the VNF's Heat Orchestration Template.

VNF

MUST

OS::ContrailV2::VirtualNetwork

R-99174

The VNF **MUST**, if not integrated with the Operator's Identity and Access Management system, support the creation of multiple IDs so that individual accountability can be supported.

VNF

MUST

VNF Identity and Access Management Requirements

R-99646

A VNF's YAML files (i.e, Heat Orchestration Template files and Nested files) **MUST** have a unique name in the scope of the VNF.

VNF

MUST

ONAP Heat Orchestration Template Filenames

R-99656

The VNF **MUST** NOT terminate stable sessions if a VNFC instance fails.

VNF

MUST

VNF Design

R-99730

The VNF **MUST** include the field "Login ID" in the Security alarms (where applicable and technically feasible).

VNF

MUST

VNF Security Analytics Requirements

R-99766

The VNF **MUST** allow configurations and configuration parameters to be managed under version control to ensure the ability to rollback to a known valid configuration.

VNF

MUST

Application Configuration Management

R-99771

The VNF **MUST** have all code (e.g., QCOW2) and configuration files (e.g., HEAT template, Ansible playbook, script) hardened, or with documented recommended configurations for hardening and interfaces that allow the Operator to harden the VNF. Actions taken to harden a system include disabling all unnecessary services, and changing default values such as default credentials and community strings.

VNF

MUST

VNF General Security Requirements

R-997907

The VNF or PNF **SHOULD** support TLS as secure transport for the NETCONF protocol according to [RFC7589].

VNF or PNF

SHOULD

NETCONF Server Requirements

R-99794

An ONAP external network **MUST** have one subnet. An external network **MAY** have more than one subnet.

VNF

MUST

External Networks

R-99798

A VNF's Heat Orchestration Template's Virtual Machine (i.e., ``OS::Nova::Server`` resource) **MAY** boot from an image or **MAY** boot from a Cinder Volume.

VNF

MAY

Boot Options

R-99812

A value for VNF's Heat Orchestration Template's property ``name`` for a non ``OS::Nova::Server`` resource **MUST NOT** be declared in the VNF's Heat Orchestration Template's Environment File.

VNF

MUST NOT

Resource Property “name”