...
Table of Contents |
---|
Requirements
Functional
# | Interface | Requirement | Additional Information | Sign Off |
---|---|---|---|---|
1 | CPS-NCMP-I-01 | Upgrade module set for CM-Handle(s) using a moduleSetTag | Module Set Tag is owned (defined) by DMI Plugin |
|
2 | CPS-NCMP-I-01 | Initial Inventory shall support (Optional) moduleSetTag too | Exiting performance shall not degrade. |
|
3 | CPS-NCMP-I-01 | Update module set for CM-Handle(s) using a Blank (not defined) moduleSetTag | use 'old' algorithm from initial inventory |
|
4 | CPS-E-05 | Read moduleSetTag for given CM Handle(id) | Probably no code changes required (just a model change) |
|
5 | CPS-E-05 | Query Cm Handle(s) using CPS Path with moduleSetTag | Probably no code changes required (just a model change) |
|
6 | CPS-E-05.e (e for events) | A new notification informing the client the old and new value of moduleSetTag | Use same topic as CM Handle LCM Events (and future trust-level change notifications) |
|
...
Excerpt | ||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Performance is posted here : Performance test for updating YANG schema set API |
Out-of-scope
- Upgrade of models for cached data. "ncmp-datastore:operational" is out-of-scope.
Note: Only pass-through i.e. non-cached data upgrade is in scope; "ncmp-datastore:passthrough-running" and "ncmp-datastore:passthrough-operational" is in scope.
Assumptions
# | Assumption | Notes |
---|
Issues & Decisions
Issue | Notes | Decision | |
---|---|---|---|
1 | Type of Interface REST or Kafka | REST
Kafka
| meeting Agreed to use REST interface. |
2 | moduleSetTag based on Hash no (yet) implemented! | This study seems to assume the module set tag is already implemented but it isn't! | [kieran mccarthy]: the request it to introduce the module set tag/identifier of some kind for this new upgrade usecase. Not assuming it is there already. Will be costlier but is important for performance to avoid pulling models if they are already known to NCMP. |
3 | Expected Responses | when and what content?
Should follow error handling for Inventory | kieran mccarthy and team. |
4 | Should CM-Handle state change (e.g. to 'locked') 'during' upgrade? | Yes but is important to not be locked for long which makes it important to use the moduleSetTag | kieran mccarthy Should be set to LOCKED until the new moduleSet is associated with the cmhandle. I think there is a LOCKED_UPGRADING if I remember right. Lock reason should mention "upgrade" and have the usual timestamps. A separate notifications will be send with details of the old and new values for moduleSetTag see decision #11 |
5 | moduleSetTag is Optional (owned and defined by DMI Plugin) | Support for upgrade without continues using delete/add cm handle approach. If the update includes an moduleSetTag it would be considered an upgrade | meeting Agreed to use REST interface with "upgradedCmHandles". |
6 | moduleSetTag should be able to be used during initial inventory too! | Initial Inventory should be sped up too (capability requirements impacts ?!) Note. Current inventory 'createdCmHandles' only supports a list of cm handle Ids can this be in backward compatible way be modified to optionally include a moduleSetTag | kieran mccarthy and team. Yes, if need backward incompatible change can be handle as a new version of the interface |
7 | Exact name moduleSetTag | meeting agreed on moduleSetTag | |
8 | How to store: hardcoded (postgress schema), inventory yang model or as additional property (private or public)? | update Inventory Yang Model so it can be queried (without code changes!) like other aspect such as 'state' | meeting agreed to update Yang Model |
9 | additional operation for inventory Interface: 'upgradedCmHandles' | The interface currently supports
it possiblycould be done as part of 'updatedCmHandles' and look for /recognize the moduleSetTag update but this would be messy and confusing, also thentheoretically properties could be updated as the same time as the module set.. | meeting agreed |
10 | Clarify capabilities |
| Part of requirement listed above, to be finalized in a meeting after the holidays on |
11 | Separate Notification on change of moduleSetTag |
| kieran mccarthy separate notification see requirement #6 |
12 | Reuse schema set name or create a new one? | each cm handle now has a (unique) schema set name which is the same as the cm handle (id). we could simply change the module references but it might be more correct to create a NEW schema set and delete the old one. The name name could be a concatenation of the cm handle (id) and the module set tag
| Team agreed to re-use existing name |
Solution Proposals
Update Inventory REST Interface
Making the module upgrade request either over REST or Kafka Event with a supplied 'moduleSetTag' property will indicate to NCMP that a cmhandle has a new moduleSet (node has been upgraded). The moduleSetTag is a unique identifier for the set of modules associated with a cmhandle. This event or rest request will trigger ncmp to either retrieve the new module set for this cmhandle from the dmi plugin or if NCMP is already aware of moduleSetTag as part of a previous retrieval for a set of modules for a cmhandle that supplied this moduleSetTag then it should not re-retrieve the modules from the dmi plugin as it already has them. NCMP should use its stored moduleSetTag to get the set of modules. It can then do a delta with the existing cmhandle moduleSet and update the moduleSet for the cmhandle.
The above proposal would require model updates to NCMP to store the association between a moduleSetTag supplied by a dmi-plugin (during and updateCmHandles request) and the modules. Initially moduleSetTag is not known to NCMP. However, after retrieval of the modules for the first time for the cmhandle, NCMP can store the association. Any subsequent cmhandle that references the same moduleSetTag will not require NCMP to go back to the dmi plugin for the moduleSet.
Reuse the NCMP Inventory API (CPS-NCMP-I-01). URI : POST /v1/ch
13 | Conflicting Error code : Legacy codes for registration v. event status code (dataOperation and Subscrption) | See
ModuleSetTag error scenarios have overlapping codes for 'cm handle not found/not found' Some of these are already in use!!! Can we fix now or live with inconsistencies forever?! NEW
Create a new Jira and agree priority with E// - Prioritise it's a blocker |
|
Solution Proposals
Update Inventory REST Interface
Making the module upgrade request either over REST or Kafka Event with a supplied 'moduleSetTag' property will indicate to NCMP that a cmhandle has a new moduleSet (node has been upgraded). The moduleSetTag is a unique identifier for the set of modules associated with a cmhandle. This event or rest request will trigger ncmp to either retrieve the new module set for this cmhandle from the dmi plugin or if NCMP is already aware of moduleSetTag as part of a previous retrieval for a set of modules for a cmhandle that supplied this moduleSetTag then it should not re-retrieve the modules from the dmi plugin as it already has them. NCMP should use its stored moduleSetTag to get the set of modules. It can then do a delta with the existing cmhandle moduleSet and update the moduleSet for the cmhandle.
The above proposal would require model updates to NCMP to store the association between a moduleSetTag supplied by a dmi-plugin (during and updateCmHandles request) and the modules. Initially moduleSetTag is not known to NCMP. However, after retrieval of the modules for the first time for the cmhandle, NCMP can store the association. Any subsequent cmhandle that references the same moduleSetTag will not require NCMP to go back to the dmi plugin for the moduleSet.
Reuse the NCMP Inventory API (CPS-NCMP-I-01). URI : POST /v1/ch
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
{
upgradedCmHandles : [
{
| ||||||
Code Block | ||||||
| ||||||
{ upgradedCmHandles : [ { "cmhandle" : "<cmhandle-id-1>", "moduleSetTag" : "ffsdfg55342" # new moduleSetTag ffsdfg55342 for the cmhandle }, { "cmhandle" : "<cmhandle-id-2>1>", "moduleSetTag" : "ffsdfg55342" # new moduleSetTag ffsdfg55342 for the cmhandle }, { "cmhandle" : "<cmhandle-id-3>2>", "moduleSetTag" : "ddger34324ffsdfg55342" # new moduleSetTag ddger34324ffsdfg55342 for the cmhandle } ] } |
Proposed Inventory Model rev. 2023-08-23
Lines added: 11-14, 83-85
},
{
"cmhandle" : "<cmhandle-id-3>",
"moduleSetTag" : "ddger34324" # new moduleSetTag ddger34324 for the cmhandle }
]
} |
Proposed Inventory Model rev. 2023-08-23
Lines added: 11-14, 83-85
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
module dmi-registry { yang-version 1.1; namespace "org:onap:cps:ncmp"; prefix dmi-reg; contact "toine.siebelink@est.tech"; revision "2023-08-23" { description "Added ModuleSetTag"; } revision "2022-05-10" { description "Added DataSyncEnabled, SyncState with State, LastSyncTime, DataStoreSyncState with Operational and Running syncstate"; } revision "2022-02-10" { description "Added State, LockReason, LockReasonDetails to aid with cmHandle sync and timestamp to aid with retry/timeout scenarios"; } revision "2021-12-13" { description "Added new list of public additional properties for a Cm-Handle which are exposed to clients of the NCMP interface"; } revision "2021-10-20" { description "Added dmi-data-service-name & dmi-model-service-name to allow separate DMI instances for each responsibility"; } revision "2021-05-20" { description "Initial Version"; } grouping LockReason { leaf reason { type string; } leaf details { type string; } } grouping SyncState { leaf sync-state { type string; } leaf last-sync-time { type string; } } grouping Datastores { container operational { uses SyncState; } container running { uses SyncState; } } container dmi-registry { list cm-handles { key "id"; leaf id { type string; } leaf dmi-service-name { type string; } leaf dmi-data-service-name { type string; } leaf dmi-model-service-name { type string; } leaf module-set-tag { type string; } list additional-properties { key "name"; leaf name { type string; } leaf value { type string; } } list public-properties { key "name"; leaf name { type string; } leaf value { type string; } } container state { leaf cm-handle-state { type string; } container lock-reason { uses LockReason; } leaf last-update-time { type string; } leaf data-sync-enabled { type boolean; default "false"; } container datastores { uses Datastores; } } } } } |
...
- Need to use a new (shared) Hazelcast map with ModuleSetTags as key (value list of module refs) that have been processed (but not saved yet) to be used both inside a batch and different instance to prevent unnecessary trips to DMI/Node
- Watchdog needs to use Lock state AND lock reason to determine what node need to be upgraded
- Initial inventory and upgrade is not likely to happen at the same time but watchdog can handle both, of course performance would be affected if that does occur
- CACHE(s) needs to be cleared or updates as algorithm wil re-use existing schema set name
- Create new upgrade specific methods and reuse/slightly duplicate initial inventory methods
- Legacy (and new) checks for lock need to check the lock-reason too now! To differentiate between failed initial inventory and upgrade
- Probably need more specific (new) failure reasons to differentiate between initial inventory and upgrade failures
- as usual: small commits, early reviews to introduce all this functionality are advised, posisbel steps
- set lock state and reason upon request
- watch dog just list to be upgrade node (and does not mix them up with failed initial inventory)
- perform first upgrade for a new ModuleSetTag
- introduce and use new Hazelcast map
- perform upgrade of an node with a modueleSetTag that is already in cache
- perform upgrade of an node with a modueleSetTag that is already in DB (ie introduce DB query)
- handle failure of upgrade (re-use same retry mechanism as initial inventory but with different lock reason!)
- etc.
Proposed JIRAs
- is not likely to happen at the same time but watchdog can handle both, of course performance would be affected if that does occur
- CACHE(s) needs to be cleared or updates as algorithm wil re-use existing schema set name
- Create new upgrade specific methods and reuse/slightly duplicate initial inventory methods
- Legacy (and new) checks for lock need to check the lock-reason too now! To differentiate between failed initial inventory and upgrade
- Probably need more specific (new) failure reasons to differentiate between initial inventory and upgrade failures
- as usual: small commits, early reviews to introduce all this functionality are advised, posisbel steps
- set lock state and reason upon request
- watch dog just list to be upgrade node (and does not mix them up with failed initial inventory)
- perform first upgrade for a new ModuleSetTag
- introduce and use new Hazelcast map
- perform upgrade of an node with a modueleSetTag that is already in cache
- perform upgrade of an node with a modueleSetTag that is already in DB (ie introduce DB query)
- handle failure of upgrade (re-use same retry mechanism as initial inventory but with different lock reason!)
- etc.
Use-Case Overview (Sync in watchDog)
Operation | Tag Provided | Tag Cached | Tag In DB (other cm handle) | Steps | |
---|---|---|---|---|---|
1 | Create | No | N/A | N/A |
|
2 | Create | Yes | No | No |
|
3 | Create | Yes | No | Yes |
|
4 | Create | Yes | Yes | N/A |
|
5 | Upgrade | No | N/A | N/A |
|
6 | Upgrade | Yes | No | No |
|
7 | Upgrade | Yes | No | Yes |
|
8 | Upgrade | Yes | Yes | N/A |
|
Note. Error handling like invalid IDs are handled during the Synchronous part of registration and not part of this use-case overview.
Upgrade to the same Tag should be captured in synchronous pre-processing.
re-usable methods
- Gget modules (delta) from Node (DMI)
- Create schemaset. Combination of exiting Refs and new yang resources
New yang resources empty for known module sets (known tag) - Create anchor
- Update schemaset. Combination of exiting Refs and new yang resources
New yang resources empty for known module sets (known tag)
Changes agreed between Daniel Hanrahan , Sourabh Sourabh and Toine Siebelink
Change | Notes | |
---|---|---|
1 | No need for ModuleSetTagCache | reduce complexity, no significant impact on performance Can be re-introduced in a better way later if needed but not expected |
2 | Use same method for New and Known Schema Sets (module set tags) |
|
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
void processCreate() {
if (tagProvided && tag in DB) {
allModuleRefences = referencesFromDb
newYangResources = []
else {
delta = getModulesDelta()
newYangResources = delta.newYangResources
allModuleRefences = delta.allModuleRefences
}
creatSchemaSet(newYangResources, allModuleRefences)
createAnchor()
}
void processUpgrade() {
if (tagProvided && tag in DB) {
allModuleRefences = referencesFromDb
newYangResources = []
else {
delta = getModulesDelta()
newYangResources = delta.newYangResources
allModuleRefences = delta.allModuleRefences
}
udpateSchemaSet(newYangResources, allModuleRefences)
}
|
Proposed JIRAs
Component | Description | JIRA | Estimates | |||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
1 | CPS Core | Expose a java interface to update schema set |
| 5 Days | ||||||||||||||||||
2 | NCMP | Update existing REST endpoint add operation to upgrade YANG schema set using moduleSetTag |
| 15 Days | ||||||||||||||||||
3 | NCMP | Upgrade inventory YANG model to store moduleSetTag |
| 5 Days | ||||||||||||||||||
4 | NCMP | Use moduleSetTagCache to be cleared or updates as algorithm wil re-use existing schema set name |
| 5 Days | ||||||||||||||||||
5 | NCMP | Update cmhandle state (lock) during YANG model upgrade | ||||||||||||||||||||
Priority | Component | Description | JIRA | Estimates | ||||||||||||||||||
1 | CPS Core | Expose a java interface to update schema set
| 1800
| 5 Days | ||||||||||||||||||
26 | NCMP | Update existing REST endpoint add operation to upgrade YANG schema set using moduleSetTagModify existing inventory operations using moduleSetTag as optional attribute |
| 1798
| 15 Days | |||||||||||||||||
37 | NCMP | Upgrade inventory YANG model to store moduleSetTagIdentify and test error scenarios |
| 1804
| 5 Days | |||||||||||||||||
4 | NCMP | Upgrade anchor to new yang schema set (CPS-Core) Duplicate of #1 |
| 5 Days | ||||||||||||||||||
8 | NCMP | CSIT test and demo | 5 | NCMP | Update cmhandle state (lock) during YANG model upgrade
| 1801
| 5 Days | |||||||||||||||
69 | NCMP | Modify existing inventory operations using moduleSetTag as optional attributeTest and document performance of updating YANG schema set API. |
| 10 Days | ||||||||||||||||||
10 | NCMP | Handle yangTextSchemaSourceSetCache for module set tag |
| 1803
| 15 5 Days | 7|||||||||||||||||
11 | NCMP | Identify and test error scenariosSchema object cache not distributed |
| 1802
| ||||||||||||||||||
12 | 8 | NCMP | Update DMI Stub for testing purposes and add CSIT testImprove unit test and dmi plugin csit stub |
| ||||||||||||||||||
13 | 18065 Days | 9 | NCMP | Test and document performance of updating YANG schema set API./DMI | Add moduleSetTag to the request towards dmi plugin if moduleSetTag is set for the cmHandle |
| 180510 Days
|
Planning:
- Allow for 2 more user stories each may take 1 week.
- Estimated date of completion is based on 1 person working. There is a possibility that 1 more person will join in between for implementation but there is no clear visibility on when the person can start contributing as of now.
- These are estimates and should not be interpreted as commitments.
...