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:

  1. PDP_STATUS: PDP→PAP, used by PDPs to report to the PAP

  2. 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

  3. 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.

PDP_STATUS message from an XACML PDP running control loop policies
 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
PDP_STATUS message from a Drools PDP running control loop policies
 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
PDP_STATUS message from an APEX PDP running control loop policies
 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
PDP_STATUS message from an XACML PDP running monitoring policies
 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.

PDP_UPDATE message to upgrade XACML PDP control loop policies to version 1.0.1
 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
PDP_UPDATE message to a Drools PDP to add an extra control loop policy
 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
PDP_UPDATE message to an APEX PDP to remove a control loop policy
 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.

Change the state of Drools PDP to ACTIVE
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
Change the state of all XACML PDPs to ACTIVE
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
Change the state of APEX PDP to passive
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