Table of Contents |
---|
References
Jira | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
|
Assumptions
Assumption | Notes | Sign-off | |
---|---|---|---|
1 | Scope:
| This does not affect (bulk/batch) Read |
|
2 | Conflict Management Interface uses FDN | Conflict Management can support ANY format the Alternate ID can support (FDNs and/or URI-FDNs) |
|
3 | Request per second is per the existing numbers on NCMP |
|
Issues & Decisions
Issue | Notes | Decision | |
---|---|---|---|
1 | Uplift Ericsson source code (need permission) | CPS not allowed to lift // proprietary codes, we need to use pseudo code Gergely/team to support CPS with these codes | |
2 | Implement in REST or Service Layer ? | This is currently implemented as an in the Service layer in // | |
3 | Publish public |
Conflict Interface as part of NCMP (Concerns new generic interface)?
NCMP shall own and document. | |||
4 | Could we make this more generic to suit non-conflict-management use i.e. tbac... | Agreed to make it more generic to suit ALL the use cases | |
5 | Private properties are used to get FDN at the moment. | Will // provide us with registered Alternatid? Opensource does not support private property Peter Turcsanyi to revert TBC . // Confirmed they will implement all https://eteamproject.internal.ericsson.com/browse/IDUN-105467 |
|
6 | CPS-1992 - NCMP to Support New 3GPP sync single FDN request to support Conflict mgt | CPS-1992 - When delivered, this should also support conflict management | |
7 | Legacy and ongoing bulk/batch interface (dataJobs CPS-1964) are not in scope | Bulk/batch operation
| |
8 | Name for more generic interface | Suggestion: External Validation AP Kolawole Adebisi-Adeolokun to inform other stakeholders | New Interface name shall be PolicyExecution as agreed with stakeholders Kolawole Adebisi-Adeolokun kieran mccarthy Gergely Molnar |
9 | External Validation Request format | POST operation, all parameters in body, URL ? AP Toine Siebelink to create a page & collaborate with Gergely/Brian ( on initial proposal) | |
10 | Enable/service name discovery | config parameter with service name/address. AP Toine Siebelink to create a page & collaborate with Gergely/Brian ( on initial proposal) | |
11 | case |
sensitivity of parameters (payloadType, |
decision etc.) |
e.g. accept 'allow', 'Allow', 'ALLOW' or only accept only on well defined case sensitive variation and anything else is a error scenario?!
To be discussed during proposal;
AP Toine Siebelink to create a page & collaborate with Gergely/Brian ( on initial proposal)
following existing conventions in CPS/NCMP all parameter values are case sensitive and use lower snake e.g. cm_create, deny | ||||||||||||
12 | Delivery Artefact | The new OpenAPI Interface definition wil be published on CPS Public Documentation Page. and through ONAP Gerrit. | Brian Folan, Toine Siebelink agreed to use same as DMI ie. just 'deliver' to Doc and Repo | |||||||||
13 | Specify cmChangeRequest in more detail |
Toine Siebelink I am concerned this wil reduce the flexibility of this interface. Also, NCMP itself is NOT interested in eth actual change details so why enforce them in this interface... Csaba Kocsis 'id' and 'attributes' are a 3GPP conventions only | Zoltán Szabó Toine Siebelink Validation need on Impl. side but for flexibility this is not required in CPS/NCMP so we agreed to pass it as 'an object' | |||||||||
14 | How to feed back result of CM change to Policy Execution/Executor? | Consider the following scenario (from Brian Folan). There is an active policy for time based lock against an attribute on a specific cmHandle. A change is made to the attribute, triggering the time-based lock for x minutes, but the CM change fails after letting it through to the DMI due to any reason and it's not actually rolled out to the network. The policy engine would apply the lock and no subsequent changes are allowed for the duration of the lock, however no changes were made to the network. Should we feed back the result of a CM change to the Policy Engine? | Brian Folan Toine Siebelink agreed this is out of scope for this epic but can be considered later. Interface propsosal is flexible enough to extend for something like this in the future | |||||||||
15 | Choose URL format | Gergely Molnar prefers alternative a (with an 'action'): | Zoltán Szabó Toine Siebelink agreed on Alt.a. a simple URL, all data in body | |||||||||
16 | Optional cmHandleId and resourceIdentifier | Brian Folan: Cm Handle ID wil mean nothing for Ericsson Impl but can be logged. Resource Identifier can be 'convention' but they don't depend on it if the target fdn contains the 'complete' fdn | Brian Folan, Zoltán Lajos Kis Toine Siebelink CM Handle Id and Resource Identifier are optional. CPS/NCMP will add them when provided in the incoming interface | |||||||||
17 | request accepted content type | not defined (and wrong value copied in original proposal). Now suggested: application/json | Gergely Molnar Agreed (per email) | |||||||||
18 | definition 'enum' values | defined as strings in OpenAPI to allow for flexibility and allow impl updates without having to update (and release) the OpenAPI | Gergely Molnar Agreed (per email) | |||||||||
19 | enum value description examples | although not specified in the OPenAPI definition (as enums) The convention in CPS/NCMP so far is that all 'enum' values are in lower (snake) case (and treated case-sensitive) | Gergely Molnar Agreed (per email) | |||||||||
20 | authorization header compulsory | As per the proposal the OpenAPI now defined the 'Authorization' header as 'required'. This mean omission of this header will lead to a 400 Bad Request (and NOT 401 Unauthorized) as per Swagger/Spring generated Interface. See https://gerrit.onap.org/r/c/cps/+/138401/2/docs/api/swagger/policy-executor/openapi.yaml Lines #214-219 | Gergely Molnar , Toine Siebelink Agreed (per email) making the 'Authorization' header optional for more flexibility. | |||||||||
21 | cm_write shoudl be split? | Now we use 'schema' and ncmp will use 4 different schemas , one for each operation:
| Gergely Molnar, Toine Siebelink Agreed during on site meeting in Budapest | |||||||||
22 | where to publish schemas | At least in RTD but maybe somewhere else too? | Gergely Molnar, Toine Siebelink Agreed no need to publish anywhere else |
Requirements
Functional: new generic '
...
PolicyExecution' REST interface
This interface will NOT be implemented by CPS team except a stub for testing purposes
Interface | Requirement | Additional Information | Signoff | |
---|---|---|---|---|
1 | External ValidationPolicyExecution | Documentation | NCMP own and clearly document interface using OpenAPI and RTD | |
2 | External ValidationPolicyExecution | Input Parameters:
| Payloadtype can only be 'CM_Write' for now Payloadtype can only be 'Allow' for now Exact Payload to be defined during study but should be well defined and cannot depend on Java interface (even if it is the same now) | |
3 | External ValidationPolicyExecution | Output Parameters;
| This is a New Generic interface that can support 'confllict conflict handling'. |
Excerpt | ||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Functional: CPS Impacts Policy Executor
Error Handling
Characteristics
|
Out of Scope
- Batch (bulk) interface methods and Execute a data operation for group of cm handle ids
- Data job interface
- Datajobs bulk write operations
Solution Proposal
External Validation REST Interface
URI
- jobs (write) operations
Suggested User Stories
Description | Jira | ||||||||
---|---|---|---|---|---|---|---|---|---|
Agree, Define (and Publish) Open Source Interface for Policy Execution |
| ||||||||
Feature toggle and addressing configuration parameters (use logging instead of actual call to new interface) |
| ||||||||
Dummy Stub implementation (to allow for integration testing) |
| ||||||||
Use new interface in NCMP (use Stub to allow/disallow predefined names/patterns) |
| ||||||||
Handle non-responding policy executor (using watchdog?) TBC | |||||||||
Metrics | |||||||||
Update official documentation (when feature completed from OpenSource point-of-view) |
Solution Proposal
Policy Executor REST Interface
Alternative a. No Parameters in URL (all data in body)
URI: <server-address>/policy-executor/api/v1
Alternative b-2. Payload and decision Type in URL
remaining data in request body, no need for 'payload' object because the body = payload
URI: <server-address>/policy-executor/api/v1/<payload-type>/<decision-type>
e.g. myhost:1234//policy-executor/api/v1/CM_Write/Allow
Alternative b-2. Payload and decision Type in URL with variable names
remaining data in request body, no need for 'payload' object because the body = payload
URI: <server-address>/policy-executor/api/v1/payload/<payload-type>/decision/<decision-type>
e.g. TBC - Gergely Molnar /Brian ( To provide initial proposal)myhost:1234//policy-executor/api/v1/payload/CM_Write/decision/Allow
Input Parameters
Name | Parent | Type | Example Value | Optional/Compulsory | Notes | |
---|---|---|---|---|---|---|
1 |
action |
url path | String | execute | Required | The policy action. Currently supported value: | ||
2 | Authorization | request (authorization header) | String | Bearer edaa8e7ce30f8904 | Required | required for tracking/ (future) authentication and to identify the source (rApp) of the request |
3 |
|
DecisionType
payload
targetFdn
resourceIdentifer
changeRequest
body | String | allow | Required | currently supported value: allow | ||
4 |
| body | Object[] Array | Required | ||
5 |
| requests[n] | String | org.onap.cps.ncmp.policy-executor:ncmp-create-schema:1.0.0 | Required | the schema name can also be used to determine the type of operation as each ncmp operation has its own schema (but can have similar/identical) content |
6 |
| requests[n] | Object | Required | Defined by schema above |
Create Schema (cps:org.onap.cps.ncmp.policy-executor:ncmp-create-schema:1.0.0)
Name | Parent | Type | Example Value | Optional/Compulsory | Notes | |
---|---|---|---|---|---|---|
1 |
| data | String | F811AF64F5146DFC545EC60B73DE948E | Optional | Can be sent while cmHandle is used instead of alternateId NCMP will populate when available |
2 |
| data | String | ManagedElement=Kista/GNBDUFunction=1/UECC=1 | Optional | Remainder of FDN NCMP will populate when available |
3 |
| data | String | /Subnetwork=22/MeContext=Kista/ManagedElement=Kista/GNBDUFunction=1/UECC=1 | Required | Complete FDN representing the cm handle and the resource identifier ie point to the target of the change to 'CM-Handle' ?! |
4 |
| data | Object | {"Cell":[{"id":"Cell-id","attributes":{"administrativeState":"UNLOCKED"}}]} | Required | CM Change Request |
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
{
"$schema": "https://json-schema.org/draft/2019-09/schema",
"$id": "urn:cps:org.onap.cps.ncmp.policy-executor:ncmp-create-schema:1.0.0",
"$ref": "#/definitions/NcmpCreate",
"definitions": {
"NcmpCreate": {
"javaType": "org.onap.cps.ncmp.impl.data.policyexecutor.NcmpCreate",
"type": "object",
"additionalProperties": false,
"properties": {
"cmHandleId": {
"type": "string"
},
"resourceIdentifier": {
"type": "string"
},
"targetIdentifier": {
"type": "string"
},
"cmChangeRequest": {
"type": "object"
}
},
"required": [
"targetIdentifier",
"cmChangeRequest"
]
}
}
} |
Update Schema (cps:org.onap.cps.ncmp.policy-executor:ncmp-update-schema:1.0.0)
Name | Parent | Type | Example Value | Optional/Compulsory | Notes | |
---|---|---|---|---|---|---|
1 |
| data | String | F811AF64F5146DFC545EC60B73DE948E | Optional | Can be sent while cmHandle is used instead of alternateId NCMP will populate when available |
2 |
| data | String | ManagedElement=Kista/GNBDUFunction=1/UECC=1 | Optional | Remainder of FDN NCMP will populate when available |
3 |
| data | String | /Subnetwork=22/MeContext=Kista/ManagedElement=Kista/GNBDUFunction=1/UECC=1 | Required | Complete FDN representing the cm handle and the resource identifier ie point to the target of the change to 'CM-Handle' ?! |
4 |
| data | Object | {"Cell":[{"id":"Cell-id","attributes":{"administrativeState":"UNLOCKED"}}]} | Required | CM Change Request |
Patch Schema (cps:org.onap.cps.ncmp.policy-executor:ncmp-patch-schema:1.0.0)
Name | Parent | Type | Example Value | Optional/Compulsory | Notes | |
---|---|---|---|---|---|---|
1 |
| data | String | F811AF64F5146DFC545EC60B73DE948E | Optional | Can be sent while cmHandle is used instead of alternateId NCMP will populate when available |
2 |
| data | String | ManagedElement=Kista/GNBDUFunction=1/UECC=1 | Optional | Remainder of FDN NCMP will populate when available |
3 |
| data | String | /Subnetwork=22/MeContext=Kista/ManagedElement=Kista/GNBDUFunction=1/UECC=1 | Required | Complete FDN representing the cm handle and the resource identifier ie point to the target of the change to 'CM-Handle' ?! |
4 |
| data | Object | {"Cell":[{"id":"Cell-id","attributes":{"administrativeState":"UNLOCKED"}}]} | Required | CM Change Request |
Delete Schema (cps:org.onap.cps.ncmp.policy-executor:ncmp-delete-schema:1.0.0)
Name | Parent | Type | Example Value | Optional/Compulsory | Notes | |
---|---|---|---|---|---|---|
1 |
| data | String | F811AF64F5146DFC545EC60B73DE948E | Optional | Can be sent while cmHandle is used instead of alternateId NCMP will populate when available |
2 |
| data | String | ManagedElement=Kista/GNBDUFunction=1/UECC=1 | Optional | Remainder of FDN NCMP will populate when available |
3 |
| data | String | /Subnetwork=22/MeContext=Kista/ManagedElement=Kista/GNBDUFunction=1/UECC=1 | Required | Complete FDN representing the cm handle and the resource identifier ie point to the target of the change to 'CM-Handle' ?! |
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
{
"decisionType": "allow",
"requests": [
{
"schema": "cps:org.onap.cps.ncmp.ploicy-executor:ncmp-create-schema:1.0.0",
"data": {
"cmHandleId": "F811AF64F5146DFC545EC60B73DE948E",
"resourceIdentifier": "GNBDUFunction=1/UECC=1",
"targetFdn": "/Subnetwork=22/MeContext=Kista/ManagedElement=Kista/GNBDUFunction=1/UECC=1",
"cmChangeRequest": {
"Cell": [
{
"id": "Cell-id",
"attributes": {
"administrativeState": "UNLOCKED"
}
}
]
}
}
}
]
} |
Output Parameters
Name | Parent | Type | Example | Optional/Compulsory | Notes | |
---|---|---|---|---|---|---|
1 | decisionId | body | String | 550e8400-e29b-41d4-a716-446655440000 | Required | UUIDUID |
2 | decision | body | String | deny | RequiredDeny | currently only 'Allow' and 'Deny' are supported (case sensitive ?!)supported values: allow, deny |
3 | message | body | String | to many updates | Optional |
How to use the Interface in NCMP
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
IF property "CONFLICT_MANAGER_CLIENT_ENABLED" is set to "true" THEN
DEFINE class NetworkCmProxyDataServiceInterceptor which EXTENDS NetworkCmProxyDataServiceImpl
INJECT ConflictManagerApiClient conflictManagerApiClient
CREATE defaultPermitOnError AS boolean
// Define a method named writeResourceDataPassThroughRunningForCmHandle that overrides the method from the parent class
METHOD writeResourceDataPassThroughRunningForCmHandle(cmHandleId, resourceIdentifier, operationType, requestData, dataType, authorization)
targetFdn = CALL createTargetFdn(cmHandleId)
evaluationRequest = CALL createEvaluationRequest(cmHandleId, resourceIdentifier, targetFdn, requestData)
TRY
evaluatedResponse = CALL conflictManagerApiClient.evaluateRequest(evaluationRequest)
RETURN CALL processResponseFromConflictManager(evaluatedResponse, evaluationRequest, operationType, requestData, dataType, authorization)
CATCH ResourceAccessException WITH e
CALL log.error(CONVERT e TO String)
RETURN CALL checkDefaultDecision(evaluationRequest, operationType, requestData, dataType, authorization)
END TRY
END METHOD
METHOD createTargetFdn(String cmHandleId)
ncmpServiceCmHandle = CALL getNcmpServiceCmHandle(cmHandleId)
dmiProperties = CALL getDmiProperties ON ncmpServiceCmHandle
CREATE targetFdn AS new StringJoiner
IF dmiProperties contains key "targetDnPrefix" AND dmiProperties contains key "targetNode" THEN
CALL add(dmiProperties.get(targetDnPrefix)) ON targetFdn
CALL add(dmiProperties.get(targetNode)) ON targetFdn
RETURN targetFdn
ELSE
THROW InvalidPropertyException WITH (CmHandle.class, cmHandleId, "missing targetDnPrefix or targetNode from cmHandleProperties")
END IF
END METHOD
METHOD createEvaluationRequest(cmHandleId, resourceIdentifier, targetFdn, requestData)
CREATE evaluationRequest AS new EvaluationRequest
CALL evaluationRequest.cmHandleId(cmHandleId)
CALL evaluationRequest.resourceIdentifier(resourceIdentifier)
CALL evaluationRequest.targetFdn(targetFdn)
CALL evaluationRequest.requestData(requestData)
END METHOD
METHOD checkDefaultDecision(evaluationRequest, operationType, requestData, dataType, authorization)
IF defaultPermitOnError IS true THEN
CALL log.info(""Failed to get response from Conflict Manager for fields: cmHandleId: {}, resourceIdentifier: {}, targetFDN: {}, requestData: {}, default decision is permit",
evaluationRequest.getCmHandleId(),
evaluationRequest.getResourceIdentifier(),
evaluationRequest.getTargetFdn(),
requestData)
RETURN super.writeResourceDataPassThroughRunningForCmHandle(evaluationRequest.getCmHandleId(),
evaluationRequest.getResourceIdentifier(), operationType, requestData, dataType, authorization)
ELSE
CALL log.info("Failed to get response from Conflict Manager for fields: cmHandleId: {}, resourceIdentifier: {}, targetFDN: {}, requestData: {}, default decision is deny",
evaluationRequest.getCmHandleId(),
evaluationRequest.getResourceIdentifier(),
evaluationRequest.getTargetFdn(),
requestData)
THROW DataInUseException WITH ("Change request denied by Conflict Manager for reason: failed to get response from Conflict Manager, default decision is deny.",
"Check logs for details.")
END METHOD
METHOD processResponseFromConflictManager(evaluatedResponse, evaluationRequest, operationType, requestData, dataType, authorization)
IF evaluatedResponse.getDecision() NOT NULL AND evaluatedResponse.getDecision() EQUALS ResponseDecisionEnum.PERMIT THEN
RETURN super.writeResourceDataPassThroughRunningForCmHandle(evaluationRequest.getCmHandleId(),
evaluationRequest.getResourceIdentifier(), operationType, requestData, dataType, authorization)
ELSE IF evaluatedResponse.getDecision() NOT NULL AND evaluatedResponse.getDecision() EQUALS ResponseDecisionEnum.DENY THEN
CALL log.info("Change request denied by Conflict Manager for fields cmHandleId: {}, resourceIdentifier: {}, targetFDN: {}, requestData: {}",
evaluationRequest.getCmHandleId(),
evaluationRequest.getResourceIdentifier(),
evaluationRequest.getTargetFdn(),
requestData)
THROW DataInUseException WITH ("Change request denied by Conflict Manager for reason: " + evaluatedResponse.getReason(), "Check logs for details.")
ELSE IF evaluatedResponse.getDecision() NOT NULL AND evaluatedResponse.getDecision() EQUALS ResponseDecisionEnum.PREEMPT THEN
CALL log.info("Change request preempt by Conflict Manager for fields cmHandleId: {}, resourceIdentifier: {}, targetFDN: {}, requestData: {}",
evaluationRequest.getCmHandleId(),
evaluationRequest.getResourceIdentifier(),
evaluationRequest.getTargetFdn(),
requestData)
RETURN super.writeResourceDataPassThroughRunningForCmHandle(evaluationRequest.getCmHandleId(), evaluationRequest.getResourceIdentifier(), operationType, requestData, dataType, authorization)
ELSE
RETURN CALL checkDefaultDecision(evaluationRequest, operationType, requestData, dataType, authorization)
END METHOD |