docs/pap/pap.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3
   4 .. _pap-label:
   5
   6 Policy Administration Point API
   7 ###############################
   8
   9 .. contents::
  10     :depth: 3
  11
  12 .. toctree::
  13    InternalPapPdp.rst
  14
  15 Policy Administration Point (PAP) Architecture
  16 ==============================================
  17
  18 The Policy Administration Point (PAP) keeps track of PDPs, supporting the deployment of PDP groups and the deployment
  19 of policies across those PDP groups. Policies are created using the Policy API, but are deployed via the PAP.
  20
  21 The PAP is stateless in a RESTful sense, using the database (persistent storage) to track PDPs and the deployment of
  22 policies to those PDPs. In short, policy management on PDPs is the responsibility of PAP; management of policies by
  23 any other manner is not permitted.
  24
  25 Because the PDP is the main unit of scalability in the Policy Framework, the framework is designed to allow PDPs in a
  26 PDP group to arbitrarily appear and disappear and for policy consistency across all PDPs in a PDP group to be easily
  27 maintained. The PAP is responsible for controlling the state across the PDPs in a PDP group. The PAP interacts with the
  28 policy database and transfers policies to PDPs.
  29
  30 The unit of execution and scaling in the Policy Framework is a *PolicyImpl* entity. A *PolicyImpl* entity runs on a PDP.
  31 As is explained above, a *PolicyImpl* entity is a *PolicyTypeImpl* implementation parameterized with a TOSCA *Policy*.
  32
  33 .. image:: images/PolicyImplPDPSubGroup.svg
  34
  35 In order to achieve horizontal scalability, we group the PDPs running instances of a given *PolicyImpl* entity logically
  36 together into a *PDPSubGroup*. The number of PDPs in a *PDPSubGroup* can then be scaled up and down using Kubernetes. In
  37 other words, all PDPs in a subgroup run the same *PolicyImpl*, that is the same policy template implementation (in
  38 XACML, Drools, or APEX) with the same parameters.
  39
  40 The figure above shows the layout of *PDPGroup* and *PDPSubGroup* entities. The figure shows examples of PDP groups for
  41 Control Loop and Monitoring policies on the right.
  42
  43 The health of PDPs is monitored by the PAP in order to alert operations teams managing policies. The PAP manages the life
  44 cycle of policies running on PDPs.
  45
  46 The table below shows the deployment methods in which *PolicyImpl* entities can be deployed to PDP Subgroups.
  47
  48 ========== =========================================== ============================== ==================================
  49 **Method** **Description**                             **Advantages**                 **Disadvantages**
  50 ========== =========================================== ============================== ==================================
  51 Cold       The *PolicyImpl* (*PolicyTypeImpl* and      No run time configuration      Very restrictive, no run time
  52            TOSCA *Policy*) are predeployed on the PDP. required and run time          configuration of PDPs is possible.
  53            PDP is fully configured and ready to        administration is simple.
  54            execute when started.
  55
  56            PDPs register with the PAP when they
  57            start, providing the *pdpGroup* they
  58            have been preconfigured with.
  59
  60 Warm       The *PolicyTypeImpl* entity is predeployed  The configuration, parameters, Administration and management is
  61            on the PDP. A TOSCA *Policy* may be loaded  and PDP group of PDPs may be   required. The configuration and
  62            at startup. The PDP may be configured or    changed at run time by loading life cycle of the TOSCA policies
  63            reconfigured with a new or updated TOSCA    or updating a TOSCA *Policy*   can change at run time and must be
  64            *Policy* at run time.                       into the PDP.                  administered and managed.
  65
  66            PDPs register with the PAP when they start, Support TOSCA *Policy* entity
  67            providing the *pdpGroup* they have been     life cycle managgement is
  68            predeployed with if any. The PAP may update supported, allowing features
  69            the TOSCA *Policy* on a PDP at any time     such as *PolicyImpl* Safe Mode
  70            after registration.                         and *PolicyImpl* retirement.
  71
  72 Hot        The *PolicyImpl* (*PolicyTypeImpl* and      The policy logic, rules,       Administration and management is
  73            TOSCA *Policy*) are deployed at run time.   configuration, parameters, and more complex. The *PolicyImpl*
  74            The *PolicyImpl* (*PolicyTypeImpl* and      PDP group of PDPs may be       itself and its configuration and
  75            TOSCA *Policy*) may be loaded at startup.   changed at run time by loading life cycle as well as the life
  76            The PDP may be configured or reconfigured   or updating a TOSCA *Policy*   cycle of the TOSCA policies can
  77            with a new or updated *PolicyTypeImpl*      and *PolicyTypeImpl* into the  change at run time and must be
  78            and/or TOSCA *Policy* at run time.          PDP.                           administered and managed.
  79
  80            PDPs register with the PAP when they        Lifecycle management of TOSCA
  81            start, providing the *pdpGroup* they have   *Policy* entities and
  82            been preconfigured with if any. The PAP may *PolicyTypeImpl* entites is
  83            update the TOSCA *Policy* and               supported, allowing features
  84            *PolicyTypeImpl* on a PDP at any time after such as *PolicyImpl* Safe Mode
  85            registration                                and *PolicyImpl* retirement.
  86 ========== =========================================== ============================== ==================================
  87
  88
  89 1 APIs
  90 ======
  91 The APIs in the subchapters below are supported by the PAP.
  92
  93 1.1 REST API
  94 ------------
  95
  96 The purpose of this API is to support CRUD of PDP groups and subgroups and to support the deployment and life cycles of
  97 policies on PDP sub groups and PDPs. This API is provided by the *PolicyAdministration* component (PAP) of the Policy
  98 Framework, see the :ref:`ONAP Policy Framework Architecture <architecture-label>` page.
  99
 100 PDP groups and subgroups may be prefedined in the system. Predefined groups and subgroups may be modified or deleted
 101 over this API. The policies running on predefined groups or subgroups as well as the instance counts and properties may
 102 also be modified.
 103
 104 A PDP may be preconfigured with its PDP group, PDP subgroup, and policies. The PDP sends this information to the PAP
 105 when it starts. If the PDP group, subgroup, or any policy is unknown to the PAP, the PAP locks the PDP in state PASSIVE.
 106
 107 PAP supports the operations listed in the following table, via its REST API:
 108
 109 .. csv-table::
 110    :header: "Operation", "Description"
 111    :widths: 25,70
 112
 113    "Health check", "Queries the health of the PAP"
 114    "Consolidated healthcheck", "Queries the health of all policy components"
 115    "Statistics", "Queries various statistics"
 116    "PDP state change", "Changes the state of all PDPs in a PDP Group"
 117    "PDP Group create/update", "Creates/updates PDP Groups"
 118    "PDP Group delete", "Deletes a PDP Group"
 119    "PDP Group query", "Queries all PDP Groups"
 120    "Deployment update", "Deploy/undeploy one or more policies in specified PdpGroups"
 121    "Deploy policy", "Deploys one or more policies to the PDPs"
 122    "Undeploy policy", "Undeploys a policy from the PDPs"
 123    "Policy Status", "Queries the status of all policies"
 124    "Policy deployment status", "Queries the status of all deployed policies"
 125    "PDP statistics", "Queries the statistics of PDPs"
 126    "Policy Audit", "Queries the audit records of policies"
 127
 128 1.2 DMaaP API
 129 -------------
 130
 131 PAP interacts with the PDPs via the DMaaP Message Router.  The messages listed
 132 in the following table are transmitted via DMaaP:
 133
 134 .. csv-table::
 135    :header: "Message", "Direction", "Description"
 136    :widths: 25,10,70
 137
 138    "PDP status", "Incoming", "Registers a PDP with PAP; also sent as a periodic heart beat; also sent in response to requests from the PAP"
 139    "PDP update", "Outgoing", "Assigns a PDP to a PDP Group and Subgroup; also deploys or undeploys policies from the PDP"
 140    "PDP state change", "Outgoing", "Changes the state of a PDP or all PDPs within a PDP Group or Subgroup"
 141
 142 In addition, PAP generates notifications via the DMaaP Message Router when policies are successfully or unsuccessfully
 143 deployed (or undeployed) from all relevant PDPs.
 144
 145 Here is a sample notification:
 146
 147 .. literalinclude:: notification/dmaap-pap-notif.json
 148     :language: json
 149
 150
 151 2 PAP REST API Swagger
 152 ======================
 153
 154 It is worth noting that we use basic authorization for access with user name and password set to *policyadmin* and
 155 *zb!XztG34*, respectively.
 156
 157 For every call, the client is encouraged to insert a uuid-type *requestID* as parameter. It is helpful for tracking each
 158 http transaction and facilitates debugging. More importantly, it complies with Logging requirements v1.2. If the client
 159 does not provide the requestID in a call, one will be randomly generated and attached to the response header,
 160 *x-onap-requestid*.
 161
 162 In accordance with `ONAP API Common Versioning Strategy Guidelines
 163 <https://wiki.onap.org/display/DW/ONAP+API+Common+Versioning+Strategy+%28CVS%29+Guidelines>`_, several custom headers
 164 are added in the response to each call:
 165
 166 .. csv-table::
 167    :header: "Header", "Example value", "Description"
 168    :widths: 25,10,70
 169
 170    "x-latestversion", "1.0.0", "latest version of the API"
 171    "x-minorversion", "0", "MINOR version of the API"
 172    "x-patchversion", "0", "PATCH version of the API"
 173    "x-onap-requestid", "e1763e61-9eef-4911-b952-1be1edd9812b", "described above; used for logging purposes"
 174
 175 .. csv-table::
 176    :header: "/healthcheck"
 177    :widths: 10
 178
 179    `Health Check PAP Swagger <./local-swagger.html#tag/HealthCheckRestControllerV1>`_
 180
 181 This operation performs a health check on the PAP.
 182
 183 Here is a sample response:
 184
 185 .. literalinclude:: response/health-check-pap-resp.json
 186     :language: json
 187
 188 .. csv-table::
 189    :header: "/pdps/healthcheck"
 190    :widths: 10
 191
 192    `Consolidated Health Check PAP Swagger <./local-swagger.html#tag/PolicyComponentsHealthCheckControllerV1>`_
 193
 194 This operation performs a health check of all policy components. The response
 195 contains the health check result of each component. The consolidated health check
 196 is reported as healthy only if all the components are healthy, otherwise the
 197 "healthy" flag is marked as false.
 198
 199 Here is a sample response:
 200
 201 .. literalinclude:: response/consolidated-healthcheck-pap-resp.json
 202     :language: json
 203
 204 .. csv-table::
 205    :header: "/statistics"
 206    :widths: 10
 207
 208    `Statistics PAP Swagger <./local-swagger.html#tag/StatisticsRestControllerV1>`_
 209
 210 This operation allows statistics for PDP groups, PDP subgroups, and individual PDPs to be retrieved.
 211
 212 .. note::
 213   While this API is supported, most of the statistics are not currently updated; that work has been deferred to a later
 214   release.
 215
 216 Here is a sample response:
 217
 218 .. literalinclude:: response/statistics-pap-resp.json
 219     :language: json
 220
 221 .. csv-table::
 222    :header: "/pdps/groups/{name}"
 223    :widths: 10
 224
 225    `PDP State Change PAP Swagger <./local-swagger.html#tag/PdpGroupStateChangeControllerV1>`_
 226
 227 The state of PDP groups is managed by this operation. PDP groups can be in states PASSIVE, TEST, SAFE, or ACTIVE. For a full
 228 description of PDP group states, see the :ref:`ONAP Policy Framework Architecture <architecture-label>` page.
 229
 230 .. csv-table::
 231    :header: "/pdps/groups/batch"
 232    :widths: 10
 233
 234    `Group Batch PAP Swagger <./local-swagger.html#tag/PdpGroupCreateOrUpdateControllerV1>`_
 235
 236 This operation allows the PDP groups and subgroups to be created and updated. Many PDP groups can be created or updated
 237 in a single POST operation by specifying more than one PDP group in the POST operation body.
 238 This can be used to create the PDP group by providing all the details including the supported policy types for each subgroup.
 239 However, it cannot be used to update policies; that is done using one of
 240 the deployment requests.  Consequently, the "policies" property of this
 241 request will be ignored.
 242 This can also be used to update a PDP Group, but supported policy types cannot be updated during the update operation.
 243 So, "policies" and "supportedPolicyTypes" properties in the request will be ignored if provided during the PDP Group update operation.
 244
 245 The "desiredInstanceCount" specifies the minimum number of PDPs of the given
 246 type that should be registered with PAP.  Currently, this is just used for
 247 health check purposes; if the number of PDPs registered with PAP drops below
 248 the given value, then PAP will return an "unhealthy" indicator if a
 249 "Consolidated Health Check" is performed.
 250
 251 .. note::
 252   If a subgroup is to be deleted from a PDP Group, then the policies must be removed from
 253   the subgroup first.
 254
 255 .. note::
 256   Policies cannot be added/updated during PDP Group create/update operations. So, if provided, they are ignored.
 257   Supported policy types are defined during PDP Group creation. They cannot be updated once they are created.
 258   So, supportedPolicyTypes are expected during PDP Group create, but ignored if provided during PDP Group update.
 259
 260 Here is a sample request:
 261
 262 .. literalinclude:: request/groups-batch-pap-req.json
 263     :language: json
 264
 265 .. csv-table::
 266    :header: "/pdps/groups/{name}"
 267    :widths: 10
 268
 269    `PdpGroup Delete PAP Swagger <./local-swagger.html#tag/PdpGroupDeleteControllerV1>`_
 270
 271 The API also allows PDP groups to be deleted. DELETE operations are only permitted on PDP groups in PASSIVE state.
 272
 273 .. csv-table::
 274    :header: "/pdps"
 275    :widths: 10
 276
 277    `PdpGroup Query PAP Swagger <./local-swagger.html#tag/PdpGroupQueryControllerV1>`_
 278
 279 This operation allows the PDP groups and subgroups to be listed as well as the policies that are deployed on each PDP
 280 group and subgroup.
 281
 282 Here is a sample response:
 283
 284 .. literalinclude:: response/group-query-pap-resp.json
 285     :language: json
 286
 287 .. csv-table::
 288    :header: "/pdps/deployments/batch"
 289    :widths: 10
 290
 291    `Deployments Update PAP Swagger <./local-swagger.html#tag/PdpGroupDeployControllerV1>`_
 292
 293 This operation allows policies to be deployed on specific PDP groups.
 294 Each subgroup includes an "action" property, which is used to indicate
 295 that the policies are being added (POST) to the subgroup, deleted (DELETE)
 296 from the subgroup, or that the subgroup's entire set of policies is being
 297 replaced (PATCH) by a new set of policies.  As such, a subgroup may appear
 298 more than once in a single request, one time to delete some policies and
 299 another time to add new policies to the same subgroup.
 300
 301 Here is a sample request:
 302
 303 .. literalinclude:: request/deployment-batch-pap-req.json
 304     :language: json
 305
 306 Here is a sample response:
 307
 308 .. literalinclude:: response/deployment-pap-resp.json
 309     :language: json
 310
 311 .. csv-table::
 312    :header: "/pdps/policies"
 313    :widths: 10
 314
 315    `Deploy PAP Swagger <./local-swagger.html#operation/deployPolicies>`_
 316
 317 This operation allows policies to be deployed across all relevant PDP groups.
 318 PAP will deploy the specified policies to all relevant subgroups.  Only the
 319 policies supported by a given subgroup will be deployed to that subgroup.
 320
 321 .. note::
 322   The policy version is optional.  If left unspecified, then the latest version of the policy is deployed. On the other
 323   hand, if it is specified, it may be an integer, or it may be a fully qualified version (e.g., "3.0.2").
 324   In addition, a subgroup to which a policy is being deployed must have at
 325   least one PDP instance, otherwise the request will be rejected.
 326
 327 Here is a sample request:
 328
 329 .. literalinclude:: request/policy-deploy-pap-req.json
 330     :language: json
 331
 332 Here is a sample response:
 333
 334 .. literalinclude:: response/deployment-pap-resp.json
 335     :language: json
 336
 337 .. csv-table::
 338    :header: "/pdps/policies/{name}"
 339    :widths: 10
 340
 341    `Undeploy PAP Swagger <./local-swagger.html#operation/deletePolicy>`_
 342
 343 This operation allows policies to be undeployed from PDP groups.
 344
 345 .. note::
 346   If the policy version is specified, then it may be an integer, or it may be a fully qualified version (e.g., "3.0.2").
 347   On the other hand, if left unspecified, then the latest deployed version will be undeployed.
 348
 349 .. note::
 350   Due to current limitations, a fully qualified policy version must always be specified.
 351
 352 Here is a sample response:
 353
 354 .. literalinclude:: response/deployment-pap-resp.json
 355     :language: json
 356
 357 .. csv-table::
 358    :header: "/policies/status"
 359    :widths: 10
 360
 361    `All Policy Status PAP Swagger <./local-swagger.html#operation/getStatusOfAllPolicies>`_
 362
 363
 364 This operation allows the status of all policies that are deployed or undeployed to be listed together.
 365 The result can be filtered based on pdp group name, policy name & version.
 366
 367 .. note::
 368   When a policy is successfully undeployed, it will no longer appear in the policy status response.
 369
 370 Here is a sample response:
 371
 372 .. literalinclude:: response/policy-status-pap-resp.json
 373     :language: json
 374
 375 .. csv-table::
 376    :header: "/policies/deployed"
 377    :widths: 10
 378
 379    `Deployed Policy Status PAP Swagger <./local-swagger.html#operation/queryAllDeployedPolicies>`_
 380
 381 This operation allows the deployed policies to be listed together with their respective deployment status.
 382 The result can be filtered based on policy name & version.
 383
 384 Here is a sample response:
 385
 386 .. literalinclude:: response/deployed-policy-pap-resp.json
 387     :language: json
 388
 389 .. csv-table::
 390    :header: "/pdps/statistics"
 391    :widths: 10
 392
 393    `Policy Statistics PAP Swagger <./local-swagger.html#tag/StatisticsRestControllerV1>`_
 394
 395 This operation allows the PDP statistics to be retrieved for all registered PDPs.
 396 The result can be filtered based on PDP group, PDP subgroup & PDP instance.
 397 Along with record count, start time & end time as query parameters.
 398
 399 Here is a sample response:
 400
 401 .. literalinclude:: response/pdp-statistics-pap-resp.json
 402     :language: json
 403
 404 .. csv-table::
 405    :header: "/policies/audit"
 406    :widths: 10
 407
 408    `Policy Status PAP Swagger <./local-swagger.html#tag/PolicyAuditControllerV1>`_
 409
 410 This operation allows the audit records of policies to be listed together.
 411 The result can be filtered based on pdp group name, policy name & version.
 412 Along with record count, start time & end time as query parameters.
 413
 414 Here is a sample response:
 415
 416 .. literalinclude:: response/policy-audit-pap-resp.json
 417     :language: json
 418
 419 3 Configuration
 420 =================
 421
 422 The *PolicyAdministration* component (PAP) is initialized using a configuration file: `papParameters.yaml
 423 <https://github.com/onap/policy-pap/blob/master/packages/policy-pap-tarball/src/main/resources/etc/papParameters.yaml>`_
 424
 425 The configuration file is a YAML file containing the relevant fields for configuring the REST server, Database and DMaaP connectivity and so on.
 426
 427 3.1 Disable collection of PDP Statistics
 428 ========================================
 429
 430 This configuration is to inform PAP to not save the PDP statistics in the database.
 431
 432 In *papParameters.yaml*, add or change the property savePdpStatisticsInDb to false.
 433
 434 .. note::
 435   By default, if the property is not present, it will be considered as false and
 436   PDP statistics will not be saved in the database.
 437
 438 End of Document