This page shows how the Policy Design and API Flow to/from the PAP and PDP's will work to support Model Driven Control Loops in Dublin.
The figure below shows the Artifacts (Blue) in the ONAP Policy Framework, the Activities (Yellow) that manipulate them, and important components (Pink) that interact with them.
Please see the TOSCA Policy Primer page for an introduction to TOSCA policy concepts.
TOSCA defines a PolicyType, the definition of a type of policy that can be applied to a service. It also defines a Policy, the definition of an instance of a policy. In the Policy Framework, we must handle and manage these TOSCA definitions and tie them to real implementations of policies that can run on PDPs.
The diagram above outlines how this is achieved. Each TOSCA PolicyType must have a corresponding PolicyTypeImpl in the Policy Framework. The TOSCA PolicyType definition is used to create a TOSCA Policy definition, either directly by the Policy Framework, by CLAMP, or by some other system. Once the Policy artifact exists, it can be used together with the PolicyTypeImpl artifact to create a PolicyImpl artifact. A PolicyImpl artifact is an executable policy implementation that can run on a PDP.
The TOSCA PolicyType artifact defines the external characteristics of the policy; defining its properties, the types of entities it acts on, and its triggers. A PolicyTypeImpl artifact is an XACML, Drools, or APEX implementation of that policy definition. PolicyType and PolicyTypeImpl artifacts may be preloaded, may be loaded manually, or may be created using the Lifecycle API. Alternatively, PolicyType definitions may be loaded over the Lifecycle API for preloaded PolicyTypeImpl artifacts.
The TOSCA Policy artifact is used internally by the Policy Framework, or is input by CLAMP or other systems. This artifact specifies the values of the properties for the policy and specifies the specific entities the policy acts on. Policy Design uses the TOSCA Policy artifact and the PolicyTypeImpl artifact to create an executable PolicyImpl artifact.
1 Policy Types
Policy Type Design manages TOSCA PolicyType artifacts and their PolicyTypeImpl implementations.
TOSCA PolicyType may ultimately be defined by the modeling team but for now are defined by the Policy Framework project. Various editors and GUIs are available for creating PolicyTypeImpl implementations. However, systematic integration of PolicyTypeImpl implementation is outside the scope of the ONAP Dublin release.
The PolicyType definitions and implementations listed below are preloaded and are always available for use in the Policy Framework.
| Policy Type | Description |
|---|---|
| onap.policies.Monitoring | Overarching model that supports Policy driven DCAE microservice components used in a Control Loops |
| onap.policies.controlloop.Operational | Used to support actor/action operational policies for control loops |
| onap.policies.controlloop.Guard | Control Loop guard policies for policing control loops |
| onap.policies.controlloop.Coordination | Control Loop Coordination policies to assist in coordinating multiple control loops at runtime |
1.1 onap.policies.Monitoring Policy Type
This is a base Policy Type that supports Policy driven DCAE microservice components used in a Control Loops. The implementation of this Policy Type is developed using the XACML PDP to support question/answer Policy Decisions during runtime for the DCAE Policy Handler.
The PolicyTypeImpl implementation of the onap.policies.Montoring Policy Type is generic to support definition of TOSCA PolicyType artifacts in the Policy Framework using the Policy Type Design API. Therefore many TOSCA PolicyType artifacts will use the same PolicyTypeImpl implementation with different property types and towards different targets. This allows dynamically generated DCAE microservice component Policy Types to be created at Design Time.
DCAE microservice components can generate their own TOSCA PolicyType using TOSCA-Lab in SDC (Stretch Goal) or can do so manually.
1.2 onap.policies.controlloop.Operational Policy Type
This policy type is used to support actor/action operational policies for control loops. There are two types of implementations for this policy type
- Existing Drools implementations that supports runtime Control Loop actions taken on components such as SO/APPC/VFC/SDNC/SDNR
- New implementations using APEX to support Control Loops.
TODO: Operational Policy Model Parameter Schema for Drools
TODO: Operational Policy Model Parameter Schema for APEX
1.3 onap.policies.controlloop.Guard Policy Type
This policy type is the the type definition for Control Loop guard policies for frequency limiting, blacklisting and min/max guards to help protect runtime Control Loop Actions from doing harm to the network. This policy type is developed using the XACML PDP to support question/answer Policy Decisions during runtime for the Drools and APEX onap.controlloop.Operational policy type implementations.
The base schema is defined as below:
As with onap.policies.Monitoring policy type, the PolicyTypeImpl implementation of the onap.policies.controlloop.Guard Policy Type is generic to support definition of TOSCA PolicyType artifacts in the Policy Framework using the Policy Type Design API.
The derived Policy Type definitions below are preloaded in the Policy Framework.
1.3.1 onap.policies.controlloop.Guard.FrequencyLimiter Policy Type
1.3.2 onap.policies.controlloop.Guard.Blacklist Policy Type
1.3.3 onap.policies.controlloop.Guard.MinMax Policy Type
1.3.4 onap.policies.controlloop.Coordination Policy Type (STRETCH)
This policy type defines Control Loop Coordination policies to assist in coordinating multiple control loops during runtime. This policy type is developed using XACML PDP to support question/answer policy decisions at runtime for the onap.policies.controlloop.operational policy types.
2 PDP Deployment and Registration with PAP
The unit of execution and scaling in the Policy Framework is a PolicyImpl entity. A PolicyImpl entity runs on a PDP. As is explained above a PolicyImpl entity is a PolicyTypeImpl implementation parameterized with a TOSCA Policy.
In order to achieve horizontal scalability, we group the PDPs running instances of a given PolicyImpl entity logically together into a PDPSubGroup. The number of PDPs in a PDPSubGroup can then be scaled up and down using Kubernetes. In other words, all PDPs in a subgroup run the same PolicyImpl, that is the same policy template implementation (in XACML, Drools, or APEX) with the same parameters.
The figure above shows the layout of PDPGroup and PDPSubGroup entities. The figure shows examples of PDP groups for Control Loop and Monitoring policies on the right.
The health of PDPs is monitored by the PAP in order to alert operations teams managing policy. The PAP manages the life cycle of policies running on PDPs.
The table below shows the methods in which PolicyImpl entities can be deployed to PDP Subgroups
| Method | Description | Advantages | Disadvantages |
|---|---|---|---|
| Cold Deployment | The PolicyImpl (PolicyTypeImpl and TOSCA Policy) are predeployed on the PDP. The PDP is fully configured and ready to execute when started. PDPs register with the PAP when they start, providing the PolicyImpl they have been predeployed with. | No run time configuration required and run time administration is simple. | Very restrictive, no run time configuration of PDPs is possible. |
| Warm Deployment | The PolicyTypeImpl entity is predeployed on the PDP. A TOSCA Policy may be loaded at startup. The PDP may be configured or reconfigured with a new or updated TOSCA Policy at run time. PDPs register with the PAP when they start, providing the PolicyImpl they have been predeployed with if any. The PAP may update the TOSCA Policy on a PDP at any time after registration. | The configuration and parameters of the PDPs in a PDP group may be changed at run time by loading or updating the TOSCA Policy of the PDP Group at run time. Lifecycle management of TOSCA Policy entities is supported, allowing features such as PolicyImpl Safe Mode and PolicyImpl retirement. | Administration and management is required. The configuration and life cycle of the TOSCA policies can change at run time and must be administered and managed. |
| Hot Deployment | The PolicyImpl (PolicyTypeImpl and TOSCA Policy) are deployed at run time. The PolicyImpl (PolicyTypeImpl and TOSCA Policy) may be loaded at startup. The PDP may be configured or reconfigured with a new or updated PolicyTypeImpl and/or TOSCA Policy at run time. PDPs register with the PAP when they start, providing the PolicyImpl they have been predeployed with if any. The PAP may update the TOSCA Policy and PolicyTypeImpl on a PDP at any time after registration. | The policy logic, rules, configuration, and parameters of the PDPs in a PDP group may be changed at run time by loading or updating the PolicyTypeImpl and TOSCA Policy of the PDP Group at run time. Lifecycle management of TOSCA Policy entities and PolicyTypeImpl entites is supported, allowing features such as PolicyImpl Safe Mode and PolicyImpl retirement. | Administration and management is more complex. The PolicyImpl itself and its configuration and life cycle as well as the life cycle of the TOSCA policies can change at run time and must be administered and managed. |
3. APIs
The Policy Framework supports the APIs documented in the subsections below.
*** Note This Section is being restructured ***
3.1 Policy Type Design API
The purpose of this API is to support CRUD of TOSCA PolicyType entities from TOSCA compliant PolicyType definitions. It also supports CRUD of PolicyTypeImpl policy type implementations, where the XACML, Drools, and APEX policy type implementations are supplied as strings.
Note that client-side editing support for TOSCA PolicyType definitions or for PolicyTypeImpl implementations in XACML, Drools, or APEX is outside the current scope of the API.
3.1.1Policy Type query
The API allows applications (such as CLAMP and Integration) to query the PolicyType entities that are available for Policy creation
NOTE: Seems this is a reverse hierarchy of the PAP PDP Groups listing:
http:{url}:{port}/api/v1/policytype GET
models:
- The purpose of this API is to support CRUD of PDP groups and subgroups and to support the assignment and life cycles of PolicyImpl entities (TOSCA Policy and PolicyTypeImpl entities) on PDP sub groups and PDPs.
model: onap.Monitoring
description: A base policy type for all policies that govern monitoring provision
pdp_groups:
-
name: DCAE policy group
description: DCAE mS Configuration Policies
pdp_types:
- XACML
-
model: onap.controlloop.Operational
description: Operational Policy for Control Loops
pdp_groups:
-
name: Control Loop runtime group
description: ONAP Control Loop Operational and Guard policies
pdp_types:
- Drools
- Apex
-
model: onap.policy.controlloop.guard.frequencylimiter
description: Supports limiting the frequency of actions being taken by a Actor.
pdp_groups:
-
name: Control Loop runtime group
description: ONAP Control Loop Operational and Guard policies
pdp_types:
- XACML
-
model: onap.policy.controlloop.guard.blacklist
description: Supports blacklist of VNF's from performing control loop actions on.
pdp_groups:
-
name: Control Loop runtime group
description: ONAP Control Loop Operational and Guard policies
pdp_types:
- XACML
-
model: onap.policy.controlloop.guard.minmax
description: Supports Min/Max number of VF Modules
pdp_groups:
-
name: Control Loop runtime group
description: ONAP Control Loop Operational and Guard policies
pdp_types:
- XACML
-
model: onap.controlloop.Coordination.TBD
description: CLC description TBD
pdp_groups:
-
name: Control Loop runtime group
description: ONAP Control Loop Operational and Guard policies
pdp_types:
- XACML
3.1.2 Policy Lifecycle API - Adding new DCAE microservice component domains
For Dublin, the DCAE microservice component developer will use TOSCA-LAB to generate a specific yaml for their microservice component. These can be now loaded into the policy framework using the Policy Lifecycle API using the onap.monitoring domain. TOSCA-LAB produces the following example yaml:
tosca_definitions_version: tosca_simple_yaml_1_0_0
policy_types:
onap.policies.Monitoring:
derived_from: tosca.policies.Root
description: a base policy type for all policies that govern monitoring provision
onap.policy.monitoring.cdap.tca.hi.lo.app:
derived_from: onap.policies.Monitoring
properties:
tca_policy:
type: map
description: TCA Policy JSON
default: '{"domain":"measurementsForVfScaling","metricsPerEventName":[{"eventName":"Mfvs_eNodeB_RANKPI","controlLoopSchemaType":"VNF","policyScope":"resource=vFirewall;type=configuration","policyName":"configuration.dcae.microservice.tca.xml","policyVersion":"v0.0.1","thresholds":[{"closedLoopControlName":"CL-FRWL-LOW-TRAFFIC-SIG-d925ed73-8231-4d02-9545-db4e101f88f8","closedLoopEventStatus":"ONSET","version":"1.0.2","fieldPath":"$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedBroadcastPacketsAccumulated","thresholdValue":4000,"direction":"LESS_OR_EQUAL","severity":"MAJOR"},{"closedLoopControlName":"CL-FRWL-HIGH-TRAFFIC-SIG-EA36FE84-9342-5E13-A656-EC5F21309A09","closedLoopEventStatus":"ONSET","version":"1.0.2","fieldPath":"$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedBroadcastPacketsAccumulated","thresholdValue":20000,"direction":"GREATER_OR_EQUAL","severity":"CRITICAL"},{"closedLoopControlName":"CL-FRWL-HIGH-TRAFFIC-SIG-EA36FE84-9342-5E13-A656-EC5F21309A09","closedLoopEventStatus":"ABATED","version":"1.0.2","fieldPath":"$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedBroadcastPacketsAccumulated","thresholdValue":0,"direction":"EQUAL","severity":"CRITICAL"}]},{"eventName":"vLoadBalancer","controlLoopSchemaType":"VNF","policyScope":"resource=vLoadBalancer;type=configuration","policyName":"configuration.dcae.microservice.tca.xml","policyVersion":"v0.0.1","thresholds":[{"closedLoopControlName":"CL-LBAL-LOW-TRAFFIC-SIG-FB480F95-A453-6F24-B767-FD703241AB1A","closedLoopEventStatus":"ONSET","version":"1.0.2","fieldPath":"$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedBroadcastPacketsAccumulated","thresholdValue":500,"direction":"LESS_OR_EQUAL","severity":"MAJOR"},{"closedLoopControlName":"CL-LBAL-LOW-TRAFFIC-SIG-0C5920A6-B564-8035-C878-0E814352BC2B","closedLoopEventStatus":"ONSET","version":"1.0.2","fieldP*** Note This Section is being restructured ***ath":"$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedBroadcastPacketsAccumulated","thresholdValue":5000,"direction":"GREATER_OR_EQUAL","severity":"CRITICAL"}]}]}'
entry_schema:
type: onap.datatypes.monitoring.tca_policy
data_types:
onap.datatypes.monitoring.metricsPerEventName:
derived_from: tosca.datatypes.Root
properties:
controlLoopSchemaType:
type: string
description: Specifies Control Loop Schema Type for the
event Name e.g. VNF, VM
constraints:
- valid_values:
- VM
- VNF
eventName:
type: string
description: Event name to which thresholds need to be
applied
policyName:
type: string
description: TCA Policy Scope Name
policyScope:
type: string
description: TCA Policy Scope
policyVersion:
type: string
description: TCA Policy Scope Version
thresholds:
type: list
description: Thresholds associated with eventName
entry_schema:
type: onap.datatypes.monitoring.thresholds
onap.datatypes.monitoring.tca_policy:
derived_from: tosca.datatypes.Root
properties:
domain:
type: string
description: Domain name to which TCA needs to be applied
default: measurementsForVfScaling
constraints:The purpose of this API is to support CRUD of PDP groups and subgroups and to support the assignment and life cycles of PolicyImpl entities (TOSCA Policy and PolicyTypeImpl entities) on PDP sub groups and PDPs.
- equal: measurementsForVfScaling
metricsPerEventName:
type: list
description: Contains eventName and threshold details
that need to be applied to given eventName
entry_schema:
type: onap.datatypes.monitoring.metricsPerEventName
onap.datatypes.monitoring.thresholds:
derived_from: tosca.datatypes.Root
properties:
closedLoopControlName:
type: string
description: Closed Loop Control Name associated with
the threshold
closedLoopEventStatus:
type: string
description: Closed Loop Event Status of the threshold
constraints:
- valid_values:
- ONSET
- ABATED
direction:
type: string
description: Direction of the threshold
constraints:
- valid_values:
- LESS
- LESS_OR_EQUAL
- GREATER
- GREATER_OR_EQUAL
fieldPath:
type: stringThe purpose of this API is to support CRUD of PDP groups and subgroups and to support the assignment and life cycles of PolicyImpl entities (TOSCA Policy and PolicyTypeImpl entities) on PDP sub groups and PDPs.
description: Json field Path as per CEF message which
needs to be analyzed for TCA
severity:
type: string
description: Threshold Event Severity
constraints:
- valid_values:
- CRITICAL
- MAJOR
- MINOR
- WARNING
- NORMAL
thresholdValue:
type: integer
description: Threshold value for the field Path inside
CEF message
version:
type: string
description: Version number associated with the threshold
Once this call is made, now the models query will display the following available models for policy creation, notice the new "onap.policy.monitoring.cdap.tca.hi.lo.app" domain listed.
http:{url}:{port}/api/v1/models GET
models:
-
model: onap.Monitoring
description: A base policy type for all policies that govern monitoring provision
pdp_groups:
-
name: DCAE policy group
description: DCAE mS Configuration PoliciesThe purpose of this API is to support CRUD of PDP groups and subgroups and to support the assignment and life cycles of PolicyImpl entities (TOSCA Policy and PolicyTypeImpl entities) on PDP sub groups and PDPs.
pdp_types:
- XACML
-
model: onap.policy.monitoring.cdap.tca.hi.lo.app
description:
pdp_groups:
-
name: DCAE policy group
description: DCAE mS Configuration Policies
pdp_types:
- XACML
-
model: onap.controlloop.Operational
description: Operational Policy for Control Loops
pdp_groups:
-
name: Control Loop runtime group
description: ONAP Control Loop Operational and Guard policies
pdp_types:
- Drools
- Apex
-
model: onap.policy.controlloop.guard.frequencylimiter
description: Supports limiting the frequency of actions being taken by a Actor.
pdp_groups:
-
name: Control Loop runtime group
description: ONAP Control Loop Operational and Guard policies
pdp_types:
- XACML
-
model: onap.policy.controlloop.guard.blacklist
description: Supports blacklist of VNF's from performing control loop actions on.
pdp_groups:
-
name: Control Loop runtime group
description: ONAP Control Loop Operational and Guard policies
pdp_types:The purpose of this API is to support CRUD of PDP groups and subgroups and to support the assignment and life cycles of PolicyImpl entities (TOSCA Policy and PolicyTypeImpl entities) on PDP sub groups and PDPs.
- XACML
-
model: onap.policy.controlloop.guard.minmax
description: Supports Min/Max number of VF Modules
pdp_groups:
-
name: Control Loop runtime group
description: ONAP Control Loop Operational and Guard policies
pdp_types:
- XACML
-
model: onap.controlloop.Coordination.TBD
description: CLC description TBD
pdp_groups:
-
name: Control Loop runtime group
description: ONAP Control Loop Operational and Guard policies
pdp_types:
- XACML
Now that domain is available to CLAMP for creating concrete policies creation.
3.2 Policy Design API
3.2.1 Policy Lifecycle API - Creating Monitoring Policies
While designing a control loop using CLAMP, a Control Loop Designer will use the Model Schema for a specific DCAE mS component Policy Model and create a specific Policy.
GET are used by CLAMP/Integration to query an existing policy.
NOTE: This call is NOT used by DCAE for a decision on what policy the DCAE PolicyHandler should retrieve and enforce (next section)
http:{url}:{port}/api/v1/domains/onap.policy.monitoring.cdap.tca.hi.lo.app/policies/ GET
Content-Type: application/yaml
#
# Return Output
#
HTTP/1.1 200 OK
Content-Type: application/yaml
policies:
-
policy_id: onap.scaleout.tcaThe purpose of this API is to support CRUD of PDP groups and subgroups and to support the assignment and life cycles of PolicyImpl entities (TOSCA Policy and PolicyTypeImpl entities) on PDP sub groups and PDPs.
policy_metadata:
model: onap.policy.monitoring.cdap.tca.hi.lo.app
status:
latest:
version: 1
status: Undeployed
3.2.2 Policy Lifecycle API - Creating Operational Policies
3.2.3 Policy Lifecycle API - Creating Guard Policies
3.2.4 Policy Lifecycle API - Creating Coordination Policies
3.3 Policy Administration API
The purpose of this API is to support CRUD of PDP groups and subgroups and to support the assignment and life cycles of PolicyImpl entities (TOSCA Policy and PolicyTypeImpl entities) on PDP sub groups and PDPs.
3.3.1 PDP Group Query
http:{url}:{port}/pap/v1/pdps GET
#
# PAP - how it lists existing PDP Groups and Sub Groups and the models loaded
#
pdp_groups:
-
name: Control Loop runtime group
description: ONAP Control Loop Operational and Guard policies
subgroups:
-
pdp_type: drools
instances:
-
instance: drools_1 # K8S identifier? IP??
models:
- onap.controlloop.operational
-
instance: drools_2
models:
- onap.controlloop.operational
-
instance: drools-3
models:
- onap.controlloop.operational
-
pdp_type: apex
instances:
-
instance: apex_1
models:
- onap.controlloop.operational
-
instance: apex_2
models:
- onap.controlloop.operational
-
instance: apex_3
models:
- onap.controlloop.operational
-
pdp_type: xacml
instances:
-
instance: xacml_1
models:
- onap.controlloop.guard
- onap.controlloop.coordination
-http:{url}:{port}/pap/v1/pdps GET
instance: xacml_2
models:
- onap.controlloop.guard
- onap.controlloop.coordination
-
name: DCAE policy group
description: DCAE mS Configuration Policies
subgroups:
-
pdp_type: xacml
instances:
-
instance: xacml_1
models:
- onap.controlloop.monitoring
-
instance: xacml_2
models:
- onap.controlloop.monitoring
3.3.2 PDP Group Creation
http:{url}:{port}/pap/v1/pdpgroup POST
#
# PAP - how it lists existing PDP Groups and Sub Groups and the models loaded
#
pdp_groups:
-
name: Control Loop runtime group
description: ONAP Control Loop Operational and Guard policies
subgroups:
-
pdp_type: drools
models:
# Maven coordinates here
- "onap.controlloop.operational:operational-standard"
- "onap.controlloop.operational:operational-enhanced"
instances:
# Parameters somehow passed to K8S for scaling
min_instances: 3
# The parameters below are for illustration in Dublin, may be implemented later
instance_spawn_load_threshold: 70%
instance_kill_load_threshold: 50%
instance_geo_redundnacy: true
-
pdp_type: apex
models:
# Maven coordinates here
- "onap.controlloop.operational:operational-standard"
- "onap.controlloop.operational:operational-enhanced"
instances:
# Parameters somehow passed to K8S for scaling
min_instances: 3
# The parameters below are for illustration in Dublin, may be implemented later
instance_spawn_load_threshold: 80%
instance_kill_load_threshold: 60%
instance_geo_redundnacy: true
-
pdp_type: xacml
models:
- "onap.controlloop.guard:guard-standard"
- "onap.controlloop.coordination:coordination-standard"
# Parameters somehow passed to K8S for scaling
min_instances: 2
# The parameters below are for illustration in Dublin, may be implemented later
instance_geo_redundnacy: true
-
name: DCAE policy group
subgroups:
-
pdp_type: xacml
models:
- "onap.controlloop.monitoring:monitoring-standard"
- "onap.controlloop.monitoring:monitoring-acme-inc"
# Parameters somehow passed to K8S for scaling
min_instances: 2
# The parameters below are for illustration in Dublin, may be implemented later
instance_geo_redundnacy: true
3.3.3 PAP API - Deploying Policies
For CLAMP to deploy policies, we need to make sure there is a simple default way for this to support Dublin.
http:{url}:{port}/pap/v1/pdps PUT
Content-Type: application/yaml
#
# Return Output
#
HTTP/1.1 200 OK
Content-Type: application/yaml
policies:
- policy_id: onap.scaleout.tca
# TODO add the other operational and guard policies
3.4 Policy Decision API - Getting Policy Decisions
Policy decisions are required by ONAP components to support the policy-driven ONAP architecture. Currently implemented using the XACML PDP.