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
|
The VNF SHOULD be decomposed into granular re-usable VNFCs. |
Requirement: 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). |
Requirement: 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). |
Requirement: R-02360
|
The VNFC MUST be designed as a standalone, executable process. |
Requirement: R-34484
|
The VNF SHOULD create a single component VNF for VNFCs that can be used by other VNFs. |
Requirement: 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. |
Requirement: 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. |
Requirement: R-12709
|
The VNFC SHOULD be independently deployed, configured, upgraded, scaled, monitored, and administered by ONAP. |
Requirement: R-37692
|
The VNFC MUST provide API versioning to allow for independent upgrades of VNFC. |
Requirement: R-86585
|
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
|
The VNF SHOULD maintain state in a geographically redundant datastore that may, in fact, be its own VNFC. |
Requirement: 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. |
Requirement: 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) |
Requirement: R-99656
|
The VNF MUST NOT terminate stable sessions if a VNFC instance fails. |
Requirement: 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. |
Requirement: R-54430
|
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
|
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
|
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
|
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
|
The VNF MUST meet their own resiliency goals and not rely on the Network Cloud. |
Requirement: 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. |
Requirement: R-03954
|
The VNF MUST survive any single points of failure within the Network Cloud (e.g., virtual NIC, VM, disk failure). |
Requirement: R-89010
|
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
|
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
|
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
|
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
|
The VNF MUST NOT impact the ability of the VNF to provide service/function due to a single container restart. |
Requirement: R-79952
|
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
|
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
|
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
|
The VNF MUST handle the restart of a single VNFC instance without requiring all VNFC instances to be restarted. |
Requirement: 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. |
Requirement: 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). |
Requirement: 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. |
Requirement: 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. |
Requirement: 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. |
Requirement: R-36792
|
The VNF MUST automatically retry/resubmit failed requests made by the software to its downstream system to increase the success rate. |
Requirement: R-70013
|
The VNF MUST NOT require any manual steps to get it ready for service after a container rebuild. |
Requirement: 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. |
Requirement: 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. |
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
|
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
|
The VNF MUST automatically advertise newly scaled components so there is no manual intervention required. |
Requirement: R-74712
|
The VNF MUST utilize FQDNs (and not IP address) for both Service Chaining and scaling. |
Requirement: 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. |
Requirement: R-85959
|
The VNF SHOULD automatically enable/disable added/removed sub-components or component so there is no manual intervention required. |
Requirement: 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. |
Requirement: R-12538
|
The VNF SHOULD support load balancing and discovery mechanisms in resource pools containing VNFC instances. |
Requirement: 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. |
Requirement: 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. |
Requirement: 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. |
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
|
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
|
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
|
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
|
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
|
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
|
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
|
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
|
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
|
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
|
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
|
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
|
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
|
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
|
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
|
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
|
The VNF MUST provide unique traceability of a transaction through its life cycle to ensure quick and efficient troubleshooting. |
Requirement: 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. |
Requirement: 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. |
Requirement: 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. |
Requirement: 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. |
Requirement: 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. |
Requirement: 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. |
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
|
The VNF MUST support ONAP Controller’s Restart (stop/start or reboot) command. |
Requirement: 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.
|
Requirement: R-38001
|
The VNF MUST support ONAP Controller’s Rebuild command. |
Requirement: R-76901
|
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
|
The VNF MUST support ONAP Controller’s Evacuate command. |
Requirement: R-48761
|
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
|
The VNF MUST implement and enforce the principle of least privilege on all protected interfaces. |
Requirement: 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. |
Requirement: R-92207
|
The VNF SHOULD provide a mechanism that enables the operators to perform automated system configuration auditing at configurable time intervals. |
Requirement: 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). |
Requirement: 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. |
Requirement: 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. |
Requirement: 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. |
Requirement: 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. |
Requirement: R-62498
|
The VNF MUST support only encrypted access protocols, e.g., TLS, SSH, SFTP. |
Requirement: 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. |
Requirement: 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. |
Requirement: R-19082
|
The VNF MUST not contain undocumented functionality. |
Requirement: 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. |
Requirement: R-86261
|
The VNF MUST be able to authenticate and authorize all remote access. |
Requirement: 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. |
Requirement: R-756950
|
The VNF MUST be operable without the use of Network File System (NFS). |
Requirement: R-240760
|
The VNF MUST NOT contain any backdoors. |
Requirement: R-256267
|
If SNMP is utilized, the VNF MUST support at least SNMPv3 with message authentication. |
Requirement: 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. |
Requirement: 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. |
Requirement: 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. |
Requirement: 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. |
Requirement: 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 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
|
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
|
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
|
The VNF MUST support at least the following roles: system administrator, application administrator, network function O&M. |
Requirement: 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. |
Requirement: 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. |
Requirement: R-86835
|
The VNF MUST set the default settings for user access to deny authorization, except for a super user type of account. |
Requirement: 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. |
Requirement: R-39562
|
The VNF MUST disable unnecessary or vulnerable cgi-bin programs. |
Requirement: R-75041
|
The VNF MUST, if not integrated with the Operator’s Identity and Access Management system, support configurable password expiration. |
Requirement: 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. |
Requirement: R-844011
|
The VNF MUST not store authentication credentials to itself in clear text or any reversible form and must use salting. |
Requirement: 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. |
Requirement: R-23135
|
The VNF MUST, if not integrated with the Operator’s identity and access management system, authenticate all access to protected resources. |
Requirement: 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. |
Requirement: 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. |
Requirement: 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. |
Requirement: R-581188
|
The VNF MUST NOT identify the reason for a failed authentication, only that the authentication failed. |
Requirement: 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. |
Requirement: R-231402
|
The VNF MUST provide a means to explicitly logout, thus ending that session. |
Requirement: R-251639
|
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
|
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
|
The VNF SHOULD integrate with the Operator’s authentication and authorization services (e.g., IDAM). |
Requirement: 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. |
Requirement: 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). |
Requirement: 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 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
|
The VNF MUST support Real-time detection and notification of security events. |
Requirement: 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. |
Requirement: 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. |
Requirement: 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. |
Requirement: R-58370
|
The VNF SHOULD operate with anti-virus software which produces alarms every time a virus is detected. |
Requirement: 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. |
Requirement: 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. |
Requirement: R-55478
|
The VNF MUST log logoffs. |
Requirement: R-13344
|
The VNF MUST log starting and stopping of security logging. |
Requirement: R-07617
|
The VNF MUST log success and unsuccessful creation, removal, or change to the inherent privilege level of users. |
Requirement: R-94525
|
The VNF MUST log connections to the network listeners of the resource. |
Requirement: R-31614
|
The VNF MUST log the field “event type” in the security audit logs. |
Requirement: R-97445
|
The VNF MUST log the field “date/time” in the security audit logs. |
Requirement: R-25547
|
The VNF MUST log the field “protocol” in the security audit logs. |
Requirement: R-06413
|
The VNF MUST log the field “service or program used for access” in the security audit logs. |
Requirement: R-15325
|
The VNF MUST log the field “success/failure” in the security audit logs. |
Requirement: R-89474
|
The VNF MUST log the field “Login ID” in the security audit logs. |
Requirement: R-04982
|
The VNF MUST NOT include an authentication credential, e.g., password, in the security audit logs, even if encrypted. |
Requirement: R-63330
|
The VNF MUST detect when its security audit log storage medium is approaching capacity (configurable) and issue an alarm. |
Requirement: R-41252
|
The VNF MUST support the capability of online storage of security audit logs. |
Requirement: R-41825
|
The VNF MUST activate security alarms automatically when a configurable number of consecutive unsuccessful login attempts is reached. |
Requirement: R-43332
|
The VNF MUST activate security alarms automatically when it detects the successful modification of a critical system or application file. |
Requirement: 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. |
Requirement: R-15884
|
The VNF MUST include the field “date” in the Security alarms (where applicable and technically feasible). |
Requirement: R-23957
|
The VNF MUST include the field “time” in the Security alarms (where applicable and technically feasible). |
Requirement: R-71842
|
The VNF MUST include the field “service or program used for access” in the Security alarms (where applicable and technically feasible). |
Requirement: R-57617
|
The VNF MUST include the field “success/failure” in the Security alarms (where applicable and technically feasible). |
Requirement: R-99730
|
The VNF MUST include the field “Login ID” in the Security alarms (where applicable and technically feasible). |
Requirement: R-29705
|
The VNF MUST restrict changing the criticality level of a system security alarm to users with administrative privileges. |
Requirement: 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. |
Requirement: R-04492
|
The VNF MUST generate security audit logs that can be sent to Security Analytics Tools for analysis. |
Requirement: R-30932
|
The VNF MUST log successful and unsuccessful access to VNF resources, including data. |
Requirement: R-54816
|
The VNF MUST support the storage of security audit logs for a configurable period of time. |
Requirement: 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. |
Requirement: R-34552
|
The VNF MUST be implemented so that it is not vulnerable to OWASP Top 10 web application security risks. |
Requirement: 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. |
Requirement: 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. |
Requirement: R-303569
|
The VNF MUST log the Source IP address in the security audit logs. |
Requirement: 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. |
Requirement: R-465236
|
The VNF SHOULD provide the capability of maintaining the integrity of its static files using a cryptographic method. |
Requirement: R-859208
|
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
|
The VNF MUST provide the capability to restrict read and write access to data handled by the VNF. |
Requirement: R-83227
|
The VNF MUST Provide the capability to encrypt data in transit on a physical or virtual network. |
Requirement: 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. |
Requirement: 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. |
Requirement: R-73067
|
The VNF MUST use NIST and industry standard cryptographic algorithms and standard modes of operations when implementing cryptography. |
Requirement: 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). |
Requirement: 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. |
Requirement: R-70933
|
The VNF MUST provide the ability to migrate to newer versions of cryptographic algorithms and protocols with minimal impact. |
Requirement: R-95864
|
The VNF MUST support digital certificates that comply with X.509 standards. |
Requirement: 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. |
Requirement: R-69610
|
The VNF MUST provide the capability of using X.509 certificates issued by an external Certificate Authority. |
Requirement: 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 Cryptography Requirements
This section covers VNF cryptography requirements that are mostly applicable to encryption or protocol meethods.
Requirement: 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). |
Requirement: R-93860
|
The VNF SHOULD provide the capability to integrate with an external encryption service. |
Requirement: R-44723
|
The VNF MUST use symmetric keys of at least 112 bits in length. |
Requirement: R-25401
|
The VNF MUST use asymmetric keys of at least 2048 bits in length. |
Requirement: 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. |
Requirement: R-83500
|
The VNF MUST provide the capability of allowing certificate renewal and revocation. |
Requirement: R-29977
|
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
|
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
|
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
|
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
|
The VNF or PNF MUST support HTTPS using TLS v1.2 or higher with strong cryptographic ciphers. |
Requirement: 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 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:
Base Module
Incremental Module
Cinder Volume Module
(R-37028) - The VNF MUST be composed of one “base” module.
Requirement: R-41215
|
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:
Base Module
Incremental Module
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
Base module contains only the shared resources.
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}.
For a given {vm-type} incremental module, the VNF may have
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.
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
Base module contains a complete initial VNF instance
Incremental modules for incremental scaling units
May contain VMs of multiple types in logical scaling combinations
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:
All VNFs must have one Base VNF Module (template) that must be the first one deployed. The base template:
Must include all shared resources (e.g., private networks, server groups, security groups)
Must expose all shared resources (by UUID) as “outputs” in its associated Heat template (i.e., ONAP Base Module Output Parameters)
May include initial set of VMs
May be operational as a stand-alone “minimum” configuration of the VNF
VNFs may have one or more incremental modules which:
Defines additional resources that can be added to an existing VNF
Must be complete Heat templates
i.e. not snippets to be incorporated into some larger template
Should define logical growth-units or sub-components of an overall VNF
On creation, receives appropriate Base Module outputs as parameters
Provides access to all shared resources (by UUID)
must not be dependent on other Add-On VNF Modules
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)
Each VNF Module (base or incremental) may have (optional) an associated Cinder Volume Module (see Cinder Volume Templates)
Volume modules must correspond 1:1 with a base module or incremental module
A Cinder volume may be embedded within the base module or incremental module if persistence is not required
Shared resource UUIDs are passed between the base module and incremental modules via Heat Outputs Parameters (i.e., Base Module Output Parameters)
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
|
NCSPs MAY operate a limited set of Guest OS and CPU architectures and families, virtual machines, etc. |
Requirement: 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. |
Requirement: R-33846
|
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
|
The VNF MUST utilize only NCSP standard compute flavors. 1 |
Requirement: R-02997
|
The VNF MUST preserve their persistent data. Running VMs will not be backed up in the Network Cloud infrastructure. |
Requirement: 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. |
Requirement: 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. |
Requirement: R-89800
|
The VNF MUST NOT require Hypervisor-level customization from the cloud provider. |
Requirement: 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. |
Requirement: R-39650
|
The VNF SHOULD provide the ability to test incremental growth of the VNF. |
Requirement: R-14853
|
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
|
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
|
The VNF SHOULD support a software promotion methodology from dev/test -> pre-prod -> production in software, development & testing and operations. |
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:
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.
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
ETSI GS NFV-SOL001 v.2.5.1
TOSCA SIMPLE Profile in YAML v.1.2
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.
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
|
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
|
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
|
The VNF or PNF CSAR file MUST be a zip file with .csar extension. |
VNF or PNF Package Contents
Requirement: 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. |
Requirement: 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 |
Requirement: R-21322
|
The VNF provider MUST provide their testing scripts to support testing as specified in ETSI NFV-SOL004 - Testing directory in CSAR |
Requirement: 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 |
Requirement: R-293901
|
The VNF or PNF CSAR PACKAGE with TOSCA-Metadata MUST include following additional keywords pointing to TOSCA files:
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
|
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):
|
Requirement: 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. |
Requirement: 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:
|
Requirement: 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:
|
Requirement: 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:
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
|
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
|
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
TOSCA data type extension tosca.datatypes.nfv.injectFile is used for vCPE use case.
ONAP extensions for VNF package that is currently proposed for Dublin release is VES extension described below.
TOSCA VNF Descriptor
General
Requirement: 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. |
Requirement: 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. |
Requirement: 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. |
Requirement: 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:
Note: The deployment aspects (deployment flavour etc.) are postponed for future ONAP releases.
|
Requirement: 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: |
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
|
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. |
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
|
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. |
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
|
The VNFD provided by VNF vendor may use the below described TOSCA capabilities. An on-boarding entity (ONAP SDC) MUST support them.
|
Relationship Types
Requirement: R-95321
|
The VNFD provided by VNF vendor may use the below described TOSCA relationships. An on-boarding entity (ONAP SDC) MUST support them.
|
Interface Types
Requirement: 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 PNF Descriptor
General
Requirement: 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. |
Data Types
Requirement: R-484843
|
The PNFD provided by a PNF vendor MUST comply with the following Data Types as specified in ETSI NFV-SOL001 standard:
|
Artifact Types
No artifact type is currently supported in ONAP.
Capability Types
Requirement: R-177937
|
The PNFD provided by a PNF vendor MUST comply with the following Capabilities Types as specified in ETSI NFV-SOL001 standard:
|
Requirements Types
Relationship Types
Requirement: R-64064
|
The PNFD provided by a PNF vendor MUST comply with the following Relationship Types as specified in ETSI NFV-SOL001 standard:
|
Interface Types
No interface type is currently supported in ONAP.
Node Types
Requirement: R-535009
|
The PNFD provided by a PNF vendor MUST comply with the following Node Types as specified in ETSI NFV-SOL001 standard:
|
Group Types
No group type is currently supported in ONAP.
Policy Types
Requirement: R-596064
|
The PNFD provided by a PNF vendor MUST comply with the following Policy Types as specified in ETSI NFV-SOL001 standard:
|
HPA Requirements
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
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
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"
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"
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 |
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
|
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
|
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
|
A VNF’s Heat Orchestration template MUST contain the
section |
The section heat_template_version:
must be set to a date that
is supported by the OpenStack environment.
description
Requirement: R-39402
|
A VNF’s Heat Orchestration Template MUST contain the
section |
parameter_groups
A VNF Heat Orchestration template may contain the section “parameter_groups:”.
parameters
Requirement: R-35414
|
A VNF Heat Orchestration’s template
MUST contain the section |
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
|
A VNF Heat Orchestration’s template’s parameter MUST be used
with the exception of the parameters for the |
Requirement: R-91273
|
A VNF Heat Orchestration’s template’s parameter for the
|
That is, the parameter associated with the property availability_zone
maybe declared but not used in a resource.
The name of the parameter.
Requirement: R-25877
|
A VNF’s Heat Orchestration Template’s parameter name (i.e., <param name>) MUST contain only alphanumeric characters and underscores (‘_’). |
Requirement: R-36772
|
A VNF’s Heat Orchestration Template’s parameter MUST include the
attribute |
Requirement: R-11441
|
A VNF’s Heat Orchestration Template’s parameter type MUST be one of the following values:
|
Requirement: R-32094
|
A VNF’s Heat Orchestration Template parameter declaration MAY
contain the attribute |
Requirement: R-44001
|
A VNF’s Heat Orchestration Template parameter declaration MUST
contain the attribute |
Note that the parameter attribute description:
is an OpenStack optional
attribute that provides a description of the parameter.
ONAP implementation requires this attribute.
Requirement: R-90526
|
A VNF Heat Orchestration Template parameter declaration MUST NOT
contain the |
Requirement: R-26124
|
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.
The parameter attribute constraints:
is an OpenStack optional attribute
that defines a list of constraints to apply to the parameter.
Requirement: R-88863
|
A VNF’s Heat Orchestration Template’s parameter defined
in a non-nested YAML file as type
|
Requirement: R-40518
|
A VNF’s Heat Orchestration Template’s parameter defined
in a non-nested YAML file as type
|
Requirement: R-96227
|
A VNF’s Heat Orchestration Template’s parameter defined
in a non-nested YAML file as type
|
Requirement: R-79817
|
A VNF’s Heat Orchestration Template’s parameter defined
in a non-nested YAML file as
type |
Requirement: R-06613
|
A VNF’s Heat Orchestration Template’s parameter defined
in a non-nested YAML file as type
|
Requirement: R-00011
|
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>
- ...
Requirement: R-22589
|
A VNF’s Heat Orchestration Template parameter declaration
MAY contain the attribute |
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
.
resources
Requirement: R-23663
|
A VNF’s Heat Orchestration template’s base module
MAY (or MAY NOT)
contain the section |
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
|
A VNF’s Heat Orchestration template’s incremental
module and volume module MUST
contain the section |
Requirement: R-90152
|
A VNF’s Heat Orchestration Template’s
|
Requirement: R-40551
|
A VNF’s Heat Orchestration Template’s Nested YAML files MAY
(or MAY NOT) contain the section |
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>
Requirement: R-75141
|
A VNF’s Heat Orchestration Template’s resource name (i.e., <resource ID>) MUST only contain alphanumeric characters and underscores (‘_’). |
Requirement: 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. |
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.
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
|
A VNF’s Heat Orchestration Template’s Resource MUST NOT reference a HTTP-based resource definitions. |
Requirement: R-71699
|
A VNF’s Heat Orchestration Template’s Resource MUST NOT reference a HTTP-based Nested YAML file. |
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
|
A VNF’s Heat Orchestration Template resource attribute
|
The resource attribute metadata
is an OpenStack optional attribute.
Requirement: R-67386
|
A VNF’s Heat Orchestration Template’s Resource MAY declare the
attribute |
The resource attribute depends_on
is an OpenStack optional attribute.
See Section 9.7 for additional details.
Requirement: R-46968
|
VNF’s Heat Orchestration Template’s Resource MAY declare the
attribute |
Requirement: R-63137
|
VNF’s Heat Orchestration Template’s Resource MAY declare the
attribute |
Requirement: R-43740
|
VNF’s Heat Orchestration Template’s Resource MAY declare the
attribute |
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.
Requirement: R-78569
|
VNF’s Heat Orchestration Template’s Resource MAY declare the
attribute |
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.
The resource attribute condition
is an OpenStack optional attribute.
outputs
Requirement: R-36982
|
A VNF’s Heat Orchestration template MAY contain the |
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
|
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
|
A VNF’s Heat Orchestration template’s Environment File MUST
contain the |
Requirement: R-68198
|
A VNF’s Heat Orchestration template’s Environment File’s
|
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
|
A VNF’s Heat Orchestration template’s Environment File’s
MAY contain the |
The parameter_defaults:
section contains default parameters that are
passed to all template resources.
Requirement: R-46096
|
A VNF’s Heat Orchestration template’s Environment File’s
MAY contain the |
The encrypted_parameters:
section contains a list of encrypted parameters.
Requirement: R-24893
|
A VNF’s Heat Orchestration template’s Environment File’s
MAY contain the |
The event_sinks:
section contains the list of endpoints that would receive
stack events.
Requirement: R-42685
|
A VNF’s Heat Orchestration template’s Environment File’s
MAY contain the |
The parameter_merge_strategies:
section provides the merge strategies for
merging parameters and parameter defaults from the environment file.
Requirement: R-67231
|
A VNF’s Heat Orchestration template’s Environment File’s
MUST NOT contain the |
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
|
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
|
|
Requirement: R-37028
|
A VNF MUST be composed of one Base Module |
Requirement: R-13196
|
A VNF MAY be composed of zero to many Incremental Modules. |
Requirement: R-28980
|
A VNF’s incremental module MAY be used for initial VNF deployment only. |
Requirement: R-86926
|
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
|
A VNF’s incremental module MAY be used for both deployment and scale out. |
Requirement: R-68122
|
A VNF’s incremental module MAY be deployed more than once, either during initial VNF deployment and/or scale out. |
Requirement: R-46119
|
A VNF’s Heat Orchestration Template’s Resource |
Requirement: R-90748
|
A VNF’s Heat Orchestration Template’s Resource |
Requirement: R-03251
|
A VNF’s Heat Orchestration Template’s Resource |
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
|
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
|
A VNF’s Base Module MUST have a corresponding Environment File. |
Requirement: R-81725
|
A VNF’s Incremental Module MUST have a corresponding Environment File |
Requirement: R-53433
|
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
|
A VNF’s Base Module MAY utilize nested heat. |
Requirement: R-56721
|
A VNF’s Incremental Module MAY utilize nested heat. |
Requirement: R-30395
|
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
|
A VNF’s Heat Orchestration Template’s file extension MUST
be in the lower case format |
Requirement: R-56438
|
A VNF’s Heat Orchestration Template’s Nested YAML file extension MUST
be in the lower case format |
Requirement: R-74304
|
A VNF’s Heat Orchestration Template’s Environment file extension MUST
be in the lower case format |
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. |
Base Modules
Requirement: 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:
where |
Requirement: 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 |
Incremental Modules
Requirement: 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 |
Requirement: 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 |
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
|
A VNF Heat Orchestration Template’s Cinder Volume Module MUST
be named identical to the base or incremental module it is supporting with
|
Requirement: R-589037
|
A VNF Heat Orchestration Template’s Cinder Volume Module
|
Requirement: 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 |
Nested Heat file
Requirement: 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 |
Requirement: R-70276
|
A VNF HEAT’s Orchestration Nested Template’s YAML file name MUST NOT
be in the format |
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:
ONAP Base Module Output Parameters
ONAP Volume Module Output Parameters
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
|
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
|
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 |
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
|
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
|
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
|
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
|
A VNF Heat Orchestration Template MUST NOT be designed to utilize the
OpenStack |
Requirement: R-43413
|
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
|
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
|
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
|
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
. Theget_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
|
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
|
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
|
A VNF MAY be connected to zero, one or more than one ONAP external network. |
Requirement: R-57424
|
A VNF’s port connected to an ONAP external network MAY use the port for the purpose of
|
Requirement: R-99794
|
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
|
A VNF MAY contain zero, one or more than one ONAP internal network. |
Requirement: 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., |
Requirement: 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. |
Requirement: 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. |
Requirement: R-16241
|
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
|
A VNF SHOULD create the ONAP internal network in the VNF’s Heat Orchestration Template’s Base Module. |
Requirement: 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
and the base module MUST contain an output parameter that provides either the network UUID or network name.
The The Base Module Output Parameter MUST be declared in the |
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:
Resource IDs
Resource Property Parameters
{vm-type}
Requirement: R-01455
|
When a VNF’s Heat Orchestration Template creates a Virtual Machine
(i.e.,
|
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
|
A VNF’s Heat Orchestration Template’s |
Requirement: R-48067
|
A VNF’s Heat Orchestration Template’s |
It may cause the VNF Validation Program validation-scripts project to produce erroneous error messages.
Requirement: R-32394
|
A VNF’s Heat Orchestration Template’s use of |
Requirement: R-46839
|
A VNF’s Heat Orchestration Template’s use of |
Requirement: R-36687
|
A VNF’s Heat Orchestration Template’s |
{network-role}
Requirement: R-69014
|
When a VNF’s port connects to an ONAP internal network or ONAP
external network,
a network role, referred to
as the |
Requirement: R-05201
|
When a VNF connects to two or more unique networks, each
network MUST be assigned a unique |
Requirement: R-21330
|
A VNF’s Heat Orchestration Template’s Resource property parameter that is
associated with an ONAP
external network MUST include the |
Requirement: R-11168
|
A VNF’s Heat Orchestration Template’s Resource ID that is associated with
an ONAP external network MUST include the |
Requirement: 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
|
Requirement: 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 |
Requirement: R-26506
|
A VNF’s Heat Orchestration Template’s
|
Requirement: R-00977
|
A VNF’s Heat Orchestration Template’s |
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
|
A VNF’s Heat Orchestration Template’s use of |
Requirement: R-21511
|
A VNF’s Heat Orchestration Template’s use of |
Requirement: R-86588
|
A VNF’s Heat Orchestration Template’s |
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
|
When a VNF’s Heat Orchestration Template’s resource is associated with
a single |
Requirement: 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 |
Requirement: 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
|
Requirement: R-82115
|
When a VNF’s Heat Orchestration Template’s resource is associated with a
single
|
Requirement: R-82551
|
When a VNF’s Heat Orchestration Template’s resource is associated with a
single
|
Requirement: R-67793
|
When a VNF’s Heat Orchestration Template’s resource is associated
with more than one |
Requirement: R-27970
|
When a VNF’s Heat Orchestration Template’s resource is associated with
more than one |
Requirement: R-11690
|
When a VNF’s Heat Orchestration Template’s Resource ID contains an
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 |
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.
Requirement: R-87004
|
A VNF’s Heat Orchestration Template’s Resource
where
|
Requirement: R-86497
|
A VNF’s Heat Orchestration Template’s Resource
where
|
Requirement: R-04747
|
A VNF’s Heat Orchestration Template’s Resource |
Requirement: R-20319
|
A VNF’s Heat Orchestration Template’s Resource
where
|
Requirement: R-30804
|
A VNF’s Heat Orchestration Template’s Resource
|
Requirement: R-18202
|
A VNF’s Heat Orchestration Template’s Resource
where
|
There is no mandatory naming convention for the resource ‘OS::Heat::ResourceGroup’.
Requirement: R-08975
|
A VNF’s Heat Orchestration Template’s Resource |
Requirement: R-03656
|
A VNF’s Heat Orchestration Template’s Resource
where
|
Requirement: R-25720
|
A VNF’s Heat Orchestration Template’s Resource
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 |
Requirement: R-20453
|
A VNF’s Heat Orchestration Template’s Resource
where
|
Requirement: R-26351
|
A VNF’s Heat Orchestration Template’s Resource
where
|
Requirement: R-27469
|
A VNF’s Heat Orchestration Template’s Resource
where
|
Requirement: R-68520
|
A VNF’s Heat Orchestration Template’s Resource
where
|
Requirement: R-08775
|
A VNF’s Heat Orchestration Template’s Resource
where
|
Requirement: R-03595
|
A VNF’s Heat Orchestration Template’s Resource
where
|
Requirement: R-73213
|
A VNF’s Heat Orchestration Template’s Resource
where
|
Requirement: R-17334
|
A VNF’s Heat Orchestration Template’s Resource
where
|
Requirement: R-14198
|
A VNF’s Heat Orchestration Template’s Resource
where
|
Requirement: R-30005
|
A VNF’s Heat Orchestration Template’s Resource
or
where
|
Requirement: R-59434
|
A VNF’s Heat Orchestration Template’s Resource
where
|
Requirement: R-24997
|
A VNF’s Heat Orchestration Template’s Resource
where
|
Requirement: R-65516
|
A VNF’s Heat Orchestration Template’s Resource
where
|
Requirement: R-29751
|
A VNF’s Heat Orchestration Template’s Resource
where
|
Requirement: R-15189
|
A VNF’s Heat Orchestration Template’s Resource
or
or
or
|
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.
Requirement: R-53310
|
A VNF’s Heat Orchestration Template’s Resource
where
|
Requirement: R-46128
|
A VNF’s Heat Orchestration Template’s Resource
where
|
Requirement: R-62187
|
A VNF’s Heat Orchestration Template’s Resource
where
|
Requirement: R-87563
|
A VNF’s Heat Orchestration Template’s Resource
where
|
Requirement: R-81214
|
A VNF’s Heat Orchestration Template’s Resource
|
Requirement: R-28189
|
A VNF’s Heat Orchestration Template’s Resource
where
|
Requirement: R-30753
|
A VNF’s Heat Orchestration Template’s Resource
|
Requirement: R-81979
|
A VNF’s Heat Orchestration Template’s Resource
where
|
Requirement: R-20065
|
A VNF’s Heat Orchestration Template’s Resource
|
Requirement: R-84457
|
A VNF’s Heat Orchestration Template’s Resource
where
|
Requirement: R-76014
|
A VNF’s Heat Orchestration Template’s Resource
|
Requirement: R-65618
|
A VNF’s Heat Orchestration Template’s Resource
where
|
Requirement: R-16437
|
A VNF’s Heat Orchestration Template’s Resource
|
Requirement: R-14447
|
A VNF’s Heat Orchestration Template’s Resource
where
|
Requirement: R-96253
|
A VNF’s Heat Orchestration Template’s Resource
where
|
Requirement: R-50468
|
A VNF’s Heat Orchestration Template’s Resource
where
|
Requirement: R-99110
|
A VNF’s Heat Orchestration Template’s Resource
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 |
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.
image
flavor
name
availability_zone
Requirement R-01455 defines how the {vm-type]
is defined.
Requirement: R-304011
|
A VNF’s Heat Orchestration Template’s
MUST contain the identical |
The table below provides a summary. The sections that follow provides the detailed requirements.
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
|
The VNF’s Heat Orchestration Template’s Resource |
Requirement: R-71152
|
The VNF’s Heat Orchestration Template’s Resource |
Requirement: R-58670
|
The VNF’s Heat Orchestration Template’s Resource |
Requirement: R-91125
|
The VNF’s Heat Orchestration Template’s Resource |
Requirement: R-57282
|
Each VNF’s Heat Orchestration Template’s |
Example Parameter Definition
parameters:
{vm-type}_image_name:
type: string
description: {vm-type} server image
Property: flavor
Requirement: R-481670
|
The VNF’s Heat Orchestration Template’s Resource |
Requirement: R-50436
|
The VNF’s Heat Orchestration Template’s Resource |
Requirement: R-45188
|
The VNF’s Heat Orchestration Template’s Resource ‘OS::Nova::Server’ property
|
Requirement: R-69431
|
The VNF’s Heat Orchestration Template’s Resource |
Requirement: R-40499
|
Each VNF’s Heat Orchestration Template’s |
Example Parameter Definition
parameters:
{vm-type}_flavor_name:
type: string
description: {vm-type} flavor
Property: Name
Requirement: R-663631
|
The VNF’s Heat Orchestration Template’s Resource |
Requirement: R-51430
|
The VNF’s Heat Orchestration Template’s Resource |
Requirement: R-54171
|
When the VNF’s Heat Orchestration Template’s Resource
where |
Requirement: R-87817
|
When the VNF’s Heat Orchestration Template’s Resource |
Requirement: R-22838
|
The VNF’s Heat Orchestration Template’s Resource |
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 }
...
Requirement: R-44271
|
The VNF’s Heat Orchestration Template’s Resource However, if special characters must be used, the only special characters supported are: — " ! $ ‘ () = ~ ^ | @ ` { } [ ] > , . _ |
Property: availability_zone
Requirement: R-98450
|
A VNF’s Heat Orchestration Template’s base module or incremental module
resource
where |
Requirement: R-23311
|
The VNF’s Heat Orchestration Template’s base module or incremental module
resource |
The parameter must not be declared as type comma_delimited_list
, ONAP does
not support it.
Requirement: R-59568
|
The VNF’s Heat Orchestration Template’s Resource |
Requirement: R-256790
|
A VNF’s Heat Orchestration Template’s Resource |
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
|
A VNF’s Heat Orchestration Template that contains an |
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
|
A VNF’s Heat Orchestration Template’s Virtual Machine
(i.e., |
Requirement: R-83706
|
When a VNF’s Heat Orchestration Template’s Virtual Machine
(i.e., |
The requirements associated with the ‘image’ property are detailed in Property: image
Requirement: R-69588
|
When a VNF’s Heat Orchestration Template’s Virtual Machine
(i.e., |
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.
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
|
A VNF’s Heat Orchestration Template’s |
Requirement: R-07507
|
A VNF’s Heat Orchestration Template’s |
Requirement: R-55218
|
A VNF’s Heat Orchestration Template’s |
Requirement: R-20856
|
A VNF’s Heat Orchestration Template’s |
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
|
A VNF’s Heat Orchestration Template’s |
Requirement: R-82134
|
A VNF’s Heat Orchestration Template’s |
Requirement: R-98374
|
A VNF’s Heat Orchestration Template’s |
Requirement: R-72871
|
A VNF’s Heat Orchestration Template’s |
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
|
A VNF’s Heat Orchestration Template’s |
Requirement: R-62428
|
A VNF’s Heat Orchestration Template’s |
Requirement: R-44318
|
A VNF’s Heat Orchestration Template’s |
Requirement: R-36542
|
A VNF’s Heat Orchestration Template’s |
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
|
A VNF’s Heat Orchestration Template’s |
Requirement: R-68023
|
A VNF’s Heat Orchestration Template’s |
Requirement: R-39067
|
A VNF’s Heat Orchestration Template’s |
Requirement: R-15480
|
A VNF’s Heat Orchestration Template’s |
Requirement: R-80374
|
A VNF’s Heat Orchestration Template’s |
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
|
A VNF’s Heat Orchestration Template’s
|
Requirement: R-95430
|
If a VNF’s Heat Orchestration Template’s
|
Requirement: R-67597
|
A VNF’s Heat Orchestration Template’s |
Defining the vm_role
as the {vm-type}
is a recommended convention
Requirement: R-86476
|
A VNF’s Heat Orchestration Template’s |
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
|
A VNF’s Heat Orchestration Template’s |
Requirement: R-50816
|
A VNF’s Heat Orchestration Template’s |
Requirement: R-54340
|
A VNF’s Heat Orchestration Template’s |
Requirement: R-09811
|
A VNF’s Heat Orchestration Template’s |
Requirement: R-37039
|
A VNF’s Heat Orchestration Template’s |
Requirement: R-55306
|
A VNF’s Heat Orchestration Template’s |
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
propertyname
parameter (defined as acomma_delimited_list
).OS::Neutron::Port
propertyfixed_ips
map propertyip_address
parameter (defined as acomma_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
|
A VNF’s Heat Orchestration Template’s parameter
|
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
|
A VNF’s Heat Orchestration Template’s OS::Nova::Server Resource SHOULD contain the metadata map value parameter ‘workload_context’. |
Requirement: R-74978
|
A VNF’s Heat Orchestration Template’s |
Requirement: R-34055
|
A VNF’s Heat Orchestration Template’s |
Requirement: R-02691
|
A VNF’s Heat Orchestration Template’s |
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
|
A VNF’s Heat Orchestration Template’s OS::Nova::Server Resource SHOULD contain the metadata map value parameter ‘environment_context’. |
Requirement: R-20308
|
A VNF’s Heat Orchestration Template’s |
Requirement: R-56183
|
A VNF’s Heat Orchestration Template’s |
Requirement: R-13194
|
A VNF’s Heat Orchestration Template’s |
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:
network
fixed_ips, ip_address
fixed_ips, subnet
Note that earlier versions of this document mentioned the property fixed_ips, subnet_id. This property has been removed from the document since it has been deprecated. See https://github.com/openstack/heat/blob/stable/ocata/heat/engine/resources/openstack/neutron/port.py
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.
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
|
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
|
Requirement: 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. |
Requirement: 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
|
Requirement: 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. |
Requirement: 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
|
Requirement: R-681859
|
A VNF’s Heat Orchestration Template’s
MUST contain the identical |
Property: network
The Resource OS::Neutron::Port
property network
determines what network
the port is attached to.
Requirement: R-18008
|
The VNF’s Heat Orchestration Template’s Resource |
Requirement: R-62983
|
When the VNF’s Heat Orchestration Template’s Resource
where |
Requirement: R-86182
|
When the VNF’s Heat Orchestration Template’s Resource
where |
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 functionget_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
|
The VNF’s Heat Orchestration Template’s Resource |
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
|
The VNF’s Heat Orchestration Template’s
resource |
Requirement: R-40971
|
When the VNF’s Heat Orchestration Template’s Resource
where
|
Requirement: R-39841
|
The VNF’s Heat Orchestration Template’s Resource
|
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
|
When the VNF’s Heat Orchestration Template’s Resource
|
Requirement: R-98905
|
The VNF’s Heat Orchestration Template’s Resource
|
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
|
When the VNF’s Heat Orchestration Template’s Resource
where
|
Requirement: R-87123
|
The VNF’s Heat Orchestration Template’s Resource
|
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
|
When the VNF’s Heat Orchestration Template’s Resource
where
|
Requirement: R-93030
|
The VNF’s Heat Orchestration Template’s Resource
|
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
|
When the VNF’s Heat Orchestration Template’s Resource
where
|
Requirement: R-28795
|
The VNF’s Heat Orchestration Template’s Resource
|
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
|
When the VNF’s Heat Orchestration Template’s Resource
where
|
Requirement: R-90206
|
The VNF’s Heat Orchestration Template’s Resource
|
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
|
When the VNF’s Heat Orchestration Template’s Resource
where
|
Requirement: R-97201
|
The VNF’s Heat Orchestration Template’s Resource
|
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
|
When the VNF’s Heat Orchestration Template’s Resource
where
|
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
|
The VNF’s Heat Orchestration Template’s Resource
|
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
|
The VNF’s Heat Orchestration Template’s Resource
MUST NOT be enumerated in the Heat Orchestration Template’s Environment File. ONAP provides the IP address assignments at orchestration time. |
Requirement: R-93496
|
The VNF’s Heat Orchestration Template’s Resource
MUST be enumerated in the Heat Orchestration Template’s Environment File and IP addresses MUST be assigned. |
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 |
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
|
The VNF’s Heat Orchestration Template’s
resource |
Requirement: R-62802
|
When the VNF’s Heat Orchestration Template’s
resource
where
|
Note that ONAP only supports cloud assigned IP addresses from one IPv4 subnet of a given network.
Requirement: R-83677
|
The VNF’s Heat Orchestration Template’s Resource
|
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
|
When the VNF’s Heat Orchestration Template’s
resource
where
|
Note that ONAP only supports cloud assigned IP addresses from one IPv6 subnet of a given network.
Requirement: R-80829
|
The VNF’s Heat Orchestration Template’s Resource
|
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
|
When
the parameter MUST follow the naming convention
where
Note that the parameter MUST be defined as an |
Requirement: R-69634
|
The VNF’s Heat Orchestration Template’s Resource
|
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
|
When
the parameter MUST follow the naming convention
where Note that the parameter MUST be defined as an |
Requirement: R-22288
|
The VNF’s Heat Orchestration Template’s Resource
|
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.
Requirement: R-83412
|
If a VNF’s Heat Orchestration Template’s resource
|
Requirement: R-41492
|
When the VNF’s Heat Orchestration Template’s resource
where
And the parameter MUST be declared as type 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
|
When the VNF’s Heat Orchestration Template’s resource
where
And the parameter MUST be declared as type 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
|
When the VNF’s Heat Orchestration Template’s resource
And the And the |
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
|
A VNF’s Heat Orchestration Template’s MUST NOT
contain the Resource |
Requirement: R-76449
|
A VNF’s Heat Orchestration Template’s MUST NOT
contain the Resource |
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}}]
Requirement: R-717227
|
When the VNF’s Heat Orchestration Template’s Resource
where
And the parameter MUST be declared as OR the parameter name MUST follow the naming convention
where
And the parameter MUST be declared as |
Requirement: R-805572
|
When the VNF’s Heat Orchestration Template’s Resource
where
And the parameter MUST be declared as OR the parameter name MUST follow the naming convention
where
And the parameter MUST be declared as |
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
|
If a VNF’s Heat Orchestration Template contains the property |
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
|
A value for VNF’s Heat Orchestration Template’s property |
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
|
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:
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
|
A VNF’s Heat Orchestration Template’s Base Module Output Parameter names
MUST contain |
ONAP Volume Template Output Parameters:
Requirement: R-88524
|
A VNF’s Heat Orchestration Template’s Volume Template
Output Parameter names
MUST contain |
Predefined Output Parameters
ONAP currently defines one predefined output parameter the 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
|
|
Requirement: 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
|
Requirement: 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
|
- The OAM Management IP Address maybe assigned either via
ONAP SDN-C
DHCP
Requirement: 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
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
|
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 |
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.
Requirement: R-02164
|
When a VNF’s Heat Orchestration Template’s Contrail resource
|
Requirement: R-92193
|
A VNF’s Heat Orchestration Template’s Contrail resource
|
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
|
If a VNF’s Heat Orchestration Template
|
Requirement: R-19756
|
If a VNF’s Heat Orchestration Template
|
Requirement: R-76682
|
If a VNF’s Heat Orchestration Template
|
The parameter {vm-type}_{network-role}_route_prefixes
supports IP addresses in the format:
Host IP Address (e.g., 10.10.10.10)
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 }]
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
|
The VNF’s Heat Orchestration Template’s
resource |
Requirement: R-100010
|
When the VNF’s Heat Orchestration Template’s Resource
where
|
Requirement: R-100020
|
The VNF’s Heat Orchestration Template’s Resource
|
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
|
When the VNF’s Heat Orchestration Template’s Resource
|
Requirement: R-100040
|
The VNF’s Heat Orchestration Template’s Resource
|
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
|
When the VNF’s Heat Orchestration Template’s Resource
where
|
Requirement: R-100060
|
The VNF’s Heat Orchestration Template’s Resource
|
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
|
When the VNF’s Heat Orchestration Template’s Resource
where
|
Requirement: R-100080
|
The VNF’s Heat Orchestration Template’s Resource
|
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
|
When the VNF’s Heat Orchestration Template’s Resource
where
|
Requirement: R-100100
|
The VNF’s Heat Orchestration Template’s Resource
|
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
|
When the VNF’s Heat Orchestration Template’s Resource
where
|
Requirement: R-100120
|
The VNF’s Heat Orchestration Template’s Resource
|
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
|
When the VNF’s Heat Orchestration Template’s Resource
where
|
Requirement: R-100140
|
The VNF’s Heat Orchestration Template’s Resource
|
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
|
When the VNF’s Heat Orchestration Template’s Resource
where
|
Requirement: R-100160
|
The VNF’s Heat Orchestration Template’s Resource
|
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
|
The VNF’s Heat Orchestration Template’s Resource
MUST NOT be enumerated in the Heat Orchestration Template’s Environment File. ONAP provides the IP address assignments at orchestration time. |
Requirement: R-100180
|
The VNF’s Heat Orchestration Template’s Resource
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 ] }
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
|
The VNF’s Heat Orchestration Template’s
resource |
Requirement: R-100200
|
When the VNF’s Heat Orchestration Template’s
resource
where
|
Note that ONAP only supports cloud assigned IP addresses from one IPv4 subnet of a given network.
Requirement: R-100210
|
The VNF’s Heat Orchestration Template’s Resource
|
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
|
When the VNF’s Heat Orchestration Template’s
resource
where
|
Note that ONAP only supports cloud assigned IP addresses from one IPv6 subnet of a given network.
Requirement: R-100230
|
The VNF’s Heat Orchestration Template’s Resource
|
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
|
When
the parameter MUST follow the naming convention
where
Note that the parameter MUST be defined as an |
Requirement: R-100250
|
The VNF’s Heat Orchestration Template’s Resource
|
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
|
When
the parameter MUST follow the naming convention
where Note that the parameter MUST be defined as an |
Requirement: R-100270
|
The VNF’s Heat Orchestration Template’s Resource
|
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.
Requirement: R-100280
|
If a VNF’s Heat Orchestration Template’s resource
parameter MUST NOT be enumerated in the VNF’s Heat Orchestration Template’s Environment File. |
Requirement: R-100310
|
When the VNF’s Heat Orchestration Template’s resource
parameter name MUST follow the naming convention
where
And the parameter MUST be declared as type 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
|
When the VNF’s Heat Orchestration Template’s resource
parameter name MUST follow the naming convention
where
And the parameter MUST be declared as type 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
|
When the VNF’s Heat Orchestration Template’s resource
And the And the
parameters not supported by the ONAP data model. |
Requirement: R-100360
|
When the VNF’s Heat Orchestration Template’s Resource
where
And the parameter MUST be declared as OR the parameter name MUST follow the naming convention
where
And the parameter MUST be declared as |
Requirement: R-100370
|
When the VNF’s Heat Orchestration Template’s Resource
where
And the parameter MUST be declared as OR the parameter name MUST follow the naming convention
where
And the parameter MUST be declared as |
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
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
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
Parameter Name |
Parameter Type |
Notes |
---|---|---|
{network-role}_subnet_<index>_default_gateway |
string |
|
{network-role}_v6_subnet_<index>_default_gateway |
string |
DCAE Collector IP Address
Parameter Name |
Parameter Type |
Notes |
---|---|---|
dcae_collector_ip_<index> |
string |
|
dcae_collector_v6_ip_<index> |
string |
NTP Server IP Address
Parameter Name |
Parameter Type |
Notes |
---|---|---|
ntp_ip_<index> |
string |
|
ntp_v6_ip_<index> |
string |
DNS
Parameter Name |
Parameter Type |
Notes |
---|---|---|
dns_{network-role}_ip_<index> |
string |
|
dns_{network-role}_v6_ip_<index> |
string |
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
Base Module Heat Orchestration Template (also referred to as a Base Module),
Incremental Module Heat Orchestration Template (referred to as an Incremental Module), or
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
|
A VNF’s Heat Orchestration Template’s Base Module MAY declare zero, one,
or more than one |
Requirement: R-610020
|
If a VNF’s Heat Orchestration Template’s Base Module contains two or more
Note that
|
Requirement: R-610030
|
A VNF’s Heat Orchestration Template’s Incremental Module MUST declare
An An |
Requirement: R-610040
|
If a VNF’s Heat Orchestration Template’s Incremental Module contains two or
more Note that
|
Requirement: R-610050
|
The same |
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
|
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
For ONAP to provided the UUID value of the shared resource to the
incremental module, the parameter name defined in the 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
Base module contains only the shared resources.
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}.
For a given {vm-type} incremental module, the VNF may have
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.
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
Base module contains a complete initial VNF instance
Incremental modules for incremental scaling units
May contain VMs of multiple types in logical scaling combinations
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:
All VNFs must have one Base VNF Module (template) that must be the first one deployed. The base template:
Must include all shared resources (e.g., private networks, server groups, security groups)
Must expose all shared resources (by UUID) as “outputs” in its associated Heat template (i.e., ONAP Base Module Output Parameters)
May include initial set of VMs
May be operational as a stand-alone “minimum” configuration of the VNF
VNFs may have one or more incremental modules which:
Defines additional resources that can be added to an existing VNF
Must be complete Heat templates
i.e. not snippets to be incorporated into some larger template
Should define logical growth-units or sub-components of an overall VNF
On creation, receives appropriate Base Module outputs as parameters
Provides access to all shared resources (by UUID)
VNFs may have one or more incremental modules which must not be dependent on other Add-On VNF Modules
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)
Each VNF Module (base or incremental) may have (optional) an associated Cinder Volume Module (see Cinder Volumes)
Volume modules must correspond 1:1 with a base module or incremental module
A Cinder volume may be embedded within the base module or incremental module if persistence is not required
Shared resource UUIDs are passed between the base module and incremental modules via Heat Outputs Parameters (i.e., Base Module Output Parameters)
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
|
A VNF’s Heat Orchestration Template’s Cinder Volume Template MUST contain either
|
Optional Property availability_zone
Requirement: R-25190
|
A VNF’s Heat Orchestration Template’s Resource |
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
|
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
|
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
|
A VNF’s Heat Orchestration Template MAY reference the nested heat statically by repeated definition. |
Requirement: R-01101
|
A VNF’s Heat Orchestration Template MAY
reference the nested heat dynamically using the resource
|
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
|
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
|
A VNF’s Heat Orchestration Template’s first level Nested YAML file
MUST NOT contain more than one |
Requirement: R-708564
|
If a VNF’s Heat Orchestration Template’s resource invokes a nested
YAML file, either statically or dynamically
(via
|
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
|
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
|
A VNF’s Nested YAML file MAY be invoked more than once by a VNF’s Heat Orchestration Template. |
Requirement: 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). |
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} ] }
Requirement: R-50011
|
A VNF’s Heat Orchestration Template’s |
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
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 }
]
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.

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
|
If a VNF’s Heat Orchestration Template uses the intrinsic function
|
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
|
A VNF’s Heat Orchestration Template intrinsic function
|
Requirement: R-05050
|
A VNF’s Heat Orchestration Templates intrinsic function
|
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
|
If a VNF requires the use of an SSH key created by OpenStack, the VNF
Heat Orchestration Template SHOULD create the 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
|
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
|
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
|
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
|
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
|
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
|
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
|
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
|
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
|
The VNF or PNF Provider MUST provide VES Event Registration for all VES events provided by that VNF or PNF. |
Requirement: 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. |
Requirement: R-025941
|
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
|
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
|
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
|
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
|
The VNF or PNF provider MUST provide cookbooks to be loaded on the appropriate Chef Server. |
Requirement: 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. |
Configuration Management via Ansible
Requirement: R-75608
|
The VNF or PNF provider MUST provide playbooks to be loaded on the appropriate Ansible Server. |
Requirement: 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. |
Requirement: R-46567
|
The VNF or PNF Package MUST include configuration scripts for boot sequence and configuration. |
Requirement: 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). |
Resource Control Loop
Requirement: 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. |
Requirement: 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. |
Requirement: 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. |
Requirement: 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. |
Requirement: 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 ) and for the overall VNF or PNF. |
Requirement: 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. |
Requirement: 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. |
Requirement: 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. |
Requirement: 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. |
Requirement: R-33904
|
The VNF or PNF Package MUST include documentation for each KPI, provide lower and upper limits. |
Requirement: 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. |
Requirement: 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. |
Requirement: 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. |
Requirement: R-33694
|
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
|
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
|
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
|
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
|
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
|
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
|
The VNF Package MUST include VM requirements via a Heat template that provides the necessary data for high availability redundancy model. |
Requirement: 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. |
Requirement: R-26881
|
The VNF provider MUST provide the binaries and images needed to instantiate the VNF (VNF and VNFC images). |
Requirement: 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. |
Testing
Requirement: R-43958
|
The VNF Documentation Package MUST describe the tests that were conducted by the VNF provider and the test results. |
Requirement: R-04298
|
The VNF provider MUST provide their testing scripts to support testing. |
Requirement: 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. |
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
|
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
|
The VNF or PNF provider MUST enumerate all of the open source licenses their VNF or PNF(s) incorporate. |
Requirement: 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. |
Requirement: R-13613
|
The VNF MUST provide clear measurements for licensing purposes if needed to allow automated scale up/down by the management system. |
Requirement: 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. |
Requirement: 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. |
Requirement: 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, 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
|
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
|
The VNF or PNF MUST support APPC/SDN-C |
Requirement: R-19366
|
The VNF or PNF MUST support APPC |
Requirement: R-32981
|
The VNF or PNF MUST support APPC |
Requirement: R-48247
|
The VNF or PNF MUST support APPC |
Requirement: R-94084
|
The VNF or PNF MUST support APPC/SDN-C |
Requirement: R-56385
|
The VNF or PNF MUST support APPC |
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
|
The VNF or PNF MUST include a NETCONF server enabling runtime configuration and lifecycle management capabilities. |
Requirement: R-95950
|
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
|
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
|
The VNF or PNF MUST implement the protocol operation:
|
Requirement: R-70496
|
The VNF or PNF MUST implement the protocol operation:
|
Requirement: R-18733
|
The VNF or PNF MUST implement the protocol operation:
|
Requirement: R-44281
|
The VNF or PNF MUST implement the protocol operation:
|
Requirement: R-60106
|
The VNF or PNF MUST implement the protocol operation:
|
Requirement: R-29488
|
The VNF or PNF MUST implement the protocol operation:
|
Requirement: R-11235
|
The VNF or PNF MUST implement the protocol operation:
|
Requirement: R-02597
|
The VNF or PNF MUST implement the protocol operation:
|
Requirement: R-96554
|
The VNF or PNF MUST implement the protocol operation:
|
Requirement: R-29324
|
The VNF or PNF SHOULD implement the protocol operation:
|
Requirement: R-88031
|
The VNF or PNF SHOULD implement the protocol operation:
|
Requirement: R-97529
|
The VNF or PNF SHOULD implement the protocol operation:
|
Requirement: 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. |
Requirement: 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. |
Requirement: R-28756
|
The VNF or PNF MAY support |
Requirement: R-83873
|
The VNF or PNF MUST support |
Requirement: R-68990
|
The VNF or PNF MAY support the |
Requirement: R-68200
|
The VNF or PNF MAY support the |
Requirement: R-20353
|
The VNF or PNF MUST implement at least one of |
Requirement: 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 |
Requirement: R-83790
|
The VNF or PNF MAY implement the |
Requirement: R-49145
|
The VNF or PNF MUST implement |
Requirement: R-58358
|
The VNF or PNF MAY implement the |
Requirement: R-59610
|
The VNF or PNF MUST implement the data model discovery and download as defined in [RFC6022]. |
Requirement: 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. |
Requirement: 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. |
Requirement: 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). |
Requirement: 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. |
Requirement: 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. |
Requirement: 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). |
Requirement: 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). |
Requirement: 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. |
Requirement: 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). |
Requirement: 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. |
Requirement: 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. |
Requirement: R-60656
|
The VNF or PNF MUST support sub tree filtering. |
Requirement: R-80898
|
TThe VNF or PNF MUST support heartbeat via a <get> with null filter. |
Requirement: R-25238
|
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
|
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
|
The VNF or PNF MUST conform its YANG model to RFC 6244, “An Architecture for Network Management Using NETCONF and YANG”. |
Requirement: R-53317
|
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
|
The VNF or PNF SHOULD conform its YANG model to RFC 6991, “Common YANG Data Types”. |
Requirement: R-22946
|
The VNF or PNF SHOULD conform its YANG model to RFC 8341, “NETCONF Access Control Model”. |
Requirement: R-10129
|
The VNF or PNF SHOULD conform its YANG model to RFC 7223, “A YANG Data Model for Interface Management”. |
Requirement: R-12271
|
The VNF or PNF SHOULD conform its YANG model to RFC 7223, “IANA Interface Type YANG Module”. |
Requirement: R-49036
|
The VNF or PNF SHOULD conform its YANG model to RFC 7277, “A YANG Data Model for IP Management”. |
Requirement: R-87564
|
The VNF or PNF SHOULD conform its YANG model to RFC 7317, “A YANG Data Model for System Management”. |
Requirement: 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. |
The NETCONF server interface shall fully conform to the following NETCONF RFCs.
Requirement: R-33946
|
The VNF or PNF MUST conform to the NETCONF RFC 4741, “NETCONF Configuration Protocol”. |
Requirement: R-04158
|
The VNF or PNF MUST conform to the NETCONF RFC 4742, “Using the NETCONF Configuration Protocol over Secure Shell (SSH)”. |
Requirement: R-01334
|
The VNF or PNF MAY conform to the NETCONF RFC 5717, “Partial Lock Remote Procedure Call”. |
Requirement: R-78282
|
The VNF or PNF MUST conform to the NETCONF RFC 6242, “Using the Network Configuration Protocol over Secure Shell”. |
Requirement: R-997907
|
The VNF or PNF SHOULD support TLS as secure transport for the NETCONF protocol according to [RFC7589]. |
LCM Operations via NETCONF
Requirement: 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 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
|
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
|
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
|
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
|
The VNF or PNF MAY expose a single endpoint that is responsible for all functionality. |
Requirement: R-67114
|
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
|
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
|
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
|
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
|
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
|
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
|
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
|
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
|
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
|
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.
|
Requirement: 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. |
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.
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.
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.
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.
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>"
}
}
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.
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
|
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
|
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
|
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
|
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
|
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 |
Requirement: R-97345
|
The VNF or PNF MUST permit authentication, using root account, only right after instantiation and until post-instantiation configuration is completed. |
Requirement: R-97451
|
The VNF or PNF MUST provide the ability to remove root access once post-instantiation configuration (Configure) is completed. |
Requirement: 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. |
Requirement: 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. |
Requirement: 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. |
Requirement: 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. |
Requirement: 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. |
Requirement: 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. |
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
|
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
|
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
|
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
|
Requirement: 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. |
Requirement: R-444446
|
The VNF or PNF Provider’s Ansible playbooks SHOULD issue log messages
in the same format as Ansible’s default messages:
Example:
|
Requirement: 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
|
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
|
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
|
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
|
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
|
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
|
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
|
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
|
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
|
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
|
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
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
|
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
|
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
|
Requirement: 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. |
Requirement: 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 |
Requirement: 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
|
Requirement: 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 |
Requirement: 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. |
Requirement: 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. |
Requirement: 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. |
Requirement: 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. |
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.
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.
The APPC/SDN-C sends a request to the Ansible server to execute the action.
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. |
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
|
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
|
The VNF or PNF MUST report performance metrics using Virtual Function Event Streaming (VES) or Bulk Performance Measurement. |
Requirement: R-69111
|
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
|
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
|
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
|
Requirement: R-935717
|
The VNF or PNF MUST report heartbeats using Virtual Function Event Streaming (VES). |
Requirement: 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 HV-VES collector service details for more information. |
Requirement: R-857511
|
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
|
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
|
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
|
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
|
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
|
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:
|
Requirement: 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 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:
|
Requirement: R-123044
|
The VNF or PNF Provider MAY require that specific events, identified by
their |
Event Formatting and Usage
Requirement: 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: The latest version (7.2) should be preferred. Earlier versions are provided for backwards compatibility. |
Requirement: 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. |
Requirement: 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. |
Requirement: 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. |
Requirement: 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. |
Requirement: 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:
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
|
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
|
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
|
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
|
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
|
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
|
A VNF or PNF producing VES events SHOULD use the recommended parameter name for the configurable value from Table 1. |
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
|
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
|
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
|
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
|
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
|
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
|
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.
|
Requirement: 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. |
Requirement: 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. |
Requirement: 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) |
Requirement: 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:
|
Requirement: 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. |
Requirement: R-103464
|
A VNF or PNF producing VES events that is buffering events due to an
unavailable VES Event Listener MAY leverage to |
Security
Requirement: 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. |
Requirement: R-33878
|
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
|
The VNF or PNF SHOULD support FileReady VES event for event-driven bulk transfer of monitoring data. |
Requirement: 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. |
Requirement: 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. |
Requirement: 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. |
PNF Plug and Play
PNF Plug and Play
The following are the requirements related to PNF Plug and Play.
Requirement: 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. |
Requirement: R-106240
|
A PNF MUST support the pnfRegistration VES event which is required to integrate with ONAP’s PNF Plug and Play capabilities. |
Requirement: 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. |
Requirement: 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. |
Requirement: 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:
|
Requirement: 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. |
Requirement: R-763774
|
The VNF or PNF MUST support a HTTPS connection to the DCAE VES Event Listener. |
Requirement: R-686466
|
The PNF MUST support sending a pnfRegistration VES event. |
Requirement: R-980039
|
The PNF MUST send the pnfRegistration VES event periodically. |
Requirement: 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. |
Requirement: 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. |
Requirement: 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. |
Requirement: R-707977
|
When the PNF receives a Service configuration from ONAP, the PNF MUST cease sending the pnfRegistration VES Event. |
Requirement: 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. |
Requirement: 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. |
Requirement: 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. |
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:
The JSON file must be created for each action for each VNF.
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
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:
Process the “FileParameters” dictionary and generate a file named ‘config.txt’ with contents set to the value of the ‘config.txt’ key.
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
If execution time of the playbook exceeds 60 secs (across all hosts), it will be terminated.
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 playbookspreconfig
– Contains post-instantiation pre-configuration playbook(s), that is to run before running the configure playbookpostconfig
– Contains post-instantiation post-configuration playbook(s), that is to run after running the configure playbook, example, to integrate VNFs of different typesprovision
– 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 VMrestartpods
– Contains a playbook used to perform tasks to restart application containersuser_management
– Contains a playbook used to manage user accounts on demand (add, update, delete) as part of VNF instance life cycle managementpreinstantiate
– 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.
Upload CSAR, zip, or tar file containing VNF playbooks and related artifacts to Development Ansible Server with connectivity to central repository.
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
When manually creating directory structure make this directory (VNF ansible root directory) current directory for next few steps:
cd /storage/vfdb/V16.1/ansible/
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
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”.
(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 “-“.
Perform some basic playbook validation running with “–check” option, running dummy playbooks or other.
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:
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).
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: Ifup
,down
orat
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 anup
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 allup
guidance to mean ‘at the indicated trigger level or greater’, and they may choose to define and interpret alldown
guidance to mean ‘at the indicated trigger level or lower’.The third value optionally names the condition that has been attained when the triggers fires (e.g.,
invalidLicence
orcapacityExhaustion
). 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 keywordnull
may be used as the third value.The fourth value recommends a specific microservice (e.g.,
rebootVm
orrebuildVnf
) 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
.
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 VESarrayOfFields
structure (specifically throughadditionalMeasurements
in the VESmeasurementField
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
) calledkeyValuePairs: [ ]
. Within the square brackets, a list ofkeyValuePair
keywords can be provided as follows:Each
keyValuePair
is a structure (used only withinkeyValuePairs
) which has akey
and avalue
. EachkeyValuePair
,key
andvalue
may be decorated with any of the other keywords specified in this specification (e.g., withpresence
,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:
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.
eventId construction for Fault Events:
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)
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.
lastEpochMicrosec indicates the current event time. This value will be updated for each subsequent event for a given fault.
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.
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.
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:
The username and password are formed into one string as
username:password
The resulting string is Base64 encoded to produce the encoded credential.
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.
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
The faultFields datatype consists of the following fields:
Field |
Type |
Required? |
Description |
---|---|---|---|
alarmAdditional Information |
hashMap |
No |
Additional alarm information.
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
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.
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 |
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 |
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 |
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 |
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 |
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) |
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 |
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 |
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 |
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) |
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 |
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 |
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 |
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 |
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 |
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) |
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 |
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 |
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 |
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 |
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. |
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 |
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
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
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
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 |
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 |
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 |
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 |
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 |
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’ |
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 |
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 |
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 |
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 |
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 |
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
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
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
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
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 |
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
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 |
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
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
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 |
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 :
|
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.
|
%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
, orCRITICAL
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
, orWarning
All measurements events
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
.
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:
|
Authorization |
string |
No |
The username and password are formed
into one string as
|
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:
|
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
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"
}
}
}
}
HTTPS/1.1 202 Accepted
X-MinorVersion: 1
X-PatchVersion: 1
X-LatestVersion: 7.1.1
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",
}
}
}
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:
|
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:
|
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
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"
}
}
]
}
HTTPS/1.1 202 Accepted
X-MinorVersion: 1
X-PatchVersion: 1
X-LatestVersion: 7.1.1
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",
}
}
}
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 |
|
6/3/2015 |
0.3 |
|
6/5/2015 |
0.4 |
|
6/5/2015 |
0.5 |
|
6/10/2015 |
0.6 |
|
7/7/2015 |
0.7 |
|
7/15/2015 |
1.0 |
|
7/23/2015 |
v1.1 |
Changes to eventHeader data format:
Changes to faultFields data format:
Changes to thresholdCrossingFields data format:
Other:
|
8/11/2015 |
v1.2 |
Timestamp format:
Event Header Severity Enumeration:
|
8/20/2015 |
v1.3 |
JSON Schema rev’d to v9:
Sample Responses:
|
9/16/2015 |
v1.4 |
JSON Schema rev’d to v10:
Sample Responses:
|
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 |
|
1/18/2016 |
v1.7 |
|
1/22/2016 |
v1.8 |
|
2/11/2016 |
v1.9 |
|
2/12/2016 |
v2.0 |
|
3/11/2016 |
v2.1 |
|
3/15/2016 |
v2.2 |
|
4/26/2016 |
v2.3 |
|
4/27/2016 |
v2.4 |
|
5/26/2016 |
v2.5 |
|
8/9/2016 |
v2.6 |
|
8/10/2016 |
v2.7 |
|
8/12/2016 |
v2.8 |
|
8/27/2016 |
v2.9 |
|
9/1/2016 |
v2.10 |
|
9/16/2016 |
v2.11 |
|
9/23/2016 |
v2.12 |
|
11/29/2016 |
v3.0 |
|
12/1/2016 |
v3.1 |
|
1/5/2017 |
v4.0 |
|
3/21/2017 |
v4.1 |
|
4/14/2017 |
v5.0 |
|
5/22/2017 |
v5.1 |
|
6/14/2017 |
v5.2 |
|
6/22/2017 |
v5.3 |
|
9/12/2017 |
v5.4 |
|
9/19/2017 |
v5.4.1 |
|
6/28/2018 |
v6.0 |
|
7/30/2018 |
v7.0 |
|
7/31/2018 |
v7.0.1 |
|
12/10/2018 |
v7.1 |
|
1/28/202 |
v7.1.1 |
|
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:
The username and password are formed into one string as “username:password”
The resulting string is Base64 encoded to produce the encoded credential.
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 |
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
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:
|
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:
|
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
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:
|
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:
|
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.
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
orVdbe-Juniper
, where a hyphen is used to separate theproductName
andvendorName
subfields. Note that theproductName
andvendorName
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
andNfcName
subfields. Note that theNfName
andNfcName
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:
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.
eventId construction for Fault Events:
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)
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.
lastEpochMicrosec indicates the current event time. This value will be updated for each subsequent event for a given fault.
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.
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.
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
The faultFields datatype consists of the following fields:
Field |
Type |
Required? |
Description |
---|---|---|---|
alarmAdditional Information |
hashMap |
No |
Additional alarm information.
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
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.
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 |
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 |
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 |
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 |
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 |
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) |
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 |
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 |
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 |
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) |
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 |
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 |
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 |
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 |
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 |
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) |
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 |
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 |
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 |
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.
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 |
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. |
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 |
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
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
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
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 |
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 |
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 |
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 |
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 |
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’ |
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 |
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 |
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 |
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 |
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 |
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
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
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
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. |
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
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
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 |
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
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 |
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
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
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 |
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:
The username and password are formed into one string as
username:password
The resulting string is Base64 encoded to produce the encoded credential.
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
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"
}
}
}
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 :
|
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.
|
%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:
|
Authorization |
string |
No |
The username and password are formed
into one string as
|
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:
|
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
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"
}
}
}
}
HTTPS/1.1 202 Accepted
X-MinorVersion: 2
X-PatchVersion: 1
X-LatestVersion: 7.2.1
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",
}
}
}
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:
|
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:
|
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
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"
}
}
]
}
HTTPS/1.1 202 Accepted
X-MinorVersion: 2
X-PatchVersion: 1
X-LatestVersion: 7.2.1
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",
}
}
}
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 |
|
6/3/2015 |
0.3 |
|
6/5/2015 |
0.4 |
|
6/5/2015 |
0.5 |
|
6/10/2015 |
0.6 |
|
7/7/2015 |
0.7 |
|
7/15/2015 |
1.0 |
|
7/23/2015 |
v1.1 |
Changes to eventHeader data format:
Changes to faultFields data format:
Changes to thresholdCrossingFields data format:
Other:
|
8/11/2015 |
v1.2 |
Timestamp format:
Event Header Severity Enumeration:
|
8/20/2015 |
v1.3 |
JSON Schema rev’d to v9:
Sample Responses:
|
9/16/2015 |
v1.4 |
JSON Schema rev’d to v10:
Sample Responses:
|
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 |
|
1/18/2016 |
v1.7 |
|
1/22/2016 |
v1.8 |
|
2/11/2016 |
v1.9 |
|
2/12/2016 |
v2.0 |
|
3/11/2016 |
v2.1 |
|
3/15/2016 |
v2.2 |
|
4/26/2016 |
v2.3 |
|
4/27/2016 |
v2.4 |
|
5/26/2016 |
v2.5 |
|
8/9/2016 |
v2.6 |
|
8/10/2016 |
v2.7 |
|
8/12/2016 |
v2.8 |
|
8/27/2016 |
v2.9 |
|
9/1/2016 |
v2.10 |
|
9/16/2016 |
v2.11 |
|
9/23/2016 |
v2.12 |
|
11/29/2016 |
v3.0 |
|
12/1/2016 |
v3.1 |
|
1/5/2017 |
v4.0 |
|
3/21/2017 |
v4.1 |
|
4/14/2017 |
v5.0 |
|
5/22/2017 |
v5.1 |
|
6/14/2017 |
v5.2 |
|
6/22/2017 |
v5.3 |
|
9/12/2017 |
v5.4 |
|
9/19/2017 |
v5.4.1 |
|
6/28/2018 |
v6.0 |
|
7/30/2018 |
v7.0 |
|
7/31/2018 |
v7.0.1 |
|
12/10/2018 |
v7.1 |
|
1/28/2020 |
v7.1.1 |
|
5/27/2020 |
v7.2 |
|
01/16/2021 |
v7.2.1 |
|
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.

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 asoclip
servicevtp_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:

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 |
---|---|---|---|---|
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 |
|
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 |
|
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 |
|
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 |
|
A VNF's Heat Orchestration Template **MAY** reference the nested heat statically by repeated definition. |
VNF |
MAY |
Nested Heat Template Requirements |
|
A VNF **MAY** be connected to zero, one or more than one ONAP external network. |
VNF |
MAY |
External Networks |
|
A VNF's Heat Orchestration Template's ``{network-role}`` **MUST NOT** be a substring of ``{vm-type}``. |
VNF |
MUST NOT |
{network-role} |
|
A VNF's Heat Orchestration Template **MAY** reference the nested heat dynamically using the resource ``OS::Heat::ResourceGroup``. |
VNF |
MAY |
Nested Heat Template Requirements |
|
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 |
|
The VNF or PNF **MAY** conform to the NETCONF RFC 5717, "Partial Lock Remote Procedure Call". |
VNF or PNF |
MAY |
NETCONF Server Requirements |
|
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 |
|
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 |
|
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} |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
The VNFC **MUST** be designed as a standalone, executable process. |
VNF |
MUST |
VNF Design |
|
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 |
|
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 |
|
The VNF or PNF **MUST** implement the protocol operation: ``lock(target)`` - Lock the configuration data store target. |
VNF or PNF |
MUST |
NETCONF Server Requirements |
|
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 |
|
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 |
|
The VNF **MUST** preserve their persistent data. Running VMs will not be backed up in the Network Cloud infrastructure. |
VNF |
MUST |
VNF Devops |
|
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 |
|
A VNF's Heat Orchestration template's Environment File **MUST** contain the ``parameters:`` section. |
VNF |
MUST |
Environment File Format |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
The VNF provider **MUST** provide their testing scripts to support testing. |
VNF |
MUST |
Testing |
|
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 |
|
The VNF **MUST** generate security audit logs that can be sent to Security Analytics Tools for analysis. |
VNF |
MUST |
VNF Security Analytics Requirements |
|
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 |
|
A VNF's Heat Orchestration Template's Resource ``OS::Heat::CloudConfig`` Resource ID **MUST** contain the ``{vm-type}``. |
VNF |
MUST |
OS::Heat::CloudConfig |
|
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 |
|
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) |
|
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} |
|
A VNF's Heat Orchestration Template's **MUST NOT** contain the Resource ``OS::Neutron::FloatingIP``. |
VNF |
MUST NOT |
VIP Assignment, ONAP External Networks |
|
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 |
|
The VNF **MUST** log the field "service or program used for access" in the security audit logs. |
VNF |
MUST |
VNF Security Analytics Requirements |
|
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 |
|
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 |
|
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 |
|
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 |
|
The VNF or PNF **MUST** support APPC/SDN-C ``ResumeTraffic`` command. |
VNF or PNF |
MUST |
Lifecycle Management Related Commands |
|
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 |
|
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 |
|
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 |
|
The VNF **MUST** log success and unsuccessful creation, removal, or change to the inherent privilege level of users. |
VNF |
MUST |
VNF Security Analytics Requirements |
|
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 |
|
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 |
|
A VNF's Heat Orchestration Template's Resource ``OS::Heat::SoftwareConfig`` Resource ID **MUST** contain the ``{vm-type}``. |
VNF |
MUST |
OS::Heat::SoftwareConfig |
|
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 |
|
The VNF **MUST** utilize only NCSP standard compute flavors. [#4.5.1]_ |
VNF |
MUST |
VNF Devops |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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} |
|
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 |
|
The VNF or PNF **MUST** implement the protocol operation: ``kill-session(session``- Force the termination of **session**. |
VNF or PNF |
MUST |
NETCONF Server Requirements |
|
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 |
|
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 |
|
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 |
|
The VNF **MUST** support ONAP Controller's **Restart (stop/start or reboot)** command. |
VNF |
MUST |
Virtual Function - Container Recovery Requirements |
|
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 |
|
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 |
|
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 |
|
The VNF or PNF **SHOULD** conform its YANG model to RFC 7223, "IANA Interface Type YANG Module". |
VNF or PNF |
SHOULD |
NETCONF Server Requirements |
|
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 |
|
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 |
|
The VNF **SHOULD** support load balancing and discovery mechanisms in resource pools containing VNFC instances. |
VNF |
SHOULD |
System Resource Optimization |
|
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 |
|
The VNF or PNF **MUST** support APPC/SDN-C ``QuiesceTraffic`` command. |
VNF or PNF |
MUST |
Lifecycle Management Related Commands |
|
The VNFC **SHOULD** be independently deployed, configured, upgraded, scaled, monitored, and administered by ONAP. |
VNF |
SHOULD |
VNF Design |
|
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 |
|
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 |
|
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 |
|
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 |
|
A VNF **MAY** be composed of zero to many Incremental Modules. |
VNF |
MAY |
ONAP VNF Modularity Overview |
|
The VNF **MUST** log starting and stopping of security logging. |
VNF |
MUST |
VNF Security Analytics Requirements |
|
The VNF or PNF provider **MUST** provide cookbooks to be loaded on the appropriate Chef Server. |
VNF or PNF |
MUST |
Configuration Management via Chef |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
The VNF **MUST** log the field "success/failure" in the security audit logs. |
VNF |
MUST |
VNF Security Analytics Requirements |
|
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 |
|
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 |
|
The VNF **MUST** include the field "date" in the Security alarms (where applicable and technically feasible). |
VNF |
MUST |
VNF Security Analytics Requirements |
|
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 |
|
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 |
|
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 |
|
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 |
|
A VNF's Heat Orchestration Template's Resource ``OS::ContrailV2::ServiceTemplate`` Resource ID **MUST** contain the ``{vm-type}``. |
VNF |
MUST |
OS::ContrailV2::ServiceTemplate |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
The VNF's Heat Orchestration Template's Resource ``OS::Neutron::Port`` property ``network`` parameter **MUST** be declared as type: ``string``. |
VNF |
MUST |
Property: network |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
The VNF **MUST** not contain undocumented functionality. |
VNF |
MUST |
VNF General Security Requirements |
|
The VNF or PNF **MUST** support APPC ``ConfigModify`` command. |
VNF or PNF |
MUST |
Configuration Commands |
|
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 |
|
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 |
|
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 |
|
The VNF or PNF **MUST** support APPC/SDN-C ``UpgradePrecheck`` command. |
VNF or PNF |
MUST |
Lifecycle Management Related Commands |
|
A VNF's Heat Orchestration Template's Resource ``OS::ContrailV2::PortTuple`` Resource ID **MUST** contain the ``{vm-type}``. |
VNF |
MUST |
OS::ContrailV2::PortTuple |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
The VNF or PNF **MUST** support APPC/SDN-C ``Configure`` command. |
VNF or PNF |
MUST |
Configuration Commands |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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} |
|
A VNF's Heat Orchestration Template's use of ``{network-role}`` in all Resource IDs **MUST** be the same case. |
VNF |
MUST |
{network-role} |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
A VNF's Heat Orchestration Template parameter declaration **MAY** contain the attribute ``immutable:``. |
VNF |
MAY |
immutable |
|
A VNF's Heat Orchestration Template parameter declaration **MAY** contain the attribute ``tags:``. |
VNF |
MAY |
tags |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
The VNF or PNF **SHOULD** conform its YANG model to RFC 8341, "NETCONF Access Control Model". |
VNF or PNF |
SHOULD |
NETCONF Server Requirements |
|
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 |
|
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 |
|
The VNF **MUST** provide a means to explicitly logout, thus ending that session. |
VNF |
MUST |
VNF Identity and Access Management Requirements |
|
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 |
|
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 |
|
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 |
|
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 |
|
A VNF's Heat Orchestration template's base module **MAY** (or **MAY NOT**) contain the section ``resources:``. |
VNF |
MAY |
resources |
|
A VNF's Heat Orchestration template's incremental module and volume module **MUST** contain the section ``resources:``. |
VNF |
MUST |
resources |
|
The VNF **MUST** implement and enforce the principle of least privilege on all protected interfaces. |
VNF |
MUST |
VNF General Security Requirements |
|
The VNF **MUST** include the field "time" in the Security alarms (where applicable and technically feasible). |
VNF |
MUST |
VNF Security Analytics Requirements |
|
The VNF **MUST NOT** contain any backdoors. |
VNF |
MUST NOT |
VNF General Security Requirements |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
A VNF's Heat Orchestration template's Environment File's **MAY** contain the ``event_sinks:`` section. |
VNF |
MAY |
Environment File Format |
|
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 |
|
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 |
|
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 |
|
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 |
|
The VNF **MUST** use asymmetric keys of at least 2048 bits in length. |
VNF |
MUST |
VNF Cryptography Requirements |
|
The VNF **MUST** log the field "protocol" in the security audit logs. |
VNF |
MUST |
VNF Security Analytics Requirements |
|
If SNMP is utilized, the VNF **MUST** support at least SNMPv3 with message authentication. |
VNF |
MUST |
VNF General Security Requirements |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
A VNF's Heat Orchestration Template's parameter name (i.e., <param name>) **MUST** contain only alphanumeric characters and underscores ('_'). |
VNF |
MUST |
<param name> |
|
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 |
|
If a VNF Heat Orchestration Template parameter has a default value, it **MUST** be enumerated in the environment file. |
VNF |
MUST |
default |
|
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 |
|
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 |
|
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 |
|
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} |
|
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 |
|
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 |
|
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 |
|
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 |
|
A VNF's Heat Orchestration template **MUST** contain the section ``heat_template_version:``. |
VNF |
MUST |
heat_template_version |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
A VNF's incremental module **MAY** be used for initial VNF deployment only. |
VNF |
MAY |
ONAP VNF Modularity Overview |
|
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 |
|
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 |
|
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 |
|
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 |
|
The VNF **MUST** restrict changing the criticality level of a system security alarm to users with administrative privileges. |
VNF |
MUST |
VNF Security Analytics Requirements |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
The VNF **MUST** log the Source IP address in the security audit logs. |
VNF |
MUST |
VNF Security Analytics Requirements |
|
A VNF's Cinder Volume Module **MAY** utilize nested heat. |
VNF |
MAY |
Nested Heat Orchestration Templates Overview |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
A VNF's Heat Orchestration Template's Resource ``OS::Heat::MultipartMime`` Resource ID **MUST** contain the ``{vm-type}``. |
VNF |
MUST |
OS::Heat::MultipartMime |
|
The VNF **MUST** log successful and unsuccessful access to VNF resources, including data. |
VNF |
MUST |
VNF Security Analytics Requirements |
|
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 |
|
The VNF **MUST** log the field "event type" in the security audit logs. |
VNF |
MUST |
VNF Security Analytics Requirements |
|
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 |
|
A VNF's Heat Orchestration Template parameter declaration **MAY** contain the attribute ``label:``. |
VNF |
MAY |
label |
|
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 |
|
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 |
|
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} |
|
A VNF's Heat Orchestration Template parameter declaration **MAY** contain the attribute ``hidden:``. |
VNF |
MAY |
hidden |
|
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 |
|
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 |
|
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 |
|
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 |
|
The VNF or PNF **MUST** support APPC ``ConfigBackup`` command. |
VNF or PNF |
MUST |
Configuration Commands |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
The VNF or PNF **MUST** utilize one of the authentication methods prescribed by the relevant VES Event Listener specification. |
VNF or PNF |
MUST |
Security |
|
The VNF or PNF Package **MUST** include documentation for each KPI, provide lower and upper limits. |
VNF or PNF |
MUST |
Resource Control Loop |
|
The VNF or PNF **MUST** conform to the NETCONF RFC 4741, "NETCONF Configuration Protocol". |
VNF or PNF |
MUST |
NETCONF Server Requirements |
|
The VNF or PNF **SHOULD** conform its YANG model to RFC 6991, "Common YANG Data Types". |
VNF or PNF |
SHOULD |
NETCONF Server Requirements |
|
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 |
|
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 |
|
The VNF **SHOULD** create a single component VNF for VNFCs that can be used by other VNFs. |
VNF |
SHOULD |
VNF Design |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
A VNF Heat Orchestration's template **MUST** contain the section ``parameters:`` with at least one parameter defined. |
VNF |
MUST |
parameters |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
A VNF's Base Module **MAY** utilize nested heat. |
VNF |
MAY |
Nested Heat Orchestration Templates Overview |
|
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} |
|
A VNF's Heat Orchestration Template's parameter **MUST** include the attribute ``type:``. |
VNF |
MUST |
type |
|
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 |
|
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 |
|
A VNF's Heat Orchestration template **MAY** contain the ``outputs:`` section. |
VNF |
MAY |
outputs |
|
A VNF **MUST** be composed of one Base Module |
VNF |
MUST |
ONAP VNF Modularity Overview |
|
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 |
|
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 |
|
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 |
|
The VNFC **MUST** provide API versioning to allow for independent upgrades of VNFC. |
VNF |
MUST |
VNF Design |
|
(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 |
|
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 |
|
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 |
|
The VNF **MUST** support ONAP Controller's **Rebuild** command. |
VNF |
MUST |
Virtual Function - Container Recovery Requirements |
|
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 |
|
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 |
|
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 |
|
A VNF's Base Module **MUST** have a corresponding Environment File. |
VNF |
MUST |
ONAP VNF Modularity Overview |
|
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 |
|
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 |
|
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 |
|
A VNF's Heat Orchestration Template **MUST** contain the section ``description:``. |
VNF |
MUST |
description |
|
The VNF **MUST** disable unnecessary or vulnerable cgi-bin programs. |
VNF |
MUST |
VNF Identity and Access Management Requirements |
|
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 |
|
The VNF **SHOULD** provide the ability to test incremental growth of the VNF. |
VNF |
SHOULD |
VNF Devops |
|
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 |
|
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 |
|
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 |
|
A VNF's Heat Orchestration Template's Nested YAML files **MAY** (or **MAY NOT**) contain the section ``resources:``. |
VNF |
MAY |
resources |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
The VNF **MAY** have zero to many "incremental" modules. |
VNF |
MAY |
ONAP VNF Modularity Overview |
|
The VNF **MUST** support the capability of online storage of security audit logs. |
VNF |
MUST |
VNF Security Analytics Requirements |
|
The VNF or PNF **MUST** support APPC/SDN-C ``HealthCheck`` command. |
VNF or PNF |
MUST |
HealthCheck and Failure Related Commands |
|
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 |
|
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 |
|
The VNF **MUST** activate security alarms automatically when a configurable number of consecutive unsuccessful login attempts is reached. |
VNF |
MUST |
VNF Security Analytics Requirements |
|
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 |
|
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) |
|
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 |
|
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 |
|
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 |
|
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 |
|
A VNF's Heat Orchestration template's Environment File's **MAY** contain the ``parameter_merge_strategies:`` section. |
VNF |
MAY |
Environment File Format |
|
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 |
|
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 |
|
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 |
|
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 |
|
A VNF **MUST** utilize a modular Heat Orchestration Template design to support scaling (growth/de-growth). |
VNF |
MUST |
Support of heat stack update |
|
VNF's Heat Orchestration Template's Resource **MAY** declare the attribute ``deletion_policy:``. |
VNF |
MAY |
deletion_policy |
|
The VNF **SHOULD** integrate with the Operator's authentication and authorization services (e.g., IDAM). |
VNF |
SHOULD |
VNF API Security Requirements |
|
The VNF Documentation Package **MUST** describe the tests that were conducted by the VNF provider and the test results. |
VNF DOCUMENTATION PACKAGE |
MUST |
Testing |
|
A VNF's Heat Orchestration Template parameter declaration **MUST** contain the attribute ``description``. |
VNF |
MUST |
description |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
The VNF **MUST** use symmetric keys of at least 112 bits in length. |
VNF |
MUST |
VNF Cryptography Requirements |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
The VNF or PNF **MUST** support APPC/SDN-C ``UpgradePostCheck`` command. |
VNF or PNF |
MUST |
Lifecycle Management Related Commands |
|
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 |
|
A VNF's Heat Orchestration template's Environment File's **MAY** contain the ``encrypted_parameters:`` section. |
VNF |
MAY |
Environment File Format |
|
A VNF's Heat Orchestration Template's Resource ``OS::Cinder::Volume`` **MAY** be defined in a Base Module. |
VNF |
MAY |
ONAP VNF Modularity Overview |
|
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 |
|
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 |
|
The VNF **SHOULD** provide the capability of maintaining the integrity of its static files using a cryptographic method. |
VNF |
SHOULD |
VNF Security Analytics Requirements |
|
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 |
|
The VNF or PNF Package **MUST** include configuration scripts for boot sequence and configuration. |
VNF or PNF |
MUST |
Configuration Management via Ansible |
|
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 |
|
A VNF's Heat Orchestration Template's use of ``{vm-type}`` in all Resource IDs **MUST** be the same case. |
VNF |
MUST |
{vm-type} |
|
The VNF **MUST** support ONAP Controller's Evacuate command. |
VNF |
MUST |
Virtual Function - Container Recovery Requirements |
|
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 |
|
NCSPs **MAY** operate a limited set of Guest OS and CPU architectures and families, virtual machines, etc. |
VNF |
MAY |
VNF Devops |
|
VNF's Heat Orchestration Template's Resource **MAY** declare the attribute ``depends_on:``. |
VNF |
MAY |
depends_on |
|
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 |
|
A VNF's Heat Orchestration Template's OS::Nova::Server Resource **SHOULD** contain the metadata map value parameter 'workload_context'. |
VNF |
SHOULD |
workload_context |
|
The VNF or PNF **MAY** expose a single endpoint that is responsible for all functionality. |
VNF or PNF |
MAY |
Chef Client Requirements |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
A VNF's Heat Orchestration Template's ``{vm-type}`` **MUST NOT** be a substring of ``{network-role}``. |
VNF |
MUST NOT |
{vm-type} |
|
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 |
|
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 |
|
The VNF or PNF **MUST** support APPC ``ConfigRestore`` command. |
VNF or PNF |
MUST |
Configuration Commands |
|
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 |
|
The VNF **MUST** support Real-time detection and notification of security events. |
VNF |
MUST |
VNF Security Analytics Requirements |
|
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 |
|
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 |
|
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 |
|
The VNF **MUST** support ONAP Controller's Snapshot command. |
VNF |
MUST |
Virtual Function - Container Recovery Requirements |
|
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 |
|
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 |
|
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 |
|
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 |
|
The VNF or PNF **MUST** support HTTPS using TLS v1.2 or higher with strong cryptographic ciphers. |
VNF or PNF |
MUST |
VNF Cryptography Requirements |
|
The VNF or PNF **MUST** implement ``:confirmed-commit`` If ``:candidate`` is supported. |
VNF or PNF |
MUST |
NETCONF Server Requirements |
|
The VNF **MUST** provide unique traceability of a transaction through its life cycle to ensure quick and efficient troubleshooting. |
VNF |
MUST |
Monitoring & Dashboard |
|
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 |
|
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 |
|
The VNF or PNF **MUST** support APPC/SDN-C ``UpgradeSoftware`` command. |
VNF or PNF |
MUST |
Lifecycle Management Related Commands |
|
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 |
|
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 |
|
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 |
|
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 |
|
The VNF's Heat Orchestration Template's Resource ``OS::Nova::Server`` property ``flavor`` parameter **MUST** be declared as type: ``string``. |
VNF |
MUST |
Property: flavor |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
The VNF **MUST** meet their own resiliency goals and not rely on the Network Cloud. |
VNF |
MUST |
All Layer Redundancy |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
A VNF's Cinder Volume Module **MUST** have a corresponding environment file |
VNF |
MUST |
ONAP VNF Modularity Overview |
|
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 |
|
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 |
|
A VNF's Heat Orchestration Template's Resource **MUST NOT** reference a HTTP-based resource definitions. |
VNF |
MUST NOT |
type |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
The VNF **MUST** support the storage of security audit logs for a configurable period of time. |
VNF |
MUST |
VNF Security Analytics Requirements |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
The VNF **MUST** log logoffs. |
VNF |
MUST |
VNF Security Analytics Requirements |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
The VNF or PNF **MUST** support APPC ``Audit`` command. |
VNF or PNF |
MUST |
Configuration Commands |
|
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 |
|
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 |
|
A VNF's Incremental Module **MAY** utilize nested heat. |
VNF |
MAY |
Nested Heat Orchestration Templates Overview |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
The VNF **MUST** include the field "success/failure" in the Security alarms (where applicable and technically feasible). |
VNF |
MUST |
VNF Security Analytics Requirements |
|
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 |
|
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 |
|
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 |
|
The VNF or PNF **MAY** implement the ``:with-defaults`` capability [RFC6243]. |
VNF or PNF |
MAY |
NETCONF Server Requirements |
|
The VNF **SHOULD** operate with anti-virus software which produces alarms every time a virus is detected. |
VNF |
SHOULD |
VNF Security Analytics Requirements |
|
The VNF **SHOULD** be decomposed into granular re-usable VNFCs. |
VNF |
SHOULD |
VNF Design |
|
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} |
|
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 |
|
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 |
|
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 |
|
The VNF **MUST** provide the capability to restrict read and write access to data handled by the VNF. |
VNF |
MUST |
VNF Data Protection Requirements |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
The VNF or PNF **MUST** implement the data model discovery and download as defined in [RFC6022]. |
VNF or PNF |
MUST |
NETCONF Server Requirements |
|
A VNF's Heat Orchestration template's Environment File's **MAY** contain the ``parameter_defaults:`` section. |
VNF |
MAY |
Environment File Format |
|
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 |
|
A VNF's Heat Orchestration Template **MUST** have no more than two levels of nesting. |
VNF |
MUST |
Nested Heat Template Requirements |
|
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 |
|
The VNF or PNF **MUST** support sub tree filtering. |
VNF or PNF |
MUST |
NETCONF Server Requirements |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
The VNF **MUST** support only encrypted access protocols, e.g., TLS, SSH, SFTP. |
VNF |
MUST |
VNF General Security Requirements |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
VNF's Heat Orchestration Template's Resource **MAY** declare the attribute ``update_policy:``. |
VNF |
MAY |
update_policy |
|
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 |
|
The VNF **MUST** automatically advertise newly scaled components so there is no manual intervention required. |
VNF |
MUST |
System Resource Optimization |
|
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 |
|
(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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
The VNF **SHOULD** support a software promotion methodology from dev/test -> pre-prod -> production in software, development & testing and operations. |
VNF |
SHOULD |
VNF Devops |
|
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 |
|
The VNF **SHOULD** maintain state in a geographically redundant datastore that may, in fact, be its own VNFC. |
VNF |
SHOULD |
VNF Design |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
The VNF or PNF **MUST** support APPC/SDN-C ``UpgradeBackOut`` command. |
VNF or PNF |
MUST |
Lifecycle Management Related Commands |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
The VNF or PNF **MUST** be installed with Chef-Client >= 12.0 and Chef push jobs client >= 2.0. |
VNF |
MUST |
Chef Client Requirements |
|
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 |
|
A VNF's Heat Orchestration template's Environment File's **MUST NOT** contain the ``resource_registry:`` section. |
VNF |
MUST NOT |
Environment File Format |
|
A VNF's Heat Orchestration Template's Resource **MAY** declare the attribute ``metadata``. |
VNF |
MAY |
metadata |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
A VNF's Heat Orchestration template's Environment File's ``parameters:`` section **MAY** (or **MAY NOT**) enumerate parameters. |
VNF |
MAY |
Environment File Format |
|
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 |
|
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 |
|
The PNF **MUST** support sending a pnfRegistration VES event. |
PNF |
MUST |
PNF Plug and Play |
|
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 |
|
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} |
|
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 |
|
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 |
|
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 |
|
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 |
|
The VNF **MUST** provide the capability of using X.509 certificates issued by an external Certificate Authority. |
VNF |
MUST |
VNF Data Protection Requirements |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
When the PNF receives a Service configuration from ONAP, the PNF **MUST** cease sending the pnfRegistration VES Event. |
PNF |
MUST |
PNF Plug and Play |
|
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 |
|
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 |
|
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 |
|
The VNF's Heat Orchestration Template's Resource ``OS::Nova::Server`` property ``image`` parameter **MUST** be declared as type: ``string``. |
VNF |
MUST |
Property: image |
|
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 |
|
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 |
|
A VNF's Heat Orchestration Template's Resource **MUST NOT** reference a HTTP-based Nested YAML file. |
VNF |
MUST NOT |
type |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
The VNF **MUST** use NIST and industry standard cryptographic algorithms and standard modes of operations when implementing cryptography. |
VNF |
MUST |
VNF Data Protection Requirements |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
The VNF **MUST NOT** require the use of a dynamic routing protocol unless necessary to meet functional requirements. |
VNF |
MUST NOT |
VNF Design |
|
The VNF **MUST** utilize FQDNs (and not IP address) for both Service Chaining and scaling. |
VNF |
MUST |
System Resource Optimization |
|
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 |
|
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 |
|
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 |
|
A VNF's Heat Orchestration Template's resource name (i.e., <resource ID>) **MUST** only contain alphanumeric characters and underscores ('_'). |
VNF |
MUST |
resource ID |
|
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 |
|
The VNF or PNF provider **MUST** provide playbooks to be loaded on the appropriate Ansible Server. |
VNF or PNF |
MUST |
Configuration Management via Ansible |
|
The VNF **MUST** be operable without the use of Network File System (NFS). |
VNF |
MUST |
VNF General Security Requirements |
|
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 |
|
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 |
|
A VNF's Heat Orchestration Template's Resource ``OS::ContrailV2::ServiceHealthCheck`` Resource ID **MUST** contain the ``{vm-type}``. |
VNF |
MUST |
OS::ContrailV2::ServiceHealthCheck |
|
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 |
|
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 |
|
The VNF or PNF **MUST** support a HTTPS connection to the DCAE VES Event Listener. |
VNF or PNF |
MUST |
PNF Plug and Play |
|
A VNF's Heat Orchestration Template's **MUST NOT** contain the Resource ``OS::Neutron::FloatingIPAssociation``. |
VNF |
MUST NOT |
VIP Assignment, ONAP External Networks |
|
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 |
|
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) |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
VNF's Heat Orchestration Template's Resource **MAY** declare the attribute ``external_id:``. |
VNF |
MAY |
external_id |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
The VNF **SHOULD** support container snapshots if not for rebuild and evacuate for rollback or back out mechanism. |
VNF |
SHOULD |
All Layer Redundancy |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
TThe VNF or PNF **MUST** support heartbeat via a <get> with null filter. |
VNF or PNF |
MUST |
NETCONF Server Requirements |
|
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 |
|
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 |
|
A VNF's Heat Orchestration Template's Resource ``OS::ContrailV2::InterfaceRouteTable`` Resource ID **MUST** contain the ``{network-role}``. |
VNF |
MUST |
OS::ContrailV2::InterfaceRouteTable |
|
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 |
|
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 |
|
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 |
|
A VNF's Incremental Module **MUST** have a corresponding Environment File |
VNF |
MUST |
ONAP VNF Modularity Overview |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
The VNF or PNF **MUST** support APPC ``StartApplication`` command. |
VNF or PNF |
MUST |
Lifecycle Management Related Commands |
|
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 |
|
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 |
|
The VNF or PNF **MUST** support APPC ``StopApplication`` command. |
VNF or PNF |
MUST |
Lifecycle Management Related Commands |
|
The VNF **MUST** Provide the capability to encrypt data in transit on a physical or virtual network. |
VNF |
MUST |
VNF Data Protection Requirements |
|
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 |
|
The VNF **MUST** provide the capability of allowing certificate renewal and revocation. |
VNF |
MUST |
VNF Cryptography Requirements |
|
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 |
|
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 |
|
The VNF or PNF **MAY** implement the ``:validate`` capability. |
VNF or PNF |
MAY |
NETCONF Server Requirements |
|
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 |
|
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 |
|
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 |
|
The VNF or PNF **SHOULD** support FileReady VES event for event-driven bulk transfer of monitoring data. |
VNF or PNF |
SHOULD |
Bulk Performance Measurement |
|
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 |
|
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} |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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” |
|
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 |
|
The VNF **MUST** log automated remote activities performed with elevated privileges. |
VNF |
MUST |
VNF Security Analytics Requirements |
|
The VNF **SHOULD** automatically enable/disable added/removed sub-components or component so there is no manual intervention required. |
VNF |
SHOULD |
System Resource Optimization |
|
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 |
|
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 |
|
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 |
|
The VNF **MUST** be able to authenticate and authorize all remote access. |
VNF |
MUST |
VNF General Security Requirements |
|
A VNF's Heat Orchestration template **MUST** have a corresponding environment file. |
VNF |
MUST |
Environment File Format |
|
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 |
|
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 |
|
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 |
|
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} |
|
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 |
|
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 |
|
A VNF's incremental module **MAY** be used for scale out only. |
VNF |
MAY |
ONAP VNF Modularity Overview |
|
A VNF **SHOULD** create the ONAP internal network in the VNF's Heat Orchestration Template's Base Module. |
VNF |
SHOULD |
Internal Networks |
|
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 |
|
A VNF **MAY** contain zero, one or more than one ONAP internal network. |
VNF |
MAY |
Internal Networks |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
The VNF or PNF **MUST** include a NETCONF server enabling runtime configuration and lifecycle management capabilities. |
VNF or PNF |
MUST |
Configuration Management |
|
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 |
|
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 |
|
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: |
|
A VNF's Heat Orchestration Template's OS::Nova::Server Resource **SHOULD** contain the metadata map value parameter 'environment_context'. |
VNF |
SHOULD |
environment_context |
|
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 |
|
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 |
|
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 |
|
The VNF **MUST** log the field "Login ID" in the security audit logs. |
VNF |
MUST |
VNF Security Analytics Requirements |
|
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 |
|
The VNF **MUST NOT** require Hypervisor-level customization from the cloud provider. |
VNF |
MUST NOT |
VNF Devops |
|
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 |
|
The VNF or PNF **MUST** implement the protocol operation: ``close-session()`` - Gracefully close the current session. |
VNF or PNF |
MUST |
NETCONF Server Requirements |
|
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 |
|
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 |
|
A VNF's Heat Orchestration Template's ``resources:`` section **MUST** contain the declaration of at least one resource. |
VNF |
MUST |
resources |
|
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 |
|
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 |
|
A VNF Heat Orchestration Template parameter declaration **MUST NOT** contain the ``default`` attribute. |
VNF |
MUST NOT |
default |
|
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 |
|
A VNF's Heat Orchestration Template's Resource ``OS::Cinder::Volume`` **MAY** be defined in an Incremental Module. |
VNF |
MAY |
ONAP VNF Modularity Overview |
|
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 |
|
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 |
|
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 |
|
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 |
|
A VNF's incremental module **MAY** be used for both deployment and scale out. |
VNF |
MAY |
ONAP VNF Modularity Overview |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
A VNF's Heat Orchestration Template **MUST** be compliant with the OpenStack Template Guide. |
VNF |
MUST |
ONAP Heat Orchestration Template Format |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
The VNF **SHOULD** provide the capability to integrate with an external encryption service. |
VNF |
SHOULD |
VNF Cryptography Requirements |
|
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 |
|
The VNF or PNF **MUST** support APPC/SDN-C ``ConfigScaleOut`` command. |
VNF or PNF |
MUST |
Configuration Commands |
|
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 |
|
The VNF **MUST** log connections to the network listeners of the resource. |
VNF |
MUST |
VNF Security Analytics Requirements |
|
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 |
|
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 |
|
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 |
|
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 |
|
A VNF's Heat Orchestration Template **MUST** be defined using valid YAML. |
VNF |
MUST |
YAML Format |
|
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 |
|
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 |
|
The VNF **MUST** support digital certificates that comply with X.509 standards. |
VNF |
MUST |
VNF Data Protection Requirements |
|
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 |
|
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 |
|
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 |
|
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 |
|
The VNF or PNF **MUST** implement the protocol operation: ``unlock(target)`` - Unlock the configuration data store target. |
VNF or PNF |
MUST |
NETCONF Server Requirements |
|
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 |
|
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} |
|
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 |
|
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 |
|
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 |
|
The VNF or PNF **MUST** support APPC/SDN-C ``UpgradeBackup`` command. |
VNF or PNF |
MUST |
Lifecycle Management Related Commands |
|
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 |
|
The VNF **MUST** log the field "date/time" in the security audit logs. |
VNF |
MUST |
VNF Security Analytics Requirements |
|
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 |
|
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 |
|
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: |
|
The PNF **MUST** send the pnfRegistration VES event periodically. |
PNF |
MUST |
PNF Plug and Play |
|
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 |
|
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 |
|
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 |
|
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} |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
The VNF **MUST** NOT terminate stable sessions if a VNFC instance fails. |
VNF |
MUST |
VNF Design |
|
The VNF **MUST** include the field "Login ID" in the Security alarms (where applicable and technically feasible). |
VNF |
MUST |
VNF Security Analytics Requirements |
|
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 |
|
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 |
|
The VNF or PNF **SHOULD** support TLS as secure transport for the NETCONF protocol according to [RFC7589]. |
VNF or PNF |
SHOULD |
NETCONF Server Requirements |
|
An ONAP external network **MUST** have one subnet. An external network **MAY** have more than one subnet. |
VNF |
MUST |
External Networks |
|
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 |
|
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” |