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 three 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
29 The fields in the table below are valid on API calls:
31 =============================== ======== ======== ======== =====================================================
32 **Field** **PDP **PDP **PDP **Comment**
33 STATUS** UPDATE** STATE
35 =============================== ======== ======== ======== =====================================================
36 (message_name) M M M pdp_status, pdp_update, pdp_state_change, or
38 name M M M The name of the PDP, for state changes and health
39 checks, the PDP group and subgroup can be used to
40 specify the scope of the operation
41 pdpType M N/A N/A The type of the PDP, currently xacml, drools, or apex
42 state M N/A M The administrative state of the PDP group: PASSIVE,
43 SAFE, TEST, ACTIVE, or TERMINATED
44 healthy M N/A N/A The result of the latest health check on the PDP:
45 HEALTHY/NOT_HEALTHY/TEST_IN_PROGRESS
46 description O O N/A The description of the PDP
47 pdpGroup M M C The PDP group to which the PDP belongs, the PDP group
48 and subgroup can be used to specify the scope of the
50 pdpSubgroup O M C The PDP subgroup to which the PDP belongs, the PDP
51 group and subgroup can be used to specify the scope
53 source N/A M M The source of the message
54 policies M N/A N/A The list of policies running on the PDP
55 policiesToBeDeployed N/A M N/A The list of policies to be deployed on the PDP
56 policiesToBeUndeployed N/A M N/A The list of policies to be undeployed from the PDP
57 ->(name) O M N/A The name of a TOSCA policy running on the PDP
58 ->policy_type O M N/A The TOSCA policy type of the policyWhen a PDP starts,
59 it commences periodic sending of *PDP_STATUS*
60 messages on DMaaP. The PAP receives these messages
61 and acts in whatever manner is appropriate.
62 ->policy_type_version O M N/A The version of the TOSCA policy type of the policy
63 ->properties O M N/A The properties of the policy for the XACML, Drools,
64 or APEX PDP for details
66 properties O N/A N/A Other properties specific to the PDP
67 statistics O N/A N/A Statistics on policy execution in the PDP
68 ->policyDeployCount M N/A N/A The number of policies deployed into the PDP
69 ->policyDeploySuccessCount M N/A N/A The number of policies successfully deployed into
71 ->policyDeployFailCount M N/A N/A The number of policies deployed into the PDP where
73 ->policyUndeployCount M N/A N/A The number of policies undeployed from the PDP
74 ->policyUndeploySuccessCount M N/A N/A The number of policies successfully undeployed from
76 ->policyUndeployFailCount M N/A N/A The number of policies undeployed from the PDP where
77 the undeployment failed
78 ->policyExecutedCount M N/A N/A The number of policy executions on the PDP
79 ->policyExecutedSuccessCount M N/A N/A The number of policy executions on the PDP that
80 completed successfully
81 ->policyExecutedFailCount M N/A N/A The number of policy executions on the PDP that
83 response O N/A N/A The response to the last operation that the PAP
85 ->responseTo M N/A N/A The PAP to PDP message to which this is a response
86 ->responseStatus M N/A N/A SUCCESS or FAIL
87 ->responseMessage O 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* and *PDP_STATE_CHANGE* 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 or pdp-state_change 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
120 description: XACML PDP running control loop policies
122 - name: SDNC_Policy.ONAP_NF_NAMING_TIMESTAMP
124 - name: onap.policies.controlloop.guard.frequencylimiter.EastRegion
126 - name: onap.policies.controlloop.guard.blacklist.eastRegion
128 - name: .policies.controlloop.guard.minmax.eastRegion
130 messageName: PDP_STATUS
131 requestId: 5551bd1b-4020-4fc5-95b7-b89c80a337b1
132 timestampMs: 1633534472002
133 name: xacml-23d33c2a-8715-43a8-ade5-5923fc0f185c
134 pdpGroup: defaultGroup
138 policyDeploySuccessCount: 0
139 policyDeployFailCount: 0
140 policyExecutedCount: 123
141 policyExecutedSuccessCount: 122
142 policyExecutedFailCount: 1
146 :caption: PDP_STATUS message from a Drools PDP running control loop policies
153 description: Drools PDP running control loop policies
155 - name: onap.controllloop.operational.drools.vcpe.EastRegion
157 - name: onap.controllloop.operational.drools.vfw.EastRegion
160 deployment_instance_info:
161 node_address: drools_2_pod
162 # Other deployment instance info
165 policyDeploySuccessCount: 3
166 policyDeployFailCount: 0
167 policyExecutedCount: 123
168 policyExecutedSuccessCount: 122
169 policyExecutedFailCount: 1
170 policyUndeployCount: 0
171 policyUndeploySuccessCount: 0
172 policyUndeployFailCount: 0
174 responseTo: 52117e25-f416-45c7-a955-83ed929d557f
175 responseStatus: SUCCESSSS
176 messageName: PDP_STATUS
177 requestId: 52117e25-f416-45c7-a955-83ed929d557f
178 timestampMs: 1633355052181
179 name: drools-8819a672-57fd-4e74-ad89-aed1a64e1837
180 pdpGroup: defaultGroup
184 :caption: PDP_STATUS message from an APEX PDP running control loop policies
190 description: Pdp status response message for PdpUpdate
192 - name: onap.controllloop.operational.apex.bbs.EastRegion
195 policyExecutedCount: 0
196 policyExecutedSuccessCount: 0
197 policyExecutedFailCount: 0
199 policyDeploySuccessCount: 1
200 policyDeployFailCount: 0
201 policyUndeployCount: 0
202 policyUndeploySuccessCount: 0
203 policyUndeployFailCount: 0
205 responseTo: 679fad9b-abbf-4b9b-971c-96a8372ec8af
206 responseStatus: SUCCESS
208 Apex engine started. Deployed policies are:
209 onap.policies.apex.sample.Salecheck:1.0.0
210 messageName: PDP_STATUS
211 requestId: 932c17b0-7ef9-44ec-be58-f17e104e7d5d
212 timestampMs: 1633435952217
213 name: apex-d0610cdc-381e-4aae-8e99-3f520c2a50db
214 pdpGroup: defaultGroup
219 :caption: PDP_STATUS message from an XACML PDP running monitoring policies
226 description: XACML PDP running control loop policies
228 - name: SDNC_Policy.ONAP_NF_NAMING_TIMESTAMP
230 - name: onap.scaleout.tca:message
232 messageName: PDP_STATUS
233 requestId: 5551bd1b-4020-4fc5-95b7-b89c80a337b1
234 timestampMs: 1633534472002
235 name: xacml-23d33c2a-8715-43a8-ade5-5923fc0f185c
236 pdpGroup: onap.pdpgroup.Monitoring
240 policyDeploySuccessCount: 0
241 policyDeployFailCount: 0
242 policyExecutedCount: 123
243 policyExecutedSuccessCount: 122
244 policyExecutedFailCount: 1
250 The purpose of this API is for the PAP to load and update policies on PDPs and to change the state of PDPs.
251 The PAP sends *PDP_UPDATE* and *PDP_STATE_CHANGE* messages to PDPs using the *POLICY_PAP_PDP* DMaaP topic.
252 PDPs listen on this topic for messages.
254 The PAP can set the scope of *PDP_STATE_CHANGE* message:
256 - PDP Group: If a PDP group is specified in a message, then the PDPs in that PDP group respond to the message and all
257 other PDPs ignore it.
259 - PDP Group and subgroup: If a PDP group and subgroup are specified in a message, then only the PDPs of that subgroup
260 in the PDP group respond to the message and all other PDPs ignore it.
262 - Single PDP: If the name of a PDP is specified in a message, then only that PDP responds to the message and all other
269 The *PDP_UPDATE* operation allows the PAP to modify the PDP with information such as policiesToBeDeployed/Undeployed,
270 the interval to send heartbeats, subgroup etc.
272 The following examples illustrate how the operation is used.
275 :caption: PDP_UPDATE message to upgrade XACML PDP control loop policies to version 1.0.1
279 source: pap-6e46095a-3e12-4838-912b-a8608fc93b51
280 pdpHeartbeatIntervalMs: 120000
281 policiesToBeDeployed:
282 - type: onap.policies.Naming
285 # Omitted for brevity
286 name: onap.policies.controlloop.guard.frequencylimiter.EastRegion
289 policy-id: onap.policies.controlloop.guard.frequencylimiter.EastRegion
290 policy-version: 1.0.1
291 messageName: PDP_UPDATE
292 requestId: cbfb9781-da6c-462f-9601-8cf8ca959d2b
293 timestampMs: 1633466294898
294 name: xacml-23d33c2a-8715-43a8-ade5-5923fc0f185c
295 description: XACML PDP running control loop policies, Upgraded
296 pdpGroup: defaultGroup
301 :caption: PDP_UPDATE message to a Drools PDP to add an extra control loop policy
305 source: pap-0674bd0c-0862-4b72-abc7-74246fd11a79
306 pdpHeartbeatIntervalMs: 120000
307 policiesToBeDeployed:
308 - type: onap.controllloop.operational.drools.vFW
311 # Omitted for brevity
312 name: onap.controllloop.operational.drools.vfw.WestRegion
315 policy-id: onap.controllloop.operational.drools.vfw.WestRegion
316 policy-version: 1.0.0
317 messageName: PDP_UPDATE
318 requestId: e91c4515-86db-4663-b68e-e5179d0b000e
319 timestampMs: 1633355039004
320 name: drools-8819a672-57fd-4e74-ad89-aed1a64e1837
321 description: Drools PDP running control loop policies, extra policy added
322 pdpGroup: defaultGroup
327 :caption: PDP_UPDATE message to an APEX PDP to remove a control loop policy
331 source: pap-56c8531d-5376-4e53-a820-6973c62bfb9a
332 pdpHeartbeatIntervalMs: 120000
333 policiesToBeDeployed:
334 - type: onap.policies.native.Apex
337 # Omitted for brevity
338 name: onap.controllloop.operational.apex.bbs.WestRegion
341 policy-id: onap.controllloop.operational.apex.bbs.WestRegion
342 policy-version: 1.0.0
343 messageName: PDP_UPDATE
344 requestId: 3534e54f-4432-4c68-81c8-a6af07e59fb2
345 timestampMs: 1632325037040
346 name: apex-45c6b266-a5fa-4534-b22c-33c2f9a45d02
347 pdpGroup: defaultGroup
353 The *PDP_STATE_CHANGE* operation allows the PAP to order state changes on PDPs in PDP groups and subgroups. The
354 following examples illustrate how the operation is used.
357 :caption: Change the state of Drools PDP to ACTIVE
361 source: pap-6e46095a-3e12-4838-912b-a8608fc93b51
363 messageName: PDP_STATE_CHANGE
364 requestId: 7d422be6-5baa-4316-9649-09e18301b5a8
365 timestampMs: 1633466294899
366 name: drools-23d33c2a-8715-43a8-ade5-5923fc0f185c
367 pdpGroup: defaultGroup
371 :caption: Change the state of all XACML PDPs to ACTIVE
375 source: pap-6e46095a-3e12-4838-912b-a8608fc93b51
377 messageName: PDP_STATE_CHANGE
378 requestId: 7d422be6-5baa-4316-9649-09e18301b5a8
379 timestampMs: 1633466294899
380 name: xacml-23d33c2a-8715-43a8-ade5-5923fc0f185c
381 pdpGroup: defaultGroup
385 :caption: Change the state of APEX PDP to passive
389 source: pap-e6272159-e1a3-4777-860a-19c47a14cc00
391 messageName: PDP_STATE_CHANGE
392 requestId: 60d9a724-ebf3-4434-9da4-caac9c515a2c
393 timestampMs: 1633528747518
394 name: apex-a3c58a9e-af72-436c-b46f-0c6f31032ca5
395 pdpGroup: defaultGroup