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 O M N/A N/A The list of policies running on the PDP
58 ->(name) O M N/A N/A The name of a TOSCA policy running on the PDP
59 ->policy_type O M N/A N/A The TOSCA policy type of the policyWhen a PDP starts,
60 it commences periodic sending of *PDP_STATUS*
61 messages on DMaaP. The PAP receives these messages
62 and acts in whatever manner is appropriate.
63 ->policy_type_version O M N/A N/A The version of the TOSCA policy type of the policy
64 ->properties O M N/A N/A The properties of the policy for the XACML, Drools,
65 or APEX PDP for details
66 instance M N/A N/A N/A The instance ID of the PDP running in a Kuberenetes
68 deployment_instance_info M N/A N/A N/A Information on the node running the PDP
69 properties O O N/A N/A Other properties specific to the PDP
70 statistics M N/A N/A N/A Statistics on policy execution in the PDP
71 ->policy_download_count M N/A N/A N/A The number of policies downloaded into the PDP
72 ->policy_download_success_count M N/A N/A N/A The number of policies successfully downloaded into
74 ->policy_download_fail_count M N/A N/A N/A The number of policies downloaded into the PDP where
76 ->policy_executed_count M N/A N/A N/A The number of policy executions on the PDP
77 ->policy_executed_success_count M N/A N/A N/A The number of policy executions on the PDP that
78 completed successfully
79 ->policy_executed_fail_count M N/A N/A N/A The number of policy executions on the PDP that
81 response O N/A N/A N/A The response to the last operation that the PAP
83 ->response_to M N/A N/A N/A The PAP to PDP message to which this is a response
84 ->response_status M N/A N/A N/A SUCCESS or FAIL
85 ->response_message O N/A N/A N/A Message giving further information on the successful
87 =============================== ======== ======== ======== ======= =====================================================
89 YAML is used for illustrative purposes in the examples in this section. JSON (application/json) is used as the content
90 type in the implementation of this API.
94 The purpose of this API is for PDPs to provide heartbeat, status, health, and statistical information to Policy
95 Administration. There is a single *PDP_STATUS* message on this API. PDPs send this message to the PAP using the
96 *POLICY_PDP_PAP* DMaaP topic. The PAP listens on this topic for messages.
98 When a PDP starts, it commences periodic sending of *PDP_STATUS* messages on DMaaP. The PAP receives these messages and
99 acts in whatever manner is appropriate. *PDP_UPDATE*, *PDP_STATE_CHANGE*, and *PDP_HEALTH_CHECK* operations trigger a
100 *PDP_STATUS* message as a response.
102 The *PDP_STATUS* message is used for PDP heartbeat monitoring. A PDP sends a *PDP_STATUS* message with a state of
103 *TERMINATED* when it terminates normally. If a *PDP_STATUS* message is not received from a PDP periodically or in
104 response to a pdp_update, pdp-state_change, or pdp_health_check message in a certain configurable time, then the PAP
105 assumes the PDP has failed.
107 A PDP may be preconfigured with its PDP group, PDP subgroup, and policies. If the PDP group, subgroup, or any policy
108 sent to the PAP in a *PDP_STATUS* message is unknown to the PAP, the PAP locks the PDP in state PASSIVE.
111 :caption: PDP_STATUS message from an XACML PDP running control loop policies
120 description: XACML PDP running control loop policies
121 pdp_group: onap.pdpgroup.controlloop.operational
123 supported_policy_types:
124 - onap.policies.controlloop.guard.FrequencyLimiter
125 - onap.policies.controlloop.guard.BlackList
126 - onap.policies.controlloop.guard.MinMax
128 - onap.policies.controlloop.guard.frequencylimiter.EastRegion:
129 policy_type: onap.policies.controlloop.guard.FrequencyLimiter
130 policy_type_version: 1.0.0
132 # Omitted for brevity
133 - onap.policies.controlloop.guard.blacklist.eastRegion:
134 policy_type: onap.policies.controlloop.guard.BlackList
135 policy_type_version: 1.0.0
137 # Omitted for brevity
138 - onap.policies.controlloop.guard.minmax.eastRegion:
139 policy_type: onap.policies.controlloop.guard.MinMax
140 policy_type_version: 1.0.0
142 # Omitted for brevity
144 deployment_instance_info:
145 node_address: xacml_1_pod
146 # Other deployment instance info
148 policy_download_count: 0
149 policy_download_success_count: 0
150 policy_download_fail_count: 0
151 policy_executed_count: 123
152 policy_executed_success_count: 122
153 policy_executed_fail_count: 1
156 :caption: PDP_STATUS message from a Drools PDP running control loop policies
165 description: Drools PDP running control loop policies
166 pdp_group: onap.pdpgroup.controlloop.operational
168 supported_policy_types:
169 - onap.controllloop.operational.drools.vCPE
170 - onap.controllloop.operational.drools.vFW
172 - onap.controllloop.operational.drools.vcpe.EastRegion:
173 policy_type: onap.controllloop.operational.drools.vCPE
174 policy_type_version: 1.0.0
176 # Omitted for brevity
177 - onap.controllloop.operational.drools.vfw.EastRegion:
178 policy_type: onap.controllloop.operational.drools.vFW
179 policy_type_version: 1.0.0
181 # Omitted for brevity
183 deployment_instance_info:
184 node_address: drools_2_pod
185 # Other deployment instance info
187 policy_download_count: 3
188 policy_download_success_count: 3
189 policy_download_fail_count: 0
190 policy_executed_count: 123
191 policy_executed_success_count: 122
192 policy_executed_fail_count: 1
194 response_to: PDP_HEALTH_CHECK
195 response_status: SUCCESS
198 :caption: PDP_STATUS message from an APEX PDP running control loop policies
207 description: Drools PDP running control loop policies
208 pdp_group: onap.pdpgroup.controlloop.operational
210 supported_policy_types:
211 - onap.controllloop.operational.drools.vCPE
212 - onap.controllloop.operational.drools.vFW
214 - onap.controllloop.operational.drools.vcpe.EastRegion:
215 policy_type: onap.controllloop.operational.drools.vCPE
216 policy_type_version: 1.0.0
218 # Omitted for brevity
219 - onap.controllloop.operational.drools.vfw.EastRegion:
220 policy_type: onap.controllloop.operational.drools.vFW
221 policy_type_version: 1.0.0
223 # Omitted for brevity
225 deployment_instance_info:
226 node_address: drools_2_pod
227 # Other deployment instance info
229 policy_download_count: 3
230 policy_download_success_count: 3
231 policy_download_fail_count: 0
232 policy_executed_count: 123
233 policy_executed_success_count: 122
234 policy_executed_fail_count: 1
236 response_to: PDP_HEALTH_CHECK
237 response_status: SUCCESS
240 :caption: PDP_STATUS message from an XACML PDP running monitoring policies
249 description: XACML PDP running monitoring policies
250 pdp_group: onap.pdpgroup.Monitoring
252 supported_policy_types:
253 - onap.monitoring.tcagen2
255 - onap.scaleout.tca:message
256 policy_type: onap.policies.monitoring.tcagen2
257 policy_type_version: 1.0.0
259 # Omitted for brevity
261 deployment_instance_info:
262 node_address: xacml_1_pod
263 # Other deployment instance info
265 policy_download_count: 0
266 policy_download_success_count: 0
267 policy_download_fail_count: 0
268 policy_executed_count: 123
269 policy_executed_success_count: 122
270 policy_executed_fail_count: 1
275 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
276 allows the PAP to order health checks to run on PDPs. The PAP sends *PDP_UPDATE*, *PDP_STATE_CHANGE*, and
277 *PDP_HEALTH_CHECK* messages to PDPs using the *POLICY_PAP_PDP* DMaaP topic. PDPs listen on this topic for messages.
279 The PAP can set the scope of *PDP_STATE_CHANGE* and *PDP_HEALTH_CHECK* messages:
281 - PDP Group: If a PDP group is specified in a message, then the PDPs in that PDP group respond to the message and all
282 other PDPs ignore it.
284 - PDP Group and subgroup: If a PDP group and subgroup are specified in a message, then only the PDPs of that subgroup
285 in the PDP group respond to the message and all other PDPs ignore it.
287 - Single PDP: If the name of a PDP is specified in a message, then only that PDP responds to the message and all other
290 Note: *PDP_UPDATE* messages must be issued individually to PDPs because the *PDP_UPDATE* operation can change the PDP
291 group to which a PDP belongs.
296 The *PDP_UPDATE* operation allows the PAP to modify the PDP group to which a PDP belongs and the policies in a PDP.
298 The following examples illustrate how the operation is used.
301 :caption: PDP_UPDATE message to upgrade XACML PDP control loop policies to version 1.0.1
307 description: XACML PDP running control loop policies, Upgraded
308 pdp_group: onap.pdpgroup.controlloop.operational
311 - onap.policies.controlloop.guard.frequencylimiter.EastRegion:
312 policy_type: onap.policies.controlloop.guard.FrequencyLimiter
313 policy_type_version: 1.0.1
315 # Omitted for brevity
316 - onap.policies.controlloop.guard.blackList.EastRegion:
317 policy_type: onap.policies.controlloop.guard.BlackList
318 policy_type_version: 1.0.1
320 # Omitted for brevity
321 - onap.policies.controlloop.guard.minmax.EastRegion:
322 policy_type: onap.policies.controlloop.guard.MinMax
323 policy_type_version: 1.0.1
325 # Omitted for brevity
328 :caption: PDP_UPDATE message to a Drools PDP to add an extra control loop policy
334 description: Drools PDP running control loop policies, extra policy added
335 pdp_group: onap.pdpgroup.controlloop.operational
338 - onap.controllloop.operational.drools.vcpe.EastRegion:
339 policy_type: onap.controllloop.operational.drools.vCPE
340 policy_type_version: 1.0.0
342 # Omitted for brevity
343 - onap.controllloop.operational.drools.vfw.EastRegion:
344 policy_type: onap.controllloop.operational.drools.vFW
345 policy_type_version: 1.0.0
347 # Omitted for brevity
348 - onap.controllloop.operational.drools.vfw.WestRegion:
349 policy_type: onap.controllloop.operational.drools.vFW
350 policy_type_version: 1.0.0
352 # Omitted for brevity
355 :caption: PDP_UPDATE message to an APEX PDP to remove a control loop policy
361 description: APEX PDP updated to remove a control loop policy
362 pdp_group: onap.pdpgroup.controlloop.operational
365 - onap.controllloop.operational.apex.bbs.EastRegion:
366 policy_type: onap.controllloop.operational.apex.BBS
367 policy_type_version: 1.0.0
369 # Omitted for brevity
374 The *PDP_STATE_CHANGE* operation allows the PAP to order state changes on PDPs in PDP groups and subgroups. The
375 following examples illustrate how the operation is used.
378 :caption: Change the state of all control loop Drools PDPs to ACTIVE
383 pdp_group: onap.pdpgroup.controlloop.Operational
387 :caption: Change the state of all monitoring PDPs to SAFE
392 pdp_group: onap.pdpgroup.Monitoring
395 :caption: Change the state of a single APEX PDP to TEST
405 The *PDP_HEALTH_CHECK* operation allows the PAP to order health checks on PDPs in PDP groups and subgroups. The
406 following examples illustrate how the operation is used.
409 :caption: Perform a health check on all control loop Drools PDPs
413 pdp_group: onap.pdpgroup.controlloop.Operational
417 :caption: perform a health check on all monitoring PDPs
421 pdp_group: onap.pdpgroup.Monitoring
424 :caption: Perform a health check on a single APEX PDP