1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
2 .. http://creativecommons.org/licenses/by/4.0
6 Policy Administration Point API
7 ###############################
15 Policy Administration Point (PAP) Architecture
16 ==============================================
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.
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.
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.
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*.
33 .. image:: images/PolicyImplPDPSubGroup.svg
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.
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.
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.
46 The table below shows the deployment methods in which *PolicyImpl* entities can be deployed to PDP Subgroups.
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.
56 PDPs register with the PAP when they
57 start, providing the *pdpGroup* they
58 have been preconfigured with.
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.
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.
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.
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 ========== =========================================== ============================== ==================================
91 The APIs in the subchapters below are supported by the PAP.
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.
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
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.
107 PAP supports the operations listed in the following table, via its REST API:
110 :header: "Operation", "Description"
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 "Policy Audit", "Queries the audit records of policies"
130 PAP interacts with the PDPs via the kafka interface. The messages listed
131 in the following table are transmitted via Kafka:
134 :header: "Message", "Direction", "Description"
137 "PDP status", "Incoming", "Registers a PDP with PAP; also sent as a periodic heart beat; also sent in response to requests from the PAP"
138 "PDP update", "Outgoing", "Assigns a PDP to a PDP Group and Subgroup; also deploys or undeploys policies from the PDP"
139 "PDP state change", "Outgoing", "Changes the state of a PDP or all PDPs within a PDP Group or Subgroup"
141 In addition, PAP generates notifications via the Kafka when policies are successfully or unsuccessfully
142 deployed (or undeployed) from all relevant PDPs.
144 Here is a sample notification:
146 .. literalinclude:: notification/kafka-pap-notif.json
150 2 PAP REST API Swagger
151 ======================
153 It is worth noting that we use basic authorization for access with user name and password set to *policyadmin* and
154 *zb!XztG34*, respectively.
156 For every call, the client is encouraged to insert a uuid-type *requestID* as parameter. It is helpful for tracking each
157 http transaction and facilitates debugging. More importantly, it complies with Logging requirements v1.2. If the client
158 does not provide the requestID in a call, one will be randomly generated and attached to the response header,
161 In accordance with `ONAP API Common Versioning Strategy Guidelines
162 <https://wiki.onap.org/display/DW/ONAP+API+Common+Versioning+Strategy+%28CVS%29+Guidelines>`_, several custom headers
163 are added in the response to each call:
166 :header: "Header", "Example value", "Description"
169 "x-latestversion", "1.0.0", "latest version of the API"
170 "x-minorversion", "0", "MINOR version of the API"
171 "x-patchversion", "0", "PATCH version of the API"
172 "x-onap-requestid", "e1763e61-9eef-4911-b952-1be1edd9812b", "described above; used for logging purposes"
175 :header: "/healthcheck"
178 `Health Check PAP Swagger <./local-swagger.html#tag/HealthCheckRestControllerV1>`_
180 This operation performs a health check on the PAP.
182 Here is a sample response:
184 .. literalinclude:: response/health-check-pap-resp.json
188 :header: "/pdps/healthcheck"
191 `Consolidated Health Check PAP Swagger <./local-swagger.html#tag/PolicyComponentsHealthCheckControllerV1>`_
193 This operation performs a health check of all policy components. The response
194 contains the health check result of each component. The consolidated health check
195 is reported as healthy only if all the components are healthy, otherwise the
196 "healthy" flag is marked as false.
198 Here is a sample response:
200 .. literalinclude:: response/consolidated-healthcheck-pap-resp.json
205 :header: "/pdps/groups/{name}"
208 `PDP State Change PAP Swagger <./local-swagger.html#tag/PdpGroupStateChangeControllerV1>`_
210 The state of PDP groups is managed by this operation. PDP groups can be in states PASSIVE, TEST, SAFE, or ACTIVE. For a full
211 description of PDP group states, see the :ref:`ONAP Policy Framework Architecture <architecture-label>` page.
214 :header: "/pdps/groups/batch"
217 `Group Batch PAP Swagger <./local-swagger.html#tag/PdpGroupCreateOrUpdateControllerV1>`_
219 This operation allows the PDP groups and subgroups to be created and updated. Many PDP groups can be created or updated
220 in a single POST operation by specifying more than one PDP group in the POST operation body.
221 This can be used to create the PDP group by providing all the details including the supported policy types for each subgroup.
222 However, it cannot be used to update policies; that is done using one of
223 the deployment requests. Consequently, the "policies" property of this
224 request will be ignored.
225 This can also be used to update a PDP Group, but supported policy types cannot be updated during the update operation.
226 So, "policies" and "supportedPolicyTypes" properties in the request will be ignored if provided during the PDP Group update operation.
228 The "desiredInstanceCount" specifies the minimum number of PDPs of the given
229 type that should be registered with PAP. Currently, this is just used for
230 health check purposes; if the number of PDPs registered with PAP drops below
231 the given value, then PAP will return an "unhealthy" indicator if a
232 "Consolidated Health Check" is performed.
235 If a subgroup is to be deleted from a PDP Group, then the policies must be removed from
239 Policies cannot be added/updated during PDP Group create/update operations. So, if provided, they are ignored.
240 Supported policy types are defined during PDP Group creation. They cannot be updated once they are created.
241 So, supportedPolicyTypes are expected during PDP Group create, but ignored if provided during PDP Group update.
243 Here is a sample request:
245 .. literalinclude:: request/groups-batch-pap-req.json
249 :header: "/pdps/groups/{name}"
252 `PdpGroup Delete PAP Swagger <./local-swagger.html#tag/PdpGroupDeleteControllerV1>`_
254 The API also allows PDP groups to be deleted. DELETE operations are only permitted on PDP groups in PASSIVE state.
260 `PdpGroup Query PAP Swagger <./local-swagger.html#tag/PdpGroupQueryControllerV1>`_
262 This operation allows the PDP groups and subgroups to be listed as well as the policies that are deployed on each PDP
265 Here is a sample response:
267 .. literalinclude:: response/group-query-pap-resp.json
271 :header: "/pdps/deployments/batch"
274 `Deployments Update PAP Swagger <./local-swagger.html#tag/PdpGroupDeployControllerV1>`_
276 This operation allows policies to be deployed on specific PDP groups.
277 Each subgroup includes an "action" property, which is used to indicate
278 that the policies are being added (POST) to the subgroup, deleted (DELETE)
279 from the subgroup, or that the subgroup's entire set of policies is being
280 replaced (PATCH) by a new set of policies. As such, a subgroup may appear
281 more than once in a single request, one time to delete some policies and
282 another time to add new policies to the same subgroup.
284 Here is a sample request:
286 .. literalinclude:: request/deployment-batch-pap-req.json
289 Here is a sample response:
291 .. literalinclude:: response/deployment-pap-resp.json
295 :header: "/pdps/policies"
298 `Deploy PAP Swagger <./local-swagger.html#operation/deployPolicies>`_
300 This operation allows policies to be deployed across all relevant PDP groups.
301 PAP will deploy the specified policies to all relevant subgroups. Only the
302 policies supported by a given subgroup will be deployed to that subgroup.
305 The policy version is optional. If left unspecified, then the latest version of the policy is deployed. On the other
306 hand, if it is specified, it may be an integer, or it may be a fully qualified version (e.g., "3.0.2").
307 In addition, a subgroup to which a policy is being deployed must have at
308 least one PDP instance, otherwise the request will be rejected.
310 Here is a sample request:
312 .. literalinclude:: request/policy-deploy-pap-req.json
315 Here is a sample response:
317 .. literalinclude:: response/deployment-pap-resp.json
321 :header: "/pdps/policies/{name}"
324 `Undeploy PAP Swagger <./local-swagger.html#operation/deletePolicy>`_
326 This operation allows policies to be undeployed from PDP groups.
329 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").
330 On the other hand, if left unspecified, then the latest deployed version will be undeployed.
333 Due to current limitations, a fully qualified policy version must always be specified.
335 Here is a sample response:
337 .. literalinclude:: response/deployment-pap-resp.json
341 :header: "/policies/status"
344 `All Policy Status PAP Swagger <./local-swagger.html#operation/getStatusOfAllPolicies>`_
347 This operation allows the status of all policies that are deployed or undeployed to be listed together.
348 The result can be filtered based on pdp group name, policy name & version.
351 When a policy is successfully undeployed, it will no longer appear in the policy status response.
353 Here is a sample response:
355 .. literalinclude:: response/policy-status-pap-resp.json
359 :header: "/policies/deployed"
362 `Deployed Policy Status PAP Swagger <./local-swagger.html#operation/queryAllDeployedPolicies>`_
364 This operation allows the deployed policies to be listed together with their respective deployment status.
365 The result can be filtered based on policy name & version.
367 Here is a sample response:
369 .. literalinclude:: response/deployed-policy-pap-resp.json
373 :header: "/policies/audit"
376 `Policy Status PAP Swagger <./local-swagger.html#tag/PolicyAuditControllerV1>`_
378 This operation allows the audit records of policies to be listed together.
379 The result can be filtered based on pdp group name, policy name & version.
380 Along with record count, start time & end time as query parameters.
382 Here is a sample response:
384 .. literalinclude:: response/policy-audit-pap-resp.json
390 The *PolicyAdministration* component (PAP) is initialized using a configuration file: `papParameters.yaml
391 <https://github.com/onap/policy-pap/blob/master/packages/policy-pap-tarball/src/main/resources/etc/papParameters.yaml>`_
393 The configuration file is a YAML file containing the relevant fields for configuring the REST server, Database and DMaaP connectivity and so on.