...
It is worthwhile to note that specifying Drools controller configuration in native policy is optional, which means it can be present or not. If they are not present, current native policy will be assigned to a default Drools controller that is specified in the helm charts and instantiated in Drools PDP when the PDP is up. If policy designers are aware of which existing Drools controller can work for the new native policy, they can specify the existing controller name only without replicating other configuration details. Alternatively, policy designers can also change the Drools controller configurations at runtime by calling exposed telemetry API, e.g. change a source/sink topic, if the current/default Drools controller setup cannot fit the needs.
...
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 teamThe detailed documentation can be found here - https://onap.readthedocs.io/en/latest/submodules/policy/parent.git/docs/apex/apex.html
2. Policy Lifecycle API CRUD Enhancements
...
| Code Block | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
tosca_definitions_version: tosca_simple_yaml_1_0_0
policy_types:
onap.policies.Native:
derived_from: tosca.policies.Root
description: a base policy type for all native PDP policies
version: 1.0.0
onap.policies.native.Drools:
derived_from: onap.policies.Native
description: a policy type for native drools policies
version: 1.0.0
properties:
rule_artifact:
type: onap.datatypes.native.rule_artifact
required: true
description: specifies rule artifact pointer
drools_controller:
type: onap.datatypes.native.drools_controller
required: truefalse
description: specifies information for drools controller instantiation
data_types:
onap.datatypes.native.rule_artifact:
derived_from: tosca.datatypes.Root
properties:
groupId:
type: string
required: true
artifactId:
type: string
required: true
version:
type: string
required: true
onap.datatypes.native.drools_controller:
derived_from: tosca.datatypes.Root
properties:
controllerName:
type: string
required: true
sourceTopicsisNewController:
type: listboolean
required: true
entry_schemadescription: a flag to indicate if the controller is a new one to instantiate or not
type: onap.datatypes.native.dmaap_config sinkTopicssourceTopics:
type: list
required: truefalse
entry_schema:
type: onap.datatypes.native.dmaap_config
onap.datatypes.native.dmaap_config: derived_sinkTopics:
type: list
required: false
entry_schema:
type: onap.datatypes.native.dmaap_config
onap.datatypes.native.dmaap_config:
derived_from: tosca.datatypes.Root
properties:
topicName:
type: string
required: true
serialization:
type: list
required: true
entry_schema:
type: onap.datatypes.native.dmaap.serialization
onap.datatypes.native.dmaap.serialization:
derived_from: tosca.datatypes.Root
properties:
eventCanonicalName:
type: string
required: true
eventFilter:
type: string
required: false
customSerializer:
type: string
required: false |
...
| Code Block | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
tosca_definitions_version: tosca_simple_yaml_1_0_0
topology_template:
policies:
-
Example_policy_name:
type: onap.policies.native.Drools
version: 1.0.0
metadata:
policy-id: Example_policy_name
properties:
rule_artifact:
groupId: org.onap.policy.native
artifactId: example_controlloop
version: 1.0.0-SNAPSHOT
drools_controller:
controllerName: example_controller_name
sourceTopicsisNewController: true
sourceTopics:
- -
topicName: POLICY_INPUT topicName: POLICY_INPUT
serialization:
-
eventCanonicalName: org.onap.policy.controlloop.event.ControlLoopEvent
eventFilter: [?($.closedLoopControlName == 'example_controlloop_name')]
customSerializer: org.onap.policy.controlloop.utils.serializer,gson
-
topicName: SDNR_TO_POLICY
serialization:
-
eventCanonicalName: org.onap.policy.controlloop.event.Response
eventFilter: [?($.closedLoopControlName == 'example_controlloop_name' && $.action == 'example_action')]
customSerializer: org.onap.policy.controlloop.utils.serializer,gson
sinkTopics:
-
topicName: POLICY_TO_SDNR
serialization:
-
eventCanonicalName: org.onap.policy.controlloop.event.Request
eventFilter: [?($.closedLoopControlName == 'example_controlloop_name' && $.action == 'example_action')]
customSerializer: org.onap.policy.controlloop.utils.serializer,gson |
...
| Code Block | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
tosca_definitions_version: tosca_simple_yaml_1_0_0
policy_types:
onap.policies.Native:
derived_from: tosca.policies.Root
description: a base policy type for all native PDP policies
version: 1.0.0
onap.policies.native.Xacml:
derived_from: onap.policies.Native
description: a policy type for native xacml policies
version: 1.0.0
metadataproperties:
encodingpolicy: URL
propertiestype: String
policy: required: true
typedescription: StringThe XML XACML 3.0 PolicySet or Policy
required: true metadata:
description: The XML XACML 3.0 PolicySet orencoding: PolicyURL |
2.2.2 TOSCA Policy for Native XACML Rules
...
Question: do we need to return native policy contents, i.e. DRL or XACML XML when GET call is invoked? If not, what if end user wants to view native policy rules???
2.3 Native Apex Policy Support
2.3.
...
PDP Engines must now register with PAP the new policy types for native policies they support in order for policies to be deployed by PAP to the PDP's. This will require an additional entry to be added into supported policy types list to indicate which native policy type each specific PDP engine can support.
3.1 Example of PDP Register
Only change needed is to add a new supported policy type to PDP status message when it registers itself with PAP. For XACML PDP, new policy type "onap.policies.controlloop.native.Xacml" should be added. Likewise, new policy type "onap.policies.controlloop.native.Drools" should be added when Drools PDP registers itself with PAP. For example
| Code Block | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
{
"pdpType": "xacml",
"state": "PASSIVE",
"healthy": "HEALTHY",
"supportedPolicyTypes": [
{
"name": "onap.Monitoring",
"version": "1.0.0"
},
{
"name": "onap.policies.monitoring.cdap.tca.hi.lo.app",
"version": "1.0.0"
},
{
"name": "onap.policies.monitoring.dcaegen2.collectors.datafile.datafile-app-server",
"version": "1.0.0"
},
{
"name": "onap.policies.monitoring.docker.sonhandler.app",
"version": "1.0.0"
},
{
"name": "onap.policies.controlloop.guard.FrequencyLimiter",
"version": "1.0.0"
},
{
"name": "onap.policies.controlloop.guard.MinMax",
"version": "1.0.0"
},
{
"name": "onap.policies.controlloop.guard.Blacklist",
"version": "1.0.0"
},
{
"name": "onap.policies.controlloop.guard.coordination.FirstBlocksSecond",
"version": "1.0.0"
},
{
"name": "onap.policies.optimization.AffinityPolicy",
"version": "1.0.0"
},
{
"name": "onap.policies.optimization.DistancePolicy",
"version": "1.0.0"
},
{
"name": "onap.policies.optimization.HpaPolicy",
"version": "1.0.0"
},
{
"name": "onap.policies.optimization.OptimizationPolicy",
"version": "1.0.0"
},
{
"name": "onap.policies.optimization.PciPolicy",
"version": "1.0.0"
},
{
"name": "onap.policies.optimization.QueryPolicy",
"version": "1.0.0"
},
{
"name": "onap.policies.optimization.SubscriberPolicy",
"version": "1.0.0"
},
{
"name": "onap.policies.optimization.Vim_fit",
"version": "1.0.0"
},
{
"name": "onap.policies.optimization.VnfPolicy",
"version": "1.0.0"
},
{
"name": "onap.policies.controlloop.native.Xacml",
"version": "1.0.0"
}
],
"policies": [],
"messageName": "PDP_STATUS",
"requestId": "77f42778-f19a-47a6-a9a1-984cbb125d96",
"timestampMs": 1571244733313,
"name": "FLCDTL02JH7358"
} |
| Code Block | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
{
"pdpType": "drools",
"state": "PASSIVE",
"healthy": "HEALTHY",
"supportedPolicyTypes": [
{
"name": "onap.policies.controlloop.Operational",
"version": "1.0.0"
},
{
"name": "onap.policies.controlloop.native.Drools",
"version": "1.0.0"
}
],
"policies": [],
"messageName": "PDP_STATUS",
"requestId": "8ae9fe00-8979-460f-83b2-92d7bd517c34",
"timestampMs": 1571244753326,
"name": "XGIQPQ96FL9182"
} |
3.2 Example PDP Group Deploy
...
1 Policy Type for Native Apex Policy
Below is the policy type defined to support native apex policies.
| Code Block | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
tosca_definitions_version: tosca_simple_yaml_1_0_0,
policy_types:
onap.policies.Native:
derived_from: tosca.policies.Root
description: a base policy type for all native PDP policies
version: 1.0.0
onap.policies.native.Apex:
derived_from: onap.policies.Native
description: a policy type for native apex policies
version: 1.0.0
properties:
engine_service:
type: onap.datatypes.native.apex.EngineService
description: APEX Engine Service Parameters
inputs:
type: map
description: Inputs for handling events coming into the APEX engine
entry_schema:
type: onap.datatypes.native.apex.EventHandler
outputs:
type: map
description: Outputs for handling events going out of the APEX engine
entry_schema:
type: onap.datatypes.native.apex.EventHandler
environment:
type: list
description: Envioronmental parameters for the APEX engine
entry_schema:
type: onap.datatypes.native.apex.Environment
data_types:
onap.datatypes.native.apex.EngineService:
derived_from: tosca.datatypes.Root
properties:
name:
type: string
description: Specifies the engine name
required: false
default: "ApexEngineService"
version:
type: string
description: Specifies the engine version in double dotted format
required: false
default: "1.0.0"
id:
type: int
description: Specifies the engine id
required: true
instance_count:
type: int
description: Specifies the number of engine threads that should be run
required: true
deployment_port:
type: int
description: Specifies the port to connect to for engine administration
required: false
default: 1
policy_model_file_name:
type: string
description: The name of the file from which to read the APEX policy model
required: false
default: ""
policy_type_impl:
type: string
description: The policy type implementation from which to read the APEX policy model
required: false
default: ""
periodic_event_period:
type: string
description: The time interval in milliseconds for the periodic scanning event, 0 means don't scan
required: false
default: 0
engine:
type: onap.datatypes.native.apex.engineservice.Engine
description: The parameters for all engines in the APEX engine service
required: true
onap.datatypes.native.apex.EventHandler:
derived_from: tosca.datatypes.Root
properties:
name:
type: string
description: Specifies the event handler name, if not specified this is set to the key name
required: false
carrier_technology:
type: onap.datatypes.native.apex.CarrierTechnology
description: Specifies the carrier technology of the event handler (such as REST/Web Socket/Kafka)
required: true
event_protocol:
type: onap.datatypes.native.apex.EventProtocol
description: Specifies the event protocol of events for the event handler (such as Yaml/JSON/XML/POJO)
required: true
event_name:
type: string
description: Specifies the event name for events on this event handler, if not specified, the event name is read from or written to the event being received or sent
required: false
event_name_filter:
type: string
description: Specifies a filter as a regular expression, events that do not match the filter are dropped, the default is to let all events through
required: false
synchronous_mode:
type: bool
description: Specifies the event handler is syncronous (receive event and send response)
required: false
default: false
synchronous_peer:
type: string
description: The peer event handler (output for input or input for output) of this event handler in synchronous mode, this parameter is mandatory if the event handler is in synchronous mode
required: false
default: ""
synchronous_timeout:
type: int
description: The timeout in milliseconds for responses to be issued by APEX torequests, this parameter is mandatory if the event handler is in synchronous mode
required: false
default: ""
requestor_mode:
type: bool
description: Specifies the event handler is in requestor mode (send event and wait for response mode)
required: false
default: false
requestor_peer:
type: string
description: The peer event handler (output for input or input for output) of this event handler in requestor mode, this parameter is mandatory if the event handler is in requestor mode
required: false
default: ""
requestor_timeout:
type: int
description: The timeout in milliseconds for wait for responses to requests, this parameter is mandatory if the event handler is in requestor mode
required: false
default: ""
onap.datatypes.native.apex.CarrierTechnology:
derived_from: tosca.datatypes.Root
properties:
label:
type: string
description: The label (name) of the carrier technology (such as REST, Kafka, WebSocket)
required: true
plugin_parameter_class_name:
type: string
description: The class name of the class that overrides default handling of event input or output for this carrier technology, defaults to the supplied input or output class
required: false
onap.datatypes.native.apex.EventProtocol:
derived_from: tosca.datatypes.Root
properties:
label:
type: string
description: The label (name) of the event protocol (such as Yaml, JSON, XML, or POJO)
required: true
event_protocol_plugin_class:
type: string
description: The class name of the class that overrides default handling of the event protocol for this carrier technology, defaults to the supplied event protocol class
required: false
onap.datatypes.native.apex.Environmental:
derived_from: tosca.datatypes.Root
properties:
name:
type: string
description: The name of the environment variable
required: true
value:
type: string
description: The value of the environment variable
required: true
onap.datatypes.native.apex.engineservice.Engine:
derived_from: tosca.datatypes.Root
properties:
context:
type: onap.datatypes.native.apex.engineservice.engine.Context
description: The properties for handling context in APEX engines, defaults to using Java maps for context
required: false
executors:
type: map
description: The plugins for policy executors used in engines such as javascript, MVEL, Jython
required: true
entry_schema:
description: The plugin class path for this policy executor
type: string
onap.datatypes.native.apex.engineservice.engine.Context:
derived_from: tosca.datatypes.Root
properties:
distributor:
type: onap.datatypes.native.apex.Plugin
description: The plugin to be used for distributing context between APEX PDPs at runtime
required: false
schemas:
type: map
description: The plugins for context schemas available in APEX PDPs such as Java and Avro
required: false
entry_schema:
type: onap.datatypes.native.apex.Plugin
locking:
type: onap.datatypes.native.apex.plugin
description: The plugin to be used for locking context in and between APEX PDPs at runtime
required: false
persistence:
type: onap.datatypes.native.apex.Plugin
description: The plugin to be used for persisting context for APEX PDPs at runtime
required: false
onap.datatypes.native.apex.Plugin:
derived_from: tosca.datatypes.Root
properties:
name:
type: string
description: The name of the executor such as Javascript, Jython or MVEL
required: true
plugin_class_name:
type: string
description: The class path of the plugin class for this executor |
NOTE: The native policy type is already loaded in policy framework during installation, hence a user can directly deploy native policies in respective pdp engines without a need to create policy type first.
3. PAP Enhancements
PDP Groups must be provisioned to support the new policy types for native policies in order for policies to be deployed by PAP to the PDP's. This will require an additional entry to be added into supported policy types list to indicate which native policy type each specific PDP Subgroup can support.
3.1 PDP Group & SubGroup
The native policy type should be added into supported policy types list to indicate which type of native policies each pdpSubGroup PDP SubGroup can support.
Below is one example to deploy a PDP groupof PDP Group with native policies support for xacml, drools & apex engines.
| Code Block | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
{
"groups": [
{
"name": "defaultGroup",
"description": "The default group that registers all supported policy types and pdps.",
"pdpGroupState": "ACTIVE",
"properties": {},
"pdpSubgroups": [
{
"pdpType": "apex",
"supportedPolicyTypes": [
{
"name": "onap.policies.controlloop.operational.Apex",
"version": "1.0.0"
},
{
"name": "onap.policies.controlloop.native.Apex",
"version": "1.0.0"
}
],
"policies": [],
"currentInstanceCount": 0,
"desiredInstanceCount": 1,
"properties": {},
"pdpInstances": [
{
"instanceId": "apex_35",
"pdpState": "ACTIVE",
"healthy": "HEALTHY",
"message": "Pdp Heartbeat"
}
]
},
{
"pdpType": "drools",
"supportedPolicyTypes": [
{
"name": "onap.policies.controlloop.Operational",
"version": "1.0.0"
},
{
"name": "onap.policies.controlloop.native.Drools",
"version": "1.0.0"
}
],
"policies": [],
"currentInstanceCount": 0,
"desiredInstanceCount": 1,
"properties": {},
"pdpInstances": [
{
"instanceId": "dev-policy-drools-0",
"pdpState": "ACTIVE",
"healthy": "HEALTHY"
}
]
},
{
"pdpType": "xacml",
"supportedPolicyTypes": [
{
"name": "onap.policies.controlloop.guard.FrequencyLimiter",
"version": "1.0.0"
},
{
"name": "onap.policies.controlloop.guard.MinMax",
"version": "1.0.0"
},
{
"name": "onap.policies.controlloop.guard.Blacklist",
"version": "1.0.0"
},
{
"name": "onap.policies.controlloop.guard.coordination.FirstBlocksSecond",
"version": "1.0.0"
},
{
"name": "onap.Monitoring",
"version": "1.0.0"
},
{
"name": "onap.policies.monitoring.cdap.tca.hi.lo.app",
"version": "1.0.0"
},
{
"name": "onap.policies.monitoring.dcaegen2.collectors.datafile.datafile-app-server",
"version": "1.0.0"
},
{
"name": "onap.policies.monitoring.docker.sonhandler.app",
"version": "1.0.0"
},
{
"name": "onap.policies.optimization.AffinityPolicy",
"version": "1.0.0"
},
{
"name": "onap.policies.optimization.DistancePolicy",
"version": "1.0.0"
},
{
"name": "onap.policies.optimization.HpaPolicy",
"version": "1.0.0"
},
{
"name": "onap.policies.optimization.OptimizationPolicy",
"version": "1.0.0"
},
{
"name": "onap.policies.optimization.PciPolicy",
"version": "1.0.0"
},
{
"name": "onap.policies.optimization.QueryPolicy",
"version": "1.0.0"
},
{
"name": "onap.policies.optimization.SubscriberPolicy",
"version": "1.0.0"
},
{
"name": "onap.policies.optimization.Vim_fit",
"version": "1.0.0"
},
{
"name": "onap.policies.optimization.VnfPolicy",
"version": "1.0.0"
},
{
"name": "onap.policies.controlloop.native.Xacml",
"version": "1.0.0"
}
],
"policies": [],
"currentInstanceCount": 1,
"desiredInstanceCount": 1,
"properties": {},
"pdpInstances": [
{
"instanceId": "dev-policy-policy-xacml-pdp-558c478477-g85jl",
"pdpState": "ACTIVE",
"healthy": "HEALTHY"
}
]
}
]
}
]
} |
3.
...
2 Deploy/Undeploy API
No change is envisioned on current deploy/undeploy API. Still, only policy-id and version are needed to tell PAP to deploy/undeploy a native policy.
...
Each PDP will need to be able to support native policies being deploy/undeployed to it as done today.
4.1 Drools PDP
On one hand, Drools PDP will need to parse the information encoded in the TOSCA policy with native Drools JAR pointer and Drools controller configuration which is deployed from PAPdeployed from PAP in terms of native DRL JAR GAV (GroupId, ArtifactId, Version) information and Drools controller configuration if present. It will then go to the nexus to pull the native DRL JAR and corresonding dependencies. If the Drools controller configuration is present, Drools PDP needs to know first if it is a new controller to instantiate or reusing an existing one by parsing the "isNewController" flag. If reusing an existing one, what Drools PDP needs to do is just assign the native DRL JAR and corresonding dependencies . A to that controller. Otherwise, a new Drools controller instance should be instantiated using the configuration configurations included in the deployed TOSCA policyproperties. The new Drools controller should be able to load the native DRL and corresponding supportive facts into Drools memory to execute native DRLwork memory for rule execution.
On the other hand, when Drools PDP receives a request to undeploy a native policy, it should be able to disable corresponding Drools controller and clean up the related facts from the memory.facts from the memory.
Another thread of extension needed is to expose the telemetry API used to manage the lifecycle of Drools controller, which is to facilitate those policy designers who want to change controller setup at runtime. Current telemetry API can only be called from within policy container. One example is shown below:
| Code Block |
|---|
curl -k --silent --user ${TELEMETRY_USER}:${TELEMETRY_PASSWORD} -X POST --data @${json} --header "Content-Type: application/json" \
https://localhost:${TELEMETRY_PORT}/policy/pdp/engine/controllers |
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 are deployed.
...
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-supportedalready supports the native policies created using the policy type defined in section 2.3.1 above.
5. Sequence flows for native policy design, deployment and enforcement
...