From 4d1d9830d51d3df59cadaa0ac9c9b004f2cb0d17 Mon Sep 17 00:00:00 2001 From: liamfallon Date: Thu, 30 May 2019 20:53:05 +0000 Subject: Design and Public API documentation completed. The draw.io diagrams are in Gerrit. If the page is ever deleted, they will be lost. They ae now saved in XML format in gerrit. The design documentation links to the examples in github rather than quoting them in the document. General tidy up and cleaning of links, rewording, and reformatting of desgin document. Added missing diagram to the Design document. Updated and tidied up the internal PAP/PDP document. General improvement of documentation. Issue-ID: POLICY-1676 Change-Id: Ie5c9f32693f047beafe14a3e412a32cdf9ed6fde Signed-off-by: liamfallon --- docs/architecture/architecture.rst | 13 +- docs/architecture/draw.io/ClassStructure.xml | 2 + docs/architecture/draw.io/DesignTimeComponents.xml | 2 + docs/architecture/draw.io/PFDesignAndAdmin.xml | 2 + docs/architecture/draw.io/PFHighestLevel.xml | 2 + docs/architecture/draw.io/PolicyExecution.xml | 2 + docs/architecture/draw.io/TOSCAPolicyConcepts.xml | 2 + docs/architecture/images/ClassStructure.svg | 2 + docs/architecture/images/DesignTimeComponents.svg | 2 + docs/architecture/images/PFDesignAndAdmin.svg | 2 + docs/architecture/images/PFHighestLevel.svg | 2 + docs/architecture/images/PolicyExecution.svg | 36 +- docs/architecture/images/PolicyExecutionFlow.svg | 34 + docs/architecture/images/TOSCAPolicyConcepts.svg | 2 + docs/architecture/images/ToscaPolicyStructure.png | Bin 26067 -> 0 bytes docs/architecture/images/detailed.png | Bin 214476 -> 0 bytes docs/architecture/images/execution.png | Bin 104106 -> 0 bytes docs/architecture/images/highest.png | Bin 40638 -> 0 bytes docs/architecture/images/objectmodel1.png | Bin 186880 -> 0 bytes docs/architecture/images/objectmodel2.png | Bin 170899 -> 0 bytes docs/architecture/plantuml/PolicyExecution.puml | 24 - .../architecture/plantuml/PolicyExecutionFlow.puml | 24 + docs/architecture/tosca-policy-primer.rst | 6 +- docs/design/InternalPapPdp.rst | 428 ++ docs/design/design.png | Bin 230981 -> 0 bytes docs/design/design.rst | 880 +++- docs/design/draw.io/APIsInPolicyFramework.xml | 2 + docs/design/draw.io/PolicyImplPDPSubGroup.xml | 2 + docs/design/foo.rst | 4898 -------------------- docs/design/images/APIsInPolicyFramework.svg | 2 + docs/design/images/PolicyImplPDPSubGroup.svg | 2 + docs/pap/pap.rst | 149 +- 32 files changed, 1407 insertions(+), 5115 deletions(-) create mode 100644 docs/architecture/draw.io/ClassStructure.xml create mode 100644 docs/architecture/draw.io/DesignTimeComponents.xml create mode 100644 docs/architecture/draw.io/PFDesignAndAdmin.xml create mode 100644 docs/architecture/draw.io/PFHighestLevel.xml create mode 100644 docs/architecture/draw.io/PolicyExecution.xml create mode 100644 docs/architecture/draw.io/TOSCAPolicyConcepts.xml create mode 100644 docs/architecture/images/ClassStructure.svg create mode 100644 docs/architecture/images/DesignTimeComponents.svg create mode 100644 docs/architecture/images/PFDesignAndAdmin.svg create mode 100644 docs/architecture/images/PFHighestLevel.svg create mode 100644 docs/architecture/images/PolicyExecutionFlow.svg create mode 100644 docs/architecture/images/TOSCAPolicyConcepts.svg delete mode 100644 docs/architecture/images/ToscaPolicyStructure.png delete mode 100644 docs/architecture/images/detailed.png delete mode 100644 docs/architecture/images/execution.png delete mode 100644 docs/architecture/images/highest.png delete mode 100644 docs/architecture/images/objectmodel1.png delete mode 100644 docs/architecture/images/objectmodel2.png delete mode 100644 docs/architecture/plantuml/PolicyExecution.puml create mode 100644 docs/architecture/plantuml/PolicyExecutionFlow.puml create mode 100644 docs/design/InternalPapPdp.rst delete mode 100644 docs/design/design.png create mode 100644 docs/design/draw.io/APIsInPolicyFramework.xml create mode 100644 docs/design/draw.io/PolicyImplPDPSubGroup.xml delete mode 100644 docs/design/foo.rst create mode 100644 docs/design/images/APIsInPolicyFramework.svg create mode 100644 docs/design/images/PolicyImplPDPSubGroup.svg diff --git a/docs/architecture/architecture.rst b/docs/architecture/architecture.rst index 727cb6c9..175bb20d 100644 --- a/docs/architecture/architecture.rst +++ b/docs/architecture/architecture.rst @@ -2,6 +2,7 @@ .. Creative Commons Attribution 4.0 International License. .. http://creativecommons.org/licenses/by/4.0 +.. _architecture-label: Architecture ############ @@ -94,7 +95,7 @@ of conflicts across all policies running in an ONAP installation. The diagram below shows the architecture of the ONAP Policy Framework at its highest level. -.. image:: images/highest.png +.. image:: images/PFHighestLevel.svg The *PolicyDevelopment* component implements the functionality for development of policy types and policies. *PolicyAdministration* is responsible for the deployment life cycle of policies as well as interworking with the @@ -113,7 +114,7 @@ with *PolicyAdministration*, *PolicyExecution* or any other run-time ONAP compon The diagram below shows a more detailed view of the architecture, as inspired by `RFC-2753 `__ and `RFC-3198 `__. -.. image:: images/detailed.png +.. image:: images/PFDesignAndAdmin.svg *PolicyDevelopment* provides a `CRUD `__ API for policy types and policies. The policy types and policy artifacts and their metadata (Information about policies, policy types, @@ -142,7 +143,7 @@ three APIs: *PolicyExecution* is the set of running PDPs that are executing policies, logically partitioned into PDP groups and subgroups. -.. image:: images/execution.png +.. image:: images/PolicyExecution.svg The figure above shows how *PolicyExecution* looks at run time with PDPs running in Kubernetes. A *PDPGroup* is a purely logical construct that collects all the PDPs that are running policies for a particular domain together. A *PDPSubGroup* @@ -179,12 +180,12 @@ for :ref:`Policy Administration Point (PAP) Architecture `. This section describes the structure of and relations between the main concepts in the Policy Framework. This model is implemented as a common model and is used by *PolicyDevelopment*, *PolicyDeployment,* and *PolicyExecution.* -.. image:: images/objectmodel1.png +.. image:: images/ClassStructure.svg The UML class diagram above shows the portion of the Policy Framework Object Model that applies to *PolicyDeployment* and *PolicyExecution.* -.. image:: images/objectmodel2.png +.. image:: images/DesignTimeComponents.svg The UML class diagram above shows the portion of the Policy Framework Object Model that applies to *PolicyDevelopment* and *PolicyDeployment.* @@ -498,7 +499,7 @@ On receipt or a shutdown request, the PDP completes or aborts any ongoing policy Policy execution is the execution of a policy in a PDP. Policy enforcement occurs in the component that receives a policy decision. -.. image:: images/PolicyExecution.svg +.. image:: images/PolicyExecutionFlow.svg Policy execution can be *synchronous* or *asynchronous*. In *synchronous* policy execution, the component requesting a policy decision requests a policy decision and waits for the result. The PDP-X and PDP-A implement synchronous policy diff --git a/docs/architecture/draw.io/ClassStructure.xml b/docs/architecture/draw.io/ClassStructure.xml new file mode 100644 index 00000000..9619a8e2 --- /dev/null +++ b/docs/architecture/draw.io/ClassStructure.xml @@ -0,0 +1,2 @@ + + \ No newline at end of file diff --git a/docs/architecture/draw.io/DesignTimeComponents.xml b/docs/architecture/draw.io/DesignTimeComponents.xml new file mode 100644 index 00000000..032d8558 --- /dev/null +++ b/docs/architecture/draw.io/DesignTimeComponents.xml @@ -0,0 +1,2 @@ + + \ No newline at end of file diff --git a/docs/architecture/draw.io/PFDesignAndAdmin.xml b/docs/architecture/draw.io/PFDesignAndAdmin.xml new file mode 100644 index 00000000..9ba43502 --- /dev/null +++ b/docs/architecture/draw.io/PFDesignAndAdmin.xml @@ -0,0 +1,2 @@ + + \ No newline at end of file diff --git a/docs/architecture/draw.io/PFHighestLevel.xml b/docs/architecture/draw.io/PFHighestLevel.xml new file mode 100644 index 00000000..a307574f --- /dev/null +++ b/docs/architecture/draw.io/PFHighestLevel.xml @@ -0,0 +1,2 @@ + + \ No newline at end of file diff --git a/docs/architecture/draw.io/PolicyExecution.xml b/docs/architecture/draw.io/PolicyExecution.xml new file mode 100644 index 00000000..1dbf4da3 --- /dev/null +++ b/docs/architecture/draw.io/PolicyExecution.xml @@ -0,0 +1,2 @@ + + \ No newline at end of file diff --git a/docs/architecture/draw.io/TOSCAPolicyConcepts.xml b/docs/architecture/draw.io/TOSCAPolicyConcepts.xml new file mode 100644 index 00000000..0d3900dd --- /dev/null +++ b/docs/architecture/draw.io/TOSCAPolicyConcepts.xml @@ -0,0 +1,2 @@ + +7VttT+M4EP41le4+UOW1Lx9pYfdOYiV0IB18WrmJm1jrxpHrQru//saJnfewKWQD6IKQiMfjsT3PeGY8CRN7vTt+5SgOvzEf04ll+MeJfTWxLNNeuvBHUk4pZWEsUkLAia+YcsId+YkV0VDUA/HxvsQoGKOCxGWix6IIe6JEQ5yz5zLbltHyrDEK1IxGTrjzEMU1tn+JL0K1C7fA/RcmQahnNg3Vs0Hej4CzQ6Tmm1j2NvlJu3dIy1L8+xD57LlAsq8n9pozJtKn3XGNqdStVls67ktLb7ZujiPRZYBexxOiB7X3W0aJd1LLEyetkv0z2VEUQWu1ZZG4Uz0GtL2QUP8GndhBzrkXoAPdWoWMk5/Ajyh0mUCAbi4U4tZMSiOUrhllPJlHqsvyvNLIOylRzcXxHsbe6g2aFdI3dCwx3qC90KtklKJ4TzbJuuXAHeIBiVZMCLZTTHvB2Q9cWI4/28xcucy6ZpWynzAX+FggKU1/xWyHBQdNGrp3rrStToXpzNP2c25jlq14wqJ9GY6ybWXXQSY7xxYeFLwtUJs1qCfWSu6Jsxj2QOSBu1QNuWofb0lEBGERNCgBRVZtAvYtXlRaG7aIkiACGsVbKUCqkMDpu1RkwWIpNkYeiYKbhOfKySn/KM1IEoOxW5ocoZD4Po4k9EwggTaZfcaMRCLRnLuCX1Dw2pi6ExeWtIa2mbfhV7JzsWYR7AqRBGsMRvSMpSE1WEF2gn5tBgp2sPpOqGu+N4FutYAOpzDAUimXCaQc1Jpo52oEuReQXWtAkO02kDkJAswVyqo1HuY+cZ4vhsPZbgvW96cYjwG7/4B9sSgH7CHDtd0pXOftMWJ3PeT2h47Y9hix3wfkISO2PUbsd8N5yIjt1CN2DUVZLoi7B6us6KE0PCkWDhqDmO2+8tppzYy3q8Csx7F7bdZjxvKLjMXpbt2DJCVmW3DCT7Dm70LmocX4ZBl/JD3wEKEd/nN0YU1pafe89B3yEbMtVO29EPsHqgC/Jzv8dyQwB74R5V5QHjIhMZ0Xs87vABBgm0KtT7SijWD3AfagdYQ2sCGz8NPrYwK0l+8XGhQd9vUqw4j2WVFap2A6GA8Ct9sOd7bDEe/firfGdhC8Zy14x5gT5qsEDXSP+MUhImIqIHaPQPcDtDtkqWjemo0DBUlHrgoJsFfcdOMaQX4VyIshS0WLFpBBUpidZnXdGuHtAV7LGDIXW7bAi7w8Ectu00zWAmW5H6VF/hHvPvC2B0zGnKbce0blXnzyBI9BgmCMPbIFCFKY034QXWBpGMW2bawVO8GRfym/koJWxJJ6Wyh2unoGnap2Zlq6mFbhLhbYTEcTvhC56wRh7AdYl+8AvZAFLEL0Oqeu8JGIBz0jPD/KkVNjOUtXUJQVgYofkm5XNx91H4y8hawGYJC304TWcBtTCmAH7ikNaHjT660+9ylNLv5Fu9GFVWNqm4Yqj3BMAawnXJqxyVCUuFuWptlZkXZZLtI6i0rtNV29GpbbW01SVZBpVQSlW35BkGZk2+0el3gS484U0c3e65cPDUduj0khteAgCtbYyTNRtMF0lX16V/Zw8uM7VVBWFttsJfpkNpfXz3ptbJ5pE52dRz2zN6bTehzooE+eurXPodBz9VkxaHUSLiyrPKQfA29Kwmuu2UPylfwGd/bl6tUf9uWw0yfy62f57ofC82PG1s2D23UPrstuZ3hwuJk7/Xjw7BtgXdGrWFtXB36RBadq8eCdPHj9AvJapzOAE5+/mxNvC+xlMC+qSWQ/GNVvER85MPQGUk8YWRWInN8AkX4JX4Ao+9jj8/hxc2oYTsmTT03TLXpzYFiWPLppZa6/mqq/On23GtL3c50/rNTUN/0M+Xk/BlX90F/Pc34ssNyyJHd+ZixQkqpyKgvqx8Trn3p83Eihz+P/LFLol8qfI1L0B1I/GFnLCkTLt0MEzfz/vVL2/J/q7Ov/AA== \ No newline at end of file diff --git a/docs/architecture/images/ClassStructure.svg b/docs/architecture/images/ClassStructure.svg new file mode 100644 index 00000000..650e5a31 --- /dev/null +++ b/docs/architecture/images/ClassStructure.svg @@ -0,0 +1,2 @@ + +

