Chenfei Gao | 55e1f55 | 2019-05-21 13:32:30 -0400 | [diff] [blame] | 1 | .. This work is licensed under a |
| 2 | .. Creative Commons Attribution 4.0 International License. |
| 3 | .. http://creativecommons.org/licenses/by/4.0 |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 4 | |
Pamela Dragosh | 9fcabd0 | 2020-05-13 07:54:15 -0400 | [diff] [blame] | 5 | .. THIS IS USED INTERNALLY IN POLICY ONLY |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 6 | .. _api-label: |
| 7 | |
Chenfei Gao | af35b6a | 2019-05-21 17:40:21 -0400 | [diff] [blame] | 8 | Policy Life Cycle API |
Pamela Dragosh | 0ac4c6a | 2019-06-11 10:55:04 -0400 | [diff] [blame] | 9 | ##################### |
Chenfei Gao | f5f6d35 | 2019-08-23 15:50:58 -0400 | [diff] [blame] | 10 | |
| 11 | .. contents:: |
Chenfei Gao | 6d69ff9 | 2020-01-13 13:20:34 -0500 | [diff] [blame] | 12 | :depth: 2 |
Chenfei Gao | af35b6a | 2019-05-21 17:40:21 -0400 | [diff] [blame] | 13 | |
liamfallon | e83e607 | 2020-05-06 13:09:09 +0100 | [diff] [blame] | 14 | The purpose of this API is to support CRUD of TOSCA *PolicyType* and *Policy* entities. This API is provided by the |
Pamela Dragosh | f65c8ff | 2020-04-29 08:23:12 -0400 | [diff] [blame] | 15 | *PolicyDevelopment* component of the Policy Framework, see the :ref:`The ONAP Policy Framework Architecture |
liamfallon | e83e607 | 2020-05-06 13:09:09 +0100 | [diff] [blame] | 16 | <architecture-label>` page. The Policy design API backend is running in an independent building block component of the |
| 17 | policy framework that provides REST services for the aforementioned CRUD behaviors. The Policy design API component interacts |
| 18 | with a policy database for storing and fetching new policies or policy types as needed. Apart from CRUD, an API is also |
| 19 | exposed for clients to retrieve healthcheck status of the API REST service and statistics report including a variety of |
| 20 | counters that reflect the history of API invocation. |
Chenfei Gao | af35b6a | 2019-05-21 17:40:21 -0400 | [diff] [blame] | 21 | |
Chenfei Gao | 7984ada | 2020-03-17 22:34:15 -0400 | [diff] [blame] | 22 | We strictly follow `TOSCA Specification <http://docs.oasis-open.org/tosca/TOSCA-Simple-Profile-YAML/v1.1/TOSCA-Simple-Profile-YAML-v1.1.pdf>`_ |
liamfallon | e83e607 | 2020-05-06 13:09:09 +0100 | [diff] [blame] | 23 | to define policy types and policies. A policy type defines the schema for a policy, expressing the properties, targets, and triggers |
| 24 | that a policy may have. The type (string, int etc) and constraints (such as the range of legal values) of each property is defined |
| 25 | in the Policy Type. Both Policy Type and policy are included in a TOSCA Service Template, which is used as the entity passed into an API |
| 26 | POST call and the entity returned by API GET and DELETE calls. More details are presented in following sections. Policy Types and Policies |
| 27 | can be composed for any given domain of application. All Policy Types and Policies must be composed as well-formed TOSCA Service Templates. |
| 28 | One Service Template can contain multiple policies and policy types. |
| 29 | |
| 30 | Child policy types can inherit from parent policy types, so a hierarchy of policy types can be built up. For example, the HpaPolicy Policy |
| 31 | Type in the table below is a child of a Resource Policy Type, which is a child of an Optimization policy. |
Eric Debeau | 1d40bf6 | 2020-08-18 10:35:28 +0200 | [diff] [blame] | 32 | See also `the examples in Github <https://github.com/onap/policy-models/tree/master/models-examples/src/main/resources/policytypes>`_. |
liamfallon | e83e607 | 2020-05-06 13:09:09 +0100 | [diff] [blame] | 33 | |
| 34 | :: |
| 35 | |
| 36 | onap.policies.Optimization.yaml |
| 37 | onap.policies.optimization.Resource.yaml |
| 38 | onap.policies.optimization.resource.AffinityPolicy.yaml |
| 39 | onap.policies.optimization.resource.DistancePolicy.yaml |
| 40 | onap.policies.optimization.resource.HpaPolicy.yaml |
| 41 | onap.policies.optimization.resource.OptimizationPolicy.yaml |
| 42 | onap.policies.optimization.resource.PciPolicy.yaml |
| 43 | onap.policies.optimization.resource.Vim_fit.yaml |
| 44 | onap.policies.optimization.resource.VnfPolicy.yaml |
| 45 | onap.policies.optimization.Service.yaml |
| 46 | onap.policies.optimization.service.QueryPolicy.yaml |
| 47 | onap.policies.optimization.service.SubscriberPolicy.yaml |
| 48 | |
| 49 | Custom data types can be defined in TOSCA for properties specified in Policy Types. Data types can also inherit from parents, so a hierarchy of data types can also be built up. |
| 50 | |
| 51 | .. warning:: |
| 52 | When creating a Policy Type, the ancestors of the Policy Type and all its custom Data Type definitions and ancestors MUST either already |
| 53 | exist in the database or MUST also be defined in the incoming TOSCA Service Template. Requests with missing or bad references are rejected |
| 54 | by the API. |
| 55 | |
| 56 | Each Policy Type can have multiple Policy instances created from it. Therefore, many Policy instances of the HpaPolicy Policy Type above can be created. When a policy is created, its Policy Type is specified in the *type* and *type_version* fields of the policy. |
| 57 | |
| 58 | .. warning:: |
| 59 | The Policy Type specified for a Policy MUST exist in the database before the policy can be created. Requests with missing or bad |
| 60 | Policy Type references are rejected by the API. |
Chenfei Gao | af35b6a | 2019-05-21 17:40:21 -0400 | [diff] [blame] | 61 | |
Pamela Dragosh | f65c8ff | 2020-04-29 08:23:12 -0400 | [diff] [blame] | 62 | The API allows applications to create, update, delete, and query *PolicyType* entities so that they become available for |
liamfallon | e83e607 | 2020-05-06 13:09:09 +0100 | [diff] [blame] | 63 | use in ONAP by applications such as CLAMP. Some Policy Type entities are preloaded in the Policy Framework. |
| 64 | |
| 65 | .. warning:: |
| 66 | If a TOSCA entity (Data Type, Policy Type, or Policy with a certain version) already exists in the database and an attempt is made |
| 67 | to re-create the entity with different fields, the API will reject the request with the error message "entity in incoming fragment |
| 68 | does not equal existing entity". In such cases, delete the Policy or Policy Type and re-create it using the API. |
| 69 | |
| 70 | |
| 71 | The TOSCA fields below are valid on API calls: |
Pamela Dragosh | f65c8ff | 2020-04-29 08:23:12 -0400 | [diff] [blame] | 72 | |
| 73 | ============ ======= ======== ========== =============================================================================== |
| 74 | **Field** **GET** **POST** **DELETE** **Comment** |
| 75 | ============ ======= ======== ========== =============================================================================== |
| 76 | (name) M M M The definition of the reference to the Policy Type, GET allows ranges to be |
| 77 | specified |
| 78 | version O M C GET allows ranges to be specified, must be specified if more than one version |
liamfallon | e83e607 | 2020-05-06 13:09:09 +0100 | [diff] [blame] | 79 | of the Policy Type exists and a specific version is required |
Pamela Dragosh | f65c8ff | 2020-04-29 08:23:12 -0400 | [diff] [blame] | 80 | description R O N/A Desciption of the Policy Type |
| 81 | derived_from R C N/A Must be specified when a Policy Type is derived from another Policy Type such |
liamfallon | e83e607 | 2020-05-06 13:09:09 +0100 | [diff] [blame] | 82 | as in the case of derived Monitoring Policy Types. The referenced Policy Type |
| 83 | must either already exist in the database or be defined as another policy type |
| 84 | in the incoming TOSCA service template |
Pamela Dragosh | f65c8ff | 2020-04-29 08:23:12 -0400 | [diff] [blame] | 85 | metadata R O N/A Metadata for the Policy Type |
liamfallon | e83e607 | 2020-05-06 13:09:09 +0100 | [diff] [blame] | 86 | properties R M N/A This field holds the specification of the specific Policy Type in ONAP. Any user |
| 87 | defined data types specified on properties must either already exist in the |
| 88 | database or be defined in the incoming TOSCA service template |
Pamela Dragosh | f65c8ff | 2020-04-29 08:23:12 -0400 | [diff] [blame] | 89 | targets R O N/A A list of node types and/or group types to which the Policy Type can be applied |
| 90 | triggers R O N/A Specification of policy triggers, not currently supported in ONAP |
| 91 | ============ ======= ======== ========== =============================================================================== |
| 92 | |
| 93 | .. note:: |
| 94 | On this and subsequent tables, use the following legend: M-Mandatory, O-Optional, R-Read-only, C-Conditional. |
| 95 | Conditional means the field is mandatory when some other field is present. |
| 96 | |
| 97 | .. note:: |
| 98 | Preloaded policy types may only be queried over this API, modification or deletion of preloaded policy type |
| 99 | implementations is disabled. |
| 100 | |
| 101 | .. note:: |
liamfallon | e83e607 | 2020-05-06 13:09:09 +0100 | [diff] [blame] | 102 | Policy types that are in use (referenced by defined Policies and/or child policy types) may not be deleted. |
Pamela Dragosh | f65c8ff | 2020-04-29 08:23:12 -0400 | [diff] [blame] | 103 | |
| 104 | .. note:: |
| 105 | The group types of targets in TOSCA are groups of TOSCA nodes, not PDP groups; the *target* concept in TOSCA is |
| 106 | equivalent to the Policy Enforcement Point (PEP) concept |
| 107 | |
| 108 | |
Chenfei Gao | 7984ada | 2020-03-17 22:34:15 -0400 | [diff] [blame] | 109 | To ease policy creation, we preload several widely used policy types in policy database. Below is a table listing the preloaded policy types. |
Chenfei Gao | af35b6a | 2019-05-21 17:40:21 -0400 | [diff] [blame] | 110 | |
Pamela Dragosh | f65c8ff | 2020-04-29 08:23:12 -0400 | [diff] [blame] | 111 | .. _policy-preload-label: |
| 112 | |
Chenfei Gao | af35b6a | 2019-05-21 17:40:21 -0400 | [diff] [blame] | 113 | .. csv-table:: |
Chenfei Gao | 0a85b8b | 2019-09-10 22:22:17 -0400 | [diff] [blame] | 114 | :header: "Policy Type Name", "Payload" |
Chenfei Gao | af35b6a | 2019-05-21 17:40:21 -0400 | [diff] [blame] | 115 | :widths: 15,10 |
| 116 | |
Pamela Dragosh | 5631660 | 2020-08-20 09:16:20 -0400 | [diff] [blame] | 117 | "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>`_ |
Chenfei Gao | dfbc0ad | 2019-10-01 14:19:39 -0400 | [diff] [blame] | 118 | "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>`_ |
| 119 | "Optimization", `onap.policies.Optimization.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.Optimization.yaml>`_ |
Chenfei Gao | 7984ada | 2020-03-17 22:34:15 -0400 | [diff] [blame] | 120 | "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>`_ |
| 121 | "Optimization.Resource.AffinityPolicy", `onap.policies.optimization.resource.AffinityPolicy.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.optimization.resource.AffinityPolicy.yaml>`_ |
| 122 | "Optimization.Resource.DistancePolicy", `onap.policies.optimization.resource.DistancePolicy.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.optimization.resource.DistancePolicy.yaml>`_ |
| 123 | "Optimization.Resource.HpaPolicy", `onap.policies.optimization.resource.HpaPolicy.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.optimization.resource.HpaPolicy.yaml>`_ |
| 124 | "Optimization.Resource.OptimizationPolicy", `onap.policies.optimization.resource.OptimizationPolicy.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.optimization.resource.OptimizationPolicy.yaml>`_ |
| 125 | "Optimization.Resource.PciPolicy", `onap.policies.optimization.resource.PciPolicy.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.optimization.resource.PciPolicy.yaml>`_ |
| 126 | "Optimization.Resource.Vim_fit", `onap.policies.optimization.resource.Vim_fit.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.optimization.resource.Vim_fit.yaml>`_ |
| 127 | "Optimization.Resource.VnfPolicy", `onap.policies.optimization.resource.VnfPolicy.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.optimization.resource.VnfPolicy.yaml>`_ |
| 128 | "Optimization.Service", `onap.policies.optimization.Service.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.optimization.Service.yaml>`_ |
| 129 | "Optimization.Service.QueryPolicy", `onap.policies.optimization.service.QueryPolicy.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.optimization.service.QueryPolicy.yaml>`_ |
| 130 | "Optimization.Service.SubscriberPolicy", `onap.policies.optimization.service.SubscriberPolicy.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.optimization.service.SubscriberPolicy.yaml>`_ |
| 131 | "Controlloop.Guard.Common", `onap.policies.controlloop.guard.Common.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.guard.Common.yaml>`_ |
| 132 | "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>`_ |
| 133 | "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>`_ |
| 134 | "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>`_ |
Pamela Dragosh | cc6265e | 2020-08-21 10:53:44 -0400 | [diff] [blame^] | 135 | "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>`_ |
Chenfei Gao | 7984ada | 2020-03-17 22:34:15 -0400 | [diff] [blame] | 136 | "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>`_ |
Chenfei Gao | 7984ada | 2020-03-17 22:34:15 -0400 | [diff] [blame] | 137 | "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>`_ |
| 138 | "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>`_ |
| 139 | "Controlloop.Operational.Common.Drools", `onap.policies.controlloop.operational.common.Drools.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.operational.common.Drools.yaml>`_ |
| 140 | "Naming", `onap.policies.Naming.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.Naming.yaml>`_ |
| 141 | "Native.Drools", `onap.policies.native.Drools.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.native.Drools.yaml>`_ |
| 142 | "Native.Xacml", `onap.policies.native.Xacml.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.native.Xacml.yaml>`_ |
| 143 | "Native.Apex", `onap.policies.native.Apex.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.native.Apex.yaml>`_ |
Chenfei Gao | af35b6a | 2019-05-21 17:40:21 -0400 | [diff] [blame] | 144 | |
Chenfei Gao | 7984ada | 2020-03-17 22:34:15 -0400 | [diff] [blame] | 145 | We also preload a policy in the policy database. Below is a table listing the preloaded polic(ies). |
| 146 | |
| 147 | .. csv-table:: |
| 148 | :header: "Policy Type Name", "Payload" |
| 149 | :widths: 15,10 |
| 150 | |
| 151 | "SDNC.Naming", `sdnc.policy.naming.input.tosca.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policies/sdnc.policy.naming.input.tosca.yaml>`_ |
| 152 | |
| 153 | Below is a table containing sample well-formed TOSCA compliant policies. |
Chenfei Gao | af35b6a | 2019-05-21 17:40:21 -0400 | [diff] [blame] | 154 | |
| 155 | .. csv-table:: |
Chenfei Gao | 0a85b8b | 2019-09-10 22:22:17 -0400 | [diff] [blame] | 156 | :header: "Policy Name", "Payload" |
Chenfei Gao | af35b6a | 2019-05-21 17:40:21 -0400 | [diff] [blame] | 157 | :widths: 15,10 |
| 158 | |
Chenfei Gao | dfbc0ad | 2019-10-01 14:19:39 -0400 | [diff] [blame] | 159 | "vCPE.Monitoring.Tosca", `vCPE.policy.monitoring.input.tosca.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policies/vCPE.policy.monitoring.input.tosca.yaml>`_ `vCPE.policy.monitoring.input.tosca.json <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policies/vCPE.policy.monitoring.input.tosca.json>`_ |
Chenfei Gao | 7984ada | 2020-03-17 22:34:15 -0400 | [diff] [blame] | 160 | "vCPE.Optimization.Tosca", `vCPE.policies.optimization.input.tosca.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policies/vCPE.policies.optimization.input.tosca.yaml>`_ `vCPE.policies.optimization.input.tosca.json <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policies/vCPE.policies.optimization.input.tosca.json>`_ |
| 161 | "vCPE.Operational.Tosca", `vCPE.policy.operational.input.tosca.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policies/vCPE.policy.operational.input.tosca.yaml>`_ `vCPE.policy.operational.input.tosca.json <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policies/vCPE.policy.operational.input.tosca.json>`_ |
| 162 | "vDNS.Guard.FrequencyLimiting.Tosca", `vDNS.policy.guard.frequencylimiter.input.tosca.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policies/vDNS.policy.guard.frequencylimiter.input.tosca.yaml>`_ |
| 163 | "vDNS.Guard.MinMax.Tosca", `vDNS.policy.guard.minmaxvnfs.input.tosca.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policies/vDNS.policy.guard.minmaxvnfs.input.tosca.yaml>`_ |
| 164 | "vDNS.Guard.Blacklist.Tosca", `vDNS.policy.guard.blacklist.input.tosca.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policies/vDNS.policy.guard.blacklist.input.tosca.yaml>`_ |
Chenfei Gao | dfbc0ad | 2019-10-01 14:19:39 -0400 | [diff] [blame] | 165 | "vDNS.Monitoring.Tosca", `vDNS.policy.monitoring.input.tosca.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policies/vDNS.policy.monitoring.input.tosca.yaml>`_ `vDNS.policy.monitoring.input.tosca.json <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policies/vDNS.policy.monitoring.input.tosca.json>`_ |
Chenfei Gao | 7984ada | 2020-03-17 22:34:15 -0400 | [diff] [blame] | 166 | "vDNS.Operational.Tosca", `vDNS.policy.operational.input.tosca.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policies/vDNS.policy.operational.input.tosca.yaml>`_ `vDNS.policy.operational.input.tosca.json <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policies/vDNS.policy.operational.input.tosca.json>`_ |
Chenfei Gao | dfbc0ad | 2019-10-01 14:19:39 -0400 | [diff] [blame] | 167 | "vFirewall.Monitoring.Tosca", `vFirewall.policy.monitoring.input.tosca.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policies/vFirewall.policy.monitoring.input.tosca.yaml>`_ `vFirewall.policy.monitoring.input.tosca.json <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policies/vFirewall.policy.monitoring.input.tosca.json>`_ |
Chenfei Gao | 7984ada | 2020-03-17 22:34:15 -0400 | [diff] [blame] | 168 | "vFirewall.Operational.Tosca", `vFirewall.policy.operational.input.tosca.yaml <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policies/vFirewall.policy.operational.input.tosca.yaml>`_ `vFirewall.policy.operational.input.tosca.json <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policies/vFirewall.policy.operational.input.tosca.json>`_ |
| 169 | "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>`_ |
Chenfei Gao | af35b6a | 2019-05-21 17:40:21 -0400 | [diff] [blame] | 170 | |
| 171 | |
Chenfei Gao | 6d69ff9 | 2020-01-13 13:20:34 -0500 | [diff] [blame] | 172 | Below is a global API table from where swagger JSON for different types of policy design API can be downloaded. |
a.sreekumar | 332b03d | 2020-03-27 10:26:05 +0000 | [diff] [blame] | 173 | |
Chenfei Gao | 55e1f55 | 2019-05-21 13:32:30 -0400 | [diff] [blame] | 174 | Global API Table |
Pamela Dragosh | f65c8ff | 2020-04-29 08:23:12 -0400 | [diff] [blame] | 175 | ---------------- |
Chenfei Gao | 55e1f55 | 2019-05-21 13:32:30 -0400 | [diff] [blame] | 176 | .. csv-table:: |
| 177 | :header: "API name", "Swagger JSON" |
| 178 | :widths: 10,5 |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 179 | |
Chenfei Gao | af35b6a | 2019-05-21 17:40:21 -0400 | [diff] [blame] | 180 | "Healthcheck API", ":download:`link <swagger/healthcheck-api.json>`" |
| 181 | "Statistics API", ":download:`link <swagger/statistics-api.json>`" |
| 182 | "Tosca Policy Type API", ":download:`link <swagger/policytype-api.json>`" |
| 183 | "Tosca Policy API", ":download:`link <swagger/policy-api.json>`" |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 184 | |
Chenfei Gao | 55e1f55 | 2019-05-21 13:32:30 -0400 | [diff] [blame] | 185 | API Swagger |
Pamela Dragosh | f65c8ff | 2020-04-29 08:23:12 -0400 | [diff] [blame] | 186 | ----------- |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 187 | |
Chenfei Gao | 6d69ff9 | 2020-01-13 13:20:34 -0500 | [diff] [blame] | 188 | It is worth noting that we use basic authorization for API access with username and password set to *healthcheck* and *zb!XztG34* respectively. |
Chenfei Gao | af35b6a | 2019-05-21 17:40:21 -0400 | [diff] [blame] | 189 | Also, the new APIs support both *http* and *https*. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 190 | |
Chenfei Gao | 6d69ff9 | 2020-01-13 13:20:34 -0500 | [diff] [blame] | 191 | For every API call, client is encouraged to insert an uuid-type requestID as parameter. |
| 192 | It is helpful for tracking each http transaction and facilitates debugging. |
| 193 | Mostly importantly, it complies with Logging requirements v1.2. |
liamfallon | e83e607 | 2020-05-06 13:09:09 +0100 | [diff] [blame] | 194 | If a client does not provide the requestID in API call, one will be randomly generated |
Chenfei Gao | 6d69ff9 | 2020-01-13 13:20:34 -0500 | [diff] [blame] | 195 | and attached to response header *x-onap-requestid*. |
Chenfei Gao | 55e1f55 | 2019-05-21 13:32:30 -0400 | [diff] [blame] | 196 | |
Chenfei Gao | af35b6a | 2019-05-21 17:40:21 -0400 | [diff] [blame] | 197 | In accordance with `ONAP API Common Versioning Strategy Guidelines <https://wiki.onap.org/display/DW/ONAP+API+Common+Versioning+Strategy+%28CVS%29+Guidelines>`_, |
| 198 | in the response of each API call, several custom headers are added:: |
Chenfei Gao | 55e1f55 | 2019-05-21 13:32:30 -0400 | [diff] [blame] | 199 | |
Chenfei Gao | 6d69ff9 | 2020-01-13 13:20:34 -0500 | [diff] [blame] | 200 | x-latestversion: 1.0.0 |
| 201 | x-minorversion: 0 |
| 202 | x-patchversion: 0 |
Chenfei Gao | af35b6a | 2019-05-21 17:40:21 -0400 | [diff] [blame] | 203 | x-onap-requestid: e1763e61-9eef-4911-b952-1be1edd9812b |
Chenfei Gao | 6d69ff9 | 2020-01-13 13:20:34 -0500 | [diff] [blame] | 204 | x-latestversion is used only to communicate an API's latest version. |
Chenfei Gao | 55e1f55 | 2019-05-21 13:32:30 -0400 | [diff] [blame] | 205 | |
Chenfei Gao | af35b6a | 2019-05-21 17:40:21 -0400 | [diff] [blame] | 206 | x-minorversion is used to request or communicate a MINOR version back from the client to the server, and from the server back to the client. |
Chenfei Gao | 55e1f55 | 2019-05-21 13:32:30 -0400 | [diff] [blame] | 207 | |
Chenfei Gao | af35b6a | 2019-05-21 17:40:21 -0400 | [diff] [blame] | 208 | x-patchversion is used only to communicate a PATCH version in a response for troubleshooting purposes only, and will not be provided by the client on request. |
| 209 | |
| 210 | x-onap-requestid is used to track REST transactions for logging purpose, as described above. |
Chenfei Gao | af35b6a | 2019-05-21 17:40:21 -0400 | [diff] [blame] | 211 | |
| 212 | .. swaggerv2doc:: swagger/healthcheck-api.json |
| 213 | |
| 214 | .. swaggerv2doc:: swagger/statistics-api.json |
| 215 | |
| 216 | .. swaggerv2doc:: swagger/policytype-api.json |
| 217 | |
| 218 | .. swaggerv2doc:: swagger/policy-api.json |
| 219 | |
Chenfei Gao | 6d69ff9 | 2020-01-13 13:20:34 -0500 | [diff] [blame] | 220 | When making a POST policy API call, the client must not only provide well-formed JSON/YAML, |
| 221 | but also must conform to the TOSCA specification. For example. the "type" field for a TOSCA |
| 222 | policy should strictly match the policy type name it derives. |
| 223 | Please check out the sample policies in above policy table. |
| 224 | |
| 225 | Also, in the POST payload passed into each policy or policy type creation call (i.e. POST API invocation), the client needs to explicitly |
| 226 | specify the version of the policy or policy type to create. That being said, the "version" field is mandatory in the TOSCA service template |
Chenfei Gao | 7984ada | 2020-03-17 22:34:15 -0400 | [diff] [blame] | 227 | formatted policy or policy type payload. If the version is missing, that POST call will return "406 - Not Acceptable" and |
| 228 | the policy or policy type to create will not be stored in the database. |
Chenfei Gao | 6d69ff9 | 2020-01-13 13:20:34 -0500 | [diff] [blame] | 229 | |
| 230 | To avoid inconsistent versions between the database and policies deployed in the PDPs, policy API REST service employs some enforcement |
| 231 | rules that validate the version specified in the POST payload when a new version is to create or an existing version to update. |
| 232 | Policy API will not blindly override the version of the policy or policy type to create/update. |
| 233 | Instead, we encourage the client to carefully select a version for the policy or policy type to change and meanwhile policy API will check the validity |
| 234 | of the version and feed an informative warning back to the client if the specified version is not good. |
| 235 | To be specific, the following rules are implemented to enforce the version: |
| 236 | |
Chenfei Gao | 7984ada | 2020-03-17 22:34:15 -0400 | [diff] [blame] | 237 | 1. If the incoming version is not in the database, we simply insert it. For example: if policy version 1.0.0 is stored in the database and now |
Chenfei Gao | 6d69ff9 | 2020-01-13 13:20:34 -0500 | [diff] [blame] | 238 | a client wants to create the same policy with updated version 3.0.0, this POST call will succeed and return "200" to the client. |
| 239 | |
Chenfei Gao | 7984ada | 2020-03-17 22:34:15 -0400 | [diff] [blame] | 240 | 2. If the incoming version is already in the database and the incoming payload is different from the same version in the database, |
| 241 | "406 - Not Acceptable" will be returned. This forces the client to update the version of the policy if the policy is changed. |
Chenfei Gao | 6d69ff9 | 2020-01-13 13:20:34 -0500 | [diff] [blame] | 242 | |
Chenfei Gao | 7984ada | 2020-03-17 22:34:15 -0400 | [diff] [blame] | 243 | 3. If a client creates a version of a policy and wishes to update a property on the policy, they must delete that version of the policy and re-create it. |
| 244 | |
| 245 | 4. If multiple policies are included in the POST payload, policy API will also check if duplicate version exists in between |
Chenfei Gao | 6d69ff9 | 2020-01-13 13:20:34 -0500 | [diff] [blame] | 246 | any two policies or policy types provided in the payload. For example, a client provides a POST payload which includes two policies with the same |
| 247 | name and version but different policy properties. This POST call will fail and return "406" error back to the calling application along with a |
| 248 | message such as "duplicate policy {name}:{version} found in the payload". |
| 249 | |
Chenfei Gao | 7984ada | 2020-03-17 22:34:15 -0400 | [diff] [blame] | 250 | 5. The same version validation is applied to policy types too. |
Chenfei Gao | 6d69ff9 | 2020-01-13 13:20:34 -0500 | [diff] [blame] | 251 | |
Chenfei Gao | 7984ada | 2020-03-17 22:34:15 -0400 | [diff] [blame] | 252 | 6. To avoid unnecessary id/version inconsistency between the ones specified in the entity fields and the ones returned in the metadata field, |
Chenfei Gao | 6d69ff9 | 2020-01-13 13:20:34 -0500 | [diff] [blame] | 253 | "policy-id" and "policy-version" in the metadata will only be set by policy API. Any incoming explicit specification in the POST payload will be |
| 254 | ignored. For example, A POST payload has a policy with name "sample-policy-name1" and version "1.0.0" specified. In this policy, the metadata |
| 255 | 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 |
| 256 | metadata including "policy-id": "sample-policy-name1" and "policy-version": "1.0.0". |
Chenfei Gao | af35b6a | 2019-05-21 17:40:21 -0400 | [diff] [blame] | 257 | |
Chenfei Gao | 7984ada | 2020-03-17 22:34:15 -0400 | [diff] [blame] | 258 | Regarding DELETE APIs for TOSCA compliant policies, we only expose API to delete one particular version of policy |
Chenfei Gao | 6d69ff9 | 2020-01-13 13:20:34 -0500 | [diff] [blame] | 259 | 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, |
Chenfei Gao | 7984ada | 2020-03-17 22:34:15 -0400 | [diff] [blame] | 260 | they will need to delete them one by one. |
Chenfei Gao | af35b6a | 2019-05-21 17:40:21 -0400 | [diff] [blame] | 261 | |
| 262 | Sample API Curl Commands |
| 263 | ------------------------- |
| 264 | |
liamfallon | e83e607 | 2020-05-06 13:09:09 +0100 | [diff] [blame] | 265 | From an API client perspective, using *http* or *https* does not make much difference to the curl command. |
Chenfei Gao | 6d69ff9 | 2020-01-13 13:20:34 -0500 | [diff] [blame] | 266 | 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. |
Chenfei Gao | af35b6a | 2019-05-21 17:40:21 -0400 | [diff] [blame] | 267 | JSON payload for POST calls can be downloaded from policy table above. |
| 268 | |
Pamela Dragosh | f65c8ff | 2020-04-29 08:23:12 -0400 | [diff] [blame] | 269 | If you are accessing the api from the container, the default *ip* and *port* would be **https:/policy-api:6969/policy/api/v1/**. |
| 270 | |
Chenfei Gao | af35b6a | 2019-05-21 17:40:21 -0400 | [diff] [blame] | 271 | Create vFirewall Monitoring Policy:: |
Pamela Dragosh | 5631660 | 2020-08-20 09:16:20 -0400 | [diff] [blame] | 272 | curl --user 'healthcheck: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 |
Chenfei Gao | af35b6a | 2019-05-21 17:40:21 -0400 | [diff] [blame] | 273 | |
| 274 | Get vFirewall Monitoring Policy:: |
Pamela Dragosh | 5631660 | 2020-08-20 09:16:20 -0400 | [diff] [blame] | 275 | curl --user 'healthcheck: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" |
Chenfei Gao | 7984ada | 2020-03-17 22:34:15 -0400 | [diff] [blame] | 276 | |
Chenfei Gao | af35b6a | 2019-05-21 17:40:21 -0400 | [diff] [blame] | 277 | Delete vFirewall Monitoring Policy:: |
Pamela Dragosh | 5631660 | 2020-08-20 09:16:20 -0400 | [diff] [blame] | 278 | curl --user 'healthcheck: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" |
Chenfei Gao | af35b6a | 2019-05-21 17:40:21 -0400 | [diff] [blame] | 279 | |
| 280 | Create vFirewall Operational Policy:: |
Chenfei Gao | 7984ada | 2020-03-17 22:34:15 -0400 | [diff] [blame] | 281 | 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 |
| 282 | |
Chenfei Gao | af35b6a | 2019-05-21 17:40:21 -0400 | [diff] [blame] | 283 | Get vFirewall Operational Policy:: |
Chenfei Gao | 7984ada | 2020-03-17 22:34:15 -0400 | [diff] [blame] | 284 | 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" |
| 285 | |
Chenfei Gao | af35b6a | 2019-05-21 17:40:21 -0400 | [diff] [blame] | 286 | Delete vFirewall Operational Policy:: |
Chenfei Gao | 7984ada | 2020-03-17 22:34:15 -0400 | [diff] [blame] | 287 | 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" |
puthuparambil.aditya | a6c09a2 | 2020-07-27 12:09:40 +0100 | [diff] [blame] | 288 | |
| 289 | Get all available policies:: |
| 290 | curl --user 'healthcheck:zb!XztG34' -X GET "http://{ip}:{port}/policy/api/v1/policies" -H "Accept: application/json" -H "Content-Type: application/json" |
| 291 | |
| 292 | Get version 1.0.0 of vFirewall Monitoring Policy:: |
| 293 | 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" |
| 294 | |
| 295 | Delete version 1.0.0 of vFirewall Monitoring Policy:: |
| 296 | 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" |