X-Git-Url: https://gerrit.onap.org/r/gitweb?a=blobdiff_plain;f=docs%2Fapi%2Fapi.rst;h=17df7463af73b8d61d3b310c5bdf666fdb68da57;hb=a43eb545dded63e1f21b7f14105ae0ed093b54db;hp=ba6cb30a7bf560b060fc42ae65458b66dd6e0267;hpb=1d40bf6051f1001212f51109a7cc4ad46bbbb9fa;p=policy%2Fparent.git diff --git a/docs/api/api.rst b/docs/api/api.rst index ba6cb30a..17df7463 100644 --- a/docs/api/api.rst +++ b/docs/api/api.rst @@ -8,6 +8,12 @@ Policy Life Cycle API ##################### +1. Policy Life Cycle API +======================== + +1.1 Overview +------------ + .. contents:: :depth: 2 @@ -105,6 +111,8 @@ triggers R O N/A Specification of policy triggers, not c 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. @@ -114,7 +122,7 @@ To ease policy creation, we preload several widely used policy types in policy d :header: "Policy Type Name", "Payload" :widths: 15,10 - "Monitoring.TCA", `onap.policies.monitoring.cdap.tca.hi.lo.app.yaml `_ + "Monitoring.TCA", `onap.policies.monitoring.tcagen2.yaml `_ "Monitoring.Collectors", `onap.policies.monitoring.dcaegen2.collectors.datafile.datafile-app-server.yaml `_ "Optimization", `onap.policies.Optimization.yaml `_ "Optimization.Resource", `onap.policies.optimization.Resource.yaml `_ @@ -132,6 +140,7 @@ To ease policy creation, we preload several widely used policy types in policy d "Controlloop.Guard.Common.Blacklist", `onap.policies.controlloop.guard.common.Blacklist.yaml `_ "Controlloop.Guard.Common.FrequencyLimiter", `onap.policies.controlloop.guard.common.FrequencyLimiter.yaml `_ "Controlloop.Guard.Common.MinMax", `onap.policies.controlloop.guard.common.MinMax.yaml `_ + "Controlloop.Guard.Common.Filter", `onap.policies.controlloop.guard.common.Filter.yaml `_ "Controlloop.Guard.Coordination.FirstBlocksSecond", `onap.policies.controlloop.guard.coordination.FirstBlocksSecond.yaml `_ "Controlloop.Operational.Common", `onap.policies.controlloop.operational.Common.yaml `_ "Controlloop.Operational.Common.Apex", `onap.policies.controlloop.operational.common.Apex.yaml `_ @@ -168,23 +177,25 @@ Below is a table containing sample well-formed TOSCA compliant policies. "vFirewallCDS.Operational.Tosca", `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 `" - "Statistics API", ":download:`link `" - "Tosca Policy Type API", ":download:`link `" - "Tosca Policy API", ":download:`link `" + "Policy Framework Lifecycle API", ":download:`link `" -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. @@ -208,13 +219,50 @@ x-patchversion is used only to communicate a PATCH version in a response for tro 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 `_ + So the final url is composed by: + + .. csv-table:: + :header: "Scheme","Host","Context-Path","Path" + :widths: 3,3,3,3 + + "http","://:","/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 `_ `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 `_ -.. 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 @@ -258,8 +306,8 @@ Regarding DELETE APIs for TOSCA compliant policies, we only expose API to delete 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. @@ -268,28 +316,36 @@ JSON payload for POST calls can be downloaded from policy table above. 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 `_