MicroService

[Not supported by viewer]

PDPGroup

[Not supported by viewer]
1
1
1..n
1..n

PDPSubGroup

[Not supported by viewer]

PDP

[Not supported by viewer]
1
1
1..n
1..n

<<enumeration>>
PDPType

PDP-X
PDP-D
PDP-A
[Not supported by viewer]
1
1

PDP-X

[Not supported by viewer]

PDP-D

[Not supported by viewer]

PDP-A

[Not supported by viewer]

Kubernetes

[Not supported by viewer]
manages
manages
0..n
[Not supported by viewer]

PolicyImpl

[Not supported by viewer]

XACMLPolicyImpl

[Not supported by viewer]

DroolsPolicyImpl

[Not supported by viewer]

ApexPolicyImpl

[Not supported by viewer]
1
1
executes
executes
0..n
[Not supported by viewer]

PolicySet

[Not supported by viewer]
executes
executes
1
1
1
1
1
1
1..n
1..n
All the PDPs in a given PDPSubGroup instance must be of the same type
[Not supported by viewer]

PolicyTypeImpl

[Not supported by viewer]

<<TOSCA>>
Policy

[Not supported by viewer]
has implementation
has implementation
n
[Not supported by viewer]
1
1
is specified by
is specified by
n
[Not supported by viewer]
1
1

<<TOSCA>>
PolicyType

[Not supported by viewer]
is defined by
is defined by
n
[Not supported by viewer]
1
1 \ No newline at end of file diff --git a/docs/architecture/images/DesignTimeComponents.svg b/docs/architecture/images/DesignTimeComponents.svg new file mode 100644 index 00000000..3766c4cc --- /dev/null +++ b/docs/architecture/images/DesignTimeComponents.svg @@ -0,0 +1,2 @@ + +

<<enumeration>>
PDPType

PDP-X
PDP-D
PDP-A
[Not supported by viewer]

XACMLPolicy

[Not supported by viewer]

DroolsPolicy

[Not supported by viewer]

ApexPolicy

[Not supported by viewer]
1
1

XACMLImpl

[Not supported by viewer]

DroolsImpl

[Not supported by viewer]

ApexImpl

[Not supported by viewer]

PolicyTypeImpl

[Not supported by viewer]
1
1
PolicyTypeXACML

[Not supported by viewer]

<<TOSCA>>
PolicyType

[Not supported by viewer]

PolicyTypeDrools


[Not supported by viewer]

PolicyTypeApex


[Not supported by viewer]
1
1

PolicyCreator

[Not supported by viewer]
applies
applies
1
1
1
1
parameterizes
parameterizes
1
1
1
1
creates
creates
1
1
1
1

PDPXCreator

[Not supported by viewer]

PDPDCreator

[Not supported by viewer]

PDPACreator

[Not supported by viewer]
1
1
implements
implements
m
m
n
n

<<TOSCA>>
Policy

