X-Git-Url: https://gerrit.onap.org/r/gitweb?a=blobdiff_plain;f=docs%2Fapi%2Fapi.rst;h=17df7463af73b8d61d3b310c5bdf666fdb68da57;hb=a43eb545dded63e1f21b7f14105ae0ed093b54db;hp=58f7e9e0dd7da093975bcf8dbb8904c9a3c46576;hpb=b77c9bec1777072f1e26071dd4f37ce65964f8be;p=policy%2Fparent.git diff --git a/docs/api/api.rst b/docs/api/api.rst index 58f7e9e0..17df7463 100644 --- a/docs/api/api.rst +++ b/docs/api/api.rst @@ -2,15 +2,18 @@ .. Creative Commons Attribution 4.0 International License. .. http://creativecommons.org/licenses/by/4.0 -.. DO NOT REMOVE THIS LABEL - EVEN IF IT GENERATES A WARNING -.. _offeredapis: - .. THIS IS USED INTERNALLY IN POLICY ONLY .. _api-label: Policy Life Cycle API ##################### +1. Policy Life Cycle API +======================== + +1.1 Overview +------------ + .. contents:: :depth: 2 @@ -32,7 +35,7 @@ One Service Template can contain multiple policies and policy types. Child policy types can inherit from parent policy types, so a hierarchy of policy types can be built up. For example, the HpaPolicy Policy Type in the table below is a child of a Resource Policy Type, which is a child of an Optimization policy. -See also `the examples in Github `_. +See also `the examples in Github `_. :: @@ -108,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. @@ -117,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 `_ @@ -135,8 +140,8 @@ 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", `onap.policies.controlloop.Operational.yaml `_ "Controlloop.Operational.Common", `onap.policies.controlloop.operational.Common.yaml `_ "Controlloop.Operational.Common.Apex", `onap.policies.controlloop.operational.common.Apex.yaml `_ "Controlloop.Operational.Common.Drools", `onap.policies.controlloop.operational.common.Drools.yaml `_ @@ -172,24 +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 `" - "Legacy Operational 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. @@ -213,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 -.. swaggerv2doc:: swagger/policytype-api.json + "sample.nodetemplates.metadatasets", `nodetemplates.metadatasets.input.tosca.yaml `_ `nodetemplates.metadatasets.input.tosca.json `_ -.. swaggerv2doc:: swagger/policy-api.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 + + "apex.decisionmaker.policy", `apex.policy.decisionmaker.input.tosca.yaml `_ + +`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 @@ -259,14 +302,12 @@ To be specific, the following rules are implemented to enforce the version: also includes "policy-id": "sample-policy-name2" and "policy-version": "2.0.0". The 200 return of this POST call will have this created policy with metadata including "policy-id": "sample-policy-name1" and "policy-version": "1.0.0". -.. swaggerv2doc:: swagger/operational-policy-api.json - Regarding DELETE APIs for TOSCA compliant policies, we only expose API to delete one particular version of policy 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. @@ -275,19 +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 '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 '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 '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 `_