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 (PAP) Architecture
   7 ##############################################
   8
   9 .. contents::
  10     :depth: 3
  11
  12 The PAP keeps track of PDPs, supporting the deployment of PDP groups and the deployment of a *policy set* across those
  13 PDP groups. Policies are created using the Policy API, but are deployed via the PAP.
  14
  15 A PAP is stateless in a RESTful sense, using the database (persistent storage) to track PDPs and the deployment of
  16 policies to those PDPs. In short, policy management on PDPs is the responsibility of PAPs; management of policy sets or
  17 policies by any other manner is not permitted.
  18
  19 Because the PDP is the main unit of scalability in the Policy Framework, the framework is designed to allow PDPs in a
  20 PDP group to arbitrarily appear and disappear and for policy consistency across all PDPs in a PDP group to be easily
  21 maintained. The PAP is responsible for controlling the state across the PDPs in a PDP group. The PAP interacts with the
  22 Policy database and transfers policy sets to PDPs.
  23
  24 There are a number of rules for PDP group and PDP state management:
  25
  26 1. Only one version of a PDP group may be ACTIVE at any time
  27
  28 2. If a PDP group with a certain version is ACTIVE and a later version   of the same PDP group is activated, then the
  29    system upgrades the PDP group
  30
  31 3. If a PDP group with a certain version is ACTIVE and an earlier version of the same PDP group is activated, then the
  32    system downgrades the PDP group
  33
  34 4. There is no restriction on the number of PASSIVE versions of a PDP group that can exist in the system
  35
  36
  37 1 APIs
  38 ======
  39 The APIs in the subchapters below are supported by the PAP.
  40
  41 1.1 REST API
  42 ------------
  43
  44 The purpose of this API is to support CRUD of PDP groups and subgroups and to support the deployment and life cycles of
  45 policies on PDP sub groups and PDPs. This API is provided by the *PolicyAdministration* component (PAP) of the Policy
  46 Framework, see the :ref:`ONAP Policy Framework Architecture <architecture-label>` page.
  47
  48 PDP groups and subgroups may be prefedined in the system. Predefined groups and subgroups may be modified or deleted
  49 over this API. The policies running on predefined groups or subgroups as well as the instance counts and properties may
  50 also be modified.
  51
  52 A PDP may be preconfigured with its PDP group, PDP subgroup, and policies. The PDP sends this information to the PAP
  53 when it starts. If the PDP group, subgroup, or any policy is unknown to the PAP, the PAP locks the PDP in state PASSIVE.
  54
  55 PAP supports the operations listed in the following table, via its REST API:
  56
  57 .. csv-table::
  58    :header: "Operation", "Description"
  59    :widths: 25,70
  60
  61    "Health check", "Queries the health of the PAP"
  62    "Statistics", "Queries various statistics"
  63    "PDP state change", "Changes the state of all PDPs in a PDP Group"
  64    "PDP Group create/update", "Creates/updates PDP Groups"
  65    "PDP Group delete", "Deletes a PDP Group"
  66    "PDP Group query", "Queries all PDP Groups"
  67    "Deploy policy", "Deploys one or more policies to the PDPs"
  68    "Undeploy policy", "Undeploys a policy from the PDPs"
  69
  70 1.2 DMaaP API
  71 -------------
  72
  73 PAP interacts with the PDPs via the DMaaP Message Router.  The messages listed
  74 in the following table are transmitted via DMaaP:
  75
  76 .. csv-table::
  77    :header: "Message", "Direction", "Description"
  78    :widths: 25,10,70
  79
  80    "PDP status", "Incoming", "Registers a PDP with PAP; also sent as a periodic heart beat; also sent in response to requests from the PAP"
  81    "PDP update", "Outgoing", "Assigns a PDP to a PDP Group and Subgroup; also deploys or undeploys policies from the PDP"
  82    "PDP state change", "Outgoing", "Changes the state of a PDP or all PDPs within a PDP Group or Subgroup"
  83
  84
  85 2 PAP REST API Swagger
  86 ======================
  87
  88 It is worth noting that we use basic authorization for access with user name and password set to *healthcheck* and
  89 *zb!XztG34*, respectively.
  90
  91 For every call, the client is encouraged to insert a uuid-type *requestID* as parameter. It is helpful for tracking each
  92 http transaction and facilitates debugging. More importantly, it complies with Logging requirements v1.2. If the client
  93 does not provide the requestID in a call, one will be randomly generated and attached to the response header,
  94 *x-onap-requestid*.
  95
  96 In accordance with `ONAP API Common Versioning Strategy Guidelines
  97 <https://wiki.onap.org/display/DW/ONAP+API+Common+Versioning+Strategy+%28CVS%29+Guidelines>`_, several custom headers
  98 are added in the response to each call:
  99
 100 .. csv-table::
 101    :header: "Header", "Example value", "Description"
 102    :widths: 25,10,70
 103
 104    "x-latestversion", "1.0.0", "latest version of the API"
 105    "x-minorversion", "0", "MINOR version of the API"
 106    "x-patchversion", "0", "PATCH version of the API"
 107    "x-onap-requestid", "e1763e61-9eef-4911-b952-1be1edd9812b", "described above; used for logging purposes"
 108
 109
 110 .. swaggerv2doc:: swagger/health-check-pap.json
 111
 112 This operation performs a health check on the PAP.
 113
 114 Here is a sample response:
 115
 116 .. literalinclude:: response/health-check-pap-resp.json
 117     :language: json
 118
 119 .. swaggerv2doc:: swagger/statistics-pap.json
 120
 121 This operation allows statistics for PDP groups, PDP subgroups, and individual PDPs to be retrieved.
 122
 123 .. note::
 124   While this API is supported, most of the statistics are not currently updated; that work has been deferred to a later
 125   release.
 126
 127 Here is a sample response:
 128
 129 .. literalinclude:: response/statistics-pap-resp.json
 130     :language: json
 131
 132 .. swaggerv2doc:: swagger/state-change-pap.json
 133
 134 The state of PDP groups is managed by this operation. PDP groups can be in states PASSIVE, TEST, SAFE, or ACTIVE. For a full
 135 description of PDP group states, see the :ref:`ONAP Policy Framework Architecture <architecture-label>` page.
 136
 137 .. swaggerv2doc:: swagger/group-pap.json
 138
 139 This operation allows the PDP groups and subgroups to be created and updated. Many PDP groups can be created or updated
 140 in a single POST operation by specifying more than one PDP group in the POST operation body.
 141
 142 .. note::
 143   Due to current limitations, if a subgroup is to be deleted from a PDP Group, then the policies must be removed from
 144   the subgroup in one request, and then the subgroup deleted in a subsequent request.
 145
 146 Here is a sample request:
 147
 148 .. literalinclude:: request/group-pap-req.json
 149     :language: json
 150
 151 .. swaggerv2doc:: swagger/group-delete-pap.json
 152
 153 The API also allows PDP groups to be deleted. DELETE operations are only permitted on PDP groups in PASSIVE state.
 154
 155 .. swaggerv2doc:: swagger/group-query-pap.json
 156
 157 This operation allows the PDP groups and subgroups to be listed as well as the policies that are deployed on each PDP
 158 group and subgroup.
 159
 160 Here is a sample response:
 161
 162 .. literalinclude:: response/group-query-pap-resp.json
 163     :language: json
 164
 165 .. swaggerv2doc:: swagger/policy-deploy-pap.json
 166
 167 This operation allows policies to be deployed on PDP groups.
 168
 169 .. note::
 170   The policy version is optional.  If left unspecified, then the latest version of the policy is deployed. On the other
 171   hand, if it is specified, it may be an integer, or it may be a fully qualified version (e.g., "3.0.2").
 172
 173 Here is a sample request:
 174
 175 .. literalinclude:: request/policy-deploy-pap-req.json
 176     :language: json
 177
 178 .. swaggerv2doc:: swagger/policy-undeploy-pap.json
 179
 180 This operation allows policies to be undeployed from PDP groups.
 181
 182 .. note::
 183   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").
 184   On the other hand, if left unspecified, then the latest deployed version will be undeployed.
 185
 186 .. note::
 187   Due to current limitations, a fully qualified policy version must always be specified.
 188
 189 3 Future Features
 190 =================
 191
 192 3.1 Order Health Check on PDPs
 193 ==============================
 194
 195 This operation will allow a PDP group health check to be ordered on PDP groups and on individual PDPs. The operation
 196 will return a HTTP status code of *202: Accepted* if the health check request has been accepted by the PAP. The PAP will
 197 then order execution of the health check on the PDPs.
 198
 199 As health checks may be long lived operations, Health checks will be scheduled for execution by this operation. Users
 200 will check the result of a health check test by issuing a PDP Group Query operation and checking the *healthy* field of
 201 PDPs.
 202
 203
 204 End of Document