1 .. This work is licensed under a
2 .. Creative Commons Attribution 4.0 International License.
3 .. http://creativecommons.org/licenses/by/4.0
7 The Internal Policy Framework PAP-PDP API
8 #########################################
13 This page describes the API between the PAP and PDPs. The APIs in this section are implemented using `DMaaP
14 API <https://wiki.onap.org/display/DW/DMaaP+API>`__ messaging. The APIs in this section are used for internal
15 communication in the Policy Framework. The APIs are NOT supported for use by components outside the Policy Framework and
16 are subject to revision and change at any time.
18 There are four messages on the API:
20 1. PDP_STATUS: PDP→PAP, used by PDPs to report to the PAP
22 2. PDP_UPDATE: PAP→PDP, used by the PAP to update the policies running on PDPs, triggers a PDP_STATUS message with
23 the result of the PDP_UPDATE operation
25 3. PDP_STATE_CHANGE: PAP→PDP, used by the PAP to change the state of PDPs, triggers a PDP_STATUS message with the result
26 of the PDP_STATE_CHANGE operation
28 4. PDP_HEALTH_CHECK: PAP→PDP, used by the PAP to order a health check on PDPs, triggers a PDP_STATUS message with the
29 result of the PDP_HEALTH_CHECK operation
31 The fields in the table below are valid on API calls:
33 =============================== ======== ======== ======== ======= =====================================================
34 **Field** **PDP **PDP **PDP **PDP **Comment**
35 STATUS** UPDATE** STATE HEALTH
37 =============================== ======== ======== ======== ======= =====================================================
38 (message_name) M M M M pdp_status, pdp_update, pdp_state_change, or
40 name M M C C The name of the PDP, for state changes and health
41 checks, the PDP group and subgroup can be used to
42 specify the scope of the operation
43 version M N/A N/A N/A The version of the PDP
44 pdp_type M M N/A N/A The type of the PDP, currently xacml, drools, or apex
45 state M N/A M N/A The administrative state of the PDP group: PASSIVE,
46 SAFE, TEST, ACTIVE, or TERMINATED
47 healthy M N/A N/A N/A The result of the latest health check on the PDP:
48 HEALTHY/NOT_HEALTHY/TEST_IN_PROGRESS
49 description O O N/A N/A The description of the PDP
50 pdp_group O M C C The PDP group to which the PDP belongs, the PDP group
51 and subgroup can be used to specify the scope of the
53 pdp_subgroup O M C C The PDP subgroup to which the PDP belongs, the PDP
54 group and subgroup can be used to specify the scope
56 supported_policy_types M N/A N/A N/A A list of the policy types supported by the PDP
57 policies M N/A N/A N/A The list of policies running on the PDP
58 policiesToBeDeployed N/A M N/A N/A The list of policies to be deployed on the PDP
59 policiesToBeUndeployed N/A M N/A N/A The list of policies to be undeployed from the PDP
60 ->(name) O M N/A N/A The name of a TOSCA policy running on the PDP
61 ->policy_type O M N/A N/A The TOSCA policy type of the policyWhen a PDP starts,
62 it commences periodic sending of *PDP_STATUS*
63 messages on DMaaP. The PAP receives these messages
64 and acts in whatever manner is appropriate.
65 ->policy_type_version O M N/A N/A The version of the TOSCA policy type of the policy
66 ->properties O M N/A N/A The properties of the policy for the XACML, Drools,
67 or APEX PDP for details
68 instance M N/A N/A N/A The instance ID of the PDP running in a Kuberenetes
70 deployment_instance_info M N/A N/A N/A Information on the node running the PDP
71 properties O O N/A N/A Other properties specific to the PDP
72 statistics M N/A N/A N/A Statistics on policy execution in the PDP
73 ->policy_download_count M N/A N/A N/A The number of policies downloaded into the PDP
74 ->policy_download_success_count M N/A N/A N/A The number of policies successfully downloaded into
76 ->policy_download_fail_count M N/A N/A N/A The number of policies downloaded into the PDP where
78 ->policy_executed_count M N/A N/A N/A The number of policy executions on the PDP
79 ->policy_executed_success_count M N/A N/A N/A The number of policy executions on the PDP that
80 completed successfully
81 ->policy_executed_fail_count M N/A N/A N/A The number of policy executions on the PDP that
83 response O N/A N/A N/A The response to the last operation that the PAP
85 ->response_to M N/A N/A N/A The PAP to PDP message to which this is a response
86 ->response_status M N/A N/A N/A SUCCESS or FAIL
87 ->response_message O N/A N/A N/A Message giving further information on the successful
89 =============================== ======== ======== ======== ======= =====================================================
91 YAML is used for illustrative purposes in the examples in this section. JSON (application/json) is used as the content
92 type in the implementation of this API.
96 The purpose of this API is for PDPs to provide heartbeat, status, health, and statistical information to Policy
97 Administration. There is a single *PDP_STATUS* message on this API. PDPs send this message to the PAP using the
98 *POLICY_PDP_PAP* DMaaP topic. The PAP listens on this topic for messages.
100 When a PDP starts, it commences periodic sending of *PDP_STATUS* messages on DMaaP. The PAP receives these messages and
101 acts in whatever manner is appropriate. *PDP_UPDATE*, *PDP_STATE_CHANGE*, and *PDP_HEALTH_CHECK* operations trigger a
102 *PDP_STATUS* message as a response.
104 The *PDP_STATUS* message is used for PDP heartbeat monitoring. A PDP sends a *PDP_STATUS* message with a state of
105 *TERMINATED* when it terminates normally. If a *PDP_STATUS* message is not received from a PDP periodically or in
106 response to a pdp_update, pdp-state_change, or pdp_health_check message in a certain configurable time, then the PAP
107 assumes the PDP has failed.
109 A PDP may be preconfigured with its PDP group, PDP subgroup, and policies. If the PDP group, subgroup, or any policy
110 sent to the PAP in a *PDP_STATUS* message is unknown to the PAP, the PAP locks the PDP in state PASSIVE.
113 :caption: PDP_STATUS message from an XACML PDP running control loop policies
122 description: XACML PDP running control loop policies
123 pdp_group: onap.pdpgroup.controlloop.operational
125 supported_policy_types:
126 - onap.policies.controlloop.guard.FrequencyLimiter
127 - onap.policies.controlloop.guard.BlackList
128 - onap.policies.controlloop.guard.MinMax
130 - onap.policies.controlloop.guard.frequencylimiter.EastRegion:
131 policy_type: onap.policies.controlloop.guard.FrequencyLimiter
132 policy_type_version: 1.0.0
134 # Omitted for brevity
135 - onap.policies.controlloop.guard.blacklist.eastRegion:
136 policy_type: onap.policies.controlloop.guard.BlackList
137 policy_type_version: 1.0.0
139 # Omitted for brevity
140 - onap.policies.controlloop.guard.minmax.eastRegion:
141 policy_type: onap.policies.controlloop.guard.MinMax
142 policy_type_version: 1.0.0
144 # Omitted for brevity
146 deployment_instance_info:
147 node_address: xacml_1_pod
148 # Other deployment instance info
150 policy_download_count: 0
151 policy_download_success_count: 0
152 policy_download_fail_count: 0
153 policy_executed_count: 123
154 policy_executed_success_count: 122
155 policy_executed_fail_count: 1
158 :caption: PDP_STATUS message from a Drools PDP running control loop policies
167 description: Drools PDP running control loop policies
168 pdp_group: onap.pdpgroup.controlloop.operational
170 supported_policy_types:
171 - onap.controllloop.operational.drools.vCPE
172 - onap.controllloop.operational.drools.vFW
174 - onap.controllloop.operational.drools.vcpe.EastRegion:
175 policy_type: onap.controllloop.operational.drools.vCPE
176 policy_type_version: 1.0.0
178 # Omitted for brevity
179 - onap.controllloop.operational.drools.vfw.EastRegion:
180 policy_type: onap.controllloop.operational.drools.vFW
181 policy_type_version: 1.0.0
183 # Omitted for brevity
185 deployment_instance_info:
186 node_address: drools_2_pod
187 # Other deployment instance info
189 policy_download_count: 3
190 policy_download_success_count: 3
191 policy_download_fail_count: 0
192 policy_executed_count: 123
193 policy_executed_success_count: 122
194 policy_executed_fail_count: 1
196 response_to: PDP_HEALTH_CHECK
197 response_status: SUCCESS
200 :caption: PDP_STATUS message from an APEX PDP running control loop policies
209 description: APEX PDP running control loop policies
210 pdp_group: onap.pdpgroup.controlloop.operational
212 supported_policy_types:
213 - onap.controllloop.operational.apex.BBS
215 - onap.controllloop.operational.apex.bbs.EastRegion:
216 policy_type: onap.controllloop.operational.apex.BBS
217 policy_type_version: 1.0.0
219 # Omitted for brevity
220 - onap.controllloop.operational.apex.bbs.WestRegion:
221 policy_type: onap.controllloop.operational.apex.BBS
222 policy_type_version: 1.0.0
224 # Omitted for brevity
226 deployment_instance_info:
227 node_address: apex_3_pod
228 # Other deployment instance info
230 policy_download_count: 3
231 policy_download_success_count: 3
232 policy_download_fail_count: 0
233 policy_executed_count: 123
234 policy_executed_success_count: 122
235 policy_executed_fail_count: 1
237 response_to: PDP_HEALTH_CHECK
238 response_status: SUCCESS
241 :caption: PDP_STATUS message from an XACML PDP running monitoring policies
250 description: XACML PDP running monitoring policies
251 pdp_group: onap.pdpgroup.Monitoring
253 supported_policy_types:
254 - onap.monitoring.tcagen2
256 - onap.scaleout.tca:message
257 policy_type: onap.policies.monitoring.tcagen2
258 policy_type_version: 1.0.0
260 # Omitted for brevity
262 deployment_instance_info:
263 node_address: xacml_1_pod
264 # Other deployment instance info
266 policy_download_count: 0
267 policy_download_success_count: 0
268 policy_download_fail_count: 0
269 policy_executed_count: 123
270 policy_executed_success_count: 122
271 policy_executed_fail_count: 1
276 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
277 allows the PAP to order health checks to run on PDPs. The PAP sends *PDP_UPDATE*, *PDP_STATE_CHANGE*, and
278 *PDP_HEALTH_CHECK* messages to PDPs using the *POLICY_PAP_PDP* DMaaP topic. PDPs listen on this topic for messages.
280 The PAP can set the scope of *PDP_STATE_CHANGE* and *PDP_HEALTH_CHECK* messages:
282 - PDP Group: If a PDP group is specified in a message, then the PDPs in that PDP group respond to the message and all
283 other PDPs ignore it.
285 - PDP Group and subgroup: If a PDP group and subgroup are specified in a message, then only the PDPs of that subgroup
286 in the PDP group respond to the message and all other PDPs ignore it.
288 - Single PDP: If the name of a PDP is specified in a message, then only that PDP responds to the message and all other
291 Note: *PDP_UPDATE* messages must be issued individually to PDPs because the *PDP_UPDATE* operation can change the PDP
292 group to which a PDP belongs.
297 The *PDP_UPDATE* operation allows the PAP to modify the PDP group to which a PDP belongs and the policies in a PDP.
299 The following examples illustrate how the operation is used.
302 :caption: PDP_UPDATE message to upgrade XACML PDP control loop policies to version 1.0.1
308 description: XACML PDP running control loop policies, Upgraded
309 pdp_group: onap.pdpgroup.controlloop.operational
311 policiesToBeDeployed:
312 - onap.policies.controlloop.guard.frequencylimiter.EastRegion:
313 policy_type: onap.policies.controlloop.guard.FrequencyLimiter
314 policy_type_version: 1.0.1
316 # Omitted for brevity
317 - onap.policies.controlloop.guard.blackList.EastRegion:
318 policy_type: onap.policies.controlloop.guard.BlackList
319 policy_type_version: 1.0.1
321 # Omitted for brevity
322 - onap.policies.controlloop.guard.minmax.EastRegion:
323 policy_type: onap.policies.controlloop.guard.MinMax
324 policy_type_version: 1.0.1
326 # Omitted for brevity
329 :caption: PDP_UPDATE message to a Drools PDP to add an extra control loop policy
335 description: Drools PDP running control loop policies, extra policy added
336 pdp_group: onap.pdpgroup.controlloop.operational
338 policiesToBeDeployed:
339 - onap.controllloop.operational.drools.vfw.WestRegion:
340 policy_type: onap.controllloop.operational.drools.vFW
341 policy_type_version: 1.0.0
343 # Omitted for brevity
346 :caption: PDP_UPDATE message to an APEX PDP to remove a control loop policy
352 description: APEX PDP updated to remove a control loop policy
353 pdp_group: onap.pdpgroup.controlloop.operational
355 policiesToBeDeployed: []
356 policiesToBeUndeployed:
357 - onap.controllloop.operational.apex.bbs.WestRegion:
358 policy_type: onap.controllloop.operational.apex.BBS
359 policy_type_version: 1.0.0
361 # Omitted for brevity
366 The *PDP_STATE_CHANGE* operation allows the PAP to order state changes on PDPs in PDP groups and subgroups. The
367 following examples illustrate how the operation is used.
370 :caption: Change the state of all control loop Drools PDPs to ACTIVE
375 pdp_group: onap.pdpgroup.controlloop.Operational
379 :caption: Change the state of all monitoring PDPs to SAFE
384 pdp_group: onap.pdpgroup.Monitoring
387 :caption: Change the state of a single APEX PDP to TEST
397 The *PDP_HEALTH_CHECK* operation allows the PAP to order health checks on PDPs in PDP groups and subgroups. The
398 following examples illustrate how the operation is used.
401 :caption: Perform a health check on all control loop Drools PDPs
405 pdp_group: onap.pdpgroup.controlloop.Operational
409 :caption: perform a health check on all monitoring PDPs
413 pdp_group: onap.pdpgroup.Monitoring
416 :caption: Perform a health check on a single APEX PDP