Policy Life Cycle API
#####################
+1. Policy Life Cycle API
+========================
+
+1.1 Overview
+------------
+
.. contents::
:depth: 2
The group types of targets in TOSCA are groups of TOSCA nodes, not PDP groups; the *target* concept in TOSCA is
equivalent to the Policy Enforcement Point (PEP) concept
+1.2 Preloaded policy types and policies
+---------------------------------------
To ease policy creation, we preload several widely used policy types in policy database. Below is a table listing the preloaded policy types.
:header: "Policy Type Name", "Payload"
:widths: 15,10
- "Monitoring.TCA", `onap.policies.monitoring.cdap.tca.hi.lo.app.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.monitoring.cdap.tca.hi.lo.app.yaml>`_
+ "Monitoring.TCA", `onap.policies.monitoring.tcagen2.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.monitoring.tcagen2.yaml>`_
"Monitoring.Collectors", `onap.policies.monitoring.dcaegen2.collectors.datafile.datafile-app-server.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.monitoring.dcaegen2.collectors.datafile.datafile-app-server.yaml>`_
"Optimization", `onap.policies.Optimization.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.Optimization.yaml>`_
"Optimization.Resource", `onap.policies.optimization.Resource.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.optimization.Resource.yaml>`_
"Controlloop.Guard.Common.Blacklist", `onap.policies.controlloop.guard.common.Blacklist.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.guard.common.Blacklist.yaml>`_
"Controlloop.Guard.Common.FrequencyLimiter", `onap.policies.controlloop.guard.common.FrequencyLimiter.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.guard.common.FrequencyLimiter.yaml>`_
"Controlloop.Guard.Common.MinMax", `onap.policies.controlloop.guard.common.MinMax.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.guard.common.MinMax.yaml>`_
+ "Controlloop.Guard.Common.Filter", `onap.policies.controlloop.guard.common.Filter.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.guard.common.Filter.yaml>`_
"Controlloop.Guard.Coordination.FirstBlocksSecond", `onap.policies.controlloop.guard.coordination.FirstBlocksSecond.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.guard.coordination.FirstBlocksSecond.yaml>`_
"Controlloop.Operational.Common", `onap.policies.controlloop.operational.Common.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.operational.Common.yaml>`_
"Controlloop.Operational.Common.Apex", `onap.policies.controlloop.operational.common.Apex.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.operational.common.Apex.yaml>`_
"vFirewallCDS.Operational.Tosca", `vFirewallCDS.policy.operational.input.tosca.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policies/vFirewallCDS.policy.operational.input.tosca.yaml>`_
-Below is a global API table from where swagger JSON for different types of policy design API can be downloaded.
+2. APIs exposed
+===============
+
+2.1 Global API Table
+--------------------
+
+Below you can download the swagger YAML for Policy Framework Lifecycle API.
+You can find *Tosca Node Template Design* and *Policy Design* operations.
-Global API Table
-----------------
.. csv-table::
- :header: "API name", "Swagger JSON"
+ :header: "API name", "Swagger YAML"
:widths: 10,5
- "Healthcheck API", ":download:`link <swagger/healthcheck-api.json>`"
- "Statistics API", ":download:`link <swagger/statistics-api.json>`"
- "Tosca Policy Type API", ":download:`link <swagger/policytype-api.json>`"
- "Tosca Policy API", ":download:`link <swagger/policy-api.json>`"
+ "Policy Framework Lifecycle API", ":download:`link <https://raw.githubusercontent.com/onap/policy-api/master/main/src/main/resources/openapi/openapi.yaml>`"
-API Swagger
------------
+2.2 API Swagger
+---------------
-It is worth noting that we use basic authorization for API access with username and password set to *healthcheck* and *zb!XztG34* respectively.
+It is worth noting that we use basic authorization for API access with username and password set to *policyadmin* and *zb!XztG34* respectively.
Also, the new APIs support both *http* and *https*.
For every API call, client is encouraged to insert an uuid-type requestID as parameter.
x-onap-requestid is used to track REST transactions for logging purpose, as described above.
-.. swaggerv2doc:: swagger/healthcheck-api.json
-.. swaggerv2doc:: swagger/statistics-api.json
+.. csv-table::
+ :header: "SWAGGER"
+ :widths: 10
+
+ `To view the full SWAGGER click here <./local-swagger.html>`_
+
+.. note::
+ Note that the context-path is not present in the document, because it is in the `application.yaml <https://github.com/onap/policy-api/blob/master/main/src/main/resources/application.yaml>`_
+ So the final url is composed by:
+
+ .. csv-table::
+ :header: "Scheme","Host","Context-Path","Path"
+ :widths: 3,3,3,3
+
+ "http","://<IP>:<PORT>","/policy/api/v1/","healthcheck"
+
+
+2.3 Creating MetadataSet for policy
+-----------------------------------
+
+The policy type implementation in tosca policy can be independently persisted to the database as metadataSets via the Tosca node template Apis .
+The policy type implementation data can be excluded from the policy properties section of the tosca policy and the user can specify only the "metadataSetName" and "metadataSetVersion"
+fields under the policy "metadata" section to map a specific policy type implementation to the policy during the policy creation.
+
+The following sample tosca service template comprises a list of tosca node templates each containing a policy type implementation data in the form of metadataSet that can be persisted to the database independently using the policy node template Api.
+
+.. csv-table::
+ :header: "Tosca node template", "Payload"
+ :widths: 15,10
+
+ "sample.nodetemplates.metadatasets", `nodetemplates.metadatasets.input.tosca.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/nodetemplates/nodetemplates.metadatasets.input.tosca.yaml>`_ `nodetemplates.metadatasets.input.tosca.json <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/nodetemplates/nodetemplates.metadatasets.input.tosca.json>`_
+
+
+The following sample tosca policy shows the policy metadata section that maps to one of the metadataSets stored in the database prior to the policy creation.
+
+.. csv-table::
+ :header: "Tosca policy", "Payload"
+ :widths: 15,10
-.. swaggerv2doc:: swagger/policytype-api.json
+ "apex.decisionmaker.policy", `apex.policy.decisionmaker.input.tosca.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policies/apex.policy.decisionmaker.input.tosca.yaml>`_
-.. swaggerv2doc:: swagger/policy-api.json
+`The node template Apis <./local-swagger.html#tag/Tosca-Node-Template-Design>`_
+are introduced to handle the policy metadataSets as independent entities that can be later mapped to a tosca policy during policy creation.
When making a POST policy API call, the client must not only provide well-formed JSON/YAML,
but also must conform to the TOSCA specification. For example. the "type" field for a TOSCA
or policy type at a time for safety purpose. If client has the need to delete multiple or a group of policies or policy types,
they will need to delete them one by one.
-Sample API Curl Commands
--------------------------
+2.4 Sample API Curl Commands
+----------------------------
From an API client perspective, using *http* or *https* does not make much difference to the curl command.
Here we list some sample curl commands (using *http*) for POST, GET and DELETE monitoring and operational policies that are used in vFirewall use case.
If you are accessing the api from the container, the default *ip* and *port* would be **https:/policy-api:6969/policy/api/v1/**.
Create vFirewall Monitoring Policy::
- curl --user 'healthcheck:zb!XztG34' -X POST "http://{ip}:{port}/policy/api/v1/policytypes/onap.policies.monitoring.cdap.tca.hi.lo.app/versions/1.0.0/policies" -H "Accept: application/json" -H "Content-Type: application/json" -d @vFirewall.policy.monitoring.input.tosca.json
+ curl --user 'policyadmin:zb!XztG34' -X POST "http://{ip}:{port}/policy/api/v1/policytypes/onap.policies.monitoring.tcagen2/versions/1.0.0/policies" -H "Accept: application/json" -H "Content-Type: application/json" -d @vFirewall.policy.monitoring.input.tosca.json
Get vFirewall Monitoring Policy::
- curl --user 'healthcheck:zb!XztG34' -X GET "http://{ip}:{port}/policy/api/v1/policytypes/onap.policies.monitoring.cdap.tca.hi.lo.app/versions/1.0.0/policies/onap.vfirewall.tca/versions/1.0.0" -H "Accept: application/json" -H "Content-Type: application/json"
+ curl --user 'policyadmin:zb!XztG34' -X GET "http://{ip}:{port}/policy/api/v1/policytypes/onap.policies.monitoring.tcagen2/versions/1.0.0/policies/onap.vfirewall.tca/versions/1.0.0" -H "Accept: application/json" -H "Content-Type: application/json"
Delete vFirewall Monitoring Policy::
- curl --user 'healthcheck:zb!XztG34' -X DELETE "http://{ip}:{port}/policy/api/v1/policytypes/onap.policies.monitoring.cdap.tca.hi.lo.app/versions/1.0.0/policies/onap.vfirewall.tca/versions/1.0.0" -H "Accept: application/json" -H "Content-Type: application/json"
+ curl --user 'policyadmin:zb!XztG34' -X DELETE "http://{ip}:{port}/policy/api/v1/policytypes/onap.policies.monitoring.tcagen2/versions/1.0.0/policies/onap.vfirewall.tca/versions/1.0.0" -H "Accept: application/json" -H "Content-Type: application/json"
Create vFirewall Operational Policy::
- curl --user 'healthcheck:zb!XztG34' -X POST "http://{ip}:{port}/policy/api/v1/policytypes/onap.policies.controlloop.operational.common.Drools/versions/1.0.0/policies" -H "Accept: application/json" -H "Content-Type: application/json" -d @vFirewall.policy.operational.input.tosca.json
+ curl --user 'policyadmin:zb!XztG34' -X POST "http://{ip}:{port}/policy/api/v1/policytypes/onap.policies.controlloop.operational.common.Drools/versions/1.0.0/policies" -H "Accept: application/json" -H "Content-Type: application/json" -d @vFirewall.policy.operational.input.tosca.json
Get vFirewall Operational Policy::
- curl --user 'healthcheck:zb!XztG34' -X GET "http://{ip}:{port}/policy/api/v1/policytypes/onap.policies.controlloop.operational.common.Drools/versions/1.0.0/policies/operational.modifyconfig/versions/1.0.0" -H "Accept: application/json" -H "Content-Type: application/json"
+ curl --user 'policyadmin:zb!XztG34' -X GET "http://{ip}:{port}/policy/api/v1/policytypes/onap.policies.controlloop.operational.common.Drools/versions/1.0.0/policies/operational.modifyconfig/versions/1.0.0" -H "Accept: application/json" -H "Content-Type: application/json"
Delete vFirewall Operational Policy::
- curl --user 'healthcheck:zb!XztG34' -X DELETE "http://{ip}:{port}/policy/api/v1/policytypes/onap.policies.controlloop.operational.common.Drools/versions/1.0.0/policies/operational.modifyconfig/versions/1.0.0" -H "Accept: application/json" -H "Content-Type: application/json"
+ curl --user 'policyadmin:zb!XztG34' -X DELETE "http://{ip}:{port}/policy/api/v1/policytypes/onap.policies.controlloop.operational.common.Drools/versions/1.0.0/policies/operational.modifyconfig/versions/1.0.0" -H "Accept: application/json" -H "Content-Type: application/json"
Get all available policies::
- curl --user 'healthcheck:zb!XztG34' -X GET "http://{ip}:{port}/policy/api/v1/policies" -H "Accept: application/json" -H "Content-Type: application/json"
+ curl --user 'policyadmin:zb!XztG34' -X GET "http://{ip}:{port}/policy/api/v1/policies" -H "Accept: application/json" -H "Content-Type: application/json"
Get version 1.0.0 of vFirewall Monitoring Policy::
- curl --user 'healthcheck:zb!XztG34' -X GET "http://{ip}:{port}/policy/api/v1/policies/onap.vfirewall.tca/versions/1.0.0" -H "Accept: application/json" -H "Content-Type: application/json"
+ curl --user 'policyadmin:zb!XztG34' -X GET "http://{ip}:{port}/policy/api/v1/policies/onap.vfirewall.tca/versions/1.0.0" -H "Accept: application/json" -H "Content-Type: application/json"
Delete version 1.0.0 of vFirewall Monitoring Policy::
- curl --user 'healthcheck:zb!XztG34' -X DELETE "http://{ip}:{port}/policy/api/v1/policies/onap.vfirewall.tca/versions/1.0.0" -H "Accept: application/json" -H "Content-Type: application/json"
+ curl --user 'policyadmin:zb!XztG34' -X DELETE "http://{ip}:{port}/policy/api/v1/policies/onap.vfirewall.tca/versions/1.0.0" -H "Accept: application/json" -H "Content-Type: application/json"
+
+
+3. Policy API application configuration
+=======================================
+
+Starting from Jakarta Release policy-api is a Springboot based microservice.
+
+The policy-api application configuration is packaged as a K8S ConfigMap object via `Policy-API OOM charts <https://raw.githubusercontent.com/onap/oom/master/kubernetes/policy/components/policy-api/resources/config/apiParameters.yaml>`_
Code Review / policy / parent.git / blobdiff