The Internal Policy Framework PAP-PDP API
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 three 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
The fields in the table below are valid on API calls:
Field |
PDP STATUS |
PDP UPDATE |
PDP STATE CHANGE |
Comment |
---|---|---|---|---|
(message_name) |
M |
M |
M |
pdp_status, pdp_update, pdp_state_change, or pdp_health_check |
name |
M |
M |
M |
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 |
pdpType |
M |
N/A |
N/A |
The type of the PDP, currently xacml, drools, or apex |
state |
M |
N/A |
M |
The administrative state of the PDP group: PASSIVE, SAFE, TEST, ACTIVE, or TERMINATED |
healthy |
M |
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 |
The description of the PDP |
pdpGroup |
M |
M |
C |
The PDP group to which the PDP belongs, the PDP group and subgroup can be used to specify the scope of the operation |
pdpSubgroup |
O |
M |
C |
The PDP subgroup to which the PDP belongs, the PDP group and subgroup can be used to specify the scope of the operation |
source |
N/A |
M |
M |
The source of the message |
policies |
M |
N/A |
N/A |
The list of policies running on the PDP |
policiesToBeDeployed |
N/A |
M |
N/A |
The list of policies to be deployed on the PDP |
policiesToBeUndeployed |
N/A |
M |
N/A |
The list of policies to be undeployed from the PDP |
->(name) |
O |
M |
N/A |
The name of a TOSCA policy running on the PDP |
->policy_type |
O |
M |
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 |
The version of the TOSCA policy type of the policy |
->properties |
O |
M |
N/A |
The properties of the policy for the XACML, Drools, or APEX PDP for details Pod |
properties |
O |
N/A |
N/A |
Other properties specific to the PDP |
statistics |
O |
N/A |
N/A |
Statistics on policy execution in the PDP |
->policyDeployCount |
M |
N/A |
N/A |
The number of policies deployed into the PDP |
->policyDeploySuccessCount |
M |
N/A |
N/A |
The number of policies successfully deployed into the PDP |
->policyDeployFailCount |
M |
N/A |
N/A |
The number of policies deployed into the PDP where the deployment failed |
->policyUndeployCount |
M |
N/A |
N/A |
The number of policies undeployed from the PDP |
->policyUndeploySuccessCount |
M |
N/A |
N/A |
The number of policies successfully undeployed from the PDP |
->policyUndeployFailCount |
M |
N/A |
N/A |
The number of policies undeployed from the PDP where the undeployment failed |
->policyExecutedCount |
M |
N/A |
N/A |
The number of policy executions on the PDP |
->policyExecutedSuccessCount |
M |
N/A |
N/A |
The number of policy executions on the PDP that completed successfully |
->policyExecutedFailCount |
M |
N/A |
N/A |
The number of policy executions on the PDP that failed |
response |
O |
N/A |
N/A |
The response to the last operation that the PAP executed on the PDP |
->responseTo |
M |
N/A |
N/A |
The PAP to PDP message to which this is a response |
->responseStatus |
M |
N/A |
N/A |
SUCCESS or FAIL |
->responseMessage |
O |
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 and PDP_STATE_CHANGE 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 or pdp-state_change 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 pdpType: xacml
3 state: ACTIVE
4 healthy: HEALTHY
5 description: XACML PDP running control loop policies
6 policies:
7 - name: SDNC_Policy.ONAP_NF_NAMING_TIMESTAMP
8 version: 1.0.0
9 - name: onap.policies.controlloop.guard.frequencylimiter.EastRegion
10 version: 1.0.0
11 - name: onap.policies.controlloop.guard.blacklist.eastRegion
12 version: 1.0.0
13 - name: .policies.controlloop.guard.minmax.eastRegion
14 version: 1.0.0
15 messageName: PDP_STATUS
16 requestId: 5551bd1b-4020-4fc5-95b7-b89c80a337b1
17 timestampMs: 1633534472002
18 name: xacml-23d33c2a-8715-43a8-ade5-5923fc0f185c
19 pdpGroup: defaultGroup
20 pdpSubgroup: xacml
21 statistics:
22 policyDeployCount: 0
23 policyDeploySuccessCount: 0
24 policyDeployFailCount: 0
25 policyExecutedCount: 123
26 policyExecutedSuccessCount: 122
27 policyExecutedFailCount: 1
1pdp_status:
2 pdpType: drools
3 state: ACTIVE
4 healthy: HEALTHY
5 description: Drools PDP running control loop policies
6 policies:
7 - name: onap.controllloop.operational.drools.vcpe.EastRegion
8 version: 1.0.0
9 - name: onap.controllloop.operational.drools.vfw.EastRegion
10 version: 1.0.0
11 instance: drools_2
12 deployment_instance_info:
13 node_address: drools_2_pod
14 # Other deployment instance info
15 statistics:
16 policyDeployCount: 3
17 policyDeploySuccessCount: 3
18 policyDeployFailCount: 0
19 policyExecutedCount: 123
20 policyExecutedSuccessCount: 122
21 policyExecutedFailCount: 1
22 policyUndeployCount: 0
23 policyUndeploySuccessCount: 0
24 policyUndeployFailCount: 0
25 response:
26 responseTo: 52117e25-f416-45c7-a955-83ed929d557f
27 responseStatus: SUCCESSSS
28 messageName: PDP_STATUS
29 requestId: 52117e25-f416-45c7-a955-83ed929d557f
30 timestampMs: 1633355052181
31 name: drools-8819a672-57fd-4e74-ad89-aed1a64e1837
32 pdpGroup: defaultGroup
33 pdpSubgroup: drools
1 pdpType: apex
2 state: ACTIVE
3 healthy: HEALTHY
4 description: Pdp status response message for PdpUpdate
5 policies:
6 - name: onap.controllloop.operational.apex.bbs.EastRegion
7 version: 1.0.0
8 statistics:
9 policyExecutedCount: 0
10 policyExecutedSuccessCount: 0
11 policyExecutedFailCount: 0
12 policyDeployCount: 1
13 policyDeploySuccessCount: 1
14 policyDeployFailCount: 0
15 policyUndeployCount: 0
16 policyUndeploySuccessCount: 0
17 policyUndeployFailCount: 0
18 response:
19 responseTo: 679fad9b-abbf-4b9b-971c-96a8372ec8af
20 responseStatus: SUCCESS
21 responseMessage: >-
22 Apex engine started. Deployed policies are:
23 onap.policies.apex.sample.Salecheck:1.0.0
24 messageName: PDP_STATUS
25 requestId: 932c17b0-7ef9-44ec-be58-f17e104e7d5d
26 timestampMs: 1633435952217
27 name: apex-d0610cdc-381e-4aae-8e99-3f520c2a50db
28 pdpGroup: defaultGroup
29 pdpSubgroup: apex
1pdp_status:
2 pdpType: xacml
3 state: ACTIVE
4 healthy: HEALTHY
5 description: XACML PDP running control loop policies
6 policies:
7 - name: SDNC_Policy.ONAP_NF_NAMING_TIMESTAMP
8 version: 1.0.0
9 - name: onap.scaleout.tca:message
10 version: 1.0.0
11 messageName: PDP_STATUS
12 requestId: 5551bd1b-4020-4fc5-95b7-b89c80a337b1
13 timestampMs: 1633534472002
14 name: xacml-23d33c2a-8715-43a8-ade5-5923fc0f185c
15 pdpGroup: onap.pdpgroup.Monitoring
16 pdpSubgroup: xacml
17 statistics:
18 policyDeployCount: 0
19 policyDeploySuccessCount: 0
20 policyDeployFailCount: 0
21 policyExecutedCount: 123
22 policyExecutedSuccessCount: 122
23 policyExecutedFailCount: 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. The PAP sends PDP_UPDATE and PDP_STATE_CHANGE 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 message:
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.
2.1 PDP Update
The PDP_UPDATE operation allows the PAP to modify the PDP with information such as policiesToBeDeployed/Undeployed, the interval to send heartbeats, subgroup etc.
The following examples illustrate how the operation is used.
1pdp_update:
2 source: pap-6e46095a-3e12-4838-912b-a8608fc93b51
3 pdpHeartbeatIntervalMs: 120000
4 policiesToBeDeployed:
5 - type: onap.policies.Naming
6 type_version: 1.0.0
7 properties:
8 # Omitted for brevity
9 name: onap.policies.controlloop.guard.frequencylimiter.EastRegion
10 version: 1.0.1
11 metadata:
12 policy-id: onap.policies.controlloop.guard.frequencylimiter.EastRegion
13 policy-version: 1.0.1
14 messageName: PDP_UPDATE
15 requestId: cbfb9781-da6c-462f-9601-8cf8ca959d2b
16 timestampMs: 1633466294898
17 name: xacml-23d33c2a-8715-43a8-ade5-5923fc0f185c
18 description: XACML PDP running control loop policies, Upgraded
19 pdpGroup: defaultGroup
20 pdpSubgroup: xacml
1pdp_update:
2 source: pap-0674bd0c-0862-4b72-abc7-74246fd11a79
3 pdpHeartbeatIntervalMs: 120000
4 policiesToBeDeployed:
5 - type: onap.controllloop.operational.drools.vFW
6 type_version: 1.0.0
7 properties:
8 # Omitted for brevity
9 name: onap.controllloop.operational.drools.vfw.WestRegion
10 version: 1.0.0
11 metadata:
12 policy-id: onap.controllloop.operational.drools.vfw.WestRegion
13 policy-version: 1.0.0
14 messageName: PDP_UPDATE
15 requestId: e91c4515-86db-4663-b68e-e5179d0b000e
16 timestampMs: 1633355039004
17 name: drools-8819a672-57fd-4e74-ad89-aed1a64e1837
18 description: Drools PDP running control loop policies, extra policy added
19 pdpGroup: defaultGroup
20 pdpSubgroup: drools
1pdp_update:
2 source: pap-56c8531d-5376-4e53-a820-6973c62bfb9a
3 pdpHeartbeatIntervalMs: 120000
4 policiesToBeDeployed:
5 - type: onap.policies.native.Apex
6 type_version: 1.0.0
7 properties:
8 # Omitted for brevity
9 name: onap.controllloop.operational.apex.bbs.WestRegion
10 version: 1.0.0
11 metadata:
12 policy-id: onap.controllloop.operational.apex.bbs.WestRegion
13 policy-version: 1.0.0
14 messageName: PDP_UPDATE
15 requestId: 3534e54f-4432-4c68-81c8-a6af07e59fb2
16 timestampMs: 1632325037040
17 name: apex-45c6b266-a5fa-4534-b22c-33c2f9a45d02
18 pdpGroup: defaultGroup
19 pdpSubgroup: apex
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 source: pap-6e46095a-3e12-4838-912b-a8608fc93b51
3 state: ACTIVE
4 messageName: PDP_STATE_CHANGE
5 requestId: 7d422be6-5baa-4316-9649-09e18301b5a8
6 timestampMs: 1633466294899
7 name: drools-23d33c2a-8715-43a8-ade5-5923fc0f185c
8 pdpGroup: defaultGroup
9 pdpSubgroup: drools
1pdp_state_change:
2 source: pap-6e46095a-3e12-4838-912b-a8608fc93b51
3 state: ACTIVE
4 messageName: PDP_STATE_CHANGE
5 requestId: 7d422be6-5baa-4316-9649-09e18301b5a8
6 timestampMs: 1633466294899
7 name: xacml-23d33c2a-8715-43a8-ade5-5923fc0f185c
8 pdpGroup: defaultGroup
9 pdpSubgroup: xacml
1pdp_state_change:
2 source: pap-e6272159-e1a3-4777-860a-19c47a14cc00
3 state: PASSIVE
4 messageName: PDP_STATE_CHANGE
5 requestId: 60d9a724-ebf3-4434-9da4-caac9c515a2c
6 timestampMs: 1633528747518
7 name: apex-a3c58a9e-af72-436c-b46f-0c6f31032ca5
8 pdpGroup: defaultGroup
9 pdpSubgroup: apex