docs/pap/InternalPapPdp.rst

   1 .. This work is licensed under a
   2 .. Creative Commons Attribution 4.0 International License.
   3 .. http://creativecommons.org/licenses/by/4.0
   4
   5 .. _pap-pdp-label:
   6
   7 The Internal Policy Framework PAP-PDP API
   8 #########################################
   9
  10 .. contents::
  11     :depth: 3
  12
  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.
  17
  18 There are three messages on the API:
  19
  20 1. PDP_STATUS: PDP→PAP, used by PDPs to report to the PAP
  21
  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
  24
  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
  27
  28
  29 The fields in the table below are valid on API calls:
  30
  31 =============================== ======== ======== ======== =====================================================
  32 **Field**                       **PDP    **PDP    **PDP    **Comment**
  33                                 STATUS** UPDATE** STATE
  34                                                   CHANGE**
  35 =============================== ======== ======== ======== =====================================================
  36 (message_name)                  M        M        M        pdp_status, pdp_update, pdp_state_change, or
  37                                                            pdp_health_check
  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
  49                                                            operation
  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
  52                                                            of the operation
  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
  65                                                            Pod
  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
  70                                                            the PDP
  71 ->policyDeployFailCount         M        N/A      N/A      The number of policies deployed into the PDP where
  72                                                            the deployment failed
  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
  75                                                            the PDP
  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
  82                                                            failed
  83 response                        O        N/A      N/A      The response to the last operation that the PAP
  84                                                            executed on the PDP
  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
  88                                                            or failed operation
  89 =============================== ======== ======== ======== =====================================================
  90
  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.
  93
  94 1 PAP API for PDPs
  95 ==================
  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.
  99
 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.
 103
 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.
 108
 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.
 111
 112 .. code-block:: yaml
 113   :caption: PDP_STATUS message from an XACML PDP running control loop policies
 114   :linenos:
 115
 116   pdp_status:
 117     pdpType: xacml
 118     state: ACTIVE
 119     healthy: HEALTHY
 120     description: XACML PDP running control loop policies
 121     policies:
 122       - name: SDNC_Policy.ONAP_NF_NAMING_TIMESTAMP
 123         version: 1.0.0
 124       - name: onap.policies.controlloop.guard.frequencylimiter.EastRegion
 125         version: 1.0.0
 126       - name: onap.policies.controlloop.guard.blacklist.eastRegion
 127         version: 1.0.0
 128       - name: .policies.controlloop.guard.minmax.eastRegion
 129         version: 1.0.0
 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
 135     pdpSubgroup: xacml
 136     statistics:
 137       policyDeployCount: 0
 138       policyDeploySuccessCount: 0
 139       policyDeployFailCount: 0
 140       policyExecutedCount: 123
 141       policyExecutedSuccessCount: 122
 142       policyExecutedFailCount: 1
 143
 144
 145 .. code-block:: yaml
 146   :caption: PDP_STATUS message from a Drools PDP running control loop policies
 147   :linenos:
 148
 149   pdp_status:
 150     pdpType: drools
 151     state: ACTIVE
 152     healthy: HEALTHY
 153     description: Drools PDP running control loop policies
 154     policies:
 155       - name: onap.controllloop.operational.drools.vcpe.EastRegion
 156         version: 1.0.0
 157       - name: onap.controllloop.operational.drools.vfw.EastRegion
 158         version: 1.0.0
 159     instance: drools_2
 160     deployment_instance_info:
 161       node_address: drools_2_pod
 162       # Other deployment instance info
 163     statistics:
 164       policyDeployCount: 3
 165       policyDeploySuccessCount: 3
 166       policyDeployFailCount: 0
 167       policyExecutedCount: 123
 168       policyExecutedSuccessCount: 122
 169       policyExecutedFailCount: 1
 170       policyUndeployCount: 0
 171       policyUndeploySuccessCount: 0
 172       policyUndeployFailCount: 0
 173     response:
 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
 181     pdpSubgroup: drools
 182
 183 .. code-block:: yaml
 184   :caption: PDP_STATUS message from an APEX PDP running control loop policies
 185   :linenos:
 186
 187     pdpType: apex
 188     state: ACTIVE
 189     healthy: HEALTHY
 190     description: Pdp status response message for PdpUpdate
 191     policies:
 192       - name: onap.controllloop.operational.apex.bbs.EastRegion
 193         version: 1.0.0
 194     statistics:
 195       policyExecutedCount: 0
 196       policyExecutedSuccessCount: 0
 197       policyExecutedFailCount: 0
 198       policyDeployCount: 1
 199       policyDeploySuccessCount: 1
 200       policyDeployFailCount: 0
 201       policyUndeployCount: 0
 202       policyUndeploySuccessCount: 0
 203       policyUndeployFailCount: 0
 204     response:
 205       responseTo: 679fad9b-abbf-4b9b-971c-96a8372ec8af
 206       responseStatus: SUCCESS
 207       responseMessage: >-
 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
 215     pdpSubgroup: apex
 216
 217
 218 .. code-block:: yaml
 219   :caption: PDP_STATUS message from an XACML PDP running monitoring policies
 220   :linenos:
 221
 222   pdp_status:
 223     pdpType: xacml
 224     state: ACTIVE
 225     healthy: HEALTHY
 226     description: XACML PDP running control loop policies
 227     policies:
 228       - name: SDNC_Policy.ONAP_NF_NAMING_TIMESTAMP
 229         version: 1.0.0
 230       - name: onap.scaleout.tca:message
 231         version: 1.0.0
 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
 237     pdpSubgroup: xacml
 238     statistics:
 239       policyDeployCount: 0
 240       policyDeploySuccessCount: 0
 241       policyDeployFailCount: 0
 242       policyExecutedCount: 123
 243       policyExecutedSuccessCount: 122
 244       policyExecutedFailCount: 1
 245
 246
 247 2 PDP API for PAPs
 248 ==================
 249
 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.
 253
 254 The PAP can set the scope of *PDP_STATE_CHANGE* message:
 255
 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.
 258
 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.
 261
 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
 263    PDPs ignore it.
 264
 265
 266 2.1 PDP Update
 267 --------------
 268
 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.
 271
 272 The following examples illustrate how the operation is used.
 273
 274 .. code-block:: yaml
 275   :caption: PDP_UPDATE message to upgrade XACML PDP control loop policies to version 1.0.1
 276   :linenos:
 277
 278   pdp_update:
 279     source: pap-6e46095a-3e12-4838-912b-a8608fc93b51
 280     pdpHeartbeatIntervalMs: 120000
 281     policiesToBeDeployed:
 282       - type: onap.policies.Naming
 283         type_version: 1.0.0
 284         properties:
 285           # Omitted for brevity
 286         name: onap.policies.controlloop.guard.frequencylimiter.EastRegion
 287         version: 1.0.1
 288         metadata:
 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
 297     pdpSubgroup: xacml
 298
 299
 300 .. code-block:: yaml
 301   :caption: PDP_UPDATE message to a Drools PDP to add an extra control loop policy
 302   :linenos:
 303
 304   pdp_update:
 305     source: pap-0674bd0c-0862-4b72-abc7-74246fd11a79
 306     pdpHeartbeatIntervalMs: 120000
 307     policiesToBeDeployed:
 308       - type: onap.controllloop.operational.drools.vFW
 309         type_version: 1.0.0
 310         properties:
 311           # Omitted for brevity
 312         name: onap.controllloop.operational.drools.vfw.WestRegion
 313         version: 1.0.0
 314         metadata:
 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
 323     pdpSubgroup: drools
 324
 325
 326 .. code-block:: yaml
 327   :caption: PDP_UPDATE message to an APEX PDP to remove a control loop policy
 328   :linenos:
 329
 330   pdp_update:
 331     source: pap-56c8531d-5376-4e53-a820-6973c62bfb9a
 332     pdpHeartbeatIntervalMs: 120000
 333     policiesToBeDeployed:
 334       - type: onap.policies.native.Apex
 335         type_version: 1.0.0
 336         properties:
 337           # Omitted for brevity
 338         name: onap.controllloop.operational.apex.bbs.WestRegion
 339         version: 1.0.0
 340         metadata:
 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
 348     pdpSubgroup: apex
 349
 350 2.2 PDP State Change
 351 --------------------
 352
 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.
 355
 356 .. code-block:: yaml
 357   :caption: Change the state of Drools PDP to ACTIVE
 358   :linenos:
 359
 360   pdp_state_change:
 361     source: pap-6e46095a-3e12-4838-912b-a8608fc93b51
 362     state: ACTIVE
 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
 368     pdpSubgroup: drools
 369
 370 .. code-block:: yaml
 371   :caption: Change the state of all XACML PDPs to ACTIVE
 372   :linenos:
 373
 374   pdp_state_change:
 375     source: pap-6e46095a-3e12-4838-912b-a8608fc93b51
 376     state: ACTIVE
 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
 382     pdpSubgroup: xacml
 383
 384 .. code-block:: yaml
 385   :caption: Change the state of APEX PDP to passive
 386   :linenos:
 387
 388   pdp_state_change:
 389     source: pap-e6272159-e1a3-4777-860a-19c47a14cc00
 390     state: PASSIVE
 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
 396     pdpSubgroup: apex