Official Documentation for Dublin
https://docs.onap.org/en/dublin/submodules/policy/parent.git/docs/design/design.html
This page shows how the Policy Design and API Flow to/from the PAP and PDP's will work PDPs works to support Model Driven Control Loops in Dublin.
...
draw.io Diagram | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
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 PolicyType. 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 can be 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. A TOSCA PolicyType artifact can be used by clients (such as CLAMP or CLI tools) to create, parse, serialize, and/or deserialize an actual Policy.
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.
...
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.
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
tosca_definitions_version: tosca_simple_yaml_1_0_0 policy_types:Operational - onap.policies.Monitoring: derived_from: tosca.policies.Root version: 1.0.0 description: a base policy type for all policies that govern monitoring provision Control Loop guard policies |
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 Control Loop guard policies in SDC (Stretch Goal) or can do so manually. See How to generate artefacts for SDC catalog using Tosca Lab Tool for details on TOSCA-LAB in SDC. For Dublin, the DCAE team is defining the manual steps required to build policy models Onboarding steps for DCAE MS through SDC/Policy/CLAMP (Dublin).
NOTE: For Dublin, mS Policy Types will be pre-loaded into the SDC platform and be available as a Normative. The policy framework will pre-load support for those mS Monitoring policy types.
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
Code Block | ||||||||
| ||||||||
tosca_definitions_version: tosca_simple_yaml_1_0_0 policy_types:will be developed - onap.policies.Monitoring: derived_from: tosca.policies.Root version: 1.0.0 description: a base policy type for all policies that govern monitoring provision - onap.policies.Monitoringmonitoring.MyDCAEComponent: derived_from: onap.policies.Monitoring version: properties: 1.0.0 properties: mydcaecomponent_policy: type: map description: The Policy Body I need entry_schema: entry_schema: type: onap.datatypes.monitoring.mydatatype data_types: - onap.datatypes.monitoring.mydatatypeMyDataType: derived_from: tosca.datatypes.Root properties: my_property_1: type: string description: A description of this property constraints: constraints: - valid_values: - value example 1 - value example 2 |
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.
TCA Example - Please note that the official version of this will be located in the SDC repository.
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
Code Block | ||||||
| ||||||
tosca_definitions_version: tosca_simple_yaml_1_0_0 policy_types: onap.policies.controlloop.OperationMonitoring: derived_from: tosca.policies.Root description: a Operationalbase policy Policytype for 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:
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
tosca_definitions_version: tosca_simple_yaml_1_0_0 policy_types: onap.policies.controlloop.Guard: all policies that governs monitoring provisioning onap.policy.monitoring.cdap.tca.hi.lo.app: derived_from: onap.policies.Monitoring version: 1.0.0 properties: tca_policy: derived_fromtype: tosca.policies.Rootmap description: Guard Policies for Control Loop Operational Policies description: TCA Policy JSON |
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
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
tosca_definitions_version: tosca_simple_yaml_1_0_0 policy entry_schema: type: onap.datatypes.monitoring.tca_policy data_types: onap.policiesdatatypes.controlloopmonitoring.GuardmetricsPerEventName: derived_from: tosca.policiesdatatypes.Root descriptionproperties: Guard Policies for Control Loop Operational Policies onap.policies.controlloop.Guard.FrequencyLimitercontrolLoopSchemaType: derived_from: onap.policies.controlloop.Guard descriptiontype: Supports limiting the frequency of actions being taken by a Actor. string propertiesrequired: true frequency_policy: description: Specifies Control Loop Schema Type for the event Name e.g. type: mapVNF, VM descriptionconstraints: entry- valid_schemavalues: type: onap.datatypes.Guard.FrequencyLimiter.nordix data_types: - VM onap.datatypes.Guard.FrequencyLimiter: derived_from: tosca.datatypes.Root properties:- VNF actoreventName: type: string descriptionrequired: Specifies the Actor true description: Event name to which thresholds need to required:be trueapplied recipepolicyName: type: string descriptionrequired: Specifiedtrue the Recipe description: TCA required: truePolicy Scope Name time_windowpolicyScope: type: scalar-unit.timestring descriptionrequired: Thetrue time window to count the actions against. description: TCA required: truePolicy Scope limitpolicyVersion: type: integerstring descriptionrequired: The limittrue requireddescription: true TCA Policy Scope Version constraintsthresholds: type: list - greater_than: 0Schema time_range:required: true type: tosca.datatypes.TimeIntervaldescription: Thresholds associated with eventName descriptionentry_schema: An optional range of time during the day the frequency is valid for. type: onap.datatypes.monitoring.thresholds onap.datatypes.monitoring.tca_policy: derived_from: tosca.datatypes.Root required properties: false controlLoopNamedomain: type: string descriptionrequired: Antrue optional specific control loop to apply this guard to. description: Domain name to which TCA needs to be applied required: false targetdefault: measurementsForVfScaling typeconstraints: string - descriptionequal: An optional specific VNF to apply this guard to.measurementsForVfScaling metricsPerEventName: requiredtype: false |
1.3.2 onap.policies.controlloop.Guard.Blacklist Policy Type
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
tosca_definitions_version: tosca_simple_yaml_1_0_0 policy_types: list onap.policies.controlloop.Guard: derived_fromrequired: tosca.policies.Roottrue description: Guard Policies for Control Loop Operational Policies description: Contains onap.policies.controlloop.Guard.Blacklist: derived_from: onap.policies.controlloop.GuardeventName and threshold details that need to be applied to given eventName description: Supports blacklist of VNF's from performing control loop actions on. entry_schema: properties: blacklist_policy:type: onap.datatypes.monitoring.metricsPerEventName onap.datatypes.monitoring.thresholds: derived_from: tosca.datatypes.Root type: map properties: descriptionclosedLoopControlName: entry_schematype: string required: true type: onap.datatypes.Guard.Blacklist data_types: onap.datatypes.Guard.Blacklist: derived_fromdescription: tosca.datatypes.Root properties:https://wiki.onap.org/display/DW/Policy+TypesClosed Loop Control Name associated with the threshold actorclosedLoopEventStatus: type: string descriptionrequired: Specifies the Actor true description: Closed Loop Event Status of required:the truethreshold recipe constraints: type: string - valid_values: description: Specified the- RecipeONSET required: - trueABATED time_rangedirection: type: tosca.datatypes.TimeIntervalstring descriptionrequired: Antrue optional range of time during the day the blacklist is valid for. description: Direction of the threshold required: false constraints: controlLoopName: - valid_values: type: string description: An optional specific- controlLESS loop to apply this guard to. required: false- LESS_OR_EQUAL blacklist: - GREATER type: list description: List of VNF's - GREATER_OR_EQUAL required: true |
1.3.3 onap.policies.controlloop.Guard.MinMax Policy Type
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
policy_types: onap.policies.controlloop.Guard: - EQUAL derived_from: tosca.policies.Root fieldPath: description: Guard Policies for Control Loop Operational Policies onap.policies.controlloop.Guard.MinMax:type: string derived_from: onap.policies.controlloop.Guard descriptionrequired: Supports Min/Max number of VF Modulestrue properties: minmax_policy: type: map description: Json field Path as per CEF message which needs to be analyzed for TCA constraints: description: - entryvalid_schemavalues: type: onap.datatypes.Guard.MinMax data_types: - $.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedTotalPacketsDelta onap.datatypes.Guard.MinMax: derived_from: tosca.datatypes.Root properties: - $.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedOctetsDelta actor: - $.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedUnicastPacketsDelta type: stringhttps://wiki.onap.org/display/DW/Policy+Types description: Specifies the Actor- $.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedMulticastPacketsDelta required: true - $.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedBroadcastPacketsDelta recipe: type: string - $.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedDiscardedPacketsDelta description: Specified the Recipe- $.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedErrorPacketsDelta required: true - $.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedTotalPacketsAccumulated time_range: type: tosca.datatypes.TimeInterval - $.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedOctetsAccumulated description: An optional range of time during the day the Min/Max limit is valid for.- $.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedUnicastPacketsAccumulated required: false - $.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedMulticastPacketsAccumulated controlLoopName: type: string- $.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedBroadcastPacketsAccumulated description: An optional specific control loop to apply this guard to.- $.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedDiscardedPacketsAccumulated required: false - $.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedErrorPacketsAccumulated min_vf_module_instances: type: integer - $.event.measurementsForVfScalingFields.vNicPerformanceArray[*].transmittedTotalPacketsDelta required: true - $.event.measurementsForVfScalingFields.vNicPerformanceArray[*].transmittedOctetsDelta description: The minimum instances of this VF-Module - $.event.measurementsForVfScalingFields.vNicPerformanceArray[*].transmittedUnicastPacketsDelta max_vf_module_instances: - $.event.measurementsForVfScalingFields.vNicPerformanceArray[*].transmittedMulticastPacketsDelta type: integer - $.event.measurementsForVfScalingFields.vNicPerformanceArray[*].transmittedBroadcastPacketsDelta required: false - $.event.measurementsForVfScalingFields.vNicPerformanceArray[*].transmittedDiscardedPacketsDelta description: The maximum instances of this VF-Module |
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
...
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.
...
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.
...
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.
...
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 Policy Lifecycle API will utilize the SQL database to make GET available to applications (eg CLAMP, Integration) for determining all the available models for policy creation:
NOTE: Seems this is a reverse hierarchy of the PAP PDP Groups listing:
http:{url}:{port}/api/v1/models GET
Code Block | ||||
---|---|---|---|---|
| ||||
models: - - $.event.measurementsForVfScalingFields.vNicPerformanceArray[*].transmittedErrorPacketsDelta - $.event.measurementsForVfScalingFields.vNicPerformanceArray[*].transmittedTotalPacketsAccumulated - $.event.measurementsForVfScalingFields.vNicPerformanceArray[*].transmittedOctetsAccumulated - $.event.measurementsForVfScalingFields.vNicPerformanceArray[*].transmittedUnicastPacketsAccumulated - $.event.measurementsForVfScalingFields.vNicPerformanceArray[*].transmittedMulticastPacketsAccumulated - $.event.measurementsForVfScalingFields.vNicPerformanceArray[*].transmittedBroadcastPacketsAccumulated - $.event.measurementsForVfScalingFields.vNicPerformanceArray[*].transmittedDiscardedPacketsAccumulated - $.event.measurementsForVfScalingFields.vNicPerformanceArray[*].transmittedErrorPacketsAccumulated - $.event.measurementsForVfScalingFields.cpuUsageArray[*].cpuIdle - $.event.measurementsForVfScalingFields.cpuUsageArray[*].cpuUsageInterrupt - $.event.measurementsForVfScalingFields.cpuUsageArray[*].cpuUsageNice - $.event.measurementsForVfScalingFields.cpuUsageArray[*].cpuUsageSoftIrq model: onap.Monitoring description: A base policy type for all policies that govern monitoring provision - $.event.measurementsForVfScalingFields.cpuUsageArray[*].cpuUsageSteal pdp_groups: - $.event.measurementsForVfScalingFields.cpuUsageArray[*].cpuUsageSystem - - $.event.measurementsForVfScalingFields.cpuUsageArray[*].cpuWait name: DCAE policy group description: DCAE mS Configuration Policies - $.event.measurementsForVfScalingFields.cpuUsageArray[*].percentUsage pdp_types: - $.event.measurementsForVfScalingFields.meanRequestLatency - XACML - $.event.measurementsForVfScalingFields.memoryUsageArray[*].memoryBuffered model: onap.controlloop.Operational description: Operational Policy for Control Loops- $.event.measurementsForVfScalingFields.memoryUsageArray[*].memoryCached pdp_groups: - $.event.measurementsForVfScalingFields.memoryUsageArray[*].memoryConfigured name: Control Loop runtime group- $.event.measurementsForVfScalingFields.memoryUsageArray[*].memoryFree description: ONAP Control Loop Operational and Guard policies - $.event.measurementsForVfScalingFields.memoryUsageArray[*].memoryUsed pdp_types: - $.event.measurementsForVfScalingFields.additionalMeasurements[*].arrayOfFields[0].value severity: - Drools type: string - Apex required: -true model: onap.policy.controlloop.guard.frequencylimiter description: SupportsThreshold limitingEvent theSeverity frequency of actions being taken by a Actor. pdp_groups: constraints: - valid_values: name: Control Loop runtime- groupCRITICAL description: ONAP Control Loop Operational and Guard- policiesMAJOR pdp_types: - MINOR - XACML - - WARNING model: onap.policy.controlloop.guard.blacklist description: Supports blacklist of VNF's from performing control loop actions on. pdp_groups: - NORMAL - thresholdValue: nametype: Control Loop runtime groupinteger descriptionrequired: ONAP Control Loop Operational and Guard policiestrue pdp_typesdescription: Threshold value for the field Path inside - XACMLCEF message - model: onap.policy.controlloop.guard.minmaxversion: description: Supports Min/Max number of VF Modules pdp_groupstype: string - name: Control Loop runtime grouprequired: true description: ONAPVersion Controlnumber Loopassociated Operationalwith 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:
the threshold
|
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.
For Dublin, this policy type will ONLY be used for the Policy Framework to distinguish the policy type as operational. The contents are still TBD for El Alto.
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
tosca_definitions_version: tosca_simple_yaml_1_0_0
policy_types:
onap.policies.controlloop.Operational:
derived_from: tosca.policies.Root
version: 1.0.0
description: Operational Policy for Control Loops
|
Applications should use the following Content-Type when creating onap.policies.controlloop.Operational policies:
Content-Type: "application/yaml; vnd.onap.operational"
1.2.1 Operational Policy Type Schema for Drools
For Dublin Drools will still support the Casablanca YAML definition of an Operational Policy for Control Loops.
Please use the Casablanca version of the YAML Operational Policy format defined https://git.onap.org/policy/drools-applications/tree/controlloop/common/policy-yaml/README-v2.0.0.md.
1.2.3 Operational Policy Type Schema for APEX (El Alto proposal)
The operational Policy Type schema for for APEX will extend the base operational Policy Type schema. This Policy Type allows parameters specific to the APEX PDP to be specified as a TOSCA policy.
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
Code Block | ||||||
| ||||||
tosca_definitions_version: tosca_simple_yaml_1_0_0 # Note: The full APEX PolicyType definition will be developed during the Dublin # timeframe of the ONAP project policy_types: onap.policies.controlloop.MonitoringOperational: derived_from: tosca.policies.Root version: 1.0.0 description: a base policy typeOperational Policy for all policies that govern monitoring provision onap.policy.monitoring.cdap.tca.hi.lo.appControl Loops onap.policies.controloop.operational.Apex: derived_from: onap.policies.Monitoringcontrolloop.Operational version: 1.0.0 description: Operational Policy properties: for Control Loops using the APEX PDP properties: # Some of these properties may be redundant in a Kubernetes deployment tca engine_policyservice: type: onap.datatypes.policies.controlloop.operational.apex.EngineService type description: mapAPEX Engine Service Parameters inputs: type: map description: TCA Policy JSONInputs for handling events coming into the APEX engine entry_schema: 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","fieldPath":"$.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: onap.datatypes.policies.controlloop.operational.apex.EventHandler outputs: type: map description: Outputs for handling events going out of the APEX engine entry_schema: type: onap.datatypes.policies.controlloop.operational.apex.EventHandler environment: type: list description: Envioronmental parameters for the APEX engine entry_schema: type: onap.datatypes.policies.controlloop.operational.apex.Environment data_types: onap.datatypes.policies.controlloop.operational.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.policies.controlloop.operational.apex.engineservice.Engine description: The parameters for all engines in the APEX engine service required: true onap.datatypes.policies.controlloop.operational.apex.EventHandler: derived_from: tosca.datatypes.Root properties: name: type: string description: Specifies the event handler name, if not specified this description:is Specifiesset Controlto Loop Schema Type for the the key name required: false carrier_technology: event Name e.g. VNF, VMtype: onap.datatypes.policies.controlloop.operational.apex.CarrierTechnology description: Specifies the carrier technology of the event handler constraints:(such as REST/Web Socket/Kafka) required: true - validevent_valuesprotocol: type: onap.datatypes.policies.controlloop.operational.apex.EventProtocol description: Specifies the event protocol of events for the -event VMhandler (such as Yaml/JSON/XML/POJO) required: true - VNFevent_name: eventName:type: string description: Specifies the event name for events on this event type:handler, stringif not specified, the event name is read from or description: Event name written to whichthe thresholds need to beevent being received or sent required: false appliedevent_name_filter: type: string policyName description: Specifies a filter as a regular expression, events that do type: string not match the filter are dropped, the default is to let all events description: TCA Policy Scope Namethrough required: false policyScopesynchronous_mode: type: stringbool description: Specifies the event handler is syncronous (receive event and description: TCA Policy Scope send response) required: policyVersion:false default: false synchronous_peer: type: string description: The peer event handler (output for input or input description: TCA Policy Scope Version for output) of this event handler in synchronous mode, this thresholds: parameter is mandatory if the event handler is in synchronous type: list mode required: false default: "" descriptionsynchronous_timeout: Thresholds associated with eventName type: int description: The timeout in milliseconds for responses entry_schema: to be issued by APEX torequests, this parameter is mandatory if the event handler type: onap.datatypes.monitoring.thresholdsis in onap.datatypes.monitoring.tca_policy: synchronous mode derived_fromrequired: tosca.datatypes.Rootfalse properties:default: "" requestor_mode: type: domain:bool description: Specifies the event handler is in requestor mode (send type:event string and wait for response mode) descriptionrequired: Domainfalse name to which TCA needs to be applieddefault: false requestor_peer: defaulttype: measurementsForVfScalingstring description: The peer event handler (output for input or input for constraints:output) of this event handler in requestor mode, this parameter is - equal: measurementsForVfScalingmandatory if the event handler is in metricsPerEventName:requestor mode required: false typedefault: list"" requestor_timeout: type: int description: ContainsThe eventNametimeout andin thresholdmilliseconds details for wait for responses to requests, this parameter is mandatory if the event handler that need to be applied to given eventNameis in requestor mode entry_schema:required: false type: default: "" onap.datatypes.monitoring.metricsPerEventName onap.datatypes.monitoring.thresholds: policies.controlloop.operational.apex.CarrierTechnology: derived_from: tosca.datatypes.Root properties: propertieslabel: type: string closedLoopControlName description: The label (name) of the carrier technology (such as REST, type: stringKafka, WebSocket) required: true plugin_parameter_class_name: description: Closed Looptype: Controlstring Name associated with description: The class name of the class that overrides default handling the threshold of event input or output for this carrier technology, defaults to the closedLoopEventStatus:supplied input or output class type required: stringfalse onap.datatypes.policies.controlloop.operational.apex.EventProtocol: derived_from: tosca.datatypes.Root properties: description: Closed Loop Event Status of the thresholdlabel: type: string description: The label (name) of the event protocol (such as constraints:Yaml, JSON, XML, or POJO) required: true - valid_values event_protocol_plugin_class: type: string description: The class name of the class that overrides -default ONSEThandling of the event protocol for this carrier technology, defaults to the - ABATED supplied event protocol class directionrequired: false onap.datatypes.policies.controlloop.operational.apex.Environmental: derived_from: tosca.datatypes.Root properties: name: type: string description: The name of the environment variable description: Direction ofrequired: thetrue threshold value: type: string constraintsdescription: The value of the environment variable required: true - valid_values: onap.datatypes.policies.controlloop.operational.apex.engineservice.Engine: derived_from: tosca.datatypes.Root properties: context: type: onap.datatypes.policies.controlloop.operational.apex.engineservice.engine.Context description: The properties -for LESS handling context in APEX engines, defaults to using Java maps for context - LESS_OR_EQUAL required: false executors: type: map description: The plugins for policy -executors GREATER used in engines such as javascript, MVEL, Jython required: true - GREATER_OR_EQUAL entry_schema: fieldPathdescription: The plugin class path for this policy executor type: string onap.datatypes.policies.controlloop.operational.apex.engineservice.engine.Context: derived_from: tosca.datatypes.Root properties: description: Json field Path as per CEF message whichdistributor: type: onap.datatypes.policies.controlloop.operational.apex.Plugin description: The plugin to be used for distributing context between needs to beAPEX analyzedPDPs forat TCAruntime required: false severityschemas: type: map typedescription: string The plugins for context schemas available in APEX PDPs such description:as ThresholdJava Eventand SeverityAvro required: false constraintsentry_schema: type: onap.datatypes.policies.controlloop.operational.apex.Plugin - valid_valueslocking: type: onap.datatypes.policies.controlloop.operational.apex.plugin description: The plugin to be used for locking context -in CRITICALand between APEX PDPs at runtime required: false - MAJORpersistence: type: onap.datatypes.policies.controlloop.operational.apex.Plugin description: The plugin to be used for persisting context -for APEX MINORPDPs at runtime required: false onap.datatypes.policies.controlloop.operational.apex.Plugin: - WARNING - NORMALderived_from: tosca.datatypes.Root properties: thresholdValue: name: type: integerstring description: ThresholdThe valuename forof the fieldexecutor Pathsuch inside as Javascript, Jython or MVEL CEF messagerequired: true versionplugin_class_name: type: string description: The class path of the plugin class for 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.
this executor |
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:http:{url}:{port}/api/v1/models GET
Code Block | |||||||||
---|---|---|---|---|---|---|---|---|---|
| |||||||||
tosca_definitions_version: tosca_simple_yaml_1_0_0 policy_typesmodels: -- onap.policies.controlloop.Guard: modelderived_from: onap.Monitoring description: A base policy type for all policies that govern monitoring provisiontosca.policies.Root pdp_groupsversion: - 1.0.0 name: DCAE policy group description: DCAEGuard mS Configuration Policies for Control Loop Operational Policies |
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.
For Dublin, only the following derived Policy Type definitions below are preloaded in the Policy Framework. However, the creation of policies will still support the payload from Casablanca.
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
ContentType: "application/json; vnd.onap.guard" Accepts: "application/json" # # Request BODY # { "policy-id" : "guard.frequency.scaleout", "contents" : { pdp_types: - XACML - model: onap.policy.monitoring.cdap.tca.hi.lo.app description: pdp_groups: -"actor": "SO", "recipe": "scaleOut", name: DCAE policy group "targets": ".*", description: DCAE mS Configuration Policies"clname": "ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3", pdp_types:"limit": "1", - XACML"timeWindow": "10", - model"timeUnits": onap.controlloop.Operational"minute", description: Operational Policy for Control Loops"guardActiveStart": "00:00:01-05:00", pdp_groups: "guardActiveEnd": "23:59:59-05:00" } } # # -Request RESPONSE # { "guard.frequency.scaleout": { name: Control Loop runtime group"type": "onap.policies.controlloop.guard.FrequencyLimiter", description: ONAP Control Loop Operational and Guard policies"version": "1.0.0", pdp_types:"metadata": { - Drools"policy-id": "guard.frequency.scaleout", "policy-version": 1 - Apex} - model: onap.policy} } |
1.3.1 onap.policies.controlloop.guard.FrequencyLimiter Policy Type
This is WIP for El Alto for the proposed policy type.
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
tosca_definitions_version: tosca_simple_yaml_1_0_0 policy_types: - onap.policies.controlloop.Guard:frequencylimiter description: Supports limiting the frequency of actions being taken by a Actor. pdpderived_groups:from: tosca.policies.Root -version: 1.0.0 description: Guard Policies for Control Loop Operational Policies name: Control Loop runtime group - onap.policies.controlloop.guard.FrequencyLimiter: derived_from: onap.policies.controlloop.Guard version: 1.0.0 description: ONAP Control Loop Operational and Guard policies Supports limiting the frequency of actions being taken by a Actor. properties: pdpfrequency_typespolicy: type: map - XACMLdescription: - modelentry_schema: type: onap.policydatatypes.controlloop.guard.blacklistFrequencyLimiter data_types: - onap.datatypes.guard.FrequencyLimiter: description: Supports blacklist of VNF's from performing control loop actions on.derived_from: tosca.datatypes.Root properties: pdp_groupsactor: type: -string description: Specifies the Actor name: Control Loop runtime group required: true recipe: description: ONAP Control Loop Operational and Guardtype: policiesstring description: Specified pdp_types:the Recipe required: true - XACMLtime_window: - modeltype: onap.policy.controlloop.guard.minmax scalar-unit.time description: The Supports Min/Max number of VF Modulestime window to count the actions against. pdp_groups: required: true limit: - type: integer namedescription: ControlThe limit Loop runtime group required: true description constraints: ONAP Control Loop Operational and Guard policies - greater_than: 0 pdptime_typesrange: type: tosca.datatypes.TimeInterval - XACML description: An optional range - of time during the day the frequency is model: onap.controlloop.Coordination.TBDvalid for. description: CLC descriptionrequired: TBDfalse pdp_groupscontrolLoopName: type: -string description: An optional specific control loop name:to Controlapply Loopthis runtimeguard groupto. required: false description: ONAP Controltarget: Loop Operational and Guard policies type: string pdp_typesdescription: An optional specific VNF to apply this guard to. - XACML |
...
3.2 Policy Design API
3.2.1 Policy Lifecycle API - Creating Monitoring Policies
...
required: false
|
1.3.2 onap.policies.controlloop.guard.Blacklist Policy Type
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
tosca_definitions_version: tosca_simple_yaml_1_0_0 importspolicy_types: -- onap.policies.controlloop.Guard: tca_policy_model.yml policies: derived_from: tosca.policies.Root -version: 1.0.0 onap.scaleout.tca: type: onap.policy.monitoring.cdap.tca.hi.lo.appdescription: Guard Policies for Control Loop Operational Policies - onap.policies.controlloop.guard.Blacklist: properties:derived_from: onap.policies.controlloop.Guard version: 1.0.0 domain description: measurementsForVfScaling Supports blacklist of VNF's from performing control loop actions on. metricsPerEventName properties: blacklist_policy: - type: map eventNamedescription: vLoadBalancer entry_schema: controlLoopSchemaTypetype: VNFonap.datatypes.guard.Blacklist data_types: - onap.datatypes.guard.Blacklist: derived_from: tosca.datatypes.Root policyScopeproperties: "type=configuration" actor: policyNametype: "onap.scaleout.tca"string description: Specifies the Actor policyVersion: "v0.0.1" # THIS MAKES NOrequired: SENSEtrue recipe: thresholdstype: string description: Specified the Recipe - required: true time_range: closedLoopControlName: "CL-LBAL-LOW-TRAFFIC-SIG-FB480F95-A453-6F24-B767-FD703241AB1A" type: tosca.datatypes.TimeInterval description: An optional range of time during closedLoopEventStatus:the ONSET day the blacklist is valid for. versionrequired: "1.0.2"false controlLoopName: fieldPath: "$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedBroadcastPacketsAccumulated"type: string description: An optional specific control loop to apply this thresholdValue: 500guard to. required: false direction: LESS_OR_EQUALblacklist: severitytype: MAJORlist description: List - of VNF's closedLoopControlName: "CL-LBAL-LOW-TRAFFIC-SIG-0C5920A6-B564-8035-C878-0E814352BC2B"required: true |
1.3.3 onap.policies.controlloop.guard.MinMax Policy Type
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
policy_types: - onap.policies.controlloop.Guard: derived_from: tosca.policies.Root version: 1.0.0 closedLoopEventStatusdescription: ONSET Guard Policies for Control Loop Operational Policies - onap.policies.controlloop.guard.MinMax: derived_from: onap.policies.controlloop.Guard version: "1.0.2"0 description: Supports Min/Max number of VF Modules fieldPath: "$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedBroadcastPacketsAccumulated"properties: minmax_policy: thresholdValuetype: 5000map description: direction: GREATER_OR_EQUALentry_schema: type: onap.datatypes.guard.MinMax data_types: - onap.datatypes.guard.MinMax: derived_from: tosca.datatypes.Root properties: actor: severity: CRITICAL |
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
#
# Supports both YAML and JSON payloads. Using the policy defined in the previous code block
#
http:{url}:{port}/api/v1/models?model=onap.policy.monitoring.cdap.tca.hi.lo.app PUT
Content-Type: application/yaml
Accepts: application/json
#
# Return Output
#
HTTP/1.1 200 OK
Content-Type: application/json
{
"policy_id": "onap.scaleout.tca",
"policy_version": 1,
"policy_metadata": {
"model": "onap.policy.monitoring.cdap.tca.hi.lo.app"
# HOW CAN WE GET THE closedLoopControlName as metadata?
}
}
|
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)
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
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: - type: string description: Specifies the Actor required: true recipe: type: string description: Specified the Recipe required: true time_range: type: tosca.datatypes.TimeInterval description: An optional range of time during the day the Min/Max limit is valid for. required: false controlLoopName: type: string policy_id: onap.scaleout.tca description: An optional specific control loop to apply this guard to. policy_metadata: required: false min_vf_module_instances: model: onap.policy.monitoring.cdap.tca.hi.lo.app type: integer statusrequired: true description: The minimum instances of latest:this VF-Module max_vf_module_instances: version type: 1integer required: false 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
description: The maximum instances of this VF-Module
|
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.
draw.io Diagram | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
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, parameters, and PDP group of PDPs may be changed at run time by loading or updating a TOSCA Policy into the PDP. 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 TOSCApolicies 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, parameters, and PDP group of PDPs may be changed at run time by loading or updating a TOSCA Policy and PolicyTypeImpl into the PDP. 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 TOSCApolicies can change at run time and must be administered and managed. |
3. Public APIs
The Policy Framework supports the APIs documented in the subsections below. The APIs in this section are supported for use by external components.
3.1 Policy Type Design API for TOSCA Policy Types
The purpose of this API is to support CRUD of TOSCA PolicyType entities. This API is provided by the PolicyDevelopment component of the Policy Framework, see The ONAP Policy Framework architecture.
The API allows applications to create, update, delete, and query PolicyType entities so that they become available for use in ONAP by applications such as CLAMP. Some Policy Type entities are preloaded in the Policy Framework. The TOSCA fields below are valid on API calls:
Field | GET | POST | DELETE | Comment |
---|---|---|---|---|
(name) | M | M | M | The definition of the reference to the Policy Type, GET allows ranges to be specified |
version | O | M | C | GET allows ranges to be specified, must be specified if more than one version of the Policy Type exists |
description | R | O | N/A | Desciption of the Policy Type |
derived_from | R | C | N/A | Must be specified when a Policy Type is derived from another Policy Type such as in the case of derived Monitoring Policy Types |
metadata | R | O | N/A | Metadata for the Policy Type |
properties | R | M | N/A | This field holds the specification of the specific Policy Type in ONAP |
targets | R | O | N/A | A list of node types and/or group types to which the Policy Type can be applied |
triggers | R | O | N/A | Specification of policy triggers, not currently supported in ONAP |
Note: On this and subsequent tables, use the following legend: M-Mandatory, O-Optional, R-Read-only, C-Conditional. Conditional means the field is mandatory when some other field is present.
Note: Preloaded policy types may only be queried over this API, modification or deletion of preloaded policy type implementations is disabled.
Note: Policy types that are in use (referenced by defined Policies) may not be deleted
Note: The group types of targets in TOSCA are groups of TOSCA nodes, not PDP groups; the target concept in TOSCA is equivalent to the Policy Enforcement Point (PEP) concept
3.1.1 Policy Type query
The API allows applications (such as CLAMP and Integration) to query the PolicyType entities that are available for Policy creation using a GET operation.
https:{url}:{port}/policy/api/v1/policytypes GET
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
policy_types:
- onap.policies.Monitoring:
version: 1.0.0
description: A base policy type for all policies that govern monitoring provision
derived_from: tosca.policies.Root
properties:
# Omitted for brevity, see Section 1
- onap.policies.controlloop.Operational:
version: 1.0.0
description: Operational Policy for Control Loops
derived_from: tosca.policies.Root
properties:
# Omitted for brevity, see Section 1
- onap.policies.controloop.operational.Drools:
version: 1.0.0
description: Operational Policy for Control Loops using the Drools PDP
derived_from: onap.policies.controlloop.Operational
properties:
# Omitted for brevity, see Section 1
- onap.policies.controloop.operational.Apex:
version: 1.0.0
description: Operational Policy for Control Loops using the APEX PDP
derived_from: onap.policies.controlloop.Operational
properties:
# Omitted for brevity, see Section 1
- onap.policies.controlloop.Guard:
version: 1.0.0
description: Operational Policy for Control Loops
derived_from: tosca.policies.Root
properties:
# Omitted for brevity, see Section 1
- onap.policies.controlloop.guard.FrequencyLimiter:
version: 1.0.0
description: Supports limiting the frequency of actions being taken by a Actor.
derived_from: onap.policies.controlloop.Guard
properties:
# Omitted for brevity, see Section 1
- onap.policies.controlloop.guard.Blacklist:
version: 1.0.0
description: Supports blacklist of VNF's from performing control loop actions on.
derived_from: onap.policies.controlloop.Guard
properties:
# Omitted for brevity, see Section 1
- onap.policies.controlloop.guard.MinMax:
version: 1.0.0
description: Supports Min/Max number of VF Modules
derived_from: onap.policies.controlloop.Guard
properties:
# Omitted for brevity, see Section 1
- onap.policies.controlloop.coordination.TBD: (STRETCH GOALS)
version: 1.0.0
description: Control Loop Coordination policy types
derived_from: onap.policies.controlloop.Coordination
properties:
# Omitted for brevity, see Section 1
data_types:
# Any bespoke data types referenced by policy type definitions |
The table below shows some more examples of GET operations
Example | Description |
---|---|
https:{url}:{port}/policy/api/v1/policytypes | Get all Policy Type entities in the system |
https:{url}:{port}/policy/api/v1/policytypes/{policy type id} eg. | Get a specific policy type and all the available versions. |
https:{url}:{port}/policy/api/v1/policytypes/{policy type id}/versions/{version id} eg. | Get the specific Policy Type with the specified name and version |
3.1.2 Policy Type Create/Update
The API allows applications and users (such as a DCAE microservice component developer) to create or update a Policy Type using a POST operation. This API allows new Policy Types to be created or existing Policy Types to be modified. POST operations with a new Policy Type name or a new version of an existing Policy Type name are used to create a new Policy Type. POST operations with an existing Policy Type name and version are used to update an existing Policy Type. Many Policy Types can be created or updated in a single POST operation by specifying more than one Policy Type on the TOSCA policy_types list.
For example, the POST operation below with the TOSCA body below is used to create a new Policy type for a DCAE microservice.
https:{url}:{port}/policy/api/v1/policytypes POST
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
policy_types:
- onap.policies.monitoring.cdap.tca.hi.lo.app:
version: 1.0.0
derived_from: onap.policies.Monitoring
description: A DCAE TCA high/low policy type
properties:
tca_policy:
type: map
description: TCA Policy JSON
default:'{<JSON omitted for brevity>}'
entry_schema:
type: onap.datatypes.monitoring.tca_policy
data_types:
<omitted for brevity> |
Following creation of a DCAE TCA policy type operation, the GET call for Monitoring policies will list the new policy type.
https:{url}:{port}/policy/api/v1/policytypes GET
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
policy_types:
- onap.policies.Monitoring:
version: 1.0.0
derived_from: tosca.policies.Root
description: A base policy type for all policies that govern monitoring provision
- onap.policies.monitoring.cdap.tca.hi.lo.app:
version: 1.0.0
derived_from: onap.policies.Monitoring
description: A DCAE TCA high/low policy type
- onap.policies.controlloop.Operational:
version: 1.0.0
description: Operational Policy for Control Loops
derived_from: tosca.policies.Root
- onap.policies.controloop.operational.Drools:
version: 1.0.0
description: Operational Policy for Control Loops using the Drools PDP
derived_from: onap.policies.controlloop.Operational
- onap.policies.controloop.operational.Apex:
version: 1.0.0
description: Operational Policy for Control Loops using the APEX PDP
derived_from: onap.policies.controlloop.Operational
- onap.policies.controlloop.Guard:
version: 1.0.0
description: Operational Policy for Control Loops
derived_from: tosca.policies.Root
- onap.policies.controlloop.guard.FrequencyLimiter:
version: 1.0.0
description: Supports limiting the frequency of actions being taken by a Actor.
derived_from: onap.policies.controlloop.Guard
- onap.policies.controlloop.guard.Blacklist:
version: 1.0.0
description: Supports blacklist of VNF's from performing control loop actions on.
derived_from: onap.policies.controlloop.Guard
- onap.policies.controlloop.guard.MinMax:
version: 1.0.0
description: Supports Min/Max number of VF Modules
derived_from: onap.policies.controlloop.Guard
- onap.policies.controlloop.coordination.TBD: (STRETCH GOALS)
version: 1.0.0
description: Control Loop Coordination policy types
derived_from: onap.policies.controlloop.Coordination |
Now the onap.policies.Monitoring.cdap.tca.hi.lo.app Policy Type is available to CLAMP for creating concrete policies. See the Yaml contribution on the Model driven Control Loop Design page for a full listing of the DCAE TCA policy type used in the example above.
3.1.3 Policy Type Delete
The API also allows Policy Types to be deleted with a DELETE operation. The format of the delete operation is as below:
https:{url}:{port}/policy/api/v1/policytypes/onap.policies.monitoring.cdap.tca.hi.lo.app/versions/1.0.0 DELETE
Note: Predefined policy types cannot be deleted
Note: Policy types that are in use (Parameterized by a TOSCA Policy) may not be deleted, the parameterizing TOSCA policies must be deleted first
Note: The version parameter may be omitted on the DELETE operation if there is only one version of the policy type in the system
3.2 Policy Design API
The purpose of this API is to support CRUD of TOSCA Policy entities from TOSCA compliant PolicyType definitions. TOSCA Policy entities become the parameters for PolicyTypeImpl entities, producing PolicyImpl entities that can run on PDPs. This API is provided by the PolicyDevelopment component of the Policy Framework, see The ONAP Policy Framework architecture.
This API allows applications (such as CLAMP and Integration) to create, update, delete, and query Policy entities. The TOSCA fields below are valid on API calls:
Field | GET | POST | DELETE | Comment |
---|---|---|---|---|
(name) | M | M | M | The definition of the reference to the Policy, GET allows ranges to be specified |
type | O | M | O | The Policy Type of the policy, see section 3.1 |
description | R | O | O | |
metadata | R | O | N/A | |
properties | R | M | N/A | This field holds the specification of the specific Policy in ONAP |
targets | R | O | N/A | A list of nodes and/or groups to which the Policy can be applied |
Note: Policies that are deployed (used on deployed PolicyImpl entities) may not be deleted
Note: This API is NOT used by DCAE for a decision on what policy the DCAE PolicyHandler should retrieve and enforce
Note: The groups of targets in TOSCA are groups of TOSCA nodes, not PDP groups; the target concept in TOSCA is equivalent to the Policy Enforcement Point (PEP) concept
YAML is used for illustrative purposes in the examples in this section. JSON (application/json) will be used as the content type in the implementation of this API.
3.2.1 Policy query
The API allows applications (such as CLAMP and Integration) to query the Policy entities that are available for deployment using a GET operation.
Note: This operation simply returns TOSCA policies that are defined in the Policy Framework, it does NOT make a decision.
The table below shows some more examples of GET operations
Example | Description |
---|---|
https:{url}:{port}/policy/api/v1/policytypes/{policy type id}/versions/{versions}/policies eg. | Get all Policies for a specific Policy Type and version |
https://{url}:{port}/policy/api/v1/policytypes/{policy type id}/versions/{version}/policies/{policy name}/versions/{version} eg. | Gets a specific Policy version |
https:{url}:{port}/policy/api/v1/policytypes/onap.policies.monitoring.cdap.tca.hi.lo.app/versions/1.0.0/policies/onap.scaleout.tca/versions/latest GET | Returns the latest version of a Policy |
https:{url}:{port}/policy/api/v1/policytypes/onap.policies.monitoring.cdap.tca.hi.lo.app/versions/1.0.0/policies/onap.scaleout.tca/deployed GET | Returns the version of the Policy that has been deployed on one or more PDP groups. |
https://{url}:{port}/policy/api/v1/policytypes/onap.policies.monitoring.cdap.tca.hi.lo.app/versions/1.2.3/policies/CL-LBAL-LOW-TRAFFIC-SIG-FB480F95-A453-6F24-B767-FD703241AB1A/versions/1.0.2 GET | Returns a specific version of a monitoring policy |
3.2.2 Policy Create/Update
The API allows applications and users (such as CLAMP and Integration) to create or update a Policy using a POST operation. This API allows new Policies to be created or existing Policies to be modified. POST operations with a new Policy name are used to create a new Policy. POST operations with an existing Policy name are used to update an existing Policy. Many Policies can be created or updated in a single POST operation by specifying more than one Policy on the TOSCA policies list.
3.2.2.1 Monitoring Policy Create/Update
While designing a control loop using CLAMP, a Control Loop Designer uses the Policy Type for a specific DCAE mS component (See Section 3.1.1) to create a specific Policy. CLAMP then uses this API operation to submit the Policy to the Policy Framework.
For example, the POST operation below with the TOSCA body below is used to create a new scaleout Policy for the onap.policies.monitoring.cdap.tca.hi.lo.app microservice. The name of the policy "onap.scaleout.tca" is up to the user to determine themselves.
https:{url}:{port}/policy/api/v1/policytypes/onap.policies.Monitoring.cdap.tca.hi.lo.app/versions/1.0.0/policies POST
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
https:{url}:{port}/policy/api/v1/policytypes/onap.policies.monitoring.cdap.tca.hi.lo.app/versions/1.0.0/policies POST
Content-Type: application/yaml
Accept: application/yaml
#Request Body
policies:
-
onap.scaleout.tca:
type: onap.policies.monitoring.cdap.tca.hi.lo.app
version: 1.0.0
metadata:
policy-id: onap.scaleout.tca # SHOULD MATCH THE TOSCA policy-name field above. DCAE needs this - convenience.
description: The scaleout policy for vDNS # GOOD FOR CLAMP GUI
properties:
domain: measurementsForVfScaling
metricsPerEventName:
-
eventName: vLoadBalancer
controlLoopSchemaType: VNF
policyScope: "type=configuration"
policyName: "onap.scaleout.tca"
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"
fieldPath: "$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedBroadcastPacketsAccumulated"
thresholdValue: 5000
direction: GREATER_OR_EQUAL
severity: CRITICAL
#Response Body
policies:
- onap.scaleout.tca:
type: onap.policies.monitoring.cdap.tca.hi.lo.app
version: 1.0.0
metadata:
#
# version is managed by Policy Lifecycle and returned
# back to the caller.
#
policy-version: 1
#
# These were passed in, and should not be changed. Will
# be passed back.
#
policy-id: onap.scaleout.tca
properties:
domain: measurementsForVfScaling
metricsPerEventName:
-
eventName: vLoadBalancer
controlLoopSchemaType: VNF
policyScope: "type=configuration"
<OMITTED FOR BREVITY> |
Given a return code of success and a "metadata" section that indicates versioning information. The "metadata" section conforms exactly to how SDC implements lifecycle management versioning for first class normatives in the TOSCA Models. The policy platform will implement lifecycle identically to SDC to ensure conformity for policy creation. The new metadata fields return versioning details.
The following new policy will be listed and will have a "metadata" section as shown below:
https:{url}:{port}/policy/api/v1/policytypes/onap.policies.monitoring.cdap.tca.hi.lo.app/versions/1.0.0/policies GET
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
policies:
- onap.scaleout.tca:
type: onap.policies.monitoring.cdap.tca.hi.lo.app
version: 1.0.0
metadata:
policy-id: onap.scaleout.tca
policy-version: 1
- my.other.policy:
type: onap.policies.monitoring.cdap.tca.hi.lo.app
version: 1.0.0
metadata:
invariantUUID: 20ad46cc-6b16-4404-9895-93d2baaa8d25
UUID: 4f715117-08b9-4221-9d63-f3fa86919742
version: 5
name: my.other.policy
scope: foo=bar;field2=value2
description: The policy for some other use case
- yet.another.policy:
type: onap.policies.monitoring.cdap.tca.hi.lo.app
version: 1.0.0
metadata:
invariantUUID: 20ad46cc-6b16-4404-9895-93d2baaa8d25
UUID: 4f715117-08b9-4221-9d63-f3fa86919742
version: 3
name: yet.another.policy
scope: foo=bar;
description: The policy for yet another use case
|
The contents of the new policy can be retrieved using the ID:
https:{url}:{port}/policy/api/v1/policytypes/onap.policies.monitoring.cdap.tca.hi.lo.app/versions/1.0.0/policies/onap.scaleout.tca GET
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
policies:
-
onap.scaleout.tca:
type: onap.policies.monitoring.cdap.tca.hi.lo.app
version: 1.0.0
metadata:
invariantUUID: 20ad46cc-6b16-4404-9895-93d2baaa8d25
UUID: 4f715117-08b9-4221-9d63-f3fa86919742
version: 1
name: onap.scaleout.tca
scope: foo=bar;
description: The scaleout policy for vDNS
properties:
domain: measurementsForVfScaling
<OMMITTED FOR BREVITY>
|
3.2.2.2 Operational Policy Create/Update
While designing an operational policy, the designer uses the Policy Type for the operational policy (See Section 3.1.1) to create a specific Policy and submits the Policy to the Policy Framework.
This URL will be fixed for CLAMP in Dublin and the payload will match updated version of Casablanca YAML that supports VFModules.
https:{url}:{port}/policy/api/v1/policytypes/onap.policies.controloop.operational/versions/1.0.0/policies POST
Content-Type: application/yaml; legacy-version
FUTURE: Content-Type: application/yaml; tosca
NOTE: The controlLoopName will be assumed to be the policy-id
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
tosca_definitions_version: tosca_simple_yaml_1_0_0
topology_template:
policies:
-
operational.scaleout:
type: onap.policies.controlloop.Operational
version: 1.0.0
metadata:
policy-id: operational.scaleout
properties:
controlLoop:
version: 2.0.0
controlLoopName: ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3
trigger_policy: unique-policy-id-1-scale-up
timeout: 1200
abatement: false
policies:
- id: unique-policy-id-1-scale-up
name: Create a new VF Module
description:
actor: SO
recipe: VF Module Create
target:
type: VNF
payload:
requestParameters: '{"usePreload":true,"userParams":[]}'
configurationParameters: '[{"ip-addr":"$.vf-module-topology.vf-module-parameters.param[9]","oam-ip-addr":"$.vf-module-topology.vf-module-parameters.param[16]","enabled":"$.vf-module-topology.vf-module-parameters.param[23]"}]'
retry: 0
timeout: 1200
success: final_success
failure: final_failure
failure_timeout: final_failure_timeout
failure_retries: final_failure_retries
failure_exception: final_failure_exception
failure_guard: final_failure_guard
|
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
tosca_definitions_version: tosca_simple_yaml_1_0_0
topology_template:
policies:
-
operational.scaleout:
type: onap.policies.controlloop.Operational
version: 1.0.0
metadata:
policy-id: operational.scaleout
policy-version: 1
properties:
controlLoop:
version: 2.0.0
controlLoopName: ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3
trigger_policy: unique-policy-id-1-scale-up
timeout: 1200
abatement: false
policies:
- id: unique-policy-id-1-scale-up
name: Create a new VF Module
description:
actor: SO
recipe: VF Module Create
target:
type: VNF
payload:
requestParameters: '{"usePreload":true,"userParams":[]}'
configurationParameters: '[{"ip-addr":"$.vf-module-topology.vf-module-parameters.param[9]","oam-ip-addr":"$.vf-module-topology.vf-module-parameters.param[16]","enabled":"$.vf-module-topology.vf-module-parameters.param[23]"}]'
retry: 0
timeout: 1200
success: final_success
failure: final_failure
failure_timeout: final_failure_timeout
failure_retries: final_failure_retries
failure_exception: final_failure_exception
failure_guard: final_failure_guard
|
3.2.2.2.1 Drools Operational Policy Create/Update
TBD Jorge Hernandez
3.2.2.2.2 APEX Operational Policy Create/Update
The POST operation below with the TOSCA body below is used to create a new Sample Domain test polict for the APEX Sample Domain operational policy type.
https:{url}:{port}/policy/api/v1/policytypes/onap.policies.controloop.operational.apex/versions/1.0.0/policies POST
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
policies:
- onap.policy.operational.apex.sampledomain.Test:
type: onap.policies.controloop.operational.Apex
properties:
engine_service:
name: "MyApexEngine"
version: "0.0.1"
id: 45
instance_count: 4
deployment_port: 12561
policy_type_impl: "onap.policies.controlloop.operational.apex.sampledomain.Impl"
engine:
executors:
JAVASCRIPT: "org.onap.policy.apex.plugins.executor.javascript.JavascriptExecutorParameters"
inputs:
first_consumer:
carrier_technology:
label: "RESTCLIENT",
plugin_parameter_class_name: "org.onap.policy.apex.plugins.event.carrier.restclient.RestClientCarrierTechnologyParameters",
parameters:
url: "https://localhost:32801/EventGenerator/GetEvents"
event_protocol:
label: "JSON"
outputs:
first_producer:
carrier_technology:
label: "RESTCLIENT",
plugin_parameter_class_name: "org.onap.policy.apex.plugins.event.carrier.restclient.RestClientCarrierTechnologyParameters",
parameters:
url: "https://localhost:32801/EventGenerator/PostEvent"
event_protocol:
label: "JSON" |
3.2.2.3 Guard Policy Create/Update
TBD Pamela Dragosh Similar to Operational Policies
3.2.2.4 Policy Lifecycle API - Creating Coordination Policies
TBD Similar to Operational Policies, stretch for Dublin
3.2.3 Policy Delete
The API also allows Policies to be deleted with a DELETE operation. The format of the delete operation is as below:
Example | Description |
---|---|
https:{url}:{port}/policy/api/v1/policytypes/onap.policies.monitoring.cdap.tca.hi.lo.app/versions/1.0.0/policies/onap.scaleout.tca DELETE | Deletes a Policy - all versions will be deleted. NOTE: The API call will fail if the policy has been deployed in one or more PDP Group. They must be undeployed first from all PDP Groups. |
3.3 Policy Administration API
The purpose of this API is to support CRUD of PDP groups and subgroups and to support the deployment and life cycles of PolicyImpl entities (TOSCA Policy and PolicyTypeImpl entities) on PDP sub groups and PDPs. See Section 2 for details on policy deployment on PDP groups and subgroups. This API is provided by the PolicyAdministration component (PAP) of the Policy Framework, see The ONAP Policy Framework architecture.
PDP groups and subgroups may be prefedined in the system. Predefined groups and subgroups may not be modified or deleted over this API. However, the policies running on predefined groups or subgroups as well as the instance counts and properties may be modified.
A PDP may be preconfigured with its PDP group, PDP subgroup, and policies. The PDP sends this information to the PAP when it starts. If the PDP group, subgroup, or any policy is unknown to the PAP, the PAP locks the PDP in state PASSIVE.
The fields below are valid on API calls:
Field | GET | POST | DELETE | Comment | ||
---|---|---|---|---|---|---|
name | M | M | M | The name of the PDP group | ||
version | O | M | C | The version of the PDP group | ||
state | R | N/A | N/A | The administrative state of the PDP group: PASSIVE, SAFE, TEST, or ACTIVE | ||
description | R | O | N/A | The PDP group description | ||
properties | R | O | N/A | Specific properties for a PDP group | ||
pdp_subgroups | R | M | N/A | A list of PDP subgroups for a PDP group | ||
pdp_type | R | M | N/A | The PDP type of this PDP subgroup, currently xacml, drools, or apex | ||
supported_policy_types | R | N/A | N/A | A list of the policy types supported by the PDPs in this PDP subgroup | ||
policies | R | M | N/A | The list of policies running on the PDPs in this PDP subgroup | ||
(name) | R | M | N/A | The name of a TOSCA policy running in this PDP subgroup | ||
policy_type | R | N/A | N/A | The TOSCA policy type of the policy | ||
policy_type_version | R | N/A | N/A | The version of the TOSCA policy type of the policy | ||
policy_type_impl | R | C | N/A | The policy type implementation (XACML, Drools Rules, or APEX Model) that implements the policy | ||
instance_count | R | N/A | N/A | The number of PDP instances running in a PDP subgroup | ||
min_instance_count | O | N/A | N/A | The minumum number of PDP instances to run in a PDP subgroup | ||
properties | O | N/A | N/A | Deployment configuration or other properties for the PDP subgroup | ||
deployment_info | R | N/A | N/A | Information on the deployment for a PDP subgroup | ||
instances | R | N/A | N/A | A list of PDP instances running in a PDP subgroup | ||
instance | R | N/A | N/A | The instance ID of a PDP running in a Kuberenetes Pod | ||
state | R | N/A | N/A | The administrative state of the PDP: PASSIVE, SAFE, TEST, or ACTIVE | ||
healthy | R | N/A | N/A | The result of the latest health check on the PDP: HEALTHY/NOT_HEALTHY/TEST_IN_PROGRESS | ||
message | O | N/A | N/A | A status message for the PDP if any | ||
deployment_instance_info | R | N/A | N/A | Information on the node running the PDP |
Note: In the Dublin release, the policy_type_impl of all policy types in a PDP subgroup must be the same.
YAML is used for illustrative purposes in the examples in this section. JSON (application/json) will be used as the content type in the implementation of this API.
3.3.1 PDP Group Query
This operation allows the PDP groups and subgroups to be listed together with the policies that are deployed on each PDP group and subgroup.
https:{url}:{port}/policy/pap/v1/pdps GET
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
pdp_groups:
- name: onap.pdpgroup.controlloop.Operational
version: 1.0.0
state: active
description: ONAP Control Loop Operational and Guard policies
properties:
# PDP group level properties if any
pdp_subgroups:
pdp_type: drools
supported_policy_types:
- onap.controllloop.operational.drools.vCPE
- onap.controllloop.operational.drools.vFW
policies:
- onap.controllloop.operational.drools.vCPE.eastRegion:
policy_type: onap.controllloop.operational.drools.vCPE
policy_type_version: 1.0.0
policy_type_impl: onap.controllloop.operational.drools.impl
- onap.controllloop.operational.drools.vFW.eastRegion:
policy_type: onap.controllloop.operational.drools.vFW
policy_type_version: 1.0.0
policy_type_impl: onap.controllloop.operational.drools.impl
min_instance_count: 3
instance_count: 3
properties:
# The properties below are for illustration only
instance_spawn_load_threshold: 70%
instance_kill_load_threshold: 50%
instance_geo_redundancy: true
deployment_info:
service_endpoint: https://<the drools service endpoint for this PDP group>
deployment: A deployment identifier
# Other deployment info
instances:
- instance: drools_1
state: active
healthy: yes
deployment_instance_info:
node_address: drools_1_pod
# Other deployment instance info
- instance: drools_2
state: active
healthy: yes
deployment_instance_info:
node_address: drools_2_pod
# Other deployment instance info
- instance: drools_3
state: active
healthy: yes
deployment_instance_info:
node_address: drools_3_pod
# Other deployment instance info
- pdp_type: apex
supported_policy_types:
- onap.controllloop.operational.apex.BBS
- onap.controllloop.operational.apex.SampleDomain
policies:
- onap.controllloop.operational.apex.BBS.eastRegion:
policy_type: onap.controllloop.operational.apex.BBS
policy_type_version: 1.0.0
policy_type_impl: onap.controllloop.operational.apex.impl
- onap.controllloop.operational.apex.sampledomain.eastRegion:
policy_type: onap.controllloop.operational.apex.SampleDomain
policy_type_version: 1.0.0
policy_type_impl: onap.controllloop.operational.apex.impl
min_instance_count: 2
instance_count: 3
properties:
# The properties below are for illustration only
instance_spawn_load_threshold: 80%
instance_kill_load_threshold: 60%
instance_geo_redundancy: true
deployment_info:
service_endpoint: https://<the apex service endpoint for this PDP group>
deployment: A deployment identifier
# Other deployment info
instances:
- instance: apex_1
state: active
healthy: yes
deployment_instance_info:
node_address: apex_1_podgroup
# Other deployment instance info
- instance: apex_2
deployment_instance_info:
node_address: apex_2_pod
# Other deployment instance infoCreation
- instance: apex_3
state: active
healthy: yes
deployment_instance_info:
node_address: apex_3_pod
# Other deployment instance info
- pdp_type: xacml
supported_policy_types:
- onap.policies.controlloop.guard.FrequencyLimiter
- onap.policies.controlloop.guard.BlackList
- onap.policies.controlloop.guard.MinMax
policies:
- onap.policies.controlloop.guard.frequencylimiter.EastRegion:
policy_type: onap.policies.controlloop.guard.FrequencyLimiter
policy_type_version: 1.0.0
policy_type_impl: onap.controllloop.guard.impl
- onap.policies.controlloop.guard.blackList.EastRegion:
policy_type: onap.policies.controlloop.guard.BlackList
policy_type_version: 1.0.0
policy_type_impl: onap.controllloop.guard.impl
- onap.policies.controlloop.Guard.MinMax.EastRegion:
policy_type: onap.policies.controlloop.guard.MinMax
policy_type_version: 1.0.0
policy_type_impl: onap.controllloop.guard.impl
min_instance_count: 2
instance_count: 2
properties:
# The properties below are for illustration only
instance_geo_redundancy: true
deployment_info:
service_endpoint: https://<the XACML service endpoint for this PDP group>
deployment: A deployment identifier
# Other deployment info
instances:
- instance: xacml_1
state: active
healthy: yes
deployment_instance_info:
node_address: xacml_1_pod
# Other deployment instance info
- instance: xacml_2
state: active
healthy: yes
deployment_instance_info:
node_address: xacml_2_pod
# Other deployment instance info
- name: onap.pdpgroup.monitoring
version: 2.1.3
state: active
description: DCAE mS Configuration Policies
properties:
# PDP group level properties if any
pdp_subgroups:
- pdp_type: xacml
supported_policy_types:
- onap.policies.monitoring.cdap.tca.hi.lo.app
policies:
- onap.scaleout.tca:
policy_type: onap.policies.monitoring.cdap.tca.hi.lo.app
policy_type_version: 1.0.0
policy_type_impl: onap.policies.monitoring.impl
min_instance_count: 2
instance_count: 2
properties:
# The properties below are for illustration only
instance_geo_redundancy: true
deployment_info:
service_endpoint: https://<the XACML service endpoint for this PDP group>
deployment: A deployment identifier
# Other deployment info
instances:
- instance: xacml_1
state: active
healthy: yes
deployment_instance_info:
node_address: xacml_1_pod
# Other deployment instance info
- instance: xacml_2
state: active
healthy: yes
deployment_instance_info:
node_address: xacml_2_pod
# Other deployment instance info |
The table below shows some more examples of GET operations
Example | Description |
---|---|
https:{url}:{port}/policy/pap/v1/pdps | Get all PDP Groups and subgroups in the system |
https:{url}:{port}/policy/pap/v1/pdps/groups/onap.pdpgroup.controlloop | Get PDP Groups and subgroups that match the supplied name filter |
https:{url}:{port}/policy/pap/v1/pdps/groups/onap.pdpgroup.monitoring/subgroups/xacml | Get the PDP subgroup informtation for the specified subgroup |
3.3.2 PDP Group Deployment
This operation allows the PDP groups and subgroups to be created. A POST operation is used to create a new PDP group name. A POST operation is also used to update an existing PDP group. Many PDP groups can be created or updated in a single POST operation by specifying more than one PDP group in the POST operation body.
https:{url}:{port}/policy/pap/v1/pdps POST
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
pdp_groups:
- name: onap.pdpgroup.controlloop.operational
description: ONAP Control Loop Operational and Guard policies
pdp_subgroups:
- pdp_type: drools
supportedPolicyTypes:
- onap.controllloop.operational.drools.vcpe.EastRegion
version: 1.2.3
- onap.controllloop.operational.drools.vfw.EastRegion
version: 1.2.3
min_instance_count: 3group
properties:
# The properties below are for illustration only
instance_spawn_load_threshold: 70%
instance_kill_load_threshold: 50%
instance_geo_redundancy: true
- pdp_type: apex
policies:
- onap.controllloop.operational.apex.bbs.EastRegion
version: 1.2.3
- onap.controllloop.operational.apex.sampledomain.EastRegion
version: 1.2.3
min_instance_count: 2
properties:
# The properties below are for illustration only
instance_spawn_load_threshold: 80%
instance_kill_load_threshold: 60%
instance_geo_redundancy: true
- pdp_type: xacml
policies:
- onap.policies.controlloop.guard.frequencylimiter.EastRegion
version: 1.2.3
- onap.policies.controlloop.guard.blacklist.EastRegion
version: 1.2.3
- onap.policies.controlloop.guard.minmax.EastRegion
version: 1.2.3
min_instance_count: 2
properties:
# The properties below are for illustration only
instance_geo_redundancy: true
- name: onap.pdpgroup.monitoring
description: DCAE mS Configuration Policies
properties:
# PDP group level properties if any
pdp_subgroups:
- pdp_type: xacml
policies:
- onap.scaleout.tca
version: 1.2.3
min_instance_count: 2
properties:
# The properties below are for illustration only
instance_geo_redundancy: true |
Other systems such as CLAMP can use this API to deploy policies using a POST operation with the body below where only mandatory fields are specified.
https:{url}:{port}/policy/pap/v1/pdps POST
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
pdp_groups:
- name: onap.pdpgroup.Monitoring
description: DCAE mS Configuration Policies
pdp_subgroups:
- pdp_type: xacml
policies:
- onap.scaleout.tca
|
Simple API for CLAMP to deploy one or more policy-id's with optional policy-version.
https:{url}:{port}/policy/pap/v1/pdps/policies POST
Content-Type: application/json
Code Block |
---|
{
"policies" : [
{
"policy-id": "onap.scaleout.tca",
"policy-version": 1
},
{
"policy-id": "ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3"
},
{
"policy-id": "guard.frequency.ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3"
},
{
"policy-id": "guard.minmax.ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3"
}
]
} |
HTTP status code indicates success or failure.{
Code Block |
---|
"errorDetails": "some error message"
} |
Simple API for CLAMP to undeploy a policy-id with optional policy-version.
https:{url}:{port}/policy/pap/v1/pdps/policies{policy-id} DELETE
https:{url}:{port}/policy/pap/v1/pdps/policies{policy-id}/versions/{policy-version} DELETE
HTTP status code indicates success or failure.
Code Block |
---|
{
"errorDetails": "some error message"
} |
3.3.3 PDP Group Delete
The API also allows PDP groups to be deleted with a DELETE operation. DELETE operations are only permitted on PDP groups in PASSIVE state. The format of the delete operation is as below:
https:{url}:{port}/policy/pap/v1/pdps/groups/onap.pdpgroup.monitoring DELETE
3.3.4 PDP Group State Management
The state of PDP groups is managed by the API. PDP groups can be in states PASSIVE, TEST, SAFE, or ACTIVE. For a full description of PDP group states, see The ONAP Policy Framework architecture page. The state of a PDP group is changed with a PUT operation.
The following PUT operation changes a PDP group to ACTIVE:
https:{url}:{port}/policy/pap/v1/pdps/groups/onap.pdpgroup.monitoring/state=active
There are a number of rules for state management:
- Only one version of a PDP group may be ACTIVE at any time
- If a PDP group with a certain version is ACTIVE and a later version of the same PDP group is activated, then the system upgrades the PDP group
- If a PDP group with a certain version is ACTIVE and an earlier version of the same PDP group is activated, then the system downgrades the PDP group
- There is no restriction on the number of PASSIVE versions of a PDP group that can exist in the system
- <Rules on SAFE/TEST> ? Pamela Dragosh
3.3.5 PDP Group Statistics
This operation allows statistics for PDP groups, PDP subgroups, and individual PDPs to be retrieved.
https:{url}:{port}/policy/pap/v1/pdps/statistics GET
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
report_timestamp: 2019-02-11T15:23:50+00:00
pdp_group_count: 2
pdp_groups:
- name: onap.pdpgroup.controlloop.Operational
state: active
create_timestamp: 2019-02-11T15:23:50+00:00
update_timestamp: 2019-02-12T15:23:50+00:00
state_change_timestamp: 2019-02-13T15:23:50+00:00
pdp_subgroups:
- pdp_type: drools
instance_count: 3
deployed_policy_count: 2
policy_execution_count: 123
policy_execution_ok_count: 121
policy_execution_fail_count: 2
instances:
- instance: drools_1
start_timestamp: 2019-02-13T15:23:50+00:00
policy_execution_count: 50
policy_execution_ok_count: 49
policy_execution_fail_count: 1
- instance: drools_2
start_timestamp: 2019-02-13T15:30:50+00:00
policy_execution_count: 50
policy_execution_ok_count: 49
policy_execution_fail_count: 1
- instance: drools_3
start_timestamp: 2019-02-13T15:33:50+00:00
policy_execution_count: 23
policy_execution_ok_count: 23
policy_execution_fail_count: 0
|
The table below shows some more examples of GET operations for statistics
Example | Description |
---|---|
https:{url}:{port}/policy/pap/v1/pdps/statistics | Get statistics for all PDP Groups and subgroups in the system |
https:{url}:{port}/policy/pap/v1/pdps/groups/onap.pdpgroup.controlloop/statistics | Get statistics for all PDP Groups and subgroups that match the supplied name filter |
https:{url}:{port}/policy/pap/v1/pdps/groups/onap.pdpgroup.monitoring/subgroups/xacml/statistics | Get statistics for the specified subgroup |
3.3.6 PDP Group Health Check
A PDP group health check allows ordering of health checks on PDP groups and on individual PDPs. As health checks may be long lived operations, Health checks are scheduled for execution by this operation. Users check the result of a health check test by issuing a PDP Group Query operation (see Section 3.3.1) and checking the healthy field of PDPs.
https:{url}:{port}/policy/pap/v1/pdps/healthcheck PUT
The operation returns a HTTP status code of 202: Accepted if the health check request has been accepted by the PAP. The PAP then orders execution of the health check on the PDPs. The health check result is retrieved with a subsequent GET operation.
The table below shows some more examples of PUT operations for ordering health checks
Example | Description |
---|---|
https:{url}:{port}/policy/pap/v1/pdps/healthcheck PUT | Order a health check on all PDP Groups and subgroups in the system |
https:{url}:{port}/policy/pap/v1/pdps/groups/onap.pdpgroup.controlloop/healthcheck PUT | Order a health check on all PDP Groups and subgroups that match the supplied name filter |
https:{url}:{port}/policy/pap/v1/pdps/groups/onap.pdpgroup.monitoring/subgroups/xacml/healthcheck PUT | Order a health check on the specified subgroup |
3.4 Policy Decision API - Getting Policy Decisions
Policy decisions are required by ONAP components to support the policy-driven ONAP architecture. Policy Decisions are implemented using the XACML PDP. The calling application must provide attributes in order for the XACML PDP to return a correct decision.
3.4.1 Decision API Schema
The schema for the decision API is defined below.
3.4.2 Decision API Queries
Decision API queries are implemented with a POST operation with a JSON body that specifies the filter for the policies to be returned. The JSON body must comply with the schema sepcified in Section 3.4.1.
https:{url}:{port}/decision/v1/ POST
Description of the JSON Payload for the decision API Call
Field | R/O | Type | Description |
---|---|---|---|
ONAPName | R | String | Name of the ONAP Project that is making the request. |
ONAPComponent | O | String | Name of the ONAP Project component that is making the request. |
ONAPInstance | O | String | Optional instance identification for that ONAP component. |
action | R | String | The action that the ONAP component is performing on a resource. eg. "configure" → DCAE uS onap.Monitoring policy Decisions to configure uS "naming" "placement" "guard" |
These sub metadata structures are used to refine which resource the ONAP component is performing an action upon. At least one is required in order for Policy to return a Decision. Multiple structures may be utilized to help refine a Decision. | |||
policy-type-name | String | The policy type name. This may be a regular expression. | |
policy-id | String | The policy id. This may be a regular expression or an exact value. | |
This example below shows the JSON body of a query for a specify policy-id
Code Block | ||||
---|---|---|---|---|
| ||||
{
"ONAPName": "DCAE",
"ONAPComponent": "PolicyHandler",
"ONAPInstance": "622431a4-9dea-4eae-b443-3b2164639c64",
"action": "configure",
"resource": {
"policy-id": "onap.scaleout.tca"
}
} |
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
{
"policies": {
"onap.scaleout.tca": {
"type": "onap.policies.monitoring.cdap.tca.hi.lo.app",
"version": "1.0.0",
"metadata": {
"policy-id": "onap.scaleout.tca",
"policy-version": 1
},
"properties": {
"tca_policy": {
"domain": "measurementsForVfScaling",
"metricsPerEventName": [
{
"eventName": "vLoadBalancer",
"controlLoopSchemaType": "VNF",
"policyScope": "type=configuration",
"policyName": "onap.scaleout.tca",
"policyVersion": "v0.0.1",
"thresholds": [
{
"closedLoopControlName": "ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3",
"closedLoopEventStatus": "ONSET",
"version": "1.0.2",
"fieldPath": "$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedBroadcastPacketsAccumulated",
"thresholdValue": 500,
"direction": "LESS_OR_EQUAL",
"severity": "MAJOR"
},
{
"closedLoopControlName": "ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3",
"closedLoopEventStatus": "ONSET",
"version": "1.0.2",
"fieldPath": "$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedBroadcastPacketsAccumulated",
"thresholdValue": 5000,
"direction": "GREATER_OR_EQUAL",
"severity": "CRITICAL"
}
]
}
]
}
}
}
}
} |
This example below shows the JSON body of a query for a multiple policy-id's
Code Block | ||||
---|---|---|---|---|
| ||||
{
"ONAPName": "DCAE",
"ONAPComponent": "PolicyHandler",
"ONAPInstance": "622431a4-9dea-4eae-b443-3b2164639c64",
"action": "configure",
"resource": {
"policy-id": [
"onap.scaleout.tca",
"onap.restart.tca"
]
}
} |
The following is the response object:
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
{
"policies": {
"onap.scaleout.tca": {
"type": "onap.policies.monitoring.cdap.tca.hi.lo.app",
"version": "1.0.0",
"metadata": {
"policy-id": "onap.scaleout.tca"
},
"properties": {
"tca_policy": {
"domain": "measurementsForVfScaling",
"metricsPerEventName": [
{
"eventName": "vLoadBalancer",
"controlLoopSchemaType": "VNF",
"policyScope": "type=configuration",
"policyName": "onap.scaleout.tca",
"policyVersion": "v0.0.1",
"thresholds": [
{
"closedLoopControlName": "ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3",
"closedLoopEventStatus": "ONSET",
"version": "1.0.2",
"fieldPath": "$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedBroadcastPacketsAccumulated",
"thresholdValue": 500,
"direction": "LESS_OR_EQUAL",
"severity": "MAJOR"
},
{
"closedLoopControlName": "ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3",
"closedLoopEventStatus": "ONSET",
"version": "1.0.2",
"fieldPath": "$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedBroadcastPacketsAccumulated",
"thresholdValue": 5000,
"direction": "GREATER_OR_EQUAL",
"severity": "CRITICAL"
}
]
}
]
}
}
},
"onap.restart.tca": {
"type": "onap.policies.monitoring.cdap.tca.hi.lo.app",
"version": "1.0.0",
"metadata": {
"policy-id": "onap.restart.tca",
"policy-version": 1
},
"properties": {
"tca_policy": {
"domain": "measurementsForVfScaling",
"metricsPerEventName": [
{
"eventName": "Measurement_vGMUX",
"controlLoopSchemaType": "VNF",
"policyScope": "DCAE",
"policyName": "DCAE.Config_tca-hi-lo",
"policyVersion": "v0.0.1",
"thresholds": [
{
"closedLoopControlName": "ControlLoop-vCPE-48f0c2c3-a172-4192-9ae3-052274181b6e",
"version": "1.0.2",
"fieldPath": "$.event.measurementsForVfScalingFields.additionalMeasurements[*].arrayOfFields[0].value",
"thresholdValue": 0,
"direction": "EQUAL",
"severity": "MAJOR",
"closedLoopEventStatus": "ABATED"
},
{
"closedLoopControlName": "ControlLoop-vCPE-48f0c2c3-a172-4192-9ae3-052274181b6e",
"version": "1.0.2",
"fieldPath": "$.event.measurementsForVfScalingFields.additionalMeasurements[*].arrayOfFields[0].value",
"thresholdValue": 0,
"direction": "GREATER",
"severity": "CRITICAL",
"closedLoopEventStatus": "ONSET"
}
]
}
]
}
}
}
}
}
|
The simple draft example below shows the JSON body of a query in which all the deployed policies for a specific policy type are returned.
Code Block | ||||
---|---|---|---|---|
| ||||
{
"ONAPName": "DCAE",
"ONAPComponent": "PolicyHandler",
"ONAPInstance": "622431a4-9dea-4eae-b443-3b2164639c64",
"action": "configure",
"resource": {
"policy-type": "onap.policies.monitoring.cdap.tca.hi.lo.app"
}
} |
The query above gives a response similar to the example shown below.
Code Block | ||
---|---|---|
| ||
{
"policies": {
"onap.scaleout.tca": {
"type": "onap.policies.monitoring.cdap.tca.hi.lo.app",
"version": "1.0.0",
"metadata": {
"policy-id": "onap.scaleout.tca",
"policy-version": 1,
},
"properties": {
"tca_policy": {
"domain": "measurementsForVfScaling",
"metricsPerEventName": [
{
"eventName": "vLoadBalancer",
"controlLoopSchemaType": "VNF",
"policyScope": "type=configuration",
"policyName": "onap.scaleout.tca",
"policyVersion": "v0.0.1",
"thresholds": [
{
"closedLoopControlName": "ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3",
"closedLoopEventStatus": "ONSET",
"version": "1.0.2",
"fieldPath": "$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedBroadcastPacketsAccumulated",
"thresholdValue": 500,
"direction": "LESS_OR_EQUAL",
"severity": "MAJOR"
},
{
"closedLoopControlName": "ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3",
"closedLoopEventStatus": "ONSET",
"version": "1.0.2",
"fieldPath": "$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedBroadcastPacketsAccumulated",
"thresholdValue": 5000,
"direction": "GREATER_OR_EQUAL",
"severity": "CRITICAL"
}
]
}
]
}
}
},
"onap.restart.tca": {
"type": "onap.policies.monitoring.cdap.tca.hi.lo.app",
"version": "1.0.0",
"metadata": {
"policy-id": "onap.restart.tca",
"policy-version": 1
},
"properties": {
"tca_policy": {
"domain": "measurementsForVfScaling",
"metricsPerEventName": [
{
"eventName": "Measurement_vGMUX",
"controlLoopSchemaType": "VNF",
"policyScope": "DCAE",
"policyName": "DCAE.Config_tca-hi-lo",
"policyVersion": "v0.0.1",
"thresholds": [
{
"closedLoopControlName": "ControlLoop-vCPE-48f0c2c3-a172-4192-9ae3-052274181b6e",
"version": "1.0.2",
"fieldPath": "$.event.measurementsForVfScalingFields.additionalMeasurements[*].arrayOfFields[0].value",
"thresholdValue": 0,
"direction": "EQUAL",
"severity": "MAJOR",
"closedLoopEventStatus": "ABATED"
},
{
"closedLoopControlName": "ControlLoop-vCPE-48f0c2c3-a172-4192-9ae3-052274181b6e",
"version": "1.0.2",
"fieldPath": "$.event.measurementsForVfScalingFields.additionalMeasurements[*].arrayOfFields[0].value",
"thresholdValue": 0,
"direction": "GREATER",
"severity": "CRITICAL",
"closedLoopEventStatus": "ONSET"
}
]
}
]
}
}
},
"onap.vfirewall.tca": {
"type": "onap.policy.monitoring.cdap.tca.hi.lo.app",
"version": "1.0.0",
"metadata": {
"policy-id": "onap.vfirewall.tca",
"policy-version": 1
},
"properties": {
"tca_policy": {
"domain": "measurementsForVfScaling",
"metricsPerEventName": [
{
"eventName": "vLoadBalancer",
"controlLoopSchemaType": "VNF",
"policyScope": "resource=vLoadBalancer;type=configuration",
"policyName": "onap.vfirewall.tca",
"policyVersion": "v0.0.1",
"thresholds": [
{
"closedLoopControlName": "ControlLoop-vFirewall-d0a1dfc6-94f5-4fd4-a5b5-4630b438850a",
"closedLoopEventStatus": "ONSET",
"version": "1.0.2",
"fieldPath": "$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedBroadcastPacketsAccumulated",
"thresholdValue": 500,
"direction": "LESS_OR_EQUAL",
"severity": "MAJOR"
},
{
"closedLoopControlName": "ControlLoop-vFirewall-d0a1dfc6-94f5-4fd4-a5b5-4630b438850a",
"closedLoopEventStatus": "ONSET",
"version": "1.0.2",
"fieldPath": "$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedBroadcastPacketsAccumulated",
"thresholdValue": 5000,
"direction": "GREATER_OR_EQUAL",
"severity": "CRITICAL"
}
]
}
]
}
}
}
}
} |
4. Policy Framework Internal APIs
The Policy Framework uses the internal APIs documented in the subsections below. The APIs in this section are used for internal communication in the Policy Framework. The APIs are NOT supported for use by components outside the Policy Framework and are subject to revision and change at any time.
4.1 PAP to PDP API
This section describes the API between the PAP and PDPs. The APIs in this section are implemented using DMaaP API messaging. There are four messages on the API:
- PDP_STATUS: PDP→PAP, used by PDPs to report to the PAP
- PDP_UPDATE: PAP→PDP, used by the PAP to update the policies running on PDPs, triggers a PDP_STATUS message with the result of the PDP_UPDATE operation
- PDP_STATE_CHANGE: PAP→PDP, used by the PAP to change the state of PDPs, triggers a PDP_STATUS message with the result of the PDP_STATE_CHANGE operation
- PDP_HEALTH_CHECK: PAP→PDP, used by the PAP to order a heakth check on PDPs, triggers a PDP_STATUS message with the result of the PDP_HEALTH_CHECK operation
The fields below are valid on API calls:
Field | PDP STATUS | PDP UPDATE | PDP STATE CHANGE | PDP HEALTH CHECK | Comment | |
---|---|---|---|---|---|---|
(message_name) | M | M | M | M | pdp_status, pdp_update, pdp_state_change, or pdp_health_check | |
name | M | M | C | C | The name of the PDP, for state changes and health checks, the PDP group and subgroup can be used to specify the scope of the operation | |
version | M | N/A | N/A | N/A | The version of the PDP | |
pdp_type | M | M | N/A | N/A | The type of the PDP, currently xacml, drools, or apex | |
state | M | N/A | M | N/A | The administrative state of the PDP group: PASSIVE, SAFE, TEST, ACTIVE, or TERMINATED | |
healthy | M | N/A | N/A | N/A | The result of the latest health check on the PDP: HEALTHY/NOT_HEALTHY/TEST_IN_PROGRESS | |
description | O | O | N/A | N/A | The description of the PDP | |
pdp_group | O | M | C | C | The PDP group to which the PDP belongs, the PDP group and subgroup can be used to specify the scope of the operation | |
pdp_subgroup | O | M | C | C | The PDP subgroup to which the PDP belongs, the PDP group and subgroup can be used to specify the scope of the operation | |
supported_policy_types | M | N/A | N/A | N/A | A list of the policy types supported by the PDP | |
policies | O | M | N/A | N/A | The list of policies running on the PDP | |
(name) | O | M | N/A | N/A | The name of a TOSCA policy running on the PDP | |
policy_type | O | M | N/A | N/A | The TOSCA policy type of the policyWhen a PDP starts, it commences periodic sending of PDP_STATUS messages on DMaaP. The PAP receives these messages and acts in whatever manner is appropriate. | |
policy_type_version | O | M | N/A | N/A | The version of the TOSCA policy type of the policy | |
properties | O | M | N/A | N/A | The properties of the policy for the XACML, Drools, or APEX PDP, see section 3.2 for details | |
instance | M | N/A | N/A | N/A | The instance ID of the PDP running in a Kuberenetes Pod | |
deployment_instance_info | M | N/A | N/A | N/A | Information on the node running the PDP | |
properties | O | O | N/A | N/A | Other properties specific to the PDP | |
statistics | M | N/A | N/A | N/A | Statistics on policy execution in the PDP | |
policy_download_count | M | N/A | N/A | N/A | The number of policies downloaded into the PDP | |
policy_download_success_count | M | N/A | N/A | N/A | The number of policies successfully downloaded into the PDP | |
policy_download_fail_count | M | N/A | N/A | N/A | The number of policies downloaded into the PDP where the download failed | |
policy_executed_count | M | N/A | N/A | N/A | The number of policy executions on the PDP | |
policy_executed_success_count | M | N/A | N/A | N/A | The number of policy executions on the PDP that completed successfully | |
policy_executed_fail_count | M | N/A | N/A | N/A | The number of policy executions on the PDP that failed | |
response | O | N/A | N/A | N/A | The response to the last operation that the PAP executed on the PDP | |
response_to | M | N/A | N/A | N/A | The PAP to PDP message to which this is a response | |
response_status | M | N/A | N/A | N/A | SUCCESS or FAIL | |
response_message | O | N/A | N/A | N/A | Message giving further information on the successful or failed operation |
YAML is used for illustrative purposes in the examples in this section. JSON (application/json) is used as the content type in the implementation of this API.
Note: The PAP checks that the set of policy types supported in all PDPs in a PDP subgroup are identical and will not add a PDP to a PDP subgroup that has a different set of supported policy types
Note: The PA checks that the set of policy loaded on all PDPs in a PDP subgroup are are identical and will not add a PDP to a PDP subgroup that has a different set of loaded policies
4.1.1 PAP API for PDPs
The purpose of this API is for PDPs to provide heartbeat, status. health, and statistical information to Policy Administration. There is a single PDP_STATUS message on this API. PDPs send this message to the PAP using the POLICY_PDP_PAP DMaaP topic. The PAP listens on this topic for messages.
When a PDP starts, it commences periodic sending of PDP_STATUS messages on DMaaP. The PAP receives these messages and acts in whatever manner is appropriate. PDP_UPDATE, PDP_STATE_CHANGE, and PDP_HEALTH_CHECK operations trigger a PDP_STATUS message as a response.
The PDP_STATUS message is used for PDP heartbeat monitoring. A PDP sends a PDP_STATUS message with a state of TERMINATED when it terminates normally. If a PDP_STATUS message is not received from a PDP in a certain configurable time, then the PAP assumes the PDP has failed.
A PDP may be preconfigured with its PDP group, PDP subgroup, and policies. If the PDP group, subgroup, or any policy sent to the PAP in a PDP_STATUS message is unknown to the PAP, the PAP locks the PDP in state PASSIVE.
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
pdp_status:
name: xacml_1
version: 1.2.3
pdp_type: xacml
state: active
healthy: true
description: XACML PDP running control loop policies
pdp_group: onap.pdpgroup.controlloop.operational
pdp_subgroup: xacml
supported_policy_types:
- onap.policies.controlloop.guard.FrequencyLimiter
- onap.policies.controlloop.guard.BlackList
- onap.policies.controlloop.guard.MinMax
policies:
- onap.policies.controlloop.guard.frequencylimiter.EastRegion:
policy_type: onap.policies.controlloop.guard.FrequencyLimiter
policy_type_version: 1.0.0
properties:
# Omitted for brevity, see Section 3.2
- onap.policies.controlloop.guard.blacklist.eastRegion:
policy_type: onap.policies.controlloop.guard.BlackList
policy_type_version: 1.0.0
properties | ||||||
Code Block | ||||||
| ||||||
# # 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: # Omitted for brevity, see Section 3.2 - onap.policies.controlloop.guard.minmax.eastRegion: policy_type: onap.policies.controlloop.guard.MinMax pdp policy_type_version: drools 1.0.0 properties: # Omitted for brevity, see Section 3.2 instance: xacml_1 instancesdeployment_instance_info: node_address: xacml_1_pod # Other deployment instance info statistics: -policy_download_count: 0 policy_download_success_count: 0 policy_download_fail_count: 0 policy_executed_count: 123 policy_executed_success_count: 122 instance: drools_1 # K8S identifier? IP?? models: policy_executed_fail_count: 1 |
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
pdp_status: name: drools_2 version: 2.3.4 pdp_type: drools state: safe healthy: true description: Drools PDP running control loop policies pdp_group: onap.pdpgroup.controlloop.operational pdp_subgroup: drools supported_policy_types: - onap.controllloop.operational.drools.vCPE - onap.controllloop.operational.drools.vFW policies: - onap.controlloopcontrollloop.operational.drools.vcpe.EastRegion: policy_type: onap.controllloop.operational.drools.vCPE -policy_type_version: 1.0.0 properties: # Omitted for brevity, see instance: drools_Section 3.2 - onap.controllloop.operational.drools.vfw.EastRegion: policy_type: onap.controllloop.operational.drools.vFW models:policy_type_version: 1.0.0 properties: # Omitted for brevity, see - onap.controlloop.operational Section 3.2 instance: drools_2 deployment_instance_info: -node_address: drools_2_pod # Other deployment instance info statistics: policy_download_count: 3 policy_download_success_count: 3 instancepolicy_download_fail_count: drools-30 policy_executed_count: 123 policy_executed_success_count: 122 policy_executed_fail_count: 1 response: response_to: PDP_HEALTH_CHECK models: response_status: SUCCESS |
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
pdp_status: name: apex_3 version: 2.2.1 pdp_type: apex state: test healthy: true description: APEX PDP running control loop policies -pdp_group: onap.pdpgroup.controlloop.operational pdp_subgroup: apex supported_policy_types: - onap.controllloop.operational.apex.BBS - onap.controllloop.operational.apex.SampleDomain policies: - onap.controllloop.operational.apex.bbs.EastRegion: pdppolicy_type: onap.controllloop.operational.apex.BBS policy_type_version: 1.0.0 instances properties: # Omitted for brevity, see Section 3.2 - onap.controllloop.operational.apex.sampledomain.EastRegion: policy_type: onap.controllloop.operational.apex.SampleDomain instancepolicy_type_version: apex_1.0.0 properties: # Omitted for brevity, see Section models: 3.2 instance: apex_3 deployment_instance_info:node_address node_address: apex_3_pod # Other deployment instance info statistics: - onap.controlloop.operationalpolicy_download_count: 2 policy_download_success_count: 2 policy_download_fail_count: 0 policy_executed_count: 123 -policy_executed_success_count: 122 policy_executed_fail_count: 1 response: response_to: PDP_UPDATE response_status: FAIL instanceresponse_message: apex_2 policies specified in update message incompatible with running policy state |
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
pdp_status: name: xacml_1 version: 1.2.3 pdp_type: xacml state: active healthy: models:true description: XACML PDP running monitoring policies pdp_group: onap.pdpgroup.Monitoring pdp_subgroup: xacml supported_policy_types: - onap.monitoring.cdap.tca.hi.lo.app policies: - onap.controlloopscaleout.operationaltca:message policy_type: onap.policies.monitoring.cdap.tca.hi.lo.app policy_type_version: 1.0.0 - properties: # Omitted for brevity, see Section 3.2 instance: apexxacml_31 deployment_instance_info: node_address: xacml_1_pod # Other deployment instance info statistics: models: policy_download_count: 0 policy_download_success_count: 0 policy_download_fail_count: 0 policy_executed_count: 123 policy_executed_success_count: 122 policy_executed_fail_count: 1 |
4.1.2 PDP API for PAPs
The purpose of this API is for the PAP to load and update policies on PDPs and to change the state of PDPs. It also allows the PAP to order health checks to run on PDPs. The PAP sends PDP_UPDATE, PDP_ STATE_CHANGE, and PDP_HEALTH_CHECK messages to PDPs using the POLICY_PAP_PDP DMaaP topic. PDPs listens on this topic for messages.
The PAP can set the scope of STATE_CHANGE, and PDP_HEALTH_CHECK messages:
- PDP Group: If a PDP group is specified in a message, then the PDPs in that PDP group respond to the message and all other PDPs ignore it.
- PDP Group and subgroup: If a PDP group and subgroup are specified in a message, then only the PDPs of that subgroup in the PDP group respond to the message and all other PDPs ignore it.
- Single PDP: If the name of a PDP is specified in a message, then only that PDP responds to the message and all other PDPs ignore it.
Note: PDP_UPDATE messages must be issued individually to PDPs because the PDP_UPDATE operation can change the PDP group to which a PDP belongs.
4.1.2.1 PDP Update
The PDP_UPDATE operation allows the PAP to modify the PDP group to which a PDP belongs and the policies in a PDP. Only PDPs in state PASSIVE accept this operation. The PAP must change the state of PDPs in state ACTIVE, TEST, or SAFE to state PASSIVE before issuing a PDP_UPDATE operation on a PDP.
The following examples illustrate how the operation is used.
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
pdp_update: name: xacml_1 pdp_type: xacml description: XACML PDP running control loop policies, Upgraded pdp_group: onap.pdpgroup.controlloop.operational pdp_subgroup: xacml policies: - onap.policies.controlloop.guard.frequencylimiter.EastRegion: - 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: policy_type: onap.policies.controlloop.guard.FrequencyLimiter - onap.controlloop.guardpolicy_type_version: 1.0.1 properties: # Omitted for brevity, see Section 3.2 - onap.policies.controlloop.coordination.guard.blackList.EastRegion: - policy_type: onap.policies.controlloop.guard.BlackList name: DCAE policy group_type_version: 1.0.1 descriptionproperties: DCAE mS Configuration Policies # Omitted subgroups: for brevity, see Section 3.2 -- onap.policies.controlloop.guard.minmax.EastRegion: policy_type: onap.policies.controlloop.guard.MinMax pdppolicy_type_version: xacml1.0.1 instancesproperties: # Omitted for brevity, see -Section 3.2 |
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
pdp_update: name: drools_2 pdp_type: drools description: Drools PDP running control loop policies, extra policy added instance: xacml_1pdp_group: onap.pdpgroup.controlloop.operational pdp_subgroup: drools policies: models- onap.controllloop.operational.drools.vcpe.EastRegion: policy_type: onap.controllloop.operational.drools.vCPE - onap.controlloop.monitoringpolicy_type_version: 1.0.0 properties: - # Omitted for brevity, see Section 3.2 - onap.controllloop.operational.drools.vfw.EastRegion: instance: xacml_2policy_type: onap.controllloop.operational.drools.vFW policy_type_version: 1.0.0 modelsproperties: # Omitted for brevity, see Section 3.2 - onap.controlloopcontrollloop.monitoring |
...
operational. |
...
http:{url}:{port}/pap/v1/pdpgroup POST
Code Block | ||
---|---|---|
| ||
# # PAP - how it lists existing PDP Groups and Sub Groups and the models loaded # pdp_groupsdrools.vfw.WestRegion: - policy_type: onap.controllloop.operational.drools.vFW name: Control Loop runtime group policy_type_version: 1.0.0 descriptionproperties: ONAP Control Loop Operational and Guard policies # Omitted for brevity, see subgroupsSection 3.2 |
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
pdp_update: name: apex_3 pdp_type: apex description: APEX PDP updated to - remove a control loop policy pdp_group: onap.pdpgroup.controlloop.operational pdp_subgroup: apex policies: pdp_type: drools - onap.controllloop.operational.apex.bbs.EastRegion: policy_type: onap.controllloop.operational.apex.BBS models:policy_type_version: 1.0.0 properties: # MavenOmitted coordinatesfor here brevity, see Section 3.2 |
4.1.2.2 PDP State Change
The PDP_STATE_CHANGE operation allows the PAP to order state changes on PDPs in PDP groups and subgroups. The following examples illustrate how the operation is used.
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
pdp_state_change: state: active - "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.
Code Block |
---|
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.
...
language | js |
---|---|
title | Decision API for getting single TCA policy |
linenumbers | true |
collapse | true |
...
pdp_group: onap.pdpgroup.controlloop.Operational
pdp_subgroup: drools |
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
pdp_state_change:
state: safe
pdp_group: onap.pdpgroup.Monitoring |
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
pdp_state_change:
state: test
name: apex_3 |
4.1.2.3 PDP Health Check
The PDP_HEALTH_CHECK operation allows the PAP to order health checks on PDPs in PDP groups and subgroups. The following examples illustrate how the operation is used.
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
pdp_health_check:
pdp_group: onap.pdpgroup.controlloop.Operational
pdp_subgroup: drools |
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
pdp_health_check:
pdp_group: onap.pdpgroup.Monitoring |
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
pdp_health_check:
name: apex_3 |
4.2 Policy Type Implementations (Native Policies)
The policy Framework must have implementations for all Policy Type entities that may be specified in TOSCA. Policy type implementations are native policies for the various PDPs supported in the Policy Framework. They may be predefined and preloaded into the Policy Framework. In addition, they may also be added, modified, queried, or deleted using this API during runtime.
The API supports CRUD of PolicyTypeImpl policy type implementations, where the XACML, Drools, and APEX policy type implementations are supplied as strings. This API is provided by the PolicyDevelopment component of the Policy Framework, see The ONAP Policy Framework architecture.
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.
Note: Preloaded policy type implementations may only be queried over this API, modification or deletion of preloaded policy type implementations is disabled.
Note: Policy type implementations that are in use (referenced by defined Policies) may not be deleted.
The fields below are valid on API calls:
Field | GET | POST | DELETE | Comment | ||
---|---|---|---|---|---|---|
name | M | M | M | The name of the Policy Type implementation | ||
version | O | M | C | The version of the Policy Type implementation | ||
policy_type | R | M | N/A | The TOSCA policy type that this policy type implementation implements | ||
pdp_type | R | M | N/A | The PDP type of this policy type implementation, currently xacml, drools, or apex | ||
description | R | O | N/A | The description of the policy type implementation | ||
writable | R | N/A | N/A | Writable flag, false for predefined policy type implementations, true for policy type implementations defined over the API | ||
policy_body | R | M | N/A | The body (source) of the policy type implementation | ||
properties | R | O | N/A | Specific properties for the policy type implementation |
4.2.1 Policy Type Implementation Query
This operation allows the PDP groups and subgroups to be listed together with the policies that are deployed on each PDP group and subgroup.
https:{url}:{port}/policy/api/v1/native/onap.policies.controlloop.operational/impls GET
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
policy_type_impls:
- name: onap.policies.controlloop.operational.drools.Impl
version: 1.0.0
policy_type: onap.policies.controlloop.Operational
pdp_type: drools
description: Implementation of the drools control loop policies
writable: false
- name: onap.policies.controlloop.operational.apex.bbs.Impl
version: 1.0.0
policy_type: onap.policies.controlloop.operational.Apex
pdp_type: apex
description: Implementation of the APEX BBS control loop policy
writable: true
policy_body: "<policy body>"
- name: onap.policies.controlloop.operational.apex.sampledomain.Impl
version: 1.0.0
policy_type: onap.policies.controlloop.operational.Apex
pdp_type: apex
description: Implementation of the SampleDomain test APEX policy
writable: true
policy_body: "<policy body>" |
The table below shows some more examples of GET operations
Example | Description |
---|---|
https:{url}:{port}/policy/api/v1/native/{policy type id}/impls eg. | Get all Policy Type implementations for the given policy type |
https:{url}:{port}/policy/api/v1/native/{policy type id}/impls/{policy type impl id} eg. | Get all Policy Type implementation versions that match the policy type and policy type implementation IDs specified |
https:{url}:{port}/policy/api/v1/native/{policy type id}/impls/{policy type impl id}/versions/{version id} eg. | Get the specific Policy Type implementation with the specified name and version, if the version ID is specified a latest, the latest version is returned |
4.2.2 Policy Type Implementation Create/Update
The API allows users (such as a policy editor or DevOps system) to create or update a Policy Type implementation using a POST operation. This API allows new Policy Type implementations to be created or existing Policy Type implementations to be modified. POST operations with a new name or a new version of an existing name are used to create a new Policy Type implementation. POST operations with an existing name and version are used to update an existing Policy Type implementations. Many implementations can be created or updated in a single POST operation by specifying more than one Policy Type implementation on the policy_type_impls list.
For example, the POST operation below with the YAML body below is used to create a new APEX Policy type implementation.
https:{url}:{port}/policy/api/v1/native/onap.policies.controlloop.operational.apex/impls POST
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
policy_type_impls:
- onap.policies.controlloop.operational.apex.bbs.Impl:
version: 1.0.0
policy_type: onap.policies.controlloop.operational.Apex
pdp_type: apex
description: Implementation of the APEX BBS control loop policy
policy_body: "<policy body>"
- onap.policies.controlloop.operational.apex.sampledomain.Impl:
version: 1.0.0
policy_type: onap.policies.controlloop.operational.Apex
pdp_type: apex
description: Implementation of the APEX SampleDomain control loop policy
policy_body: "<policy body> |
Once this call is made, the Policy Type query in Section 3.1.2.1 returns a result with the new Policy Type implementation defined.
4.2.3 Policy Type Implementation Delete
The API also allows Policy Type implementations to be deleted with a DELETE operation. The format of the delete operation is as below:
https:{url}:{port}/api/v1/native/onap.policies.controlloop.operational.apex/impls/onap.policies.apex.bbs.impl/versions/1.0.0 DELETE
Note: Predefined policy type implementations cannot be deleted
Note: Policy type implementations that are in use (Parameterized by a TOSCA Policy) may not be deleted, the parameterizing TOSCA policies must be deleted first
Note: The version parameter may be omitted on the DELETE operation if there is only one version of the policy type implementation in the system
...