blob: 132e0df1dbf26a28d5fa72599df36b643ea6b743 [file] [log] [blame]
.. This work is licensed under a
.. Creative Commons Attribution 4.0 International License.
.. http://creativecommons.org/licenses/by/4.0
.. _pap-pdp-label:
The Internal Policy Framework PAP-PDP API
#########################################
.. contents::
:depth: 3
This page describes the API between the PAP and PDPs. The APIs in this section are implemented using `DMaaP
API <https://wiki.onap.org/display/DW/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: PDPPAP, used by PDPs to report to the PAP
2. PDP_UPDATE: PAPPDP, 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: PAPPDP, 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 **PDP **PDP **Comment**
STATUS** UPDATE** STATE
CHANGE**
=============================== ======== ======== ======== =====================================================
(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.
.. code-block:: yaml
:caption: PDP_STATUS message from an XACML PDP running control loop policies
:linenos:
pdp_status:
pdpType: xacml
state: ACTIVE
healthy: HEALTHY
description: XACML PDP running control loop policies
policies:
- name: SDNC_Policy.ONAP_NF_NAMING_TIMESTAMP
version: 1.0.0
- name: onap.policies.controlloop.guard.frequencylimiter.EastRegion
version: 1.0.0
- name: onap.policies.controlloop.guard.blacklist.eastRegion
version: 1.0.0
- name: .policies.controlloop.guard.minmax.eastRegion
version: 1.0.0
messageName: PDP_STATUS
requestId: 5551bd1b-4020-4fc5-95b7-b89c80a337b1
timestampMs: 1633534472002
name: xacml-23d33c2a-8715-43a8-ade5-5923fc0f185c
pdpGroup: defaultGroup
pdpSubgroup: xacml
statistics:
policyDeployCount: 0
policyDeploySuccessCount: 0
policyDeployFailCount: 0
policyExecutedCount: 123
policyExecutedSuccessCount: 122
policyExecutedFailCount: 1
.. code-block:: yaml
:caption: PDP_STATUS message from a Drools PDP running control loop policies
:linenos:
pdp_status:
pdpType: drools
state: ACTIVE
healthy: HEALTHY
description: Drools PDP running control loop policies
policies:
- name: onap.controllloop.operational.drools.vcpe.EastRegion
version: 1.0.0
- name: onap.controllloop.operational.drools.vfw.EastRegion
version: 1.0.0
instance: drools_2
deployment_instance_info:
node_address: drools_2_pod
# Other deployment instance info
statistics:
policyDeployCount: 3
policyDeploySuccessCount: 3
policyDeployFailCount: 0
policyExecutedCount: 123
policyExecutedSuccessCount: 122
policyExecutedFailCount: 1
policyUndeployCount: 0
policyUndeploySuccessCount: 0
policyUndeployFailCount: 0
response:
responseTo: 52117e25-f416-45c7-a955-83ed929d557f
responseStatus: SUCCESSSS
messageName: PDP_STATUS
requestId: 52117e25-f416-45c7-a955-83ed929d557f
timestampMs: 1633355052181
name: drools-8819a672-57fd-4e74-ad89-aed1a64e1837
pdpGroup: defaultGroup
pdpSubgroup: drools
.. code-block:: yaml
:caption: PDP_STATUS message from an APEX PDP running control loop policies
:linenos:
pdpType: apex
state: ACTIVE
healthy: HEALTHY
description: Pdp status response message for PdpUpdate
policies:
- name: onap.controllloop.operational.apex.bbs.EastRegion
version: 1.0.0
statistics:
policyExecutedCount: 0
policyExecutedSuccessCount: 0
policyExecutedFailCount: 0
policyDeployCount: 1
policyDeploySuccessCount: 1
policyDeployFailCount: 0
policyUndeployCount: 0
policyUndeploySuccessCount: 0
policyUndeployFailCount: 0
response:
responseTo: 679fad9b-abbf-4b9b-971c-96a8372ec8af
responseStatus: SUCCESS
responseMessage: >-
Apex engine started. Deployed policies are:
onap.policies.apex.sample.Salecheck:1.0.0
messageName: PDP_STATUS
requestId: 932c17b0-7ef9-44ec-be58-f17e104e7d5d
timestampMs: 1633435952217
name: apex-d0610cdc-381e-4aae-8e99-3f520c2a50db
pdpGroup: defaultGroup
pdpSubgroup: apex
.. code-block:: yaml
:caption: PDP_STATUS message from an XACML PDP running monitoring policies
:linenos:
pdp_status:
pdpType: xacml
state: ACTIVE
healthy: HEALTHY
description: XACML PDP running control loop policies
policies:
- name: SDNC_Policy.ONAP_NF_NAMING_TIMESTAMP
version: 1.0.0
- name: onap.scaleout.tca:message
version: 1.0.0
messageName: PDP_STATUS
requestId: 5551bd1b-4020-4fc5-95b7-b89c80a337b1
timestampMs: 1633534472002
name: xacml-23d33c2a-8715-43a8-ade5-5923fc0f185c
pdpGroup: onap.pdpgroup.Monitoring
pdpSubgroup: xacml
statistics:
policyDeployCount: 0
policyDeploySuccessCount: 0
policyDeployFailCount: 0
policyExecutedCount: 123
policyExecutedSuccessCount: 122
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.
.. code-block:: yaml
:caption: PDP_UPDATE message to upgrade XACML PDP control loop policies to version 1.0.1
:linenos:
pdp_update:
source: pap-6e46095a-3e12-4838-912b-a8608fc93b51
pdpHeartbeatIntervalMs: 120000
policiesToBeDeployed:
- type: onap.policies.Naming
type_version: 1.0.0
properties:
# Omitted for brevity
name: onap.policies.controlloop.guard.frequencylimiter.EastRegion
version: 1.0.1
metadata:
policy-id: onap.policies.controlloop.guard.frequencylimiter.EastRegion
policy-version: 1.0.1
messageName: PDP_UPDATE
requestId: cbfb9781-da6c-462f-9601-8cf8ca959d2b
timestampMs: 1633466294898
name: xacml-23d33c2a-8715-43a8-ade5-5923fc0f185c
description: XACML PDP running control loop policies, Upgraded
pdpGroup: defaultGroup
pdpSubgroup: xacml
.. code-block:: yaml
:caption: PDP_UPDATE message to a Drools PDP to add an extra control loop policy
:linenos:
pdp_update:
source: pap-0674bd0c-0862-4b72-abc7-74246fd11a79
pdpHeartbeatIntervalMs: 120000
policiesToBeDeployed:
- type: onap.controllloop.operational.drools.vFW
type_version: 1.0.0
properties:
# Omitted for brevity
name: onap.controllloop.operational.drools.vfw.WestRegion
version: 1.0.0
metadata:
policy-id: onap.controllloop.operational.drools.vfw.WestRegion
policy-version: 1.0.0
messageName: PDP_UPDATE
requestId: e91c4515-86db-4663-b68e-e5179d0b000e
timestampMs: 1633355039004
name: drools-8819a672-57fd-4e74-ad89-aed1a64e1837
description: Drools PDP running control loop policies, extra policy added
pdpGroup: defaultGroup
pdpSubgroup: drools
.. code-block:: yaml
:caption: PDP_UPDATE message to an APEX PDP to remove a control loop policy
:linenos:
pdp_update:
source: pap-56c8531d-5376-4e53-a820-6973c62bfb9a
pdpHeartbeatIntervalMs: 120000
policiesToBeDeployed:
- type: onap.policies.native.Apex
type_version: 1.0.0
properties:
# Omitted for brevity
name: onap.controllloop.operational.apex.bbs.WestRegion
version: 1.0.0
metadata:
policy-id: onap.controllloop.operational.apex.bbs.WestRegion
policy-version: 1.0.0
messageName: PDP_UPDATE
requestId: 3534e54f-4432-4c68-81c8-a6af07e59fb2
timestampMs: 1632325037040
name: apex-45c6b266-a5fa-4534-b22c-33c2f9a45d02
pdpGroup: defaultGroup
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.
.. code-block:: yaml
:caption: Change the state of Drools PDP to ACTIVE
:linenos:
pdp_state_change:
source: pap-6e46095a-3e12-4838-912b-a8608fc93b51
state: ACTIVE
messageName: PDP_STATE_CHANGE
requestId: 7d422be6-5baa-4316-9649-09e18301b5a8
timestampMs: 1633466294899
name: drools-23d33c2a-8715-43a8-ade5-5923fc0f185c
pdpGroup: defaultGroup
pdpSubgroup: drools
.. code-block:: yaml
:caption: Change the state of all XACML PDPs to ACTIVE
:linenos:
pdp_state_change:
source: pap-6e46095a-3e12-4838-912b-a8608fc93b51
state: ACTIVE
messageName: PDP_STATE_CHANGE
requestId: 7d422be6-5baa-4316-9649-09e18301b5a8
timestampMs: 1633466294899
name: xacml-23d33c2a-8715-43a8-ade5-5923fc0f185c
pdpGroup: defaultGroup
pdpSubgroup: xacml
.. code-block:: yaml
:caption: Change the state of APEX PDP to passive
:linenos:
pdp_state_change:
source: pap-e6272159-e1a3-4777-860a-19c47a14cc00
state: PASSIVE
messageName: PDP_STATE_CHANGE
requestId: 60d9a724-ebf3-4434-9da4-caac9c515a2c
timestampMs: 1633528747518
name: apex-a3c58a9e-af72-436c-b46f-0c6f31032ca5
pdpGroup: defaultGroup
pdpSubgroup: apex