...
Follow principles/patterns of RESTCONF RFC-8040 https://datatracker.ietf.org/doc/html/rfc8040
Follow principles/patterns of yang-patch RFC-8072 https://datatracker.ietf.org/doc/html/rfc8040
Follow principles/patterns of RESTCONF NMDA RFC-8527 https://datatracker.ietf.org/doc/html/rfc8527
...
Issues &
...
Decisions
...
Issues | Notes |
---|
...
Decisions |
---|
1 |
...
Currently, we wrap the response of GET operations using the data node wrapper.
...
we should mainly support yang-data/json
controlled by "accept-header"
...
e.g. http://localhost:8080/ncmp/v1/data
http://localhost:8080/ncmp/v1/operation
...
This only applies to pass-through
yes, we will distinguish between data and operation
...
Parent data resource identifier can handle any path using the same query parameter
- cpsPath
- RESTConf Path (pass-through)
- Proprietary Path (pass-through)
...
Yml should include return types and examples of the payload
...
Legacy and new API documentation needs to include output examples.
Task created, see
Jira | ||||||
---|---|---|---|---|---|---|
|
...
We will use a dash for param names e.g. cmHandle (although it has since been agreed we use 'ch' in this particular case)
See no.3 https://restfulapi.net/resource-naming/
KPI for De-registration of 100 CM-handles | This was mentioned. Was this ever agreed, is this a valid use case that needs to be covered together with the Registration ? | Not priority for now, but acceptable if we match the registration req. | |
2 | DMI delay | Could we get some feedback on DMI-delays for other use cases as not mentioned in FS document | Awaiting for ETH feedback AP On Kolawole Adebisi-Adeolokun and Csaba Kocsis Provided |
3 | Number of instances In some cases, ETH have used 2 instances, can we verify the number of instances for each use case. Some of the req were defined per instance and resources used : Identify which of these ? | Agreed to; CPS use 1 instance currently, but should focus on aligning performance with 2 instances for all use case | |
4 | Input Load Distribution the CM-handle search and ID search | Currently has 5 parallel request between them distributed at 2.5 each. This fractional distribution isn't feasible for parallel processing; the load should be allocated as whole numbers. Load needs to be distributed at. Would it be acceptable to adjust this distribution to either 2 or 3 parallel requests each (and vice versa ) without any negative repercussions? Agreed to do 6 parallel request combined total and divide the load to 3 parallel request each | |
5 | Regarding CM-handle search and ID search | FS only identified Module performance, are there any testing done towards a combined search of properties and modules in a single query Confirmed no other testing was previously done on this..... CPS have the capabilities to do mixed testing. ETH tbc on if they want to consider this ( Csaba Kocsis ) |
Requirements
Note |
---|
Please note this section was added long after the implementation and focuses on characteristic and enhancements after this study only. |
Excerpt Include | ||||
---|---|---|---|---|
|
Characteristics
It is proposed that reported characteristics will be used as a baseline for NCMP when agreed and sign-off.
Operation | Concurrent requests/parallel | DMI Delay | Response size | Performance Requirement (Blue Stone tablet KPI) | Notes | Sign-Off | |
---|---|---|---|---|---|---|---|
1 | Registration of 20,000 CM-handles (in batches of 100) | 1 (requests are sequential) | 100 ms to get module references | N/A |
|
| |
2 | De-registration of 100 CM-handles | 1 (requests are sequential) | No Module delays | N/A |
| De-registration is currently not mentioned in Stone Tablet KPI or FS, however we have agreed to match the performance of registration for now as de-reg is also not a priority at this point in time | |
3 | CM-handle ID search with Module filter | 3 | N/A | 20,000 CM Handles i.e. 100*20.000 = 2MB | As provided byCsaba Kocsis 0.625 seconds/Operation | FS stated 5 parallel request for both ID search and search. CPS to run with 3 parallel each for both ID search and Search meaning a combine total of 6 parallel request | |
4 | CM-handle search with Module filter | 3 Run in parallel with #3 | N/A | 20,000 CM Handles i.e. 500*20.000 = 10MB | As provided by Csaba Kocsis 13 seconds/Operation | FS stated 5 parallel request for both ID search and search. CPS to test with 3 parallel each for both ID search and Search meaning a combine total of 6 parallel request | |
5 | Synchronous single CM-handle pass-through read | 10 | 300 ms Csaba Kocsis | 5 KB | 25 (parallel) request/sec | Read are done in parallel with Write | |
6 | Synchronous single CM-handle pass-through write (CUD) | 10 | 670 msCsaba Kocsis | 5 KB | 13 (parallel) request/sec | No response is expected | |
7 | Batch/Bulk Read | 1 read request with 200 cmHandles per second | 150 cmhandles/sec | The batch data operation is asynchronous. NCMP returns the response on the ncmp-async-m2m kafka topic. |
Notes
- This is for mixed TCs
- Single KPIs will be monitored in NCMP owned pipeline with our performance every day(2 hrs interval) - Performance
Synchronous single cm-handle pass-through (read) requests
Parameter | Expectation | Notes | Sign-Off | ||
---|---|---|---|---|---|
Average Response Size | 5KB | Shall not exceed 5KB | |||
Concurrent request | 12 clients requests toward 1 NCMP simultaneously DMI also support 12 simultaneous requests | 40ms of overhead on top of DMI latency for each requests, at most for NCMP request. This shall remain within 40ms for 12 parallel requests. Given the DMI delay below; this means up to 240 request per second | |||
DMI Delay | 10ms | This is not in control of CPS. Assume DMI is 1.25 seconds average DMI response time for high latency, low latency =10 ms, this should also work for DMI Plugin. I.e 40ms ontop of the DMI. 1.25seconds+40ms= 1.29seconds | |||
Test Environment |
| ||||
Security | Disable Basic Authentication in Springboot | If configurable from application yaml, then it’s acceptable. |
Open Issues & Decisions
Expand | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
RESTCONF/NETCONF relationship
NCMP URI
NCMP URI format to follow below pattern
<OP>/ncmp/<v{vNumber}>/ch/<cmHandle>/<data|operations|{ncmpAction}>/ds/{datastore}?[rp:]{resourcePath}&{options}
Below table shows the proposed interface, actual implementation might deviate from this but can be accessed from
- Gerrit Source
- Read-the-docs: https://docs.onap.org/projects/onap-cps/en/latest/design.html#offered-apis
URI | Mandatory or Optional | |
---|---|---|
<OP> | the HTTP method | Mandatory |
ncmp / | the ncmp root resource | Mandatory |
<v{vNumber}> | version of the ncmp interface <path> is the target resource URI <query> is the query parameter list | Mandatory |
ch/<cmHandle> | unique (string) identifier of a yang tree instance. | Mandatory |
<data|operations|{ncmpAction}> | request category - yang data, rpc operation or a (non-modelled) ncmp api action. this could be data, operations or ncmpAction (e.g. 'sync-data') | Mandatory |
ds/{datastore} | Mandatory | |
<resourceIdentifier> | the path expression identifying the resource that is being accessed by the operation. If this field is not present, then the target resource is the API itself. | Optional |
<options> | Parameters with the familiar form of "name=value" pairs. Query parameters are optional to implement by the server and optional to use by the client. Each optional query parameter is identified by a URI | Optional DMI should be able to support (/pass through) ANY parameter associated with the RESTCONF message; see Section 3.4 of [RFC3986]. |
Datastores
New datastores are defined for ncmp to access the CPS 'running' or 'operational' datastore.
Alternatively, the request can be sent directly to the 'device' itself (bypassing CPS datastores) using one of the 'passthrough-*' datastores options as below
The new ncmp datastores required for ONAP Release I include :
Excerpt Include | ||||
---|---|---|---|---|
|
Excerpt | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Datastore, Paths and Format Combinations for Read Operations
|
...
- Add child and its descendants (supported in cps core)
- Add all list elements (supported in cps core)
- Replace child and its descendants (supported in cps core)
- Replace all list elements (pending in cps core)
- Update single leaf (new)
- Add list entry (new)
...
Priority is pass-through only so it depends on the RETSConf protocol that is supported.
In Jakarta or if required by other projects more fine-grained 'operation' datastore update options can be implemented
...
Proposed syntax by CPS team
<OP>/ncmp/<v{vNumber}>/ch/<cmHandle>/<data|operations|{ncmp-operation}>/ds/{datastore}/[rp:]{resourcePath}?{query}
...
HTTP Header Limitations
Some servers put size limitations on HTTP headers, making them unsuitable for storing cmHandle information.
LIMITATION NOTE: server implementations put size limits on the headers meaning header contents should be designed carefully :
Apache - 8K
Nginx - 4K-8K
IIS - 8K-16K
Tomcat - 8K – 48K
...
The plugin will not do transformation or validation of paths in the case of pass-through:running
...
- not supported (ignored, not rejects, nice for future compatibility)
- treat as 'no descendants' (low cost)
- use to filter cached data
...
&Fields parameter will be ignored for 'cached' data in Istanbul timeframe
long term expectation is to have support following RESTConf/ODL behavior as much as possible
...
- not supported (ignored, not rejects, nice for future compatibility)
- treat as 'no descendants' (low cost)
- translate (insert module names) and forward
...
A spike
Jira | ||||||
---|---|---|---|---|---|---|
|
...
RESTCONF/NETCONF relationship
NCMP URI
NCMP URI format to follow below pattern
<OP>/ncmp/<v{vNumber}>/ch/<cmHandle>/<data|operations|{ncmpAction}>/ds/{datastore}/[rp:]{resourcePath}?{query}
...
the set of parameters associated with the RESTCONF message; see Section 3.4 of [RFC3986]. RESTCONF parameters have the familiar form of "name=value" pairs. Most query parameters are optional to implement by the server and optional to use by the client. Each optional query parameter is identified by a URI
...
Datastores
New datastores are defined for ncmp to access the CPS 'running' or 'operational' datastore.
Alternatively, the request can be sent directly to the 'device' itself (bypassing CPS datastores) using one of the 'passthrough-*' datastores options as below
The new ncmp datastores required for ONAP Release I include :
...
Excerpt | |||||||||
---|---|---|---|---|---|---|---|---|---|
Datastore, Paths and Format Combinations for Read Operations | State | Input | Behavior | Data | Notes | ||||
# | Data-Sync | Datastore parameter | Expected resourcePath format | Accept-Header | Fields (filter) | Data Source | Included DataNodes | 1 | On | Not Specified | cpsPath | application/yang-data+json | N/A | Not supported | N/A | N/A | 2 | On | Not Specified | cpsPath | application/json | N/A | Not supported | N/A | N/A | 3 | Off | Not Specified | cpsPath | application/yang-data+json | N/A | Not supported | N/A | N/A |
4 | Off | Not Specified | cpsPath | N/A | N/A | Not supported | N/A | N/A | there are NO DataNode objects in CPS to output as JSON) |
5 | Off | Not Specified | other then cpsPath | N/A | N/A | Not supported | N/A | N/A | Not supported Since NCMP can only convert cpsPaths |
6 | On | Off | ncmp/passthrough-operational | NCMP does not parse | NCMP does not parse | depends on DMI-Plugin (supported in ONAP) | Resolve DMI plugin Forward request to plugin Output received response | DMI-Plugin | config + non-config | The DMI plugin may error if the RP or accept header are not supported. The DMI plugin may forward the request without processing too. | 7 | On | Off | ncmp/passthrough-running | NCMP does not parse | NCMP does not parse | depends on DMI-Plugin (supported in ONAP) | Resolve DMI plugin Forward request to plugin Output received response | DMI-Plugin | config-only | 8 | On | ncmp/operational | cpsPath | application/yang-data+json | Not supported in Istanbul releases | Read from cache output: application/yang-data+json | CPS-Core | config + non-config | NCMP/CPS-Core needs to remove DataNode wrapping9 | On | ncmp/operational | cpsPath | application/json | Not supported in Istanbul releases | Read from cache output: application/json | CPS-Core | config + non-config | 10 | Off | ncmp/operational | cpsPath | application/yang-data+json | Resolve DMI plugin Convert cpsPath to RESTConfPath* Forward request to plugin | Read from DMI plugin Output application/yang-data+json | DMI-Plugin | config + | 11 | On | Off | ncmp/running | cpsPath | application/yang-data+json | to be determined in spike, see issue #28 | Resolve DMI plugin Convert cpsPath to RESTConfPath* Forward request to plugin | Read from DMI plugin Output application/yang-data+json | DMI-Plugin | config-only |
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
{ncmpRoot}/ncmp/v1/ch/<cmHandle>/data/ds/<datastore>/{dataResourceIdentifier}?fields={fieldsExpression}
URI :{ncmpRoot}/ncmp/v1/ch/node123/data/ds/ncmp-datastores:operational/TopElement[@id=1]/SomeFunction[@id=1]?fields=cell-model:Cell/attributes(attr1;attr2)
Header :
Accept : application/yang-data+json
Response :
200 OK
{
"function-model:SomeFunction": [
{
"id": "1",
"cell-model:Cell": [
{
"id": "Cell-001",
"attributes": {
"attr1": "value1",
"attr2": "value2"
}
},
{
"id": "Cell-002",
"attributes": {
"attr3": "value3",
"attr4": "value4"
}
}
]
}
]
}
|
Works Items for above.
Datastore, Paths and Format Combinations for Write Operations
- Write operations are only supported on the ncmp-datastores:running and ncmp-datastores:passthrough-running datastores
- The Data Target for all write operation is DMI-Plugin
- Write operations are only supported for config=true data
- Fields and similar parameters are not supported for write operations
Expected resourcePath
format
NCMP does not parse
Resolve DMI plugin
Forward request to plugin
Output received response (success or failure)The DMI plugin may error if the RP or content type are not supported.
The DMI plugin may forward the request without processing too.NCMP does not parse
) | Resolve DMI plugin Forward request to plugin Output received response |
DMI-Plugin | config + non-config | The DMI plugin may error if the RP or |
accept header are not supported. The DMI plugin may forward the request without processing too. |
7 | On | Off |
ncmp/passthrough-running | NCMP does not parse | NCMP does not parse |
depends on DMI-Plugin (supported in ONAP) | Resolve DMI plugin Forward request to plugin Output received response |
The DMI plugin may error if the RP or content type are not supported.
The DMI plugin may forward the request without processing too.DMI-Plugin | config-only | ||||||||
8 | On | ncmp/operational | cpsPath | application/yang-data+json |
| Read from cache output: application/yang-data+json | CPS-Core | config + non-config | NCMP/CPS-Core needs to remove DataNode wrapping |
9 | On | ncmp/operational | cpsPath | application/json |
| Read from cache output: application/json | CPS-Core | config + non-config | Output will use DataNode wrapping (as is from CPS-Core) For forwarding (cached config off) dmi-reposne need to be wrapped explicitly in 'DataNode' |
10 | Off | ncmp/operational |
NCMP does not parse
Resolve DMI plugin
Forward request to plugin
Output received response (success or failure)The DMI plugin may error if the RP or content type are not supported.
The DMI plugin may forward the request without processing too.Resolve DMI plugin
Convert cpsPath to RESTConfPath
Forward request to plugin
Output received response (success or failure)
cpsPath | application/yang-data+json | to be determined in spike, see issue #28 | Resolve DMI plugin Convert cpsPath to RESTConfPath* Forward request to plugin |
Output received response (success or failure)
7| Read from DMI plugin Output application/yang-data+json | DMI-Plugin | config + | |
11 | On | Off |
ncmp/running | cpsPath |
application/yang-data+json | to be determined in spike, see issue #28 | Resolve DMI plugin Convert cpsPath to RESTConfPath* Forward request to plugin | Read from DMI plugin |
Output received response (success or failure)
application/yang-data+json
(*plain patch)
Resolve DMI plugin
Convert cpsPath to RESTConfPath
Forward request to plugin
Output received response (success or failure)
Resolve DMI plugin
Convert cpsPath to RESTConfPath
Forward request to plugin
Output received response (success or failure)
Write Example
title | Write Example |
---|
Sync & Model API
*Note Convert cpsPath to RESTConfPath wil only support 'absolute' cpsPath for conversion no query-type paths Read Example
Works Items for above.
Datastore, Paths and Format Combinations for Write Operations
Write Example
|
Sync & Model API
Expand | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Expand | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Req/usecase | REST MethodURI Request/Response Example | 1 | Get all cmhandles that support a given module
Scenario : Get the all cmhandles that support a given module Request Body Header :Accept: application/json Response: { cmHandles : [ "ew534fe", "23ft4", "434fsdf", ... ] }
Response:
"ietf-yang-library:modules-set" : [ # from RFC 8525 {
"namespace" : "urn:3gpp:sa5:xxx-module", "submodule" : [ { ... } ] } ] }, {
|
NCMP / DMI Overview
Expand | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
...