Page Status: Status
| Table of Contents | ||
|---|---|---|
|
VNF Requirements Project Overview
The intent of the VNF Requirement and Guidelines project is to inform VNF providers of the standards, specifications, and guidlines to which they should adhere when targeting the ONAP platform. These requirements and guidelines will support the ONAP Architecture Principles, and ensure a consistent experience for VNF providers across the VNF lifecycle. See the VNF Requirements Charter for more information.
...
The VNF Requirements Project comprises of several different document repositories (i.e. sub-projects) that provide guidance to VNF Providers from various perspectives. The following table outlines the repository where the content is stored, the location of the latest published version of the content on the official ONAP documentation site, the description of the content. When contributing content, please familiarize yourself with the various projects and target the content to the appropriate repository.
Table 1: Repositories
| Repo | Description | Deliverable document Title(s) |
|---|---|---|
| /guidelines | This includes objectives and motivations for the VNF Requirements work as well as forward looking, narrative text for use in prototype RFP text. | |
| /requirements | This includes formalized, uniquely numbered requirements that outline the requirements and specifications to which a VNF provider should adhere. Requirements will strive to be discrete and testable where possible, and will follow the guidance of RFC 2119 of requirement key words (e.g. SHOULD, MAY, etc.) for all numbered requirements. | |
| /usecases | Documents VNF specific use cases in support of ONAP E2E use cases illustrating behavior, sequences of operation, variants, error conditions, etc. |
| Not every Use Case supported by ONAP will be documented in this section. Instead, key Use Cases that require specific coordination with the VNF can be added here to better describe the VNF's responsibilities as a participant in the Use Case. | ||
| /testcases | This expands the use case template structure to supply the additional fields necessary to describe a test scenario. There may be multiple test case descriptions associated with a single use case |
General Standards
The following standards apply to all sub-projects within the VNF Requirements Project.
- As VNF Requirements project is an ONAP project, all content must adhere to the general documentation standards defined in Creating Documentation section of the ONAP Developer Guide.
- All content must be written in reStructuredText (RST) with all warnings and errors resolved.
- Wherever possible, let RST handle numbering of content. This includes ordered lists, section numbers, footnotes, etc. This ensure content can be re-arranged easily with less likelihood of breaking numbering conventions.
Guideline Standards
TODOThe VNF and PNF Guidelines are the highest level guidance provided by the VNF Requirements project. This section is best suited to include content that may provide context or forward-looking statements instead of concrete, verifiable requirements to which a VNF Provider should adhere.This text is strictly narrative in format, and does not include enumerated requirement and associated metadata as is the case in the VNF and PNF Requirements section of the document.
If a substantial change is to be proposed in this area of the requirements, then it should be initiated as a proposal with a corresponding JIRA ticket. Refer to VNFRQTS How to Contribute for more details.
Requirement Standards
VNF Requirements are the foundation of the project and as such have the most stringent content standards. The requirements form the basis of the specifications that a VNF provider must adhere to in order to successfully onboard, deploy, and operate a VNF on ONAP. The goal of this section is to provide independent, enumerated, and generally verifiable requirements to which a VNF on the ONAP platform. When considering the content for your requirement in the first place (incomplete or out of place).
This project makes use of an Sphinx extension called sphinxcontrib-needs to enable a number of useful features both internal to the project and enable sharing of structured data/information between projects.
These objectives are as follows:
...
should adhere to be managed on ONAP and meet ONAP's architectural principles.
As these are requirements, they should follow general expectations for what constitutes a good requirement:
- Unambiguous - It should have a single, objective interpretation. It should avoid subjective terms that would be open for misinterpretation. It should also include sufficient text or references to ensure how it should comply with a directive where applicable.
- Concise - An individual requirement should be specific about a single aspect, and strive to be as short as possible without sacrificing clarity. In general, a requirement should strive to be a single sentence where possible.
- Verifiable - Compliance with the requirement should be possible with some form of test, inspection, or demonstration.
- Consistent - Requirements must not introduce conflicting or contradictory guidance
- Feasible - The requirement must be reasonably implementable by existing technology and practices. Forward looking guidance and aspirational goals are best suited for the Guidelines section of the document.
- Observable - The requirement should lend itself to externally, observable behavior where ever possible. Guidance on internal implementation of meeting specific non-functional requirements should likely be included in guidance or as supplementary text.
Requirements that meet these criteria will have a specific format within the requirements document which will consist of a requirement statement and the metadata.
Requirement Statement Standards
Here is an example requirement statement:
R-18725 - The VNF MUST handle the restart of a single VNFC instance without requiring all VNFC instances to be restarted.
Here are the additional standards the requirement must adhere to in the context of this project:
- The requirement must be uniquely numbered (ex R-XXXXX). Please refer to VNFRQTS How to Contribute for more information on how requirement numbers are assigned.
- The requirement must use RFC 2119 keywords (MUST | MUST NOT | SHOULD | SHOULD NOT | MAY), and these keywords must be in uppercase and in bold. In RST, bold is achieved by wrapping the text in double asterisks (ex: **MUST**)
- The requirement should generally start off with the subject of the requirement and refer to one of the following, and then further refine from there
VNF
PNF
- VNF or PNF
- VNF Provider
- PNF Provider
- VNF or PNF Provider
- VNF Heat Package
- VNF CSAR Package
- PNF CSAR Package
- VNF or PNF Package
- VNF Documentation Package
- PNF Documentation Package
- VNF or PNF Documentation Package
- Example: The VNF Heat Package's base module **MUST** contain...
- The requirement should apply only to a single aspect of its intended requirements target, and not combine multiple independent statements into a single requirement.
Requirement Metadata Standards
In addition to the statement itself, this project captures assorted metadata about the requirement about the requirement for a variety of purposes:
- Supporting use cases such as dependency tracking, searching, filtering, and reporting.
- Export Exporting requirements in a machine-readable format for use by other projects such as the VNF Validation Project.
- Generate Generating different formats and outputs without duplicating requirement content (ex: appendices, tables, CSV files, etc.)
- Provide Providing traceability within the document between requirements, test cases, and other items within the documents.
Approach
This project makes use of an Sphinx extension called sphinxcontrib-needs project to in support of these objectives. Requirements will still be maintained in the reStructuredText file, but they will be shifted to structured directives using formatted according to work with the sphinxcontrib-needs extension. This extension provides a way to meet each of the needs above.
Here is an example of a requirement after the conversion:that adheres to the standards.
You may use the VNFRQTS Requirement Generation Tool to generate properly RST formatted requirements with unique ID numbers.
Requirement Example
|
These requirement definitions can be processed by the sphinxcontrib-needs extension and used in a variety of ways.
- Summary tables can be created via a needtable directive which provides a number of capabilities such as:
- Export to a variety of formats such as CSV, Excel, and PDF
- Filtering
- Sorting
- All requirements can be exported as JSON file for consumption by other projects.
- By default metadata is hidden in the HTML document, but can easily be expanded to allow readers to learn more about the requirement.
...
The following table outlines the proposed standard metadata elements that will be associated with the requirements. This list may change over time.
Table 2: Requirement MetadataAnchor requirement_metadata requirement_metadata
Field Name | Required vs. Optional | Data Type | Valid Values/Format | Notes | ||||
|---|---|---|---|---|---|---|---|---|
| id | Required | String | R-##### | The unique requirement ID for this requirement. See VNFRQTS How to Contribute for more details. On a new requirement, this attribute can be left off and the tox -e docs or check.py script generate and ID and populate this field. | ||||
| target | Required | String | VNF VNF, VNFC, VNF PROVIDER, VNF HEAT ORCHESTRATION TEMPLATE, VNF PACKAGE, PNF, XNFPNF | The component to which the requirement applies. | ||||
| keyword | Required | String | MUST ,MUST NOT ,SHOULD ,SHOULD NOT ,MAY | The RFC 2119 keyword for the requirement | ||||
| introduced | Optional | String | lower case release name (ex: bejing, casablanca) | The release the requirement was initially introduced. New requirements should always have this. When adding a new requirement, this can be left off and the tox -e docs or check.py script will add this for you. | ||||
| updated | Optional | String | lower case release name | The release the requirement was last modified. Any updated requirements going forward should have this. | ||||
| impacts | Optional | List of String | Comma separated list of ONAP components (ex: so, sdc) | The various ONAP components that need to be aware of any changes to the requirement | ||||
| validation_mode | Optional | String | static, stand_alone, in_service | How the requirement is validated: static - validated by statically inspecting the VNF package data stand_alone - validated by running tests against the VNF itself in_service - validated in the context of a full or partial ONAP deployment | ||||
| validated_by | Optional | List of String | Comma separated list: vvp, vnfsdk, sdc | Projects that implement validations of this requirement. | test_case | Optional | RST Link | Link to source file that implement the test case |
| notes | Optional | String | Free form text | Short notes about the requirement |
ONAP/VNFRQTS VNF Requirements Discussion
Requirements should be single sentences using an RFC 2119 keyword { MUST | MUST NOT | SHOULD | SHOULD NOT | MAY }. The keyword should be bold.
The Subject of the Requirements sentence should be limited to { VNF | VNF Package | VNFC | VDU } – Does not match Table values
Requirements should be individually numbered. Format initially will be R-xxxxx
Draft example of the .rst format for requirements:
* R-xxxxx VNFs **MUST** meet their own resiliency goals and not rely on the Network Cloud....
Use Case Standards
The use case section of the document affords a way to provide a VNF Provider a VNF-centric view of certain use cases. It is not required that every use case supported by ONAP be documented in this section. Instead, key use cases that require discrete actions and coordination with the VNF can be described here to provide a clearer understanding of potentially multi-step complex interactions.
Formal requirements must not be defined in this section, but instead they should be defined in the appropriate requirements section of the document. Those requirements should detail out the any specific management, monitoring, or other capabilities the VNF must provide to support a given use case.
The use case section can be referenced by the requirements to provide additional context and better illustrate the interactions.
At this stage the format for use cases is not rigid, but is should comprise of the following elements:
- A sequence diagram that shows the API-level interactions between any users, ONAP components, and the VNF itself to effectively coordinate the use case. Multiple diagrams can be provided if appropriate.
- NOTE: sequence diagrams can be provided as images or leverage the Sphinx seqdiag capabilities
- A description of the workflow
- An enumerated list of VNF impacts that detail out the specific concerns for the VNF provider and provide references to key requirements
Test Case Standards
TODO