CPS-391
-
Getting issue details...
STATUS
Guiding Principles
- NCMP REST Interface will follow/be inspired by RESTConf interface for easy acceptance of and transition to this interface
- Will follow ONAP's RESTful API Design Specification
- The interface will include the concept of data-stores inspired by Network Management Datastore Architecture (NMDA) and as used in RESTConf
- The application should be able to easily switch between 'pass-through' and other datastores (also identical rest endpoint and responses)
References
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
Open Issues & Decisions
Click here to expand...
| Description | Notes | Decision |
---|
1 | Priority of async calls |
| In Istanbul, async calls are required only in pass-through cases. NCMP does not have to handle these requests |
2 | Will we use the data node wrapper on GET rest operations? | Currently, we wrap the response of GET operations using the data node wrapper. | we should mainly support yang-data/json controlled by "accept-header" |
3 | In the URI will we distinguish between data and operations (RFC calls) as part of the path? | | This only applies to pass-through yes, we will distinguish between data and operation |
4 | Which query parameters will NCMP support? |
| Parent data resource identifier can handle any path using the same query parameter - cpsPath
- RESTConf Path (pass-through)
- Proprietary Path (pass-through)
|
5 | Yml should include return types and examples of the payload |
| Legacy and new API documentation needs to include output examples. Task created, see
CPS-401
-
Getting issue details...
STATUS
|
6 | camel case or dash in URI |
| We will use a dash for param names e.g. cm-handle (although it has since been agreed we use 'ch' in this particular case) See no.3 https://restfulapi.net/resource-naming/ |
7 | Insert /resource-path in front of the resource path to prevent ambiguous paths | <OP>/ncmp/<v{v-number}>/ch/<cm-handle>/<data|operations|{ncmp-operation}>/ds/{datastore}/[rp:]{resource-path}?{query} | Optionally insert the resource path ('rp:') if it clashes with the current |
8 | Granularity of update scenarios (and priority) | - 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 |
9 | Fallback option for datastore in release I |
| No, explicit datastore options will be used in Istanbul |
10 | fields is a rest conf option, investigate is it fully supported by onap |
| Supported in pass-through for ONAP DMI plugin but depending on the support by the actual target. The intention is to increase support 'fields' in future requirements following RFC-8040 for operational datastore etc. |
11 | Agree on URI syntax | Proposed syntax by CPS team <OP>/ncmp/<v{v-number}>/ch/<cm-handle>/<data|operations|{ncmp-operation}>/ds/{datastore}/[rp:]{resource-path}?{query} | review completed and proposed URI agreed |
12 | Will we combine query capabilities with update capabilities? |
| We have decided not to combine query capabilities with update capabilities |
13 | Description of header limitations |
| 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 |
14 | Will NCMP support paths for pass-through:running |
| The plugin will not do transformation or validation of paths in the case of pass-through:running |
15 | Specification of path per cm handle |
| DMI Plugin can take cps paths or restconf paths and it needs to specify that per cm handle when cm handle is created |
16 | What is the default path for NCMP |
| In NCMP default will always be cps path and depending on the adapter we can change it as needed per cm handle |
17 | Fields parameter for ncmp/operational? |
| The fields parameter is ignored in ncmp/operational (in Istanbul release) |
18 | Is specifying the datastore mandatory? |
| Datastore is mandatory in Istanbul release |
19 | Register a DMI plugin with NCMP |
| DMI plugin is a part of cm handle registration. The rest endpoint on NCMP can be multiple calls |
20 | Retrieve list of modules (names) for a cmHandle |
| Retrieve a list of module names for cm handle - this will be used by ncmp to get the models. - assuming ncmp model discovery is complete and it is stored in cps core, this will come from cached information |
21 | Where will sync be implemented? |
| Implement sync in the dmi plugin and then have ncmp be able to pass on the request. This is not a bulk operation |
22 | Config-true only support (filter out config-false data) |
| Use datastore 'running' to select this but filtering not supported in I for cached data |
23 | Enable NCMP to convert cpsPath to mutliple options(RESTConf, netConf, leave as cpsPath) | When other DMI-Plugins are realized they might need a different conversion then the default from cspPath to RESTConf. This could be configured by using a known property for each cm-handle | Not required in Istanbul. But DB model can easily be updated to cater for this when needed |
24 | Datastore conversion in NCMP or DMI-Plugin | DMI-Plugin will know best how to convert. This will also reduce future impacts on NCMP for new options. | NCMP will do now conversion of datastore names |
25 | What datastore/s (name/s) is/are supported by NCMP to referred to the cached data. 'Operational' or 'running' | 'operational' would imply RO and config=false data is included. 'To also support 'running' using the same data a filter would have to be applied | see supported datastore in I : 103416823 |
26 | Consider fallback option when user specifies ncmp/operational but data is NOT synced |
| NCMP will forward requests for un-synced cmHandles to the DMI Plugin (Including required transformation of resource path etc.) |
27 | Support for &fields parameter when using cached data | - 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 |
28 | Support for &fields parameter when forwarding to plugin for non-synced cmHandles | - not supported (ignored, not rejects, nice for future compatibility)
- treat as 'no descendants' (low cost)
- translate (insert module names) and forward
| A spike
CPS-455
-
Getting issue details...
STATUS
will be executed to determine the feasibility of option 3 and decide if it can make Istanbul scope |
29 | Response for Data Sync request (in Istanbul timeframe) | The action is blocking synchronous through whole stack (in I) so response could include the data returned by the node. However this seem incorrect for an 'action' so maybe the response should just be just an acknowledgment it is 'done' | No need to return data, just HTTP Code 200 (OK) will suffice |
RESTCONF/NETCONF relationship
![](/download/attachments/103416822/image2021-5-10_16-28-3.png?version=1&modificationDate=1620660486000&api=v2)
NCMP URI
NCMP URI format to follow below pattern
<OP>/ncmp/<v{v-number}>/ch/<cm-handle>/<data|operations|{ncmp-action}>/ds/{datastore}/[rp:]{resource-path}?{query}
URI |
| Mandatory or Optional |
---|
<OP> | the HTTP method | Mandatory |
ncmp / | the ncmp root resource | Mandatory |
<v{v-number}> | version of the ncmp interface <path> is the target resource URI <query> is the query parameter list | Mandatory |
ch/<cm-handle> | unique (string) identifier of a yang tree instance. | Optional |
<data|operations|{ncmp-action}> | request category - yang data, rpc operation or a (non-modelled) ncmp api action. this could be data, operations or ncmp-action (e.g. 'sync-data') | Mandatory |
ds/{datastore} | optional datastore | Optional |
<resource-path> | 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 |
<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 | Optional |
Datastores
New datastores are defined for ncmp to access the CPS 'intent' 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 :
TBD USE EXCERPT FROM CPS-333
1 | ncmp-datastores:operational (RO / config=true/false) | Read from the CPS "operational" store (cached) | config true and config false data |
2 | ncmp-datastores:passthrough-running (RW / config=true) | Read/Write to/from the live devices ietf-datastores:running (no local ncmp validation) | config-true data only |
3 | ncmp-datastores:passthrough-operational (RO / config=true/false) |
| config true and config false data |
4 | ncmp-datastores:running (RW / config=true) |
|
|
Future datastores to be supported by NCMP might include :
1 | ncmp-datastores:passthrough-intented (RO) | Read from the live devices ietf-datastores:intended | ? |
| State | Input | Behavior | Data | Notes |
---|
# | Data-Sync | Datastore parameter | Expected Resource-Path format | Accept-Header | Fields (filter) | Data Source | Included DataNodes (config) |
---|
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 wrapping
|
9 | 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 | 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 + non-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 |
|
Read & Write API Example
Click here to expand...
Scenario | Sample |
---|
Read all NRCellDU MOs with attributes userLabel and id under the _3gpp-nr-nrm-gnbdufunction:GNBDUFunction MO
{ncmp-root}/ncmp/v1/ch/<cm-handle>/{data-resource-identifier}?fields={fields-expression} | Method : GET URI :{ncmp-root}/ncmp/v1/ch/3445fff/data/ManagedElement[@id=Kista-001]/GNBCUCPFunction[@id=1]?fields=_3gpp-nr-nrm-nrcelldu:NRCellDU/attributes(administrativeState;operationalState) Header : Accept : application/yang-data+json Response : HTTP/1.1 200 OK Date: Thu, 26 Jan 2017 20:56:30 GMT Server: example-server Content-Type: application/yang-data+json { "_3gpp-nr-nrm-gnbdufunction:GNBDUFunction" : [ { "_3gpp-nr-nrm-nrcelldu:NRCellDU" : [ { "top3gpp:id" : "NR-Cell-001" "attributes" : { "administrativeState " : "LOCKED", "operationalState" : "disabled" } }, { "top3gpp:id" : "NR-Cell-002" "attributes" : { "administrativeState " : "LOCKED", "operationalState" : "disabled" } }, { "top3gpp:id" : "NR-Cell-003" "attributes" : { "administrativeState " : "LOCKED", "operationalState" : "disabled" } }, { "top3gpp:id" : "NR-Cell-004" "attributes" : { "administrativeState " : "LOCKED", "operationalState" : "disabled" } }, { "top3gpp:id" : "NR-Cell-005" "attributes" : { "administrativeState " : "LOCKED", "operationalState" : "disabled" } } ] } ] }
|
Create a data resource for the given cm handle {ncmp-root}/ncmp/v1/ch/<cm-handle>/data/{parent-data-resource-identifier} | Method : POST URI : {ncmp-root}/ncmp/v1/ch/sample-cm-handle/data/sample-parent-data-resource-identifier Header : Content-Type: application/yang-data+json Body : { "sample-parent-data-resource-identifier:parent-data-resource-identifier" :[ { "id" : 4 "cld" : 5 "attributes" : { "userLabel" : "SectorCar-4", "txDirection" : "DL_AND_UL", "configuredMaxTxPower" : "90", "arfcnDL" : "9999999", "arfcnUL" : "888888", "bSChannelBwDL" : "90", "bSChannelBwUL" : "80" } }] } |
Works Items for above.
# | Description | Component | Enables |
---|
1 | Forward request from NCMP to CPS-Core | NCMP | 8,9 |
2 | Forward request from NCMP to DMI-Plugin | NCMP | 6,7 |
3 | Convert json (dataNode) to yang-data+json | CPS-Core/NCMP | 8 |
4 | Convert cpsPath to RESTConf Path | NCMP | 10,11 |
5 | Enhance &fields parameter where needed | NCMP | 10,11+fields option |
6 | NOT Supported | N/A | 1,2,3,4,5 |
- 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
| State | Input | Behavior | Notes |
---|
# | Data-Sync | Operation | Datastore parameter | Expected Resource-Path format | Content-Type |
---|
1 | On | Off | Create | ncmp/passthrough-running | NCMP does not parse | NCMP does not parse (needs to be valid JSON) | 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. |
2 | On | Off | Update | ncmp/passthrough-running | NCMP does not parse | NCMP does not parse (needs to be valid JSON) | 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. |
3 | On | Off | Delete | ncmp/passthrough-running | NCMP does not parse | N/A | 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. |
4 | On | Off | Patch | ncmp/passthrough-running | NCMP does not parse | NCMP does not parse (needs to be valid JSON) | 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. |
5 | On | Off | Create | ncmp/running | cpsPath | application/yang-data+json | Resolve DMI plugin Convert cpsPath to RESTConfPath Forward request to plugin Output received response (success or failure) |
|
6 | On | Off | Update | ncmp/running | cpsPath | application/yang-data+json | Resolve DMI plugin Convert cpsPath to RESTConfPath Forward request to plugin Output received response (success or failure) |
|
7 | On | Off | Delete | ncmp/running | cpsPath | N/A | Resolve DMI plugin Convert cpsPath to RESTConfPath Forward request to plugin Output received response (success or failure) |
|
8 | On | Off | Patch | ncmp/running | cpsPath | application/yang-data+json (*plain patch) | Resolve DMI plugin Convert cpsPath to RESTConfPath Forward request to plugin Output received response (success or failure) |
|
9 | On | Off | Patch | ncmp/running | cpsPath | application/yang-patch+json | Resolve DMI plugin Convert cpsPath to RESTConfPath Forward request to plugin Output received response (success or failure) |
|
Sync & ModelAPI
Click here to expand...
| Req/usecase | REST Method | URI / Payload | Request/Response Example |
---|
1 | Get all cmhandles that support a given module | GET | {ncmp-root}/ncmp/v1/ch/module={module-name} Content: application/json | Scenario : Get the all cmhandles that support a given module Method : GET URI : {ncmp-root}/ncmp/v1/ch/datamodule=_3gpp-nr-nrm-gnbdufunction Header : Accept: application/json Response: { cm-handles : [ "ew534fe", "23ft4", "434fsdf", ... ] } |
2 | Request (trigger) Data Sync | POST | {ncmp-root}/ncmp/v1/ch/<ch-handle>/sync-data | Scenario : Client requests to sync a node URI : {ncmp-root}/ncmp/v1/ch/node123/sync-data Response : HTTP-Status code (only, no body) |
3 | Get model info for CMHandle | GET | {ncmp-root}/ncmp/v1/ch/{cm-handle}/modules | Scenario : Get the model data for CMHandle Method : GET URI :{ncmp-root}/ncmp/v1/ch/2334dedf/modules Header : Accept: application/yang-data+json Response: { "ietf-yang-library:modules-set" : [ # from RFC 8525 { "name" : "5479120c17a619545ea6aff7aa19838b036ebbd7", "module" : [ { "name" : "_3gpp-nr-nrm-nrsectorcarrier", "revision" : "2020-12-09", "namespace" : "urn:3gpp:sa5:_3gpp-nr-nrmnrnetwork-nrsectorcarrier", "location" : "http://emsadapter.com/modules/_3gppnr-nrm-nrsectorcarrier", "submodule" : [ { "name" : "xxxx-module", "revision" : "2020-12-17", "namespace" : "urn:3gpp:sa5:xxx-module", "submodule" : [ { ... } ] } ] }, { "name" : "ietf-yang-library", "revision" : "2016-06-21", "namespace" : "urn:ietf:params:xml:ns:yang:ietfyang-library" } ] } |
NCMP / DMI Overview
Click here to expand...
eyJleHRTcnZJbnRlZ1R5cGUiOiIiLCJnQ2xpZW50SWQiOiIiLCJjcmVhdG9yTmFtZSI6Ik5pYW1oIENvcmUiLCJvdXRwdXRUeXBlIjoiYmxvY2siLCJsYXN0TW9kaWZpZXJOYW1lIjoiTmlhbWggQ29yZSIsImxhbmd1YWdlIjoiZW4iLCJkaWFncmFtRGlzcGxheU5hbWUiOiIiLCJzRmlsZUlkIjoiIiwiYXR0SWQiOiIxMDM0MTcyNjgiLCJkaWFncmFtTmFtZSI6Ik5DTVAgTm9ydGhib3VuZCBSRVNUIEFQSSIsImFzcGVjdCI6IiIsImxpbmtzIjoiYXV0byIsImNlb05hbWUiOiJDUFMtMzkxU3Bpa2U6IERlZmluZSBhbmQgQWdyZWUgTkNNUCBSRVNUIEludGVyZmFjZSIsInRic3R5bGUiOiJ0b3AiLCJjYW5Db21tZW50IjpmYWxzZSwiZGlhZ3JhbVVybCI6IiIsImNzdkZpbGVVcmwiOiIiLCJib3JkZXIiOnRydWUsIm1heFNjYWxlIjoiMSIsIm93bmluZ1BhZ2VJZCI6MTAzNDE2ODIyLCJlZGl0YWJsZSI6ZmFsc2UsImNlb0lkIjoxMDM0MjMzMDMsInBhZ2VJZCI6IiIsImxib3giOnRydWUsInNlcnZlckNvbmZpZyI6eyJlbWFpbHByZXZpZXciOiIxIn0sIm9kcml2ZUlkIjoiIiwicmV2aXNpb24iOjgsIm1hY3JvSWQiOiIxZDNmYzczNi04MGQxLTQ3NTgtODE1MC01OGNkMTY5MTEyNTAiLCJwcmV2aWV3TmFtZSI6Ik5DTVAgTm9ydGhib3VuZCBSRVNUIEFQSS5wbmciLCJsaWNlbnNlU3RhdHVzIjoiT0siLCJzZXJ2aWNlIjoiIiwiaXNUZW1wbGF0ZSI6IiIsIndpZHRoIjoiOTcxIiwic2ltcGxlVmlld2VyIjpmYWxzZSwibGFzdE1vZGlmaWVkIjoxNjIwOTA5ODAwMDAwLCJleGNlZWRQYWdlV2lkdGgiOmZhbHNlLCJvQ2xpZW50SWQiOiIifQ==