Work In Progress
Under construction
- CPS-391Getting issue details... STATUS
Guiding Principles
- NCMP REST Interface will follow/be inspired by RESTConf interface for easy acceptance of and transition to this interface
- 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)
Open Issues & Decisions
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 the default option for NCMP should be yang but we want to support both options - yang and the data node wrapper for pass through - yang data operational - data node (json) |
3 | In the URI will we distinguish between data and operations (RFC calls) as part of the path? | 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 |
4 | Which query parameters will NCMP support? | Parent data resource identifier can handle any path using the same query parameter
| |
5 | Yml should include return types and examples of the payload | ||
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) | |
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) |
| 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 | Yes, Istanbul will choose datastore based on presence of data (assuming model is always there) | |
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 LIMITATION NOTE: server implementations put size limits on the headers meaning header contents should be designed carefully : | |
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 resconf 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 datastore:operational? | The fields parameter is ignored in datastore:operational | |
18 | Is specifying the datastore mandatory? | Datastore is optional depending on the data being persisted or not | |
19 | Can the user request config=false data with ds:'ncmp-datastores:operational' if so what should NCMP do | ignore throw exception? | |
20 | Register a DMI plugin with NCMP | DMI plugin is a part of cm handle registration. The rest endpoint on NCMP can be multiple calls | |
21 | 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 | |
22 | 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 | |
23 | Config-true only support (filter out config-fals data) | Currently 'cmp-datastores:operational' will include (and return) config-false data | Future release could support additional flag or a ' ncmp-datastores:running' to filter out config-false data |
24 | 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 | No required in Istanbul. But DB model can easliy be udpated to cater for this when needed |
25 | Datastore conversion in NCMP or DMI-Plugin | DMI-Plugin wil know best how to convert. This will also reduce future impacts on NCMP for new options. |
RESTCONF/NETCONF relationship
NCMP URI
NCMP URI format to follow below pattern
<OP>/ncmp/<v{v-number}>/ch/<cm-handle>/<data|operations|{ncmp-operation}>/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 | 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 :
1 | ncmp-datastores:operational (RO / config=true/false) | Read from the CPS "operational" store. | config true and config false data |
2 | ncmp-datastores:passthrough-running (RW / config=true/false) | Read/Write to/from the live devices ietf-datastores:running (no local ncmp validation) | config-true data only |
Future datastores to be supported by NCMP include :
1 | ncmp-datastores:running (RW / config=true/false) | Read/Write to the CPS "intended" store (with validation). | config-true data only, see decision #23 |
2 | ncmp-datastores:passthrough-intented (RO) | Read from the live devices ietf-datastores:intended | ? |
3 | ncmp-datastores:passthrough-operational (RO) | Read from the live devices ietf-datastores:operational | config true and config false data |
If datastore (ds/{datastore}) is omitted from URI, the datastore from cmhandle is used
If datastore (ds/{datastore}) is omitted from URI AND the model/moduleSet exists, the datastore defaults to ncmp-datastores:running
Yang data resource actions and RPC operations are run directly on the 'device' meaning ncmp-datastores:passthrough-running is used for these request
Datastore, paths and format combinations
# | DatatStore parameters | Data-Sync "On" | Expected resource-path format | accept-header | Required Transformations | Data Source | 'config-false' data availability | Notes | Priority |
---|---|---|---|---|---|---|---|---|---|
1 | Not Specified | Yes | cpsPath | application/yang-data+json | input: none output: json to yang-data+json | CPS-Core | Yes | NCMP needs to remove DataNode wrapping | |
2 | Not Specified | Yes | cpsPath | application/json | input:none output:none | CPS-Core | Yes | ||
3 | Not Specified | No | cpsPath | application/yang-data+json | input: convert cpsPath to RESTConf Path | xNF | Yes | cm-handle known properties to resource-path format towards DMI-Plug DMI-Plugin will convert datastore as its sees fit | 2 |
4 | Not Specified | No | cpsPath | application/json | N/A | N/A | N/A | NOT Supported (there are NO DataNode objects in CPS to output as JSON) | |
5 | Not Specified | No | other then cpsPath | N/A | N/A | N/A | N/A | Not supported Since NCMP can only convert cpsPaths | |
6 | ncmp-datastores:passthrough-running | N/A | Don't care* | application/yang-data+json | input:none output:none | xNF | No | 1 | |
7 | ncmp-datastores:passthrough-running | N/A | Don't care* | application/json | NA | N/A | N/A | NCMP will ignore but DMI-Plugin might reject (ONAP wil in this case) | |
8 | ncmp-datastores:passthrough-running | N/A | cpsPath | N/A | NA | N/A | N/A | NOT Supported | |
9 | ncmp-datastores:operational | Yes | cpsPath | application/yang-data+json | input: none output: json to yang-data+json | CPS-Core | Yes | NCMP needs to remove DataNode wrapping | |
10 | ncmp-datastores:operational | Yes | cpsPath | application/json | input:none output:none | CPS-Core | Yes | ||
11 | ncmp-datastores:operational | Yes | other then cpsPath | N/A | N/A | N/A | N/A | NOT supported | |
12 | ncmp-datastores:operational | No | cpsPath | N/A | N/A | N/A | N/A | Data not available error |
* NCMP Doesn't care about resource-path but ONAP Plugin expects RESTConf compatible path if not, it or underlying component will report an error
Works Items for above TBC
# | Description | Component | Enables |
---|---|---|---|
1 | Convert json (dataNode) to yang-dat+json | CPS-Core/NCMP | 1,9 |
2 | Convert cpsPath to RESTConf Path | NCMP | 3 (and detect #5 not supported) |
3 |
REST API
# | Req/usecase | REST Method | URI / Payload | Request/Response Example | Status | Release I | ||||
---|---|---|---|---|---|---|---|---|---|---|
1 | Async read of a data resource getting | GET | {ncmp-root}/ncmp/v1/ch/<cm-handle>/{dataresource-identifier}?fields={fields}&topic={topicId} Note 'topic' and 'fields' are only supported in passthrough mode at this time (ONAP Release I). If not passthrough then an exception is thrown from NCMP at this time. | Scenario : Read the GNBCUCPFunction for cm-handle "335ff" as passthrough Method : GET URI : {ncmp-root}/ncmp/v1/data/ch/335ff/ds/GNBCUCPFunction?fields=pLMNId;gNBId;gNBIdLength;syncStatus&topic=anr-app:anr24234234:v2 OR {ncmp-root}/ncmp/v1/data/ch/335ff/ds/ncmp-datastores:passthrough-running?fields=_3gpp-common-managed-element:ManagedElement/_3gpp-nr-nrm-gnbcucpfunction:GNBCUCPFunction(pLMNId;gNBId;gNBIdLength)&topic=anr-app:anr24234234:v2 Header : Response : Event Response: { | passthrough-running is supported in Istanbul using
Note 'topic' and 'fields' are only supported in passthrough mode at this time (ONAP Release I). If not passthrough then an exception is thrown from NCMP at this time. Always return the yang-data+json in the "data" event payload | yes | ||||
2 | Read of a data resource getting specific | GET | {ncmp-root}/ncmp/v1/data/ch/<cm-handle/{data-resource-identifier}?fields={fields} | Scenario : Read the EUtranCellFDD.(administrativeState, operationalState, tac, earfcndl, cellId, physicalLayerCellId) for cmhandle "335ff" as passthrough Method: GET URI : {ncmp-root}/ncmp/v1/data/ch/335ff/ManagedElement[@id=Kista-001]/ENodeBFunction?fields=ericsson-enm-lrat:EUtranCellFDD(administrativeState;operationalState;tac;earfcndl;cellId;physicalLayerCellId) Header : Response: HTTP/1.1 200 OK | passthrough-running is supported in Istanbul using
| |||||
3 | Read a data resource directly from Synchronous call | GET | {ncmp-root}/ncmp/v1/data/ch//{data-resource-identifier}?fields={fields} Accept: application/yang-data+json | Scenario : Read the EUtranCellFDD.(administrativeState, operationalState, tac, earfcndl, cellId, physicalLayerCellId) for cmhandle "335ff" as passthrough Method : GET URI :{ncmp-root}/ncmp/v1/data/ch/335ff/ManagedElement[@id=Kista-001]/ENodeBFunction?fields=ericsson-enm-lrat:EUtranCellFDD(administrativeState;operationalState;tac;earfcndl;cellId;physicalLayerCellId) Header : Response: HTTP/1.1 200 OK { | passthrough-running is supported in Istanbul using
| Yes | ||||
4 | Read a data resource with some leaf value condition directly from the source (passthrough) for a cmHandle. Only Synchronous call | GET | {ncmp-root}/ncmp/v1/data/ch/<cmhandle>/{data-resource-identifier[<condition>]}?fields={fields} | Scenario : Read the LocalSctpEndpoint.(interfaceUsed==X2, sctpEndpointRef) for cmhandle "335ff" as passthrough Method : GET URI cps-path | passthrough-running is supported in Istanbul using
| |||||
5 | Create a data resource for a cmhandle | POST | cmp-root}/ncmp/v1/data/ch/<cm-handle>/{parent-data-resource-identifier} { | Scenario : Create ericsson-nrsectorcarrier-vdu-add:NRSectorCarrier=4 under _3gpp-common-managed-element:ManagedElement=Kista-001 Method : POST URI : {ncmp-root}/ncmp/v1/data/ch/34l5k32/ManagedElement[@id=Kista-001]/GNBDUFunction[@id=1] Header : Body : { | passthrough-running is supported in Istanbul using
ncmp-datastores:running is not supported in Istanbul | |||||
6 | Update a data resource for a cmhandle with plain-patch update | PATCH | {ncmp-root}/ncmp/v1/data/ch/<cmhandle>/{data-resource-identifier} { Content: application/yang-data+json Behaves as a merge - merge with existing if it exists or create if it does not exist. | Scenario : Update ericsson-nrsectorcarrier-vdu-add:NRSectorCarrier=4 txDirection to "DL_AND_UL" under _3gpp-common-managed-element:ManagedElement=Kista-001/_3gpp-nr-nrm-gnbdufunction:GNBDUFunction=1 Method : PATCH URI :{ncmp-root}/ncmp/v1/data/ch/34l5k32/ManagedElement[@id=Kista-001]/GNBDUFunction[@id=1]/NRSectorCarrier[@id=4] Header : Body : { NOTE : If not passthrough then ALL attributes MUST be supplied for the patch at this time. Otherwise, other attributes are removed from CPS. | passthrough-running is supported in Istanbul using
ncmp-datastores:running is not supported in Istanbul this will be treated as a merge | |||||
7 | Update a data resource with multiple edits for a cmhandle with yang-patch update | PATCH | {ncmp-root}/ncmp/v1/data/ch/<cm-handle>/{data-resource-identifier} { Content: application/yang-data+json If using yang-patch content then ds/ncmp-datastore-passthrough-running mus be used by rad apps until full | Scenario : Update _3gpp-common-managed-element:ManagedElement=Kista-001/_3gpp-nr-nrm-gnbdufunction:GNBDUFunction=1 with multiple operations on the tree Method : PATCH Header : Body : { | ||||||
8 | Delete a data resource for a cmhandle | DELETE | {ncmp-root}/ncmp/v1/data/ch/<cm-handle>/{data-resource-identifier} | Scenario: Delete ericsson-nrsectorcarrier-vdu-add:NRSectorCarrier=4 under _3gpp-common-managed-element:ManagedElement=Kista-001/_3gpp-nr-nrm-gnbdufunction:GNBDUFunction=1 Method : DELETE URI : {ncmp-root}/ncmp/v1/data/ch/34l5k32/ManagedElement[@id=Kista-001]/GNBDUFunction[@id=1]/NRSectorCarrier[@id=4] | passthrough-running is supported in Istanbul using
ncmp-datastores:running is not supported in Istanbul for delete | |||||
9 | Get all cmhandles that support a given module | GET | {ncmp-root}/ncmp/v1/data/ch?module={module-name} Content: application/json | Scenario : Get the all cmhandles that support a given module Response: | ||||||
10 | Get model info for CMHandle | GET | {ncmp-root}/ncmp/v1/data/ch/{cm-handle}/ietf-yang-library:modules-set | Scenario : Get the model data for CMHandle Method : GET URI :{ncmp-root}/ncmp/v1/data/ch/2334dedf/ietf-yang-library:modules-set Header : Response: { | passthrough-running is supported in Istanbul using
ncmp-datastores:running is not supported in Istanbul for delete | |||||
11 | Execute a yang action | POST | {ncmp-root}/ncmp/v1/data/ch/<cm-handle>/ds/ncmp-datastores:passthrough-running/{data-resource-identifier}/{action} Note : If the "action" statement | Method : POST URI : {ncmp-root}/ncmp/v1/data/ch/3445fff/ds/ncmp-datastores:passthrough-operational/ManagedElement[@id=Kista-001]/brm/backup-manager[@id="configuration-system import-backup"] Header : Body : Body : | passthrough-running is supported in Istanbul using
ncmp-datastores:running is not supported in Istanbul | |||||
12 | Execute an rpc operation | POST | {ncmp-root}/ncmp/v1/operations/ch//operations /ds/ncmp-datastores :passthrough-operational/{module-name}:{action} { Note : If there is no "input" | Method : POST URI : {ncmp-root}/ncmp/v1/operations/ch/3445fff/ds/ncmp-datastores:passthrough-operational/_3gpp-common-managed-element:resetDevice (dummy action) Header : Body : Response : | passthrough-running is supported in Istanbul using
ncmp-datastores:running is not supported in Istanbul | |||||
13 | Read descendant data resources with | GET | {ncmp-root}/ncmp/v1/ch/<cm-handle>/{data-resource-identifier}?fields={fields-expression} options
| Scenario : Read all NRCellDU MOs with attributes userLabel and id under the _3gpp-nr-nrm-gnbdufunction:GNBDUFunction MO Method : GET URI :{ncmp-root}/ncmp/v1/data/ch/3445fff/ManagedElement[@id=Kista-001] Header : Response : HTTP/1.1 200 OK { _3gpp-nr-nrm-nrcelldu:NRCellDU=1 { _3gpp-nr-nrm-nrcelldu:NRCellDU=4 { _3gpp-nr-nrm-nrcelldu:NRCellDU=5 { | passthrough-running is supported in Istanbul using
| |||||
14 | Read data resources to a given depth | POST | {ncmp-root}/ncmp/v1/ch/<cm-handle>{data-resource-identifier}?depth={level}
| Method : POST URI : {ncmp-root}/ncmp/v1/ch/3445fff/ManagedElement[@id=Kista-001]/GNBDUFunction[@id=1]?depth=4 Header : Body: Response : HTTP/1.1 200 OK _3gpp-nr-nrm-nrsectorcarrier: _3gpp-nr-nrm-nrsectorcarrier:NRSectorCarrier=3{ _3gpp-nr-nrm-nrsectorcarrier:NRSectorCarrier=4 { _3gpp-nr-nrm-nrcelldu:NRCellDU=1 { _3gpp-nr-nrm-nrcelldu:NRCellDU=4 { _3gpp-nr-nrm-nrcelldu:NRCellDU=5 { | passthrough-running is supported in Istanbul using
ncmp-datastores:running is not supported in Istanbul | |||||
15 | Replace a data resource for a cmhandle | PUT | ncmp-root}/ncmp/v1/data/ch/<cm-handle>/{data-resource-identifier} { <yang-data-resource-identifier> } | Scenario : Replace _3gpp-nr-nrm-nrsectorcarrier:NRSectorCarrier=4 txDirection Method : PUT URI : {ncmp-root}/ncmp/v1/data/ch/34l5k32/ManagedElement[@id=Kista-001] Header : Body : { | passthrough-running is supported in Istanbul using
ncmp-datastores:running is not supported in Istanbul | |||||
16 | Async Requests | GET/ POST/ PATCH /PUT/ DELETE | {ncmp-root}/ncmp/v1/ch/<cmhandle>/data/ds/ncmp-datastores:passthrough-running/ {xpath}?topic=<dmaap-topic-Identifier> **Async communication channel is DMaaP Immediate response with a requestId is sent to the caller and the CRUD request is executed asynchronously where data is returned via the provided topic identifier. | Scenario : Async request to NCMP Method : GET/POST/PATCH/PUT/DELETE URI : {ncmp-root}/ncmp/v1/data/ch/de3455/ManagedElement[@id=Kista-001]/GNBDUFunction[@id=1]?topic=5G:SectorCarrierOrchestrator-0012391:12 Body : // Include body where required Response : response data is published on the topic identified by <topicIdentifier> keyed on request. Event Successful Reponse : |
Output Specification
?fields={fields}&topic= {topicId}
Assynchronous
?fields={fields}&topic= {topicId}
Required Task
# | Description | Notes | Decision |
---|---|---|---|
1 | Yml update with return types with examples of the payload | ||
2 | Update CPS openAPI.yml with return types |
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