In essence, a native policy is a custom policy/rule implementation for a specific PDP engine such as: drools DRL rules, xacml XML policies or apex JSON policies.
Taking drools rules as one example, current usecases.drl used in PDP-D is a default DRL implementation for Control Loop operational policies. It is both a TOSCA Policy Type implementation and a native drools rule implementation since it is a set of rules that directly run in the PDP-D supporting the TOSCA onap.policies.Operational Policy Type. However, some policy authors might prefer to compose their own drools rules for certain features which are partially supported by the usecases.drl such as: changing the treatment of incoming event messages, adding custom timeout logic, or adding extra processing logic. Current policy framework does not provide an interface for such policy authors to bring in their own native rules. Hence, we need to come up with a solution in Frankfurt to bridge the gap.
Taking XACML as another example, some policy authors may want to add custom XACML policies to achieve new guard or coordination or even classification functionalities that do not require TOSCA.
1. Native Rule Development Guidelines
1.1 Drools Native Rules
1.1.1 DRL development
DRL development refers to the composition of drl file which contains one or more drools rules written in drools language. These drools rules work together to fulfill policy decision making logic required by new custom application.
Policy author should develop drl rules in IDE of choice, e.g. Eclipse/IntelliJ as well as necessary junit tests to ensure it can compile.
After drl rule development, policy author should submit composed rules for git review then deploy the new jar containing new drl rules to the existing nexus repos that hold the released artifacts currently supported by the runtime PDP-D engines.
1.1.2 Dependency JAR development
Dependency JAR development refers to the development of supportive java classes that will be used in drl rules. These dependency java classes could be the java models for I/O events and functional elements like eNodeB which may include necessary attributes of that element and operational functions/methods provided by that element, e.g. reboot. It could also be any other java class which has methods for processing input events and producing policy reactions, e.g. eventManager, operationManager. The drl rules will import these classes and use them in either condition or action part.
Dependency JAR developer should use development best practices/governance to test/deploy new and/or updated java artifacts to the nexus repo for drools PDP-D. These new java development should go through git review process and include necessary junit tests to make sure they will behave correctly as expected.
1.2 XACML XML
XACML Policy Designers can use a text or XML editor of their choice to design and test their XACML Policies. The Github:att/XACML project has tools and a GUI available for creating policies and testing those policies.
1.3 APEX JSON
APEX policy development includes three parts - develop the state machine transition using APEX language (i.e. .apex file), develop I/O event schema to each state (i.e. .avro files) and develop processing logic in each state/task (i.e. javascript files). APEX policy developer should follow best practices to develop APEX policies and submit for git review once they are done. Then APEX command line tool can be used to generate the executable JSON for PDP-A.
TBC with Apex team
2. Policy Lifecycle API CRUD Enhancements
In order to designate between native policy/rule types, the REST header "Content-Type" is configured for each PDP engines specific content.
| PDP Engine | Content-Type | Description |
|---|---|---|
| PDP-D: Drools | application/vnd.onap.drools+text application/vnd.onap.drools.mvn+xml | Drools DRL text files. Question: Does Drools have a custom content-type already?? Maven XML dependency specification for a java artifact containing drools rules. Does maven have a custom content-type?? |
| PDP-X: XACML | application/xacml+xml; version=3.0 | Per http://docs.oasis-open.org/xacml/xacml-rest/v1.0/cos01/xacml-rest-v1.0-cos01.html |
| PDP-A: Apex | application/vnd.onap.apex+json | Apex JSON policy files. TBC with Apex team |
2.1 PDP-D Content-Types
Two Content-Types can be used by policy authors to create native drools rules - "application/vnd.onap.drools+text" and "application/vnd.onap.drools.mvn+xml".
"application/vnd.onap.drools+text" refers to native drools drl text contents. When drools authors use this Content-Type in POST call, they only need to provide drl text contents into its payload. One payload example is shown as below:
One limitation of "application/vnd.onap.drools+text" Content-Type is, the payload only contains native drl contents without other dependency information (i.e. dependency artifacts) also required to load into drools memory to support execution of the native rules. In aforementioned example, "SampleMsEvent", "Enodeb" and "Logger" are from other dependency artifacts. When Drools PDP-D receives this set of native rules deployed from PAP, it does not know how many dependencies to load into memory along with the rule itself to support the rule execution. If the deployed rules cannot be executed due to missing dependencies, PAP policy deployment API should return 400 Bad Request.
To bridge the gap, one solution is to use "application/vnd.onap.drools+text" Content-Type only when there is modification to the rules (i.e. updating the rules) and the new updates will not introduce new dependency. Given a set of rules are already running in PDP-D and all required dependencies are loaded as well, now we have new requirement that means to change a logic in one rule, e.g. changing to reset enodeb other than reboot. All I want to modify is line #34 in above example, changing enb.reboot() to enb.reset() given both reboot() and reset() are supported in org.onap.policy.controlloop.ran.Enodeb dependency model. In this case, I can call the PUT call and use "application/vnd.onap.drools+text" Content-Type to update the rules.
Now the question is, how to bring in the new set of rules for a new application which has never run before in PDP-D? The second Content-Type "application/vnd.onap.drools.mvn+xml" is designed for this purpose. When policy author calls the POST call and use "application/vnd.onap.drools.mvn+xml" Content-Type, what they need to provide in the payload are, Maven XML dependency specification for a java artifact that contains new drl rules. Policy author needs to make sure that specified java artifact in this payload is already deployed to nexus repo used by runtime PDP-D engine before calling the POST API. Otherwise, this POST API should return 400 Bad Request if specified artifact is missing in nexus.
To be discuss, where should we put this artifact existence check, in API or PAP ???
One example payload with "application/vnd.onap.drools.mvn+xml" Content-Type is shown as below, reusing aforementioned rule example.
2.2 PDP-X Content-Types
"application/xacml+xml; version=3.0" is designed to be the custom Content-Type for XACML native policy. Typically, it is an XML with XACML reserved keywords. For native XACML policy CRUD, this Content-Type would be used to encode the policy content. Below is one example of native XACML policy under "application/xacml+xml; version=3.0" Content-Type.
2.3 PDP-A Content-Types
TBA
2.4 Endpoint Details
The Policy Lifecycle API will need to support new endpoints that consume these PDP specific Content-Type's as well as the ability to save them to the database.
| HTTP Method | Endpoint | Content-Type | Description | Example |
|---|---|---|---|---|
| POST | /natives | application/vnd.onap.drools.mvn+xml | Creates a native drools policy. Returns the id, version and created drl contents. Note: policyId is the same as <artifactId> specified in the payload; version is the same as <version> specified in the payload; <groupId> specified in the payload could be a fixed one for all native drools policies, e.g. org.onap.policy.native. | 200 {
"policyId": "example-policy",
"version": "1.0.0",
"pdpType": "drools"
}
|
| PUT | /natives/{policyId} | application/vnd.onap.drools+text | Updates a native drools policy. Return the id, version and updated drl contents. Note: version is an auto-increased version off the original one. For example. the original version is "1.0.0". After this PUT call, the version returned could be "1.0.1". | 200 {
"policyId": "example-policy",
"version": "1.0.1",
"pdpType": "drools"
}
|
| POST/PUT | /natives/{policyId} | application/xacml+xml; version=3.0 | Create a native xacml policy | 200 {
"policyId": "example-policy",
"version": "1.0.1",
"pdpType": "xacml"
}
|
| POST/PUT | /natives/{policyId} | application/vnd.onap.apex+json | Create a native apex policy | 200 {
"policyId": "example-policy",
"version": "1.0.1",
"pdpType": "apex"
}
|
| GET | /natives | application/json application/yaml | Returns a list of ID/Version of native policies | 200 {
"policies": [
{ "policyId": "id-1",
"version": "1.0.0",
"pdpType": "drools"
},
{
"policyId": "id-2",
"version": "1.1.0",
"pdpType": "xacml"
},
{
"policyId": "id-3",
"version": "1.2.0",
"pdpType": "apex"
}
]
}
|
| GET | /natives/{policyId} | application/json application/yaml | Get a list of versions | 200 {
"policies": [
{ "policyId": "id-1",
"version": "1.0.0",
"pdpType": "drools"
},
{
"policyId": "id-1",
"version": "1.0.1",
"pdpType": "drools"
},
{
"policyId": "id-1",
"version": "1.0.2",
"pdpType": "drools"
}
]
}
|
| GET | /natives/{policyId}/versions/{policyVersion} | application/vnd.onap.drools+text application/xacml+xml; version=3.0 application/vnd.onap.apex+json | Get a particular version | 200 policy text in DRL/XACML-XML/APEX-JSON |
| GET | /natives/{policyId}/versions/latest | application/json application/yaml | Get the latest version | 200 {
"policyId": "example-policy",
"version": "1.0.1",
"pdpType": "drools"
}
|
| (optional) GET | /natives/{policyId}/versions/deployed | application/json application/yaml | Get the deployed version(s) in each PDP group | 200 {
("pdpGroup1","1.0.0"): [
{
"policyId": "example-policy",
"version": "1.0.0",
"pdpType": "drools"
},
{
"policyId": "example-policy",
"version": "1.1.0",
"pdpType": "drools"
}
]
}
|
| DELETE | /natives/{policyId}/versions/{policyVersion} | application/vnd.onap.drools+text application/xacml+xml; version=3.0 application/vnd.onap.apex+json | Delete a particular version | 200 policy text in DRL/XACML-XML/APEX-JSON |
A safety net should be implemented for DELETE. That is, if a policy version is deployed in any PDP, it cannot be deleted. A 409 Conflict should be returned along with message saying this policy id:version is deployed in which PDP.
3. PAP Enhancements
PDP Engines must now register with the PAP the native Content-Type's they support in order for policies to be deployed by the PAP engine to the PDP's. This will require an additional parameter in the Group Deploy/Undeploy to list the supported Content-Type's for the PDP engine. The proposal is to add a field "supportedContentTypes".
3.1 Example of PDP Register
Only change needed is to add "supportedContentTypes" to PDP status message when it registers itself with PAP. For example
Question: Do we need a version attached to the native content-type? Might be easier to keep it around.
3.2 Example PDP Group Deploy
Only change needed is to add "supportedContentTypes in each "pdpSubGroups" to indicate what kind of native policies it can support. Typically, Drools PDP will support both "application/vnd.onap.drools+text" and "application/vnd.onap.drools.mvn+xml". XACML PDP will need to support "application/xacml+xml; version=3.0" and APEX PDP will need to support "application/vnd.onap.apex+json". Likewise, the same "supportedContentTypes" also needs to be added into PDP group query return.
Below is one example to deploy a PDP group.
3.3 Deploy/Undeploy API
No change is envisioned on current deploy/undeploy API. Still, only policyId and version are needed to tell PAP to deploy/undeploy a native policy.
4. PDP Changes
Each PDP will need to be able to support native policies being deploy/undeployed to it as done today.
4.1 Drools PDP
Drools PDP will need to be able to instantiate a new controller instance and then ingest native DRL to that controller. First change needed is to expose telemetry API to external users, particularly the one being used to create a new controller. One example is shown as below
curl -k --user "demo@people.osaaf.org:demo123456!" -X POST --data @example-controller.rest.json --header "Content-Type: application/json" https://{ip or hostname}:9696/policy/pdp/engine/controllers
In addition, when drools PDP receives native policy deployed from PAP, given the deployment contains groupId, artifactId and version, drools PDP will need to pull the java artifact that contains drl rules as well as corresponding dependency artifacts then place them in local m2 repo. When a new controller shown above is created, it will scan local m2, search for the artifact with specified "rules.groupId", "rules.artifactId" and "rules.version" and load its contained drl rules into drools memory.
On the other hand, if drools PDP receives a request from PAP to undeploy a native policy, it will need to disable/delete the corresponding controller and remove the corresponding artifact from local m2 repo. Deleting a controller can be realized by calling exposed telemetry API. For example:
curl -k --user "demo@people.osaaf.org:demo123456!" -X DELETE https://{ip or hostname}:9696/policy/pdp/engine/controllers/example-controller
4.2 XACML PDP
XACML PDP will need to be able to ingest a XACML XML Policy directly. One suggestion is to create an application specifically for the XACML natives rules by default. The opportunity exists where a policy designer could create a specific application that supports native XACML policies (with or without TOSCA Policy Types as an option) and uses the grouping of PDPs to differentiate itself from the default XACML native rule application. The XACML PDP should also be enhanced to support configuring of applications in order to provide flexibility to the policy designers as to where all of its possible policy types and content types are deployed.
With regards to the Decision API supported by XACML, that api can be enhanced to support XACML XML requests/responses directly.
Some scenarios are listed as below:
Scenario #1: Use pre-defined XACML policies only (i.e. Guard, Coordination, Optimization, Monitoring)
This scenario is already supported today through some pre-build XACML applications which support Guard, Coordination(W.I.P), Optimization and Monitoring. We provide TOSCA Policy Types for such types of XACML policies. XACML author can use lifecyle APIs to CRUD corresponding TOSCA policies which will then be deployed to XACML PDP. XACML PDP will be able to translate these TOSCA policies into low level native XACML XML policies and then enforce them.
Scenario #2: Use native XACML policies only
This scenario requires a new XACML application to be built which particularly handles native XACML policies only.
Scenario #3: Use pre-defined XACML policies and native XACML policies together
This scenario is the most complicated one. For new use case, XACML policy author might need to use both existing types of XACML policies, e.g. guard, together with newly composed native XACML XML policies, e.g. custom access control rules. Perhaps we need to build another new XACML application for this combination. More details need to be figured out, e.g. do we need a new TOSCA policy type for this combination? how to combine the low level XACML XML policies together? what is the combining algorithm we should use? etc. etc.
4.3 Apex PDP
Apex PDP will need to be able to ingest custom Apex JSON policies. TBC with that team - may already be well-supported.
5. Sequence flows for native policy design, deployment and enforcement
5.1 Drools native policies supported by the PDP-D engine
Create native DRL
Update native DRL
Deploy native DRL
Undeploy native DRL
Delele native DRL
5.2 XACML native policies supported by the PDP-X engine
5.2.1 Getting XACML native policies into the Policy Framework via the Policy Lifecycle API CRUD
5.2.2 Deploying/Undeploying XACML native policies using the Policy PAP API
