X-Git-Url: https://gerrit.onap.org/r/gitweb?a=blobdiff_plain;f=docs%2Fpap%2Fpap.rst;h=fe2288bd14fd16d28a35e8f47927a9e390a2cadf;hb=e2528a77fc0db9b2bf7acc72ed61e589dcdb38f7;hp=a9f6772b9304608d6be208bcdb4f08d89ff01ff8;hpb=6ec1dbbcad20e10e7aae1dd026f45b6dc63bdc1d;p=policy%2Fparent.git diff --git a/docs/pap/pap.rst b/docs/pap/pap.rst index a9f6772b..fe2288bd 100644 --- a/docs/pap/pap.rst +++ b/docs/pap/pap.rst @@ -9,29 +9,78 @@ Policy Administration Point (PAP) Architecture .. contents:: :depth: 3 -The PAP keeps track of PDPs, supporting the deployment of PDP groups and the deployment of a *policy set* across those -PDP groups. Policies are created using the Policy API, but are deployed via the PAP. +.. toctree:: + InternalPapPdp.rst -A PAP is stateless in a RESTful sense, using the database (persistent storage) to track PDPs and the deployment of -policies to those PDPs. In short, policy management on PDPs is the responsibility of PAPs; management of policy sets or -policies by any other manner is not permitted. +The Policy Administration Point (PAP) keeps track of PDPs, supporting the deployment of PDP groups and the deployment +of policies across those PDP groups. Policies are created using the Policy API, but are deployed via the PAP. + +The PAP is stateless in a RESTful sense, using the database (persistent storage) to track PDPs and the deployment of +policies to those PDPs. In short, policy management on PDPs is the responsibility of PAP; management of policies by +any other manner is not permitted. Because the PDP is the main unit of scalability in the Policy Framework, the framework is designed to allow PDPs in a PDP group to arbitrarily appear and disappear and for policy consistency across all PDPs in a PDP group to be easily maintained. The PAP is responsible for controlling the state across the PDPs in a PDP group. The PAP interacts with the -Policy database and transfers policy sets to PDPs. - -There are a number of rules for PDP group and PDP state management: - -1. Only one version of a PDP group may be ACTIVE at any time - -2. If a PDP group with a certain version is ACTIVE and a later version of the same PDP group is activated, then the - system upgrades the PDP group - -3. If a PDP group with a certain version is ACTIVE and an earlier version of the same PDP group is activated, then the - system downgrades the PDP group - -4. There is no restriction on the number of PASSIVE versions of a PDP group that can exist in the system +policy database and transfers policies to PDPs. + +The unit of execution and scaling in the Policy Framework is a *PolicyImpl* entity. A *PolicyImpl* entity runs on a PDP. +As is explained above, a *PolicyImpl* entity is a *PolicyTypeImpl* implementation parameterized with a TOSCA *Policy*. + +.. image:: images/PolicyImplPDPSubGroup.svg + +In order to achieve horizontal scalability, we group the PDPs running instances of a given *PolicyImpl* entity logically +together into a *PDPSubGroup*. The number of PDPs in a *PDPSubGroup* can then be scaled up and down using Kubernetes. In +other words, all PDPs in a subgroup run the same *PolicyImpl*, that is the same policy template implementation (in +XACML, Drools, or APEX) with the same parameters. + +The figure above shows the layout of *PDPGroup* and *PDPSubGroup* entities. The figure shows examples of PDP groups for +Control Loop and Monitoring policies on the right. + +The health of PDPs is monitored by the PAP in order to alert operations teams managing policies. The PAP manages the life +cycle of policies running on PDPs. + +The table below shows the deployment methods in which *PolicyImpl* entities can be deployed to PDP Subgroups. + +========== =========================================== ============================== ================================== +**Method** **Description** **Advantages** **Disadvantages** +========== =========================================== ============================== ================================== +Cold The *PolicyImpl* (*PolicyTypeImpl* and No run time configuration Very restrictive, no run time + TOSCA *Policy*) are predeployed on the PDP. required and run time configuration of PDPs is possible. + PDP is fully configured and ready to administration is simple. + execute when started. + + PDPs register with the PAP when they + start, providing the *pdpGroup* they + have been preconfigured with. + +Warm The *PolicyTypeImpl* entity is predeployed The configuration, parameters, Administration and management is + on the PDP. A TOSCA *Policy* may be loaded and PDP group of PDPs may be required. The configuration and + at startup. The PDP may be configured or changed at run time by loading life cycle of the TOSCA policies + reconfigured with a new or updated TOSCA or updating a TOSCA *Policy* can change at run time and must be + *Policy* at run time. into the PDP. administered and managed. + + PDPs register with the PAP when they start, Support TOSCA *Policy* entity + providing the *pdpGroup* they have been life cycle managgement is + predeployed with if any. The PAP may update supported, allowing features + the TOSCA *Policy* on a PDP at any time such as *PolicyImpl* Safe Mode + after registration. and *PolicyImpl* retirement. + +Hot The *PolicyImpl* (*PolicyTypeImpl* and The policy logic, rules, Administration and management is + TOSCA *Policy*) are deployed at run time. configuration, parameters, and more complex. The *PolicyImpl* + The *PolicyImpl* (*PolicyTypeImpl* and PDP group of PDPs may be itself and its configuration and + TOSCA *Policy*) may be loaded at startup. changed at run time by loading life cycle as well as the life + The PDP may be configured or reconfigured or updating a TOSCA *Policy* cycle of the TOSCA policies can + with a new or updated *PolicyTypeImpl* and *PolicyTypeImpl* into the change at run time and must be + and/or TOSCA *Policy* at run time. PDP. administered and managed. + + PDPs register with the PAP when they Lifecycle management of TOSCA + start, providing the *pdpGroup* they have *Policy* entities and + been preconfigured with if any. The PAP may *PolicyTypeImpl* entites is + update the TOSCA *Policy* and supported, allowing features + *PolicyTypeImpl* on a PDP at any time after such as *PolicyImpl* Safe Mode + registration and *PolicyImpl* retirement. +========== =========================================== ============================== ================================== 1 APIs @@ -59,13 +108,18 @@ PAP supports the operations listed in the following table, via its REST API: :widths: 25,70 "Health check", "Queries the health of the PAP" + "Consolidated healthcheck", "Queries the health of all policy components" "Statistics", "Queries various statistics" "PDP state change", "Changes the state of all PDPs in a PDP Group" "PDP Group create/update", "Creates/updates PDP Groups" "PDP Group delete", "Deletes a PDP Group" "PDP Group query", "Queries all PDP Groups" + "Deployment update", "Deploy/undeploy one or more policies in specified PdpGroups" "Deploy policy", "Deploys one or more policies to the PDPs" "Undeploy policy", "Undeploys a policy from the PDPs" + "Policy Status", "Queries the status of all policies" + "Policy deployment status", "Queries the status of all deployed policies" + "PDP statistics", "Queries the statistics of PDPs" 1.2 DMaaP API ------------- @@ -113,7 +167,8 @@ are added in the response to each call: "x-minorversion", "0", "MINOR version of the API" "x-patchversion", "0", "PATCH version of the API" "x-onap-requestid", "e1763e61-9eef-4911-b952-1be1edd9812b", "described above; used for logging purposes" - + +:download:`Download Health Check PAP API Swagger ` .. swaggerv2doc:: swagger/health-check-pap.json @@ -124,6 +179,22 @@ Here is a sample response: .. literalinclude:: response/health-check-pap-resp.json :language: json +:download:`Download Consolidated Health Check PAP API Swagger ` + +.. swaggerv2doc:: swagger/consolidated-healthcheck-pap.json + +This operation performs a health check of all policy components. The response +contains the health check result of each component. The consolidated health check +is reported as healthy only if all the components are healthy, otherwise the +"healthy" flag is marked as false. + +Here is a sample response: + +.. literalinclude:: response/consolidated-healthcheck-pap-resp.json + :language: json + +:download:`Download Statistics PAP API Swagger ` + .. swaggerv2doc:: swagger/statistics-pap.json This operation allows statistics for PDP groups, PDP subgroups, and individual PDPs to be retrieved. @@ -137,33 +208,54 @@ Here is a sample response: .. literalinclude:: response/statistics-pap-resp.json :language: json +:download:`Download State Change PAP Swagger ` + .. swaggerv2doc:: swagger/state-change-pap.json The state of PDP groups is managed by this operation. PDP groups can be in states PASSIVE, TEST, SAFE, or ACTIVE. For a full description of PDP group states, see the :ref:`ONAP Policy Framework Architecture ` page. +:download:`Download Group Batch PAP API Swagger ` + .. swaggerv2doc:: swagger/groups-batch-pap.json This operation allows the PDP groups and subgroups to be created and updated. Many PDP groups can be created or updated in a single POST operation by specifying more than one PDP group in the POST operation body. -This can be used to update the policy types supported by various subgroups. +This can be used to create the PDP group by providing all the details including the supported policy types for each subgroup. However, it cannot be used to update policies; that is done using one of -the deployment requests. Consequently, the "policy" property of this +the deployment requests. Consequently, the "policies" property of this request will be ignored. +This can also be used to update a PDP Group, but supported policy types cannot be updated during the update operation. +So, "policies" and "supportedPolicyTypes" properties in the request will be ignored if provided during the PDP Group update operation. + +The "desiredInstanceCount" specifies the minimum number of PDPs of the given +type that should be registered with PAP. Currently, this is just used for +health check purposes; if the number of PDPs registered with PAP drops below +the given value, then PAP will return an "unhealthy" indicator if a +"Consolidated Health Check" is performed. .. note:: - Due to current limitations, if a subgroup is to be deleted from a PDP Group, then the policies must be removed from + If a subgroup is to be deleted from a PDP Group, then the policies must be removed from the subgroup first. +.. note:: + Policies cannot be added/updated during PDP Group create/update operations. So, if provided, they are ignored. + Supported policy types are defined during PDP Group creation. They cannot be updated once they are created. + So, supportedPolicyTypes are expected during PDP Group create, but ignored if provided during PDP Group update. + Here is a sample request: .. literalinclude:: request/groups-batch-pap-req.json :language: json +:download:`Download Group Delete PAP API Swagger ` + .. swaggerv2doc:: swagger/group-delete-pap.json The API also allows PDP groups to be deleted. DELETE operations are only permitted on PDP groups in PASSIVE state. +:download:`Download Group Query PAP API Swagger ` + .. swaggerv2doc:: swagger/group-query-pap.json This operation allows the PDP groups and subgroups to be listed as well as the policies that are deployed on each PDP @@ -174,6 +266,8 @@ Here is a sample response: .. literalinclude:: response/group-query-pap-resp.json :language: json +:download:`Download Deployments Batch PAP API Swagger ` + .. swaggerv2doc:: swagger/deployments-batch-pap.json This operation allows policies to be deployed on specific PDP groups. @@ -189,6 +283,13 @@ Here is a sample request: .. literalinclude:: request/deployment-batch-pap-req.json :language: json +Here is a sample response: + +.. literalinclude:: response/deployment-pap-resp.json + :language: json + +:download:`Download Deploy PAP API Swagger ` + .. swaggerv2doc:: swagger/policy-deploy-pap.json This operation allows policies to be deployed across all relevant PDP groups. @@ -206,6 +307,13 @@ Here is a sample request: .. literalinclude:: request/policy-deploy-pap-req.json :language: json +Here is a sample response: + +.. literalinclude:: response/deployment-pap-resp.json + :language: json + +:download:`Download Undeploy PAP API Swagger ` + .. swaggerv2doc:: swagger/policy-undeploy-pap.json This operation allows policies to be undeployed from PDP groups. @@ -216,20 +324,60 @@ This operation allows policies to be undeployed from PDP groups. .. note:: Due to current limitations, a fully qualified policy version must always be specified. - -3 Future Features -================= -3.1 Order Health Check on PDPs -============================== +Here is a sample response: + +.. literalinclude:: response/deployment-pap-resp.json + :language: json + +:download:`Download Policy Status PAP API Swagger ` + +.. swaggerv2doc:: swagger/policy-status-pap.json + +This operation allows the status of all policies that are deployed or undeployed to be listed together. +The result can be filtered based on pdp group name, policy name & version. + +.. note:: + When a policy is successfully undeployed, it will no longer appear in the policy status response. + +Here is a sample response: + +.. literalinclude:: response/policy-status-pap-resp.json + :language: json + +:download:`Download Deployed Policy PAP API Swagger ` -This operation will allow a PDP group health check to be ordered on PDP groups and on individual PDPs. The operation -will return a HTTP status code of *202: Accepted* if the health check request has been accepted by the PAP. The PAP will -then order execution of the health check on the PDPs. +.. swaggerv2doc:: swagger/deployed-policy-pap.json + +This operation allows the deployed policies to be listed together with their respective deployment status. +The result can be filtered based on policy name & version. + +Here is a sample response: + +.. literalinclude:: response/deployed-policy-pap-resp.json + :language: json + +:download:`Download PDP Statistics PAP API Swagger ` + +.. swaggerv2doc:: swagger/pdp-statistics-pap.json + +This operation allows the PDP statistics to be retrieved for all registered PDPs. +The result can be filtered based on PDP group, PDP subgroup & PDP instance. + +Here is a sample response: + +.. literalinclude:: response/pdp-statistics-pap-resp.json + :language: json + + +3 Future Features +================= -As health checks may be long lived operations, Health checks will be scheduled for execution by this operation. Users -will check the result of a health check test by issuing a PDP Group Query operation and checking the *healthy* field of -PDPs. +3.1 Disable policies in PDP +=========================== +This operation will allow disabling individual policies running in PDP engine. It is mainly beneficial +in scenarios where network operators/administrators want to disable a particular policy in PDP engine +for a period of time due to a failure in the system or for scheduled maintenance. End of Document