The Internal Policy Framework PAP-PDP API¶
Contents
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:
PDP_STATUS: PDP→PAP, used by PDPs to report to the PAP
PDP_UPDATE: PAP→PDP, used by the PAP to update the policies running on PDPs, triggers a PDP_STATUS message with the result of the PDP_UPDATE operation
PDP_STATE_CHANGE: PAP→PDP, used by the PAP to change the state of PDPs, triggers a PDP_STATUS message with the result of the PDP_STATE_CHANGE operation
PDP_HEALTH_CHECK: PAP→PDP, used by the PAP to order a 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 STATUS |
PDP UPDATE |
PDP STATE CHANGE |
PDP HEALTH CHECK |
Comment |
---|---|---|---|---|---|
(message_name) |
M |
M |
M |
M |
pdp_status, pdp_update, pdp_state_change, or pdp_health_check |
name |
M |
M |
C |
C |
The name of the PDP, for state changes and health checks, the PDP group and subgroup can be used to specify the scope of the operation |
version |
M |
N/A |
N/A |
N/A |
The version of the PDP |
pdp_type |
M |
M |
N/A |
N/A |
The type of the PDP, currently xacml, drools, or apex |
state |
M |
N/A |
M |
N/A |
The administrative state of the PDP group: PASSIVE, SAFE, TEST, ACTIVE, or TERMINATED |
healthy |
M |
N/A |
N/A |
N/A |
The result of the latest health check on the PDP: HEALTHY/NOT_HEALTHY/TEST_IN_PROGRESS |
description |
O |
O |
N/A |
N/A |
The description of the PDP |
pdp_group |
O |
M |
C |
C |
The PDP group to which the PDP belongs, the PDP group and subgroup can be used to specify the scope of the operation |
pdp_subgroup |
O |
M |
C |
C |
The PDP subgroup to which the PDP belongs, the PDP group and subgroup can be used to specify the scope of the operation |
supported_policy_types |
M |
N/A |
N/A |
N/A |
A list of the policy types supported by the PDP |
policies |
O |
M |
N/A |
N/A |
The list of policies running on the PDP |
->(name) |
O |
M |
N/A |
N/A |
The name of a TOSCA policy running on the PDP |
->policy_type |
O |
M |
N/A |
N/A |
The TOSCA policy type of the policyWhen a PDP starts, it commences periodic sending of PDP_STATUS messages on DMaaP. The PAP receives these messages and acts in whatever manner is appropriate. |
->policy_type_version |
O |
M |
N/A |
N/A |
The version of the TOSCA policy type of the policy |
->properties |
O |
M |
N/A |
N/A |
The properties of the policy for the XACML, Drools, or APEX PDP 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.
1pdp_status:
2 name: xacml_1
3 version: 1.2.3
4 pdp_type: xacml
5 state: active
6 healthy: true
7 description: XACML PDP running control loop policies
8 pdp_group: onap.pdpgroup.controlloop.operational
9 pdp_subgroup: xacml
10 supported_policy_types:
11 - onap.policies.controlloop.guard.FrequencyLimiter
12 - onap.policies.controlloop.guard.BlackList
13 - onap.policies.controlloop.guard.MinMax
14 policies:
15 - onap.policies.controlloop.guard.frequencylimiter.EastRegion:
16 policy_type: onap.policies.controlloop.guard.FrequencyLimiter
17 policy_type_version: 1.0.0
18 properties:
19 # Omitted for brevity
20 - onap.policies.controlloop.guard.blacklist.eastRegion:
21 policy_type: onap.policies.controlloop.guard.BlackList
22 policy_type_version: 1.0.0
23 properties:
24 # Omitted for brevity
25 - onap.policies.controlloop.guard.minmax.eastRegion:
26 policy_type: onap.policies.controlloop.guard.MinMax
27 policy_type_version: 1.0.0
28 properties:
29 # Omitted for brevity
30 instance: xacml_1
31 deployment_instance_info:
32 node_address: xacml_1_pod
33 # Other deployment instance info
34 statistics:
35 policy_download_count: 0
36 policy_download_success_count: 0
37 policy_download_fail_count: 0
38 policy_executed_count: 123
39 policy_executed_success_count: 122
40 policy_executed_fail_count: 1
1pdp_status:
2 name: drools_2
3 version: 2.3.4
4 pdp_type: drools
5 state: safe
6 healthy: true
7 description: Drools PDP running control loop policies
8 pdp_group: onap.pdpgroup.controlloop.operational
9 pdp_subgroup: drools
10 supported_policy_types:
11 - onap.controllloop.operational.drools.vCPE
12 - onap.controllloop.operational.drools.vFW
13 policies:
14 - onap.controllloop.operational.drools.vcpe.EastRegion:
15 policy_type: onap.controllloop.operational.drools.vCPE
16 policy_type_version: 1.0.0
17 properties:
18 # Omitted for brevity
19 - onap.controllloop.operational.drools.vfw.EastRegion:
20 policy_type: onap.controllloop.operational.drools.vFW
21 policy_type_version: 1.0.0
22 properties:
23 # Omitted for brevity
24 instance: drools_2
25 deployment_instance_info:
26 node_address: drools_2_pod
27 # Other deployment instance info
28 statistics:
29 policy_download_count: 3
30 policy_download_success_count: 3
31 policy_download_fail_count: 0
32 policy_executed_count: 123
33 policy_executed_success_count: 122
34 policy_executed_fail_count: 1
35 response:
36 response_to: PDP_HEALTH_CHECK
37 response_status: SUCCESS
1pdp_status:
2 name: drools_2
3 version: 2.3.4
4 pdp_type: drools
5 state: safe
6 healthy: true
7 description: Drools PDP running control loop policies
8 pdp_group: onap.pdpgroup.controlloop.operational
9 pdp_subgroup: drools
10 supported_policy_types:
11 - onap.controllloop.operational.drools.vCPE
12 - onap.controllloop.operational.drools.vFW
13 policies:
14 - onap.controllloop.operational.drools.vcpe.EastRegion:
15 policy_type: onap.controllloop.operational.drools.vCPE
16 policy_type_version: 1.0.0
17 properties:
18 # Omitted for brevity
19 - onap.controllloop.operational.drools.vfw.EastRegion:
20 policy_type: onap.controllloop.operational.drools.vFW
21 policy_type_version: 1.0.0
22 properties:
23 # Omitted for brevity
24 instance: drools_2
25 deployment_instance_info:
26 node_address: drools_2_pod
27 # Other deployment instance info
28 statistics:
29 policy_download_count: 3
30 policy_download_success_count: 3
31 policy_download_fail_count: 0
32 policy_executed_count: 123
33 policy_executed_success_count: 122
34 policy_executed_fail_count: 1
35 response:
36 response_to: PDP_HEALTH_CHECK
37 response_status: SUCCESS
1pdp_status:
2 name: xacml_1
3 version: 1.2.3
4 pdp_type: xacml
5 state: active
6 healthy: true
7 description: XACML PDP running monitoring policies
8 pdp_group: onap.pdpgroup.Monitoring
9 pdp_subgroup: xacml
10 supported_policy_types:
11 - onap.monitoring.tcagen2
12 policies:
13 - onap.scaleout.tca:message
14 policy_type: onap.policies.monitoring.tcagen2
15 policy_type_version: 1.0.0
16 properties:
17 # Omitted for brevity
18 instance: xacml_1
19 deployment_instance_info:
20 node_address: xacml_1_pod
21 # Other deployment instance info
22 statistics:
23 policy_download_count: 0
24 policy_download_success_count: 0
25 policy_download_fail_count: 0
26 policy_executed_count: 123
27 policy_executed_success_count: 122
28 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.
1pdp_update:
2 name: xacml_1
3 pdp_type: xacml
4 description: XACML PDP running control loop policies, Upgraded
5 pdp_group: onap.pdpgroup.controlloop.operational
6 pdp_subgroup: xacml
7 policies:
8 - onap.policies.controlloop.guard.frequencylimiter.EastRegion:
9 policy_type: onap.policies.controlloop.guard.FrequencyLimiter
10 policy_type_version: 1.0.1
11 properties:
12 # Omitted for brevity
13 - onap.policies.controlloop.guard.blackList.EastRegion:
14 policy_type: onap.policies.controlloop.guard.BlackList
15 policy_type_version: 1.0.1
16 properties:
17 # Omitted for brevity
18 - onap.policies.controlloop.guard.minmax.EastRegion:
19 policy_type: onap.policies.controlloop.guard.MinMax
20 policy_type_version: 1.0.1
21 properties:
22 # Omitted for brevity
1pdp_update:
2 name: drools_2
3 pdp_type: drools
4 description: Drools PDP running control loop policies, extra policy added
5 pdp_group: onap.pdpgroup.controlloop.operational
6 pdp_subgroup: drools
7 policies:
8 - onap.controllloop.operational.drools.vcpe.EastRegion:
9 policy_type: onap.controllloop.operational.drools.vCPE
10 policy_type_version: 1.0.0
11 properties:
12 # Omitted for brevity
13 - onap.controllloop.operational.drools.vfw.EastRegion:
14 policy_type: onap.controllloop.operational.drools.vFW
15 policy_type_version: 1.0.0
16 properties:
17 # Omitted for brevity
18 - onap.controllloop.operational.drools.vfw.WestRegion:
19 policy_type: onap.controllloop.operational.drools.vFW
20 policy_type_version: 1.0.0
21 properties:
22 # Omitted for brevity
1 pdp_update:
2 name: apex_3
3 pdp_type: apex
4 description: APEX PDP updated to remove a control loop policy
5 pdp_group: onap.pdpgroup.controlloop.operational
6 pdp_subgroup: apex
7 policies:
8 - onap.controllloop.operational.apex.bbs.EastRegion:
9 policy_type: onap.controllloop.operational.apex.BBS
10 policy_type_version: 1.0.0
11 properties:
12 # 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.
1pdp_state_change:
2 state: active
3 pdp_group: onap.pdpgroup.controlloop.Operational
4 pdp_subgroup: drools
1pdp_state_change:
2 state: safe
3 pdp_group: onap.pdpgroup.Monitoring
1pdp_state_change:
2 state: test
3 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.
1pdp_health_check:
2 pdp_group: onap.pdpgroup.controlloop.Operational
3 pdp_subgroup: drools
1pdp_health_check:
2 pdp_group: onap.pdpgroup.Monitoring
1pdp_health_check:
2 name: apex_3