[Not supported by viewer] \ No newline at end of file diff --git a/docs/architecture/images/PFDesignAndAdmin.svg b/docs/architecture/images/PFDesignAndAdmin.svg new file mode 100644 index 00000000..f91d3084 --- /dev/null +++ b/docs/architecture/images/PFDesignAndAdmin.svg @@ -0,0 +1,2 @@ + +
PolicyDevelopment
PolicyDevelopment
Portal
Portal
PolicyDevAPIUser
PolicyDevAPIUser
PolicyDistribution
PolicyDistribution
SDC
SDC
PolicyDevGUI
PolicyDevGUI
PolicyDB
PolicyDB
PolicyAdminGUI
PolicyAdminGUI
PolicyAdministration
PolicyAdministration
PolicyAdminAPIUser
PolicyAdminAPIUser
PolicyExecution
PolicyExecution
DMaaP
DMaaP
AsyncCaller
AsyncCaller
SyncCaller
SyncCaller
Policy Artifacts and Metadata
PDP Group and Subgroup Definitions
Policy to PDP Group and Subgroup Mappings
[Not supported by viewer]
CRUD API for Policy Groups and Sub-Groups
API for Policy Deployment
CRUD API for Policy Groups and Sub-Groups<br>API for Policy Deployment
Policies for a given
domain execute in a
PDP Group. PDP Groups
have subgroups for each
PDP type in a PDP group
[Not supported by viewer]
Deploy
Retire
Archive
Upgrade
Rollback
[Not supported by viewer]
CRUD API for Policy Artifacts
CRUD API for Policy Artifacts
Policy Framework Component
Policy Framework Component
Other Component
Other Component \ No newline at end of file diff --git a/docs/architecture/images/PFHighestLevel.svg b/docs/architecture/images/PFHighestLevel.svg new file mode 100644 index 00000000..9f1afd6a --- /dev/null +++ b/docs/architecture/images/PFHighestLevel.svg @@ -0,0 +1,2 @@ + +
PolicyDevelopment
PolicyDevelopment
PolicyDB
PolicyDB
PolicyAdministration
PolicyAdministration
PolicyExecution
PolicyExecution
Policy Framework Component
Policy Framework Component
Other Component
Other Component \ No newline at end of file diff --git a/docs/architecture/images/PolicyExecution.svg b/docs/architecture/images/PolicyExecution.svg index c9b2f7f6..23a00770 100644 --- a/docs/architecture/images/PolicyExecution.svg +++ b/docs/architecture/images/PolicyExecution.svg @@ -1,34 +1,2 @@ -Policy ExecutionREQUESTORREQUESTORRESPONDEERESPONDEEPDPPDPalt[Synchronous Invocation]1Execute Policywait2Policy Execution Result[Asynchronous Invocation]3Execute Policy4Policy Execution Result \ No newline at end of file + +
PDPGroup
PDPGroup
PDPGroup
PDPGroup
PDPGroup
PDPGroup
PDPSubGroup
PDPSubGroup
PDPSubGroup
PDPSubGroup
PDP-X
PDP-X
PDP-X
PDP-X
PDP-A
PDP-A
PDP-A
PDP-A
PDP-A
PDP-A
PDPSubGroup
PDPSubGroup
PDP-D
PDP-D
PDP-D
PDP-D
PDP-D
PDP-D
PolicyAdministration
PolicyAdministration
DMaaP
DMaaP
AsyncCaller
<div>AsyncCaller</div>
SyncCaller
SyncCaller
Each PDP is deployed as a Kubernetes Pod
[Not supported by viewer]
In Kubernetes, a PDPSubGroup is a Kubernetes Deployment
[Not supported by viewer] \ No newline at end of file diff --git a/docs/architecture/images/PolicyExecutionFlow.svg b/docs/architecture/images/PolicyExecutionFlow.svg new file mode 100644 index 00000000..c9b2f7f6 --- /dev/null +++ b/docs/architecture/images/PolicyExecutionFlow.svg @@ -0,0 +1,34 @@ +Policy ExecutionREQUESTORREQUESTORRESPONDEERESPONDEEPDPPDPalt[Synchronous Invocation]1Execute Policywait2Policy Execution Result[Asynchronous Invocation]3Execute Policy4Policy Execution Result \ No newline at end of file diff --git a/docs/architecture/images/TOSCAPolicyConcepts.svg b/docs/architecture/images/TOSCAPolicyConcepts.svg new file mode 100644 index 00000000..fd8f18e6 --- /dev/null +++ b/docs/architecture/images/TOSCAPolicyConcepts.svg @@ -0,0 +1,2 @@ + +Policy+ properties:property definition list+ targets: string[]+ triggers: trigger listPolicyType+ properties: property definition list+ targets: string[]+ triggers: trigger listTrigger+ event_type: string (event name)+ schedule: TimeInterval+ target_filter: event filter+ condition: constraint clause+ constraint: constraint clause+ period: scalar-unit.time+ evaluations: integer+ method: string+ action: string or operation
specification
of
[Not supported by viewer]
1
1
0..n
0..n
can be
triggered by
[Not supported by viewer]
0..n
0..n
0..n
0..n
triggers
triggers
0..n
0..n
0..n
0..n \ No newline at end of file diff --git a/docs/architecture/images/ToscaPolicyStructure.png b/docs/architecture/images/ToscaPolicyStructure.png deleted file mode 100644 index f1e6cb47..00000000 Binary files a/docs/architecture/images/ToscaPolicyStructure.png and /dev/null differ diff --git a/docs/architecture/images/detailed.png b/docs/architecture/images/detailed.png deleted file mode 100644 index 9ac8cf30..00000000 Binary files a/docs/architecture/images/detailed.png and /dev/null differ diff --git a/docs/architecture/images/execution.png b/docs/architecture/images/execution.png deleted file mode 100644 index 4e564856..00000000 Binary files a/docs/architecture/images/execution.png and /dev/null differ diff --git a/docs/architecture/images/highest.png b/docs/architecture/images/highest.png deleted file mode 100644 index bfe07ae8..00000000 Binary files a/docs/architecture/images/highest.png and /dev/null differ diff --git a/docs/architecture/images/objectmodel1.png b/docs/architecture/images/objectmodel1.png deleted file mode 100644 index ef3c7d12..00000000 Binary files a/docs/architecture/images/objectmodel1.png and /dev/null differ diff --git a/docs/architecture/images/objectmodel2.png b/docs/architecture/images/objectmodel2.png deleted file mode 100644 index 44f79746..00000000 Binary files a/docs/architecture/images/objectmodel2.png and /dev/null differ diff --git a/docs/architecture/plantuml/PolicyExecution.puml b/docs/architecture/plantuml/PolicyExecution.puml deleted file mode 100644 index a06fdf5f..00000000 --- a/docs/architecture/plantuml/PolicyExecution.puml +++ /dev/null @@ -1,24 +0,0 @@ -@startuml - -title Policy Execution - -participant REQUESTOR -participant RESPONDEE -participant PDP - -autonumber - -alt Synchronous Invocation - REQUESTOR --> PDP: Execute Policy - activate PDP - hnote over REQUESTOR : wait - PDP --> REQUESTOR: Policy Execution Result - deactivate PDP -else Asynchronous Invocation - REQUESTOR --> PDP: Execute Policy - activate PDP - PDP --> RESPONDEE: Policy Execution Result - deactivate PDP -end - -@enduml \ No newline at end of file diff --git a/docs/architecture/plantuml/PolicyExecutionFlow.puml b/docs/architecture/plantuml/PolicyExecutionFlow.puml new file mode 100644 index 00000000..a06fdf5f --- /dev/null +++ b/docs/architecture/plantuml/PolicyExecutionFlow.puml @@ -0,0 +1,24 @@ +@startuml + +title Policy Execution + +participant REQUESTOR +participant RESPONDEE +participant PDP + +autonumber + +alt Synchronous Invocation + REQUESTOR --> PDP: Execute Policy + activate PDP + hnote over REQUESTOR : wait + PDP --> REQUESTOR: Policy Execution Result + deactivate PDP +else Asynchronous Invocation + REQUESTOR --> PDP: Execute Policy + activate PDP + PDP --> RESPONDEE: Policy Execution Result + deactivate PDP +end + +@enduml \ No newline at end of file diff --git a/docs/architecture/tosca-policy-primer.rst b/docs/architecture/tosca-policy-primer.rst index 686d3564..3f8e78e7 100644 --- a/docs/architecture/tosca-policy-primer.rst +++ b/docs/architecture/tosca-policy-primer.rst @@ -15,7 +15,7 @@ This page gives a short overview of how Policy is modelled in the TOSCA defines three concepts for Policy: Policy Type, Policy, and Trigger. -.. image:: images/ToscaPolicyStructure.png +.. image:: images/TOSCAPolicyConcepts.svg :width: 800 Policy Type @@ -64,12 +64,12 @@ More formally, TOSCA defines a Trigger as an artifact that "defines the event, * its event_type, which defines the name of the event that fires the policy * its schedule, which defines the time interval in which the trigger is active * its target_filter, which defines specific filters for firing such as specific characteristics of the nodes or -relations for which the trigger should or should not fire + relations for which the trigger should or should not fire * its condition, which defines extra conditions on the incoming event for firing the trigger * its constraint, which defines extra conditions on the incoming event for not firing the trigger * its period, which defines the period to use for evaluating conditions and constraints * its evaluations, which defines the number of evaluations that must be performed over the period to assert the -condition or constraint exists + condition or constraint exists * its method, the method to use for evaluation of conditions and constraints * its action, the workflow or operation to invoke when the trigger fires diff --git a/docs/design/InternalPapPdp.rst b/docs/design/InternalPapPdp.rst new file mode 100644 index 00000000..998514af --- /dev/null +++ b/docs/design/InternalPapPdp.rst @@ -0,0 +1,428 @@ +.. This work is licensed under a +.. Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +.. _pap-pdp-label: + +The Internal Policy Framework PAP-PDP API +######################################### + +.. contents:: + :depth: 3 + +This page describes the API between the PAP and PDPs. The APIs in this section are implemented using `DMaaP +API `__ messaging. 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. + +There are four messages on the API: + +1. PDP_STATUS: PDP→PAP, used by PDPs to report to the PAP + +2. 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 + +3. 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 + +4. PDP_HEALTH_CHECK: PAP→PDP, used by the PAP to order a health check on PDPs, triggers a PDP_STATUS message with the + result of the PDP_HEALTH_CHECK operation + +The fields in the table below are valid on API calls: + +=============================== ======== ======== ======== ======= ===================================================== +**Field** **PDP **PDP **PDP **PDP **Comment** + STATUS** UPDATE** STATE HEALTH + CHANGE** CHECK** +=============================== ======== ======== ======== ======= ===================================================== +(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 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. + +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 periodically or in +response to a pdp_update, pdp-state_change, or pdp_health_check message 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:: yaml + :caption: PDP_STATUS message from an XACML PDP running control loop policies + :linenos: + + 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 + - onap.policies.controlloop.guard.blacklist.eastRegion: + policy_type: onap.policies.controlloop.guard.BlackList + policy_type_version: 1.0.0 + properties: + # Omitted for brevity + - onap.policies.controlloop.guard.minmax.eastRegion: + policy_type: onap.policies.controlloop.guard.MinMax + policy_type_version: 1.0.0 + properties: + # Omitted for brevity + instance: xacml_1 + deployment_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 + policy_executed_fail_count: 1 + +.. code-block:: yaml + :caption: PDP_STATUS message from a Drools PDP running control loop policies + :linenos: + + 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.controllloop.operational.drools.vcpe.EastRegion: + policy_type: onap.controllloop.operational.drools.vCPE + policy_type_version: 1.0.0 + properties: + # Omitted for brevity + - onap.controllloop.operational.drools.vfw.EastRegion: + policy_type: onap.controllloop.operational.drools.vFW + policy_type_version: 1.0.0 + properties: + # Omitted for brevity + 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 + policy_download_fail_count: 0 + policy_executed_count: 123 + policy_executed_success_count: 122 + policy_executed_fail_count: 1 + response: + response_to: PDP_HEALTH_CHECK + response_status: SUCCESS + +.. code-block:: yaml + :caption: PDP_STATUS message from an APEX PDP running control loop policies + :linenos: + + 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.controllloop.operational.drools.vcpe.EastRegion: + policy_type: onap.controllloop.operational.drools.vCPE + policy_type_version: 1.0.0 + properties: + # Omitted for brevity + - onap.controllloop.operational.drools.vfw.EastRegion: + policy_type: onap.controllloop.operational.drools.vFW + policy_type_version: 1.0.0 + properties: + # Omitted for brevity + 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 + policy_download_fail_count: 0 + policy_executed_count: 123 + policy_executed_success_count: 122 + policy_executed_fail_count: 1 + response: + response_to: PDP_HEALTH_CHECK + response_status: SUCCESS + +.. code-block:: yaml + :caption: PDP_STATUS message from an XACML PDP running monitoring policies + :linenos: + + pdp_status: + name: xacml_1 + version: 1.2.3 + pdp_type: xacml + state: active + healthy: 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.scaleout.tca:message + policy_type: onap.policies.monitoring.cdap.tca.hi.lo.app + policy_type_version: 1.0.0 + properties: + # Omitted for brevity + instance: xacml_1 + deployment_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 + policy_executed_fail_count: 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 listen on this topic for messages. + +The PAP can set the scope of *PDP_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. + +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. + +The following examples illustrate how the operation is used. + +.. code-block:: yaml + :caption: PDP_UPDATE message to upgrade XACML PDP control loop policies to version 1.0.1 + :linenos: + + 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: + policy_type: onap.policies.controlloop.guard.FrequencyLimiter + policy_type_version: 1.0.1 + properties: + # Omitted for brevity + - onap.policies.controlloop.guard.blackList.EastRegion: + policy_type: onap.policies.controlloop.guard.BlackList + policy_type_version: 1.0.1 + properties: + # Omitted for brevity + - onap.policies.controlloop.guard.minmax.EastRegion: + policy_type: onap.policies.controlloop.guard.MinMax + policy_type_version: 1.0.1 + properties: + # Omitted for brevity + +.. code-block:: yaml + :caption: PDP_UPDATE message to a Drools PDP to add an extra control loop policy + :linenos: + + pdp_update: + name: drools_2 + pdp_type: drools + description: Drools PDP running control loop policies, extra policy added + pdp_group: onap.pdpgroup.controlloop.operational + pdp_subgroup: drools + policies: + - onap.controllloop.operational.drools.vcpe.EastRegion: + policy_type: onap.controllloop.operational.drools.vCPE + policy_type_version: 1.0.0 + properties: + # Omitted for brevity + - onap.controllloop.operational.drools.vfw.EastRegion: + policy_type: onap.controllloop.operational.drools.vFW + policy_type_version: 1.0.0 + properties: + # Omitted for brevity + - onap.controllloop.operational.drools.vfw.WestRegion: + policy_type: onap.controllloop.operational.drools.vFW + policy_type_version: 1.0.0 + properties: + # Omitted for brevity + +.. code-block:: yaml + :caption: PDP_UPDATE message to an APEX PDP to remove a control loop policy + :linenos: + + 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: + - onap.controllloop.operational.apex.bbs.EastRegion: + policy_type: onap.controllloop.operational.apex.BBS + policy_type_version: 1.0.0 + properties: + # Omitted for brevity + +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:: yaml + :caption: Change the state of all control loop Drools PDPs to ACTIVE + :linenos: + + pdp_state_change: + state: active + pdp_group: onap.pdpgroup.controlloop.Operational + pdp_subgroup: drools + +.. code-block:: yaml + :caption: Change the state of all monitoring PDPs to SAFE + :linenos: + + pdp_state_change: + state: safe + pdp_group: onap.pdpgroup.Monitoring + +.. code-block:: yaml + :caption: Change the state of a single APEX PDP to TEST + :linenos: + + pdp_state_change: + state: test + name: apex_3 + +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:: yaml + :caption: Perform a health check on all control loop Drools PDPs + :linenos: + + pdp_health_check: + pdp_group: onap.pdpgroup.controlloop.Operational + pdp_subgroup: drools + +.. code-block:: yaml + :caption: perform a health check on all monitoring PDPs + :linenos: + + pdp_health_check: + pdp_group: onap.pdpgroup.Monitoring + +.. code-block:: yaml + :caption: Perform a health check on a single APEX PDP + :linenos: + + pdp_health_check: + name: apex_3 diff --git a/docs/design/design.png b/docs/design/design.png deleted file mode 100644 index e36c1b2c..00000000 Binary files a/docs/design/design.png and /dev/null differ diff --git a/docs/design/design.rst b/docs/design/design.rst index e8a4cacc..cceba0fc 100644 --- a/docs/design/design.rst +++ b/docs/design/design.rst @@ -5,123 +5,795 @@ .. _design-label: Policy Design and Development ------------------------------ +############################# .. contents:: :depth: 3 -This document provides examples that illustrate how to write, deploy, and run policies -of various types using the framework. - -The figure below shows the Artifacts (Blue) in the ONAP Policy -Framework, the Activities (Yellow) that manipulate them, and important -components (Pink) that interact with them. - -.. image:: design.png - -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 *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 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 ONAP Policy Types +This document describes the design principles that should be used to write, deploy, and run policies of various types +using the Policy Framework. It explains the APIs that are available for Policy Framework users. It provides copious +examples to illustrate policy design and API usage. + +1 Introduction +============== + +The figure below shows the Artifacts (Blue) in the ONAP Policy Framework, the Activities (Yellow) that manipulate them, +and important components (Salmon) that interact with them. The Policy Framework is fully TOSCA compliant, and uses +TOSCA to model policies. Please see the :ref:`TOSCA Policy Primer ` page for an introduction to TOSCA +policy concepts. + +.. image:: images/APIsInPolicyFramework.svg + +TOSCA defines the concept of a *PolicyType*, the definition of a type of policy that can be applied to a service. It +also defines the concept of a *Policy*, an instance of a *PolicyType*. In the Policy Framework, we 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 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.  + +2 ONAP Policy Types =================== -Policy Type Design manages TOSCA *PolicyType* artifacts and their -*PolicyTypeImpl* implementations\ *.* +Policy Type Design manages TOSCA *PolicyType* artifacts and their *PolicyTypeImpl* implementations. -*TOSCA PolicyType* may ultimately be defined by the modeling team but -for now are defined by the Policy Framework project. Various editors and -GUIs are available for creating *PolicyTypeImpl* implementations. -However, systematic integration of *PolicyTypeImpl* implementation is -outside the scope of the ONAP Dublin release. +A TOSCA *PolicyType* may ultimately be defined by the modeling team but for now are defined by the Policy Framework +project. Various editors and GUIs are available for creating *PolicyTypeImpl* implementations. However, systematic +integration of *PolicyTypeImpl* implementation is outside the scope of the ONAP Dublin release. -The \ *PolicyType* definitions and implementations listed below are -preloaded and are always available for use in the Policy Framework. +The *PolicyType* definitions and implementations listed below are preloaded and are always available for use in the +Policy Framework. -====================================== ================================================================================================== +====================================== =============================================================================== **Policy Type** **Description** -====================================== ================================================================================================== -onap.policies.Monitoring Overarching model that supports Policy driven DCAE microservice components used in a Control Loops +====================================== =============================================================================== +onap.policies.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. - -**Base Policy Type definition for onap.policies.Monitoring**   - -.. codeblock:: yaml - - tosca_definitions_version: tosca_simple_yaml_1_0_0 - topology_template: - policy_types: - - onap.policies.Monitoring: - derived_from: tosca.policies.Root - version: 1.0.0 - description: a base policy type for all policies that govern monitoring provision - -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. +onap.policies.controlloop.Coordination Control Loop Coordination policies to assist in coordinating multiple control + loops at runtime +====================================== =============================================================================== + +2.1 Policy Type: onap.policies.Monitoring +----------------------------------------- + +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:: yaml + :caption: Base Policy Type definition for onap.policies.Monitoring + :linenos: + + tosca_definitions_version: tosca_simple_yaml_1_0_0 + topology_template: + policy_types: + - onap.policies.Monitoring: + derived_from: tosca.policies.Root + version: 1.0.0 + description: a base policy type for all policies that govern monitoring provision + +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, microservice Policy Types will be preloaded into the SDC platform and be available as a Normative. The + policy framework will preload support for those microservice Monitoring policy types. + +.. code-block:: yaml + :caption: Example PolicyType *onap.policies.monitoring.MyDCAEComponent* derived from *onap.policies.Monitoring* + :linenos: + + tosca_definitions_version: tosca_simple_yaml_1_0_0 + policy_types: + - 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.monitoring.MyDCAEComponent: + derived_from: onap.policies.Monitoring + version: 1.0.0 + properties: + mydcaecomponent_policy: + type: map + description: The Policy Body I need + entry_schema: + type: onap.datatypes.monitoring.mydatatype + + data_types: + - onap.datatypes.monitoring.MyDataType: + derived_from: tosca.datatypes.Root + properties: + my_property_1: + type: string + description: A description of this property + constraints: + - valid_values: + - value example 1 + - value example 2 + +For more examples of monitoring policy type definitions, please refer to the examples in the `ONAP policy-models gerrit +repository `__. + +2.2 Policy Type: onap.policies.controlloop.Operational +------------------------------------------------------ + +This policy type is used to support actor/action operational policies for control loops. There are two types of +implementations for this policy type + +1. Drools implementations that supports runtime Control Loop actions taken on components such as SO/APPC/VFC/SDNC/SDNR +2. Implementations using APEX to support Control Loops. + +.. note:: + For Dublin, this policy type will ONLY be used for the Policy Framework to distinguish the policy type as operational. + +.. code-block:: yaml + :caption: Base Policy Type definition for onap.policies.controlloop.Operational + :linenos: + + 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: +.. code-block:: + + Content-Type: "application/yaml" + +2.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 the `YAML Operational Policy format +`__. + +2.2.2 Operational Policy Type Schema for APEX +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The operational Policy Type schema for APEX extends the base operational Policy Type schema. This Policy Type allows +parameters specific to the APEX PDP to be specified as a TOSCA policy. See `this sample APEX policy type definition +`__. + +2.3 Policy Type: onap.policies.controlloop.Guard +------------------------------------------------ + +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. + +.. code-block:: yaml + :caption: Base Policy Type definition for onap.policies.controlloop.Guard + :linenos: + + tosca_definitions_version: tosca_simple_yaml_1_0_0 + policy_types: + - onap.policies.controlloop.Guard: + derived_from: tosca.policies.Root + version: 1.0.0 + description: Guard Policy for Control Loops Operational Policies + +As with the *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. + +.. note:: + 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. + +Guard policy type definitions for *FrequencyLimiter*, *BlackList*, and *MinMax* are available in the `ONAP +policy-models gerrit repository +`__. + +3 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*. + +.. image:: images/PolicyImplPDPSubGroup.svg + +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 deployment methods in which *PolicyImpl* entities can be deployed to PDP Subgroups. + +========== =========================================== ============================== ================================== +**Method** **Description** **Advantages** **Disadvantages** +========== =========================================== ============================== ================================== +Cold The *PolicyImpl* (*PolicyTypeImpl* and No run time configuration Very restrictive, no run time + TOSCA *Policy*) are predeployed on the PDP. required and run time configuration of PDPs is possible. + PDP is fully configured and ready to administration is simple. + execute when started. + + PDPs register with the PAP when they + start, providing the *PolicyImpl* they + have been predeployed with. + +Warm The *PolicyTypeImpl* entity is predeployed The configuration, parameters, Administration and management is + on the PDP. A TOSCA *Policy* may be loaded and PDP group of PDPs may be required. The configuration and + at startup. The PDP may be configured or changed at run time by loading life cycle of the TOSCA policies + reconfigured with a new or updated TOSCA or updating a TOSCA *Policy* can change at run time and must be + *Policy* at run time. into the PDP. administered and managed. + + PDPs register with the PAP when they start, Support TOSCA *Policy* entity + providing the *PolicyImpl* they have been life cycle managgement is + predeployed with if any. The PAP may update supported, allowing features + the TOSCA *Policy* on a PDP at any time such as *PolicyImpl* Safe Mode + after registration. and *PolicyImpl* retirement. + +Hot The *PolicyImpl* (*PolicyTypeImpl* and The policy logic, rules, Administration and management is + TOSCA *Policy*) are deployed at run time. configuration, parameters, and more complex. The *PolicyImpl* + The *PolicyImpl* (*PolicyTypeImpl* and PDP group of PDPs may be itself and its configuration and + TOSCA *Policy*) may be loaded at startup. changed at run time by loading life cycle as well as the life + The PDP may be configured or reconfigured or updating a TOSCA *Policy* cycle of the TOSCA policies can + with a new or updated *PolicyTypeImpl* and *PolicyTypeImpl* into the change at run time and must be + and/or TOSCA *Policy* at run time. PDP. administered and managed. + + PDPs register with the PAP when they Lifecycle management of TOSCA + start, providing the *PolicyImpl* they have *Policy* entities and + been predeployed with if any. The PAP may *PolicyTypeImpl* entites is + update the TOSCA *Policy* and supported, allowing features + *PolicyTypeImpl* on a PDP at any time after such as *PolicyImpl* Safe Mode + registration and *PolicyImpl* retirement. +========== =========================================== ============================== ================================== + +4. Policy Framework Public APIs +=============================== + +The Policy Framework provides the public APIs outline in the subsections below. For a full description of the APIs, see +their individual documentation linked in each subsection. + +4.1 Policy Type Design API for TOSCA Policy Types +------------------------------------------------- + +The full documentation for this API is available on the :ref:`Policy Life Cycle API ` page. + +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 :ref:`The ONAP Policy Framework Architecture +` page. + +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 + +4.2 Policy Design API +--------------------- + +The full documentation for this API is available on the :ref:`Policy Life Cycle API ` page. + +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 :ref:`The ONAP +Policy Framework Architecture ` page. + +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 + +4.3 Policy Administration API +----------------------------- + +The full documentation for this API is available on the :ref:`Policy Administration Point (PAP) ` page. + +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. This API is provided by +the *PolicyAdministration* component (PAP) of the Policy Framework, see the :ref:`The ONAP Policy Framework Architecture +` page. + +PDP groups and subgroups may be prefedined in the system. Predefined groups and subgroups can be modified or deleted +over this API. The policies running on predefined groups or subgroups as well as the desired instance counts and +properties can also 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 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, the :ref:`The ONAP Policy Framework Architecture ` page. + +The API supports retrieval of statistics for PDP groups, PDP subgroups, and individual PDPs. It also allows a PDP group +health check to be ordered on PDP groups and on individual PDPs. + +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. + +4.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. + +Decision API queries are implemented with a POST operation with a JSON body that specifies the filter for the policies +to be returned. + +*https:{url}:{port}/decision/v1/ POST* + +The table below describes the fields in 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. + "configure" → DCAE uS onap.Monitoring policy Decisions to configure uS + "naming" + "placement" + "guard" +============= ======= ======== ========================================================================== + +These sub metadata structures are used to scope the resource the ONAP component is performing an action upon. At least +one must be specified in order for Policy to return a decision. Multiple structures may be utilized to help define a +precise scope for a decision. + +================= ======= ======== ================================================================== +**Field** **R/O** **Type** **Description** +================= ======= ======== ================================================================== +policy-type-name O String The policy type name. This may be a regular expression. +policy-id O String The policy id. This may be a regular expression or an exact value. +================= ======= ======== ================================================================== + +This example below shows the JSON body of a query with a single policy ID. + +.. code-block:: yaml + :caption: Decision API Call - Single Policy ID query + :linenos: + + { + "ONAPName": "DCAE", + "ONAPComponent": "PolicyHandler", + "ONAPInstance": "622431a4-9dea-4eae-b443-3b2164639c64", + "action": "configure", + "resource": { + "policy-id": "onap.scaleout.tca" + } + } + +.. code-block:: yaml + :caption: Decision Response - Single Policy ID query + :linenos: + + { + "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 with multiple policy IDs. + +.. code-block:: yaml + :caption: Decision API Call - Multiple Policy IDs query + :linenos: + + { + "ONAPName": "DCAE", + "ONAPComponent": "PolicyHandler", + "ONAPInstance": "622431a4-9dea-4eae-b443-3b2164639c64", + "action": "configure", + "resource": { + "policy-id": [ + "onap.scaleout.tca", + "onap.restart.tca" + ] + } + } + +.. code-block:: yaml + :caption: Decision Response - Multiple Policy IDs query + :linenos: + + { + "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" + } + ] + } + ] + } + } + } + } + } + +This example below shows the JSON body of a query to return all the deployed policies for a specific policy type. + +.. code-block:: yaml + :caption: Decision API Call - Policies for Policy Type query + :linenos: + + { + "ONAPName": "DCAE", + "ONAPComponent": "PolicyHandler", + "ONAPInstance": "622431a4-9dea-4eae-b443-3b2164639c64", + "action": "configure", + "resource": { + "policy-type": "onap.policies.monitoring.cdap.tca.hi.lo.app" + } + } + +.. code-block:: yaml + :caption: Decision Response - Policies for Policy Type query + :linenos: + { + "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" + } + ] + } + ] + } + } + } + } + } End of Document diff --git a/docs/design/draw.io/APIsInPolicyFramework.xml b/docs/design/draw.io/APIsInPolicyFramework.xml new file mode 100644 index 00000000..d15c3946 --- /dev/null +++ b/docs/design/draw.io/APIsInPolicyFramework.xml @@ -0,0 +1,2 @@ + + \ No newline at end of file diff --git a/docs/design/draw.io/PolicyImplPDPSubGroup.xml b/docs/design/draw.io/PolicyImplPDPSubGroup.xml new file mode 100644 index 00000000..293f616e --- /dev/null +++ b/docs/design/draw.io/PolicyImplPDPSubGroup.xml @@ -0,0 +1,2 @@ + + \ No newline at end of file diff --git a/docs/design/foo.rst b/docs/design/foo.rst deleted file mode 100644 index e0d461be..00000000 --- a/docs/design/foo.rst +++ /dev/null @@ -1,4898 +0,0 @@ -.. contents:: - :depth: 3 -.. - -Policy Design and API Flow for Model Driven Control Loop -======================================================== - -This page shows how the Policy Design and API Flow to/from the PAP and -PDPs works to support Model Driven Control Loops in Dublin. - -- `1 Policy Types <#PolicyDesignandAPIFlowforModelDrivenCon>`__ - - - `1.1 onap.policies.Monitoring Policy - Type <#PolicyDesignandAPIFlowforModelDrivenCon>`__ - - - `1.2 onap.policies.controlloop.Operational Policy - Type <#PolicyDesignandAPIFlowforModelDrivenCon>`__ - - - `1.2.1 Operational Policy Type Schema for - Drools <#PolicyDesignandAPIFlowforModelDrivenCon>`__ - - - `1.2.3 Operational Policy Type Schema for APEX (El Alto - proposal) <#PolicyDesignandAPIFlowforModelDrivenCon>`__ - - - `1.3 onap.policies.controlloop.Guard Policy - Type <#PolicyDesignandAPIFlowforModelDrivenCon>`__ - - - `1.3.1 onap.policies.controlloop.guard.FrequencyLimiter Policy - Type <#PolicyDesignandAPIFlowforModelDrivenCon>`__ - - - `1.3.2 onap.policies.controlloop.guard.Blacklist Policy - Type <#PolicyDesignandAPIFlowforModelDrivenCon>`__ - - - `1.3.3 onap.policies.controlloop.guard.MinMax Policy - Type <#PolicyDesignandAPIFlowforModelDrivenCon>`__ - - - `1.3.4 onap.policies.controlloop.Coordination Policy Type - (STRETCH) <#PolicyDesignandAPIFlowforModelDrivenCon>`__ - -- `2 PDP Deployment and Registration with - PAP <#PolicyDesignandAPIFlowforModelDrivenCon>`__ - -- `3. Public APIs <#PolicyDesignandAPIFlowforModelDrivenCon>`__ - - - `3.1 Policy Type Design API for TOSCA Policy - Types <#PolicyDesignandAPIFlowforModelDrivenCon>`__ - - - `3.1.1 Policy Type - query <#PolicyDesignandAPIFlowforModelDrivenCon>`__ - - - `3.1.2 Policy Type - Create/Update <#PolicyDesignandAPIFlowforModelDrivenCon>`__ - - - `3.1.3 Policy Type - Delete <#PolicyDesignandAPIFlowforModelDrivenCon>`__ - - - `3.2 Policy Design - API <#PolicyDesignandAPIFlowforModelDrivenCon>`__ - - - `3.2.1 Policy - query <#PolicyDesignandAPIFlowforModelDrivenCon>`__ - - - `3.2.2 Policy - Create/Update <#PolicyDesignandAPIFlowforModelDrivenCon>`__ - - - `3.2.2.1 Monitoring Policy - Create/Update <#PolicyDesignandAPIFlowforModelDrivenCon>`__ - - - `3.2.2.2.1 Drools Operational Policy - Create/Update <#PolicyDesignandAPIFlowforModelDrivenCon>`__ - - - `3.2.2.2.2 APEX Operational Policy - Create/Update <#PolicyDesignandAPIFlowforModelDrivenCon>`__ - - - `3.2.2.3 Guard Policy - Create/Update <#PolicyDesignandAPIFlowforModelDrivenCon>`__ - - - `3.2.2.4 Policy Lifecycle API - Creating Coordination - Policies <#PolicyDesignandAPIFlowforModelDrivenCon>`__ - - - `3.2.3 Policy - Delete <#PolicyDesignandAPIFlowforModelDrivenCon>`__ - - - `3.3 Policy Administration - API <#PolicyDesignandAPIFlowforModelDrivenCon>`__ - - - `3.3.1 PDP Group - Query <#PolicyDesignandAPIFlowforModelDrivenCon>`__ - - - `3.3.2 PDP Group - Deployment <#PolicyDesignandAPIFlowforModelDrivenCon>`__ - - - `Simple API for CLAMP to deploy one or more policy-id's with - optional - policy-version. <#PolicyDesignandAPIFlowforModelDrivenCon>`__ - - - `Simple API for CLAMP to undeploy a policy-id with optional - policy-version. <#PolicyDesignandAPIFlowforModelDrivenCon>`__ - - - `3.3.3 PDP Group - Delete <#PolicyDesignandAPIFlowforModelDrivenCon>`__ - - - `3.3.4 PDP Group State - Management <#PolicyDesignandAPIFlowforModelDrivenCon>`__ - - - `3.3.5 PDP Group - Statistics <#PolicyDesignandAPIFlowforModelDrivenCon>`__ - - - `3.3.6 PDP Group Health - Check <#PolicyDesignandAPIFlowforModelDrivenCon>`__ - - - `3.4 Policy Decision API - Getting Policy - Decisions <#PolicyDesignandAPIFlowforModelDrivenCon>`__ - - - `3.4.1 Decision API - Schema <#PolicyDesignandAPIFlowforModelDrivenCon>`__ - - - `3.4.2 Decision API - Queries <#PolicyDesignandAPIFlowforModelDrivenCon>`__ - -- `4. Policy Framework Internal - APIs <#PolicyDesignandAPIFlowforModelDrivenCon>`__ - - - `4.1 PAP to PDP API <#PolicyDesignandAPIFlowforModelDrivenCon>`__ - - - `4.1.1 PAP API for - PDPs <#PolicyDesignandAPIFlowforModelDrivenCon>`__ - - - `4.1.2 PDP API for - PAPs <#PolicyDesignandAPIFlowforModelDrivenCon>`__ - - - `4.1.2.1 PDP - Update <#PolicyDesignandAPIFlowforModelDrivenCon>`__ - - - `4.1.2.2 PDP State - Change <#PolicyDesignandAPIFlowforModelDrivenCon>`__ - - - `4.1.2.3 PDP Health - Check <#PolicyDesignandAPIFlowforModelDrivenCon>`__ - - - `4.2 Policy Type Implementations (Native - Policies) <#PolicyDesignandAPIFlowforModelDrivenCon>`__ - - - `4.2.1 Policy Type Implementation - Query <#PolicyDesignandAPIFlowforModelDrivenCon>`__ - - - `4.2.2 Policy Type Implementation - Create/Update <#PolicyDesignandAPIFlowforModelDrivenCon>`__ - - - `4.2.3 Policy Type Implementation - Delete <#PolicyDesignandAPIFlowforModelDrivenCon>`__ - -The figure below shows the Artifacts (Blue) in the ONAP Policy -Framework, the Activities (Yellow) that manipulate them, and important -components (Pink) that interact with them. - -Please see the :ref:`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 *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 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\ *.* - -*TOSCA PolicyType* may ultimately be defined by the modeling team but -for now are defined by the Policy Framework project. Various editors and -GUIs are available for creating *PolicyTypeImpl* implementations. -However, systematic integration of *PolicyTypeImpl* implementation is -outside the scope of the ONAP Dublin release. - -The \ *PolicyType* definitions and implementations listed below are -preloaded and are always available for use in the Policy Framework. - -====================================== ================================================================================================== -**Policy Type** **Description** -====================================== ================================================================================================== -onap.policies.Monitoring Overarching model that supports Policy driven DCAE microservice components used in a Control Loops -onap.policies.controlloop.Operational Used to support actor/action operational policies for control loops -onap.policies.controlloop.Guard Control Loop guard policies for policing control loops -onap.policies.controlloop.Coordination Control Loop Coordination policies to assist in coordinating multiple control loops at runtime -====================================== ================================================================================================== - -1.1 onap.policies.Monitoring Policy Type ----------------------------------------- - -This is a base Policy Type that supports Policy driven DCAE microservice -components used in a Control Loops. The implementation of this Policy -Type is developed using the XACML PDP to support question/answer Policy -Decisions during runtime for the DCAE Policy Handler. - -**Base Policy Type definition for onap.policies.Monitoring**   - -.. codeblock:: yaml - - tosca_definitions_version: tosca_simple_yaml_1_0_0 - topology_template: - policy_types: - - onap.policies.Monitoring: - derived_from: tosca.policies.Root - version: 1.0.0 - description: a base policy type for all policies that govern monitoring provision - -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. - -**PolicyType onap.policies.monitoring.MyDCAEComponent derived from -onap.policies.Monitoring**  Expand source - -tosca_definitions_version: tosca_simple_yaml_1_0_0 - -policy_types: - -- 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.monitoring.MyDCAEComponent: - -derived_from: onap.policies.Monitoring - -version: 1.0.0 - -properties: - -mydcaecomponent_policy: - -type: map - -description: The Policy Body I need - -entry_schema: - -type: onap.datatypes.monitoring.mydatatype - -data_types: - -- onap.datatypes.monitoring.MyDataType: - -derived_from: tosca.datatypes.Root - -properties: - -my_property_1: - -type: string - -description: A description of this property - -constraints: - -- valid_values: - -- value example 1 - -- value example 2 - -TCA Example - Please note that the official version of this will be -located in the SDC repository. - -**Example TCA DCAE microservice**  Expand source - -tosca_definitions_version: tosca_simple_yaml_1_0_0 - -policy_types: - -onap.policies.Monitoring: - -derived_from: tosca.policies.Root - -description: a base policy type for all policies that governs monitoring -provisioning - -onap.policy.monitoring.cdap.tca.hi.lo.app: - -derived_from: onap.policies.Monitoring - -version: 1.0.0 - -properties: - -tca_policy: - -type: map - -description: TCA Policy JSON - -entry_schema: - -type: onap.datatypes.monitoring.tca_policy - -data_types: - -onap.datatypes.monitoring.metricsPerEventName: - -derived_from: tosca.datatypes.Root - -properties: - -controlLoopSchemaType: - -type: string - -required: true - -description: Specifies Control Loop Schema Type for the event Name e.g. -VNF, VM - -constraints: - -- valid_values: - -- VM - -- VNF - -eventName: - -type: string - -required: true - -description: Event name to which thresholds need to be applied - -policyName: - -type: string - -required: true - -description: TCA Policy Scope Name - -policyScope: - -type: string - -required: true - -description: TCA Policy Scope - -policyVersion: - -type: string - -required: true - -description: TCA Policy Scope Version - -thresholds: - -type: list - -required: true - -description: Thresholds associated with eventName - -entry_schema: - -type: onap.datatypes.monitoring.thresholds - -onap.datatypes.monitoring.tca_policy: - -derived_from: tosca.datatypes.Root - -properties: - -domain: - -type: string - -required: true - -description: Domain name to which TCA needs to be applied - -default: measurementsForVfScaling - -constraints: - -- equal: measurementsForVfScaling - -metricsPerEventName: - -type: list - -required: true - -description: Contains eventName and threshold details that need to be -applied to given eventName - -entry_schema: - -type: onap.datatypes.monitoring.metricsPerEventName - -onap.datatypes.monitoring.thresholds: - -derived_from: tosca.datatypes.Root - -properties: - -closedLoopControlName: - -type: string - -required: true - -description: Closed Loop Control Name associated with the threshold - -closedLoopEventStatus: - -type: string - -required: true - -description: Closed Loop Event Status of the threshold - -constraints: - -- valid_values: - -- ONSET - -- ABATED - -direction: - -type: string - -required: true - -description: Direction of the threshold - -constraints: - -- valid_values: - -- LESS - -- LESS_OR_EQUAL - -- GREATER - -- GREATER_OR_EQUAL - -- EQUAL - -fieldPath: - -type: string - -required: true - -description: Json field Path as per CEF message which needs to be -analyzed for TCA - -constraints: - -- valid_values: - -- -$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedTotalPacketsDelta - -- -$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedOctetsDelta - -- -$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedUnicastPacketsDelta - -- -$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedMulticastPacketsDelta - -- -$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedBroadcastPacketsDelta - -- -$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedDiscardedPacketsDelta - -- -$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedErrorPacketsDelta - -- -$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedTotalPacketsAccumulated - -- -$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedOctetsAccumulated - -- -$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedUnicastPacketsAccumulated - -- -$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedMulticastPacketsAccumulated - -- -$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedBroadcastPacketsAccumulated - -- -$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedDiscardedPacketsAccumulated - -- -$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedErrorPacketsAccumulated - -- -$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].transmittedTotalPacketsDelta - -- -$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].transmittedOctetsDelta - -- -$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].transmittedUnicastPacketsDelta - -- -$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].transmittedMulticastPacketsDelta - -- -$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].transmittedBroadcastPacketsDelta - -- -$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].transmittedDiscardedPacketsDelta - -- -$.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 - -- $.event.measurementsForVfScalingFields.cpuUsageArray[*].cpuUsageSteal - -- $.event.measurementsForVfScalingFields.cpuUsageArray[*].cpuUsageSystem - -- $.event.measurementsForVfScalingFields.cpuUsageArray[*].cpuWait - -- $.event.measurementsForVfScalingFields.cpuUsageArray[*].percentUsage - -- $.event.measurementsForVfScalingFields.meanRequestLatency - -- -$.event.measurementsForVfScalingFields.memoryUsageArray[*].memoryBuffered - -- -$.event.measurementsForVfScalingFields.memoryUsageArray[*].memoryCached - -- -$.event.measurementsForVfScalingFields.memoryUsageArray[*].memoryConfigured - -- $.event.measurementsForVfScalingFields.memoryUsageArray[*].memoryFree - -- $.event.measurementsForVfScalingFields.memoryUsageArray[*].memoryUsed - -- -$.event.measurementsForVfScalingFields.additionalMeasurements[*].arrayOfFields[0].value - -severity: - -type: string - -required: true - -description: Threshold Event Severity - -constraints: - -- valid_values: - -- CRITICAL - -- MAJOR - -- MINOR - -- WARNING - -- NORMAL - -thresholdValue: - -type: integer - -required: true - -description: Threshold value for the field Path inside CEF message - -version: - -type: string - -required: true - -description: Version number associated with 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 - -1. Existing Drools implementations that supports runtime Control Loop - actions taken on components such as SO/APPC/VFC/SDNC/SDNR - -2. 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. - -**Base Policy type definition for -onap.policies.controlloop.Operational**  Expand source - -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. - -**Operational Policy Model Parameter Schema for APEX**  Expand source - -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.Operational: - -derived_from: tosca.policies.Root - -version: 1.0.0 - -description: Operational Policy for Control Loops - - onap.policies.controloop.operational.Apex: - -derived_from: onap.policies.controlloop.Operational - -version: 1.0.0 - -description: Operational Policy for Control Loops using the APEX PDP - - properties: - -# Some of these properties may be redundant in a Kubernetes deployment - -engine_service: - -type: onap.datatypes.policies.controlloop.operational.apex.EngineService - -description: APEX Engine Service Parameters - -inputs: - -type: map - -description: Inputs for handling events coming into the APEX engine - -entry_schema: - -type: onap.datatypes.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 is -set to - -the key name - - required: false - -carrier_technology: - -type: -onap.datatypes.policies.controlloop.operational.apex.CarrierTechnology - -description: Specifies the carrier technology of the event handler (such - -as REST/Web Socket/Kafka) - -required: true - -event_protocol: - -type: onap.datatypes.policies.controlloop.operational.apex.EventProtocol - -description: Specifies the event protocol of events for the event -handler - -(such as Yaml/JSON/XML/POJO) - -required: true - -event_name: - -type: string - -description: Specifies the event name for events on this event handler, -if - -not specified, the event name is read from or written to the event being - -received or sent - -required: false - -event_name_filter: - -type: string - -description: Specifies a filter as a regular expression, events that do - -not match the filter are dropped, the default is to let all events - -through - -required: false - -synchronous_mode: - -type: bool - -description: Specifies the event handler is syncronous (receive event -and - -send response) - -required: false - -default: false - -synchronous_peer: - -type: string - -description: The peer event handler (output for input or input for -output) - -of this event handler in synchronous mode, this parameter is mandatory -if - -the event handler is in synchronous mode - -required: false - -default: "" - -synchronous_timeout: - -type: int - -description: The timeout in milliseconds for responses to be issued by - -APEX torequests, this parameter is mandatory if the event handler is in - -synchronous mode - -required: false - -default: "" - -requestor_mode: - -type: bool - -description: Specifies the event handler is in requestor mode (send -event - -and wait for response mode) - -required: false - -default: false - -requestor_peer: - -type: string - -description: The peer event handler (output for input or input for -output) - -of this event handler in requestor mode, this parameter is mandatory if - -the event handler is in requestor mode - -required: false - -default: "" - -requestor_timeout: - -type: int - -description: The timeout in milliseconds for wait for responses to - -requests, this parameter is mandatory if the event handler is in - -requestor mode - -required: false - -default: "" - -onap.datatypes.policies.controlloop.operational.apex.CarrierTechnology: - -derived_from: tosca.datatypes.Root - -properties: - -label: - -type: string - -description: The label (name) of the carrier technology (such as REST, - -Kafka, WebSocket) - -required: true - -plugin_parameter_class_name: - -type: string - -description: The class name of the class that overrides default handling - -of event input or output for this carrier technology, defaults to the -supplied - -input or output class - -required: false - -onap.datatypes.policies.controlloop.operational.apex.EventProtocol: - -derived_from: tosca.datatypes.Root - -properties: - -label: - -type: string - -description: The label (name) of the event protocol (such as Yaml, - -JSON, XML, or POJO) - -required: true - -event_protocol_plugin_class: - -type: string - -description: The class name of the class that overrides default handling - -of the event protocol for this carrier technology, defaults to the - -supplied event protocol class - -required: false - -onap.datatypes.policies.controlloop.operational.apex.Environmental: - -derived_from: tosca.datatypes.Root - -properties: - -name: - -type: string - -description: The name of the environment variable - -required: true - -value: - -type: string - -description: The value of the environment variable - -required: true - -onap.datatypes.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 handling context in APEX engines, - -defaults to using Java maps for context - -required: false - -executors: - -type: map - -description: The plugins for policy executors used in engines such as - -javascript, MVEL, Jython - -required: true - -entry_schema: - -description: The plugin class path for this policy executor - -type: string - -onap.datatypes.policies.controlloop.operational.apex.engineservice.engine.Context: - -derived_from: tosca.datatypes.Root - -properties: - -distributor: - -type: onap.datatypes.policies.controlloop.operational.apex.Plugin - -description: The plugin to be used for distributing context between - -APEX PDPs at runtime - -required: false - -schemas: - -type: map - -description: The plugins for context schemas available in APEX PDPs - -such as Java and Avro - -required: false - -entry_schema: - -type: onap.datatypes.policies.controlloop.operational.apex.Plugin - -locking: - -type: onap.datatypes.policies.controlloop.operational.apex.plugin - -description: The plugin to be used for locking context in and - -between APEX PDPs at runtime - -required: false - -persistence: - -type: onap.datatypes.policies.controlloop.operational.apex.Plugin - -description: The plugin to be used for persisting context for APEX PDPs - -at runtime - -required: false - -onap.datatypes.policies.controlloop.operational.apex.Plugin: - -derived_from: tosca.datatypes.Root - -properties: - -name: - -type: string - -description: The name of the executor such as Javascript, Jython or MVEL - -required: true - -plugin_class_name: - -type: string - -description: The class path of the plugin class for this executor - -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: - -**Base Policy type definition for onap.policies.controlloop.Guard** - Expand source - -tosca_definitions_version: tosca_simple_yaml_1_0_0 - -policy_types: - -- onap.policies.controlloop.Guard: - -derived_from: tosca.policies.Root - -version: 1.0.0 - -description: Guard 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. - -**Casablanca Guard Payload**  Expand source - -ContentType: "application/json; vnd.onap.guard" - -Accepts: "application/json" - -# - -# Request BODY - -# - -{ - -"policy-id" : "guard.frequency.scaleout", - -"contents" : { - -"actor": "SO", - -"recipe": "scaleOut", - -"targets": ".*", - -"clname": "ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3", - -"limit": "1", - -"timeWindow": "10", - -"timeUnits": "minute", - -"guardActiveStart": "00:00:01-05:00", - -"guardActiveEnd": "23:59:59-05:00" - -} - -} - -# - -# Request RESPONSE - -# - -{ - -"guard.frequency.scaleout": { - -"type": "onap.policies.controlloop.guard.FrequencyLimiter", - -"version": "1.0.0", - -"metadata": { - -"policy-id": "guard.frequency.scaleout", - -"policy-version": 1 - -} - -} - -} - -1.3.1 onap.policies.controlloop.guard.FrequencyLimiter Policy Type -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This is WIP for El Alto for the proposed policy type. - -**Policy Typefor Frequency Limiter Guard Policy**  Expand source - -tosca_definitions_version: tosca_simple_yaml_1_0_0 - -policy_types: - -- onap.policies.controlloop.Guard: - -derived_from: tosca.policies.Root - -version: 1.0.0 - -description: Guard Policies for Control Loop Operational Policies - -- onap.policies.controlloop.guard.FrequencyLimiter: - -derived_from: onap.policies.controlloop.Guard - -version: 1.0.0 - -description: Supports limiting the frequency of actions being taken by a -Actor. - -properties: - -frequency_policy: - -type: map - -description: - -entry_schema: - -type: onap.datatypes.guard.FrequencyLimiter - -data_types: - -- onap.datatypes.guard.FrequencyLimiter: - -derived_from: tosca.datatypes.Root - -properties: - -actor: - -type: string - -description: Specifies the Actor - -required: true - -recipe: - -type: string - -description: Specified the Recipe - -required: true - -time_window: - -type: scalar-unit.time - -description: The time window to count the actions against. - -required: true - -limit: - -type: integer - -description: The limit - -required: true - -constraints: - -- greater_than: 0 - -time_range: - -type: tosca.datatypes.TimeInterval - -description: An optional range of time during the day the frequency is -valid for. - -required: false - -controlLoopName: - -type: string - -description: An optional specific control loop to apply this guard to. - -required: false - -target: - -type: string - -description: An optional specific VNF to apply this guard to. - -required: false - -1.3.2 onap.policies.controlloop.guard.Blacklist Policy Type -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -**Policy Type for Blacklist Guard Policies**  Expand source - -tosca_definitions_version: tosca_simple_yaml_1_0_0 - -policy_types: - -- onap.policies.controlloop.Guard: - -derived_from: tosca.policies.Root - -version: 1.0.0 - -description: Guard Policies for Control Loop Operational Policies - -- onap.policies.controlloop.guard.Blacklist: - -derived_from: onap.policies.controlloop.Guard - -version: 1.0.0 - -description: Supports blacklist of VNF's from performing control loop -actions on. - -properties: - -blacklist_policy: - -type: map - -description: - -entry_schema: - -type: onap.datatypes.guard.Blacklist - -data_types: - -- onap.datatypes.guard.Blacklist: - -derived_from: tosca.datatypes.Root - -properties: - -actor: - -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 blacklist is -valid for. - -required: false - -controlLoopName: - -type: string - -description: An optional specific control loop to apply this guard to. - -required: false - -blacklist: - -type: list - -description: List of VNF's - -required: true - -1.3.3 onap.policies.controlloop.guard.MinMax Policy Type -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -**Policy Type for Min/Max VF Module Policies**  Expand source - -policy_types: - -- onap.policies.controlloop.Guard: - -derived_from: tosca.policies.Root - -version: 1.0.0 - -description: Guard Policies for Control Loop Operational Policies - -- onap.policies.controlloop.guard.MinMax: - -derived_from: onap.policies.controlloop.Guard - -version: 1.0.0 - -description: Supports Min/Max number of VF Modules - -properties: - -minmax_policy: - -type: map - -description: - -entry_schema: - -type: onap.datatypes.guard.MinMax - -data_types: - -- onap.datatypes.guard.MinMax: - -derived_from: tosca.datatypes.Root - -properties: - -actor: - -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 - -description: An optional specific control loop to apply this guard to. - -required: false - -min_vf_module_instances: - -type: integer - -required: true - -description: The minimum instances of this VF-Module - -max_vf_module_instances: - -type: integer - -required: false - -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 - -=============== ================================================================================================================================================================================================================================================================================== ================================================================================================================================================================================ ======================================================================================================================================================================================================================== -**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. No run time configuration required and run time administration is simple. Very restrictive, no run time configuration of PDPs is possible. - - PDPs register with the PAP when they start, providing the *PolicyImpl* they have been predeployed with. -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. The configuration, parameters, and PDP group of PDPs may be changed at run time by loading or updating a TOSCA *Policy* into the PDP. Administration and management is required. The configuration and life cycle of the TOSCA policies can change at run time and must be administered and managed. - - 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. Lifecycle management of TOSCA *Policy* entities is supported, allowing features such as *PolicyImpl* Safe Mode and \ *Policy*\ Impl retirement. -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. 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. Administration and management is more complex. The *PolicyImpl* itself and its configuration and life cycle as well as the life cycle of the TOSCA policies can change at run time and must be administered and managed. - - 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. Lifecycle management of TOSCA *Policy* entities and *PolicyTypeImpl* entites is supported, allowing features such as *PolicyImpl* Safe Mode and \ *Policy*\ Impl retirement. -=============== ================================================================================================================================================================================================================================================================================== ================================================================================================================================================================================ ======================================================================================================================================================================================================================== - -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* - -**Policy Type Query - When system comes up before any mS are onboarded** - Expand source - -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}* Get a specific policy type and all the available versions. - -*eg. -https:{url}:{port}/policy/api/v1/policytypes/onap.policies.monitoring.cdap.tca.hi.lo.app* -*https:{url}:{port}/policy/api/v1/policytypes/{policy type id}/versions/{version id}* Get the specific Policy Type with the specified name and version - -*eg. -https:{url}:{port}/policy/api/v1/policytypes/onap.policies.monitoring.cdap.tca.hi.lo.app/versions/1.0.0* -======================================================================================================== ================================================================ - -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* - -**Create a new Policy Type for a DCAE microservice**  Expand source - -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:'{}' - -entry_schema: - -type: onap.datatypes.monitoring.tca_policy - -data_types: - - - -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* - -**Policy Type Query after DCAE TCA mS Policy Type is created**  Expand -source - -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* Get all Policies for a specific Policy Type and version - -*eg. -https:{url}:{port}/policy/api/v1/policytypes/onap.policies.monitoring.cdap.tca.hi.lo.app/versions/1.0.0/policies* -*https://{url}:{port}/policy/api/v1/policytypes/{policy type id}/versions/{version}/policies/{policy name}/versions/{version}* Gets a specific Policy version - -*eg. -https:{url}:{port}/policy/api/v1/policytypes/onap.policies.monitoring.cdap.tca.hi.lo.app/versions/1.0.0/policies/onap.scaleout.tca/versions/1.0.0 GET* -*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* - -**TOSCA Body of a new TCA High/Low Policy**  Expand source - -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" - - - -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* - -**Policy with Metadata section for lifecycle management**  Expand source - -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* - -**Query on a new TCA High/Low Policy**  Expand source - -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 - - - -**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 - -**Create an Operational Policy**  Expand source - -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 - -**Response from creating Operational Policy**  Expand source - -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* - -**Create an APEX Policy for a Sample Domain**  Expand source - -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* - -**PDP Group query for all PDP groups and Subgroups**  Expand source - -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:// - -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:// - -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:// - -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:// - -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* - -**POST body to deploy or update PDP groups**  Expand source - -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* - -**POST body to deploy or update PDP groups**  Expand source - -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 - -{ - -"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.{ - -"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. - -{ - -"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: - -1. Only one version of a PDP group may be ACTIVE at any time - -2. 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 - -3. 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 - -4. There is no restriction on the number of PASSIVE versions of a PDP - group that can exist in the system - -5. ? `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* - -**Draft Example statistics returned for a PDP Group**  Expand source - -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 - -**Decision API Call - Policy ID** - -{ - -"ONAPName": "DCAE", - -"ONAPComponent": "PolicyHandler", - -"ONAPInstance": "622431a4-9dea-4eae-b443-3b2164639c64", - -"action": "configure", - -"resource": { - -"policy-id": "onap.scaleout.tca" - -} - -} - -**Decision Response - Single Policy ID query** - -{ - -"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 - -**Decision API Call - Policy ID** - -{ - -"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: - -**Decision Response - Single Policy ID query** - -{ - -"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. - -{ - -"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. - -{ - -"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: - -1. PDP_STATUS: PDP→PAP, used by PDPs to report to the PAP - -2. 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 - -3. 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 - -4. 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 **PDP **PDP **PDP **Comment** - STATUS** UPDATE** STATE HEALTH - CHANGE** CHECK** -======================== ============================= ======== ======== ======= ====================================================================================================================================== ================================================================================================================================================================================================== -(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. - -**PDP_STATUS message from an XACML PDP running control loop policies** - Expand source - -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: - -# Omitted for brevity, see Section 3.2 - -- onap.policies.controlloop.guard.minmax.eastRegion: - -policy_type: onap.policies.controlloop.guard.MinMax - -policy_type_version: 1.0.0 - -properties: - -# Omitted for brevity, see Section 3.2 - -instance: xacml_1 - -deployment_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 - -policy_executed_fail_count: 1 - -**PDP_STATUS message from a Drools PDP running control loop policies** - Expand source - -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.controllloop.operational.drools.vcpe.EastRegion: - -policy_type: onap.controllloop.operational.drools.vCPE - -policy_type_version: 1.0.0 - -properties: - -# Omitted for brevity, see Section 3.2 - -- onap.controllloop.operational.drools.vfw.EastRegion: - -policy_type: onap.controllloop.operational.drools.vFW - -policy_type_version: 1.0.0 - -properties: - -# Omitted for brevity, see 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 - -policy_download_fail_count: 0 - -policy_executed_count: 123 - -policy_executed_success_count: 122 - -policy_executed_fail_count: 1 - -response: - -response_to: PDP_HEALTH_CHECK - -response_status: SUCCESS - -**PDP_STATUS message from an APEX PDP running control loop policies** - Expand source - -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: - -policy_type: onap.controllloop.operational.apex.BBS - -policy_type_version: 1.0.0 - -properties: - -# Omitted for brevity, see Section 3.2 - -- onap.controllloop.operational.apex.sampledomain.EastRegion: - -policy_type: onap.controllloop.operational.apex.SampleDomain - -policy_type_version: 1.0.0 - -properties: - -# Omitted for brevity, see Section 3.2 - -instance: apex_3 - -deployment_instance_info:node_address - -node_address: apex_3_pod - -# Other deployment instance info - -statistics: - -policy_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 - -response_message: policies specified in update message incompatible with -running policy state - -**PDP_STATUS message from an XACML PDP running monitoring policies** - Expand source - -pdp_status: - -  name: xacml_1 - -version: 1.2.3 - -pdp_type: xacml - -state: active - -healthy: 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.scaleout.tca: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: xacml_1 - -deployment_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 - -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. - -**PDP_UPDATE message to upgrade XACML PDP control loop policies to -versino 1.0.1**  Expand source - -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: - -policy_type: onap.policies.controlloop.guard.FrequencyLimiter - -policy_type_version: 1.0.1 - -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.1 - -properties: - -# Omitted for brevity, see Section 3.2 - -- onap.policies.controlloop.guard.minmax.EastRegion: - -policy_type: onap.policies.controlloop.guard.MinMax - -policy_type_version: 1.0.1 - -properties: - -# Omitted for brevity, see Section 3.2 - -**PDP_UPDATE message to a Drools PDP to add an extra control loop -policy**  Expand source - -pdp_update: - -name: drools_2 - -pdp_type: drools - -description: Drools PDP running control loop policies, extra policy -added - -pdp_group: onap.pdpgroup.controlloop.operational - -pdp_subgroup: drools - -policies: - -- onap.controllloop.operational.drools.vcpe.EastRegion: - -policy_type: onap.controllloop.operational.drools.vCPE - -policy_type_version: 1.0.0 - -properties: - -# Omitted for brevity, see Section 3.2 - -- onap.controllloop.operational.drools.vfw.EastRegion: - -policy_type: onap.controllloop.operational.drools.vFW - -policy_type_version: 1.0.0 - -properties: - -# Omitted for brevity, see Section 3.2 - -- onap.controllloop.operational.drools.vfw.WestRegion: - -policy_type: onap.controllloop.operational.drools.vFW - -policy_type_version: 1.0.0 - -properties: - -# Omitted for brevity, see Section 3.2 - -**PDP_UPDATE message to an APEX PDP to remove a control loop policy** - Expand source - -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: - -- onap.controllloop.operational.apex.bbs.EastRegion: - -policy_type: onap.controllloop.operational.apex.BBS - -policy_type_version: 1.0.0 - -properties: - -# Omitted for 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. - -**Change the state of all control loop Drools PDPs to ACTIVE**  Expand -source - -pdp_state_change: - -state: active - -pdp_group: onap.pdpgroup.controlloop.Operational - -pdp_subgroup: drools - -**Change the state of all monitoring PDPs to SAFE**  Expand source - -pdp_state_change: - -state: safe - -pdp_group: onap.pdpgroup.Monitoring - -**Change the state of a single APEX PDP to TEST**  Expand source - -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. - -**Perform a health check on all control loop Drools PDPs**  Expand -source - -pdp_health_check: - -pdp_group: onap.pdpgroup.controlloop.Operational - -pdp_subgroup: drools - -**perform a health check on all monitoring PDPs**  Expand source - -pdp_health_check: - -pdp_group: onap.pdpgroup.Monitoring - -**Perform a health check on a single APEX PDP**  Expand source - -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* - -**Policy Type Implementation Query Result**  Expand source - -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: "" - -- 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: "" - -The table below shows some more examples of GET operations - -========================================================================================================================================================================= ========================================================================================================================================================== -**Example** **Description** -========================================================================================================================================================================= ========================================================================================================================================================== -*https:{url}:{port}/policy/api/v1/native/{policy type id}/impls* Get all Policy Type implementations for the given policy type - -| *eg.* -| *https:{url}:{port}/policy/api/v1/native/onap.policies.monitoring/impls* -| *https:{url}:{port}/policy/api/v1/native/onap.policies.controlloop.operational.apex/impls* -*https:{url}:{port}/policy/api/v1/native/{policy type id}/impls/{policy type impl id}* Get all Policy Type implementation versions that match the policy type and policy type implementation IDs specified - -| *eg.* -| *https:{url}:{port}/policy/api/v1/native/onap.policies.controlloop.operational/impls/onap.policies.controlloop.operational.drools.impl* -| *https:{url}:{port}/policy/api/v1/native/onap.policies.controlloop.operational.apex/impls/onap.policies.controlloop.operational.apex.sampledomain.impl* -*https:{url}:{port}/policy/api/v1/native/{policy type id}/impls/{policy type impl id}/versions/{version id}* 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 - -| *eg.* -| *https:{url}:{port}/policy/api/v1/native/onap.policies.controlloop.operational/impls/onap.policies.controlloop.operational.drools.impl/versions/1.2.3* -| *https:{url}:{port}/policy/api/v1/native/onap.policies.controlloop.operational.apex/impls/onap.policies.controlloop.operational.apex.sampledomain.impl/versions/latest* -========================================================================================================================================================================= ========================================================================================================================================================== - -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* - -**Create a new Policy Type Implementation**  Expand source - -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: "" - -- 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: " - -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 diff --git a/docs/design/images/APIsInPolicyFramework.svg b/docs/design/images/APIsInPolicyFramework.svg new file mode 100644 index 00000000..9c19d751 --- /dev/null +++ b/docs/design/images/APIsInPolicyFramework.svg @@ -0,0 +1,2 @@ + +
Policy Type Design
(Policy Type Design API)
[Not supported by viewer]
PolicyType
TOSCA Artifact
[Not supported by viewer]
Policy Design
(Policy Design API)
Policy Design<br>(Policy Design API)
Done Manually or over Lifecycle API
Done Manually or over Lifecycle API
CLAMP
CLAMP
Other System
Other System
Executable Policy
Preinstalled or created by CLAMP or another system over Policy Design API
[Not supported by viewer]
PolicyImpl
Artifact
[Not supported by viewer]
PolicyTypeImpl
Artifact
<b>PolicyTypeImpl</b><br>Artifact
PAP
PAP
PDPs
PDPs
PDPs
PDPs
PDPs
PDPs
PDPs
PDPs
PDPs
PDPs
PDPs
PDPs
Runtime Administration
(Policy Admin API)
Runtime Administration<br>(Policy Admin API)
Other System
Other System
Policy
GUI
Policy<br>GUI
Policy Type Implementation matches ToscaPolicyType
An XACML,Drools, or
APEX implementation of a Policy Type
[Not supported by viewer]
Policy
TOSCA Artifact
[Not supported by viewer]
SDC
SDC
Other System
Other System \ No newline at end of file diff --git a/docs/design/images/PolicyImplPDPSubGroup.svg b/docs/design/images/PolicyImplPDPSubGroup.svg new file mode 100644 index 00000000..8987ed22 --- /dev/null +++ b/docs/design/images/PolicyImplPDPSubGroup.svg @@ -0,0 +1,2 @@ + +
PDPGroup
PDPGroup
PDPSubGroup
PDPSubGroup
PDPSubGroup
PDPSubGroup
PDP-X
PDP-X
PDP-X
PDP-X
PDP-A
PDP-A
PDP-A
PDP-A
PDP-A
PDP-A
PDPSubGroup
PDPSubGroup
PDP-D
PDP-D
PDP-D
PDP-D
PDP-D
PDP-D
All PDPs in a PDPSubGroup run the same PolicyImpl
[Not supported by viewer]
The PDP running its PolicyImpl is the unit of scaling
[Not supported by viewer]
A PDPSubGroup is a Kubernetes Deployment
[Not supported by viewer]
PDPs run as Kubernets Pods
[Not supported by viewer]
A PDPGroup groups PDPSubGroup entities together
[Not supported by viewer]
ControlLoop
PDPGroup
ControlLoop<br>PDPGroup
CL_Apex
PDPSubGroup
CL_Apex<br>PDPSubGroup
CL_Guard
PDPSubGroup
CL_Guard<br>PDPSubGroup
PDP-X
PDP-X
PDP-X
PDP-X
PDP-A
PDP-A
PDP-A
PDP-A
PDP-A
PDP-A
CL_Drools
PDPSubGroup
CL_Drools<br>PDPSubGroup
PDP-D
PDP-D
PDP-D
PDP-D
PDP-D
PDP-D
Monitoring
PDPGroup
Monitoring<br>PDPGroup
Monitoring
PDPSubGroup
Monitoring<br>PDPSubGroup
PDP-X
PDP-X
PDP-X
PDP-X \ No newline at end of file diff --git a/docs/pap/pap.rst b/docs/pap/pap.rst index a76ab807..b420279c 100644 --- a/docs/pap/pap.rst +++ b/docs/pap/pap.rst @@ -4,29 +4,53 @@ .. _pap-label: Policy Administration Point (PAP) Architecture -============================================== -.. toctree:: +############################################## -The PAP keeps track of PDPs, supporting the deployment of PDP groups and the -deployment of a *policy set* across those PDP groups. Policies are created -using the Policy API, but are deployed via the PAP. +.. contents:: + :depth: 3 -A PAP is stateless in -a RESTful sense, using the database (persistent storage) to track PDPs and -the deployment of policies to those PDPs. In short, policy management on PDPs -is the responsibility of PAPs; management of policy sets or policies by any -other manner is not permitted. +The PAP keeps track of PDPs, supporting the deployment of PDP groups and the deployment of a *policy set* across those +PDP groups. Policies are created using the Policy API, but are deployed via the PAP. -Because the PDP is the main unit of scalability in the Policy Framework, the -framework is designed to allow PDPs in a PDP group to arbitrarily appear and -disappear and for policy consistency across all PDPs in a PDP group to be -easily maintained. The PAP is responsible for controlling the state across -the PDPs in a PDP group. The PAP interacts with the Policy database and -transfers policy sets to PDPs. +A PAP is stateless in a RESTful sense, using the database (persistent storage) to track PDPs and the deployment of +policies to those PDPs. In short, policy management on PDPs is the responsibility of PAPs; management of policy sets or +policies by any other manner is not permitted. +Because the PDP is the main unit of scalability in the Policy Framework, the framework is designed to allow PDPs in a +PDP group to arbitrarily appear and disappear and for policy consistency across all PDPs in a PDP group to be easily +maintained. The PAP is responsible for controlling the state across the PDPs in a PDP group. The PAP interacts with the +Policy database and transfers policy sets to PDPs. -REST API --------- +There are a number of rules for PDP group and PDP state management: + +1. Only one version of a PDP group may be ACTIVE at any time + +2. 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 + +3. 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 + +4. There is no restriction on the number of PASSIVE versions of a PDP group that can exist in the system + + +1 APIs +====== +The APIs in the subchapters below are supported by the PAP. + +1.1 REST API +------------ + +The purpose of this API is to support CRUD of PDP groups and subgroups and to support the deployment and life cycles of +policies on PDP sub groups and PDPs. This API is provided by the *PolicyAdministration* component (PAP) of the Policy +Framework, see the :ref:`ONAP Policy Framework Architecture ` page. + +PDP groups and subgroups may be prefedined in the system. Predefined groups and subgroups may be modified or deleted +over this API. The policies running on predefined groups or subgroups as well as the instance counts and properties may +also 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. PAP supports the operations listed in the following table, via its REST API: @@ -43,9 +67,8 @@ PAP supports the operations listed in the following table, via its REST API: "Deploy policy", "Deploys one or more policies to the PDPs" "Undeploy policy", "Undeploys a policy from the PDPs" - -DMaaP API ---------- +1.2 DMaaP API +------------- PAP interacts with the PDPs via the DMaaP Message Router. The messages listed in the following table are transmitted via DMaaP: @@ -59,20 +82,20 @@ in the following table are transmitted via DMaaP: "PDP state change", "Outgoing", "Changes the state of a PDP or all PDPs within a PDP Group or Subgroup" -PAP REST API Swagger --------------------- +2 PAP REST API Swagger +====================== -It is worth noting that we use basic authorization for access with user name -and password set to *healthcheck* and *zb!XztG34*, respectively. +It is worth noting that we use basic authorization for access with user name and password set to *healthcheck* and +*zb!XztG34*, respectively. -For every call, the client is encouraged to insert a uuid-type *requestID* as -parameter. It is helpful for tracking each http transaction and facilitates -debugging. More importantly, it complies with Logging requirements v1.2. If -the client does not provide the requestID in a call, one will be randomly -generated and attached to the response header, *x-onap-requestid*. +For every call, the client is encouraged to insert a uuid-type *requestID* as parameter. It is helpful for tracking each +http transaction and facilitates debugging. More importantly, it complies with Logging requirements v1.2. If the client +does not provide the requestID in a call, one will be randomly generated and attached to the response header, +*x-onap-requestid*. -In accordance with `ONAP API Common Versioning Strategy Guidelines `_, -several custom headers are added in the response to each call: +In accordance with `ONAP API Common Versioning Strategy Guidelines +`_, several custom headers +are added in the response to each call: .. csv-table:: :header: "Header", "Example value", "Description" @@ -86,37 +109,71 @@ several custom headers are added in the response to each call: .. swaggerv2doc:: swagger/health-check-pap.json +This operation performs a health check on the PAP. + .. swaggerv2doc:: swagger/statistics-pap.json -Note: while this API is supported, most of the statistics -are not currently updated; that work has been deferred to a later release. +This operation allows statistics for PDP groups, PDP subgroups, and individual PDPs to be retrieved. + +.. note:: + While this API is supported, most of the statistics are not currently updated; that work has been deferred to a later + release. .. swaggerv2doc:: swagger/state-change-pap.json +The state of PDP groups is managed by this operation. PDP groups can be in states PASSIVE, TEST, SAFE, or ACTIVE. For a full +description of PDP group states, see the :ref:`ONAP Policy Framework Architecture ` page. + .. swaggerv2doc:: swagger/group-pap.json -Note: due to current limitations, if a subgroup is to be deleted from a PDP -Group, then the policies must be removed from the subgroup in one request, -and then the subgroup deleted in a subsequent request. +This operation allows the PDP groups and subgroups to be created and updated. 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. + +.. note:: + Due to current limitations, if a subgroup is to be deleted from a PDP Group, then the policies must be removed from + the subgroup in one request, and then the subgroup deleted in a subsequent request. .. swaggerv2doc:: swagger/group-delete-pap.json +The API also allows PDP groups to be deleted. DELETE operations are only permitted on PDP groups in PASSIVE state. + .. swaggerv2doc:: swagger/group-query-pap.json +This operation allows the PDP groups and subgroups to be listed as well as the policies that are deployed on each PDP +group and subgroup. + .. swaggerv2doc:: swagger/policy-deploy-pap.json -Note: the policy version is optional. If left unspecified, then the latest -version of the policy is deployed. On the other hand, if it is specified, it -may be an integer, or it may be a fully qualified version (e.g., "3.0.2"). +This operation allows policies to be deployed on PDP groups. + +.. note:: + The policy version is optional. If left unspecified, then the latest version of the policy is deployed. On the other + hand, if it is specified, it may be an integer, or it may be a fully qualified version (e.g., "3.0.2"). .. swaggerv2doc:: swagger/policy-undeploy-pap.json -Note: if the policy version is specified, then it -may be an integer, or it may be a fully qualified version (e.g., "3.0.2"). -On the other hand, if left unspecified, then the latest deployed version -will be undeployed. +This operation allows policies to be undeployed from PDP groups. + +.. note:: + If the policy version is specified, then it may be an integer, or it may be a fully qualified version (e.g., "3.0.2"). + On the other hand, if left unspecified, then the latest deployed version will be undeployed. + +.. note:: + Due to current limitations, a fully qualified policy version must always be specified. + +3 Future Features +================= + +3.1 Order Health Check on PDPs +============================== + +This operation will allow a PDP group health check to be ordered on PDP groups and on individual PDPs. The operation +will return a HTTP status code of *202: Accepted* if the health check request has been accepted by the PAP. The PAP will +then order execution of the health check on the PDPs. + +As health checks may be long lived operations, Health checks will be scheduled for execution by this operation. Users +will check the result of a health check test by issuing a PDP Group Query operation and checking the *healthy* field of +PDPs. -Note: due to current limitations, a fully qualified policy version must -always be specified. End of Document -- cgit 1.2.3-korg