1 .. This work is licensed under a
2 .. Creative Commons Attribution 4.0 International License.
3 .. http://creativecommons.org/licenses/by/4.0
7 Policy Design and Development
8 #############################
13 This document describes the design principles that should be used to write, deploy, and run policies of various types
14 using the Policy Framework. It explains the APIs that are available for Policy Framework users. It provides copious
15 examples to illustrate policy design and API usage.
17 The figure below shows the Artifacts (Blue) in the ONAP Policy Framework, the Activities (Yellow) that manipulate them,
18 and important components (Salmon) that interact with them. The Policy Framework is fully TOSCA compliant, and uses
19 TOSCA to model policies. Please see the :ref:`TOSCA Policy Primer <tosca-label>` page for an introduction to TOSCA
22 .. image:: images/APIsInPolicyFramework.svg
24 TOSCA defines the concept of a *PolicyType*, the definition of a type of policy that can be applied to a service. It
25 also defines the concept of a *Policy*, an instance of a *PolicyType*. In the Policy Framework, we handle and manage
26 these TOSCA definitions and tie them to real implementations of policies that can run on PDPs.
28 The diagram above outlines how this is achieved. Each TOSCA *PolicyType* must have a corresponding *PolicyTypeImpl* in
29 the Policy Framework. The TOSCA *PolicyType* definition can be used to create a TOSCA *Policy* definition, either
30 directly by the Policy Framework, by CLAMP, or by some other system. Once the *Policy* artifact exists, it can be used
31 together with the *PolicyTypeImpl* artifact to create a *PolicyImpl* artifact. A *PolicyImpl* artifact is an executable
32 policy implementation that can run on a PDP.
34 The TOSCA *PolicyType* artifact defines the external characteristics of the policy; defining its properties, the types
35 of entities it acts on, and its triggers. A *PolicyTypeImpl* artifact is an XACML, Drools, or APEX implementation of
36 that policy definition. *PolicyType* and *PolicyTypeImpl* artifacts may be preloaded, may be loaded manually, or may be
37 created using the Lifecycle API. Alternatively, *PolicyType* definitions may be loaded over the Lifecycle API for
38 preloaded *PolicyTypeImpl* artifacts. A TOSCA *PolicyType* artifact can be used by clients (such as CLAMP or CLI tools)
39 to create, parse, serialize, and/or deserialize an actual Policy.
41 The TOSCA *Policy* artifact is used internally by the Policy Framework, or is input by CLAMP or other systems. This
42 artifact specifies the values of the properties for the policy and specifies the specific entities the policy acts on.
43 Policy Design uses the TOSCA *Policy* artifact and the *PolicyTypeImpl* artifact to create an executable *PolicyImpl*
49 Policy Type Design manages TOSCA *PolicyType* artifacts and their *PolicyTypeImpl* implementations.
51 A TOSCA *PolicyType* may ultimately be defined by the modeling team but for now are defined by the Policy Framework
52 project. Various editors and GUIs are available for creating *PolicyTypeImpl* implementations. However, systematic
53 integration of *PolicyTypeImpl* implementation is outside the scope of the ONAP Dublin release.
55 The *PolicyType* definitions and implementations listed below can be preloaded so that they are available for use in the
56 Policy Framework upon platform installation. For a full listing of available preloaded policy types, see the
57 :ref:`Policy API Preloaded Policy Type List <policy-preload-label>`.
59 ============================================ ===============================================================================
60 **Base Policy Types** **Description**
61 ============================================ ===============================================================================
62 onap.policies.Monitoring Base model that supports Policy driven DCAE microservice components used
64 onap.policies.controlloop.operational.Common Base Control Loop operational policy common definitions
65 onap.policies.controlloop.guard.Common Control Loop Guard Policy common definitions
66 onap.policies.Optimization Base OOF Optimization Policy Type definition
67 onap.policies.Naming Base SDNC Naming Policy Type definition
68 onap.policies.Native Base Native Policy Type for PDPs to inherit from in order to provide their own
70 ============================================ ===============================================================================
73 The El Alto onap.policies.controlloop.Guard policy types were deprecated and removed in Frankfurt.
75 1 Base Policy Type: onap.policies.Monitoring
76 --------------------------------------------
78 This is a base Policy Type that supports Policy driven DCAE microservice components used in a Control Loops. The
79 implementation of this Policy Type is done in the XACML PDP. The :ref:`Decision API <decision-api-label>` is used by the DCAE
80 Policy Handler to retrieve a decision on which policy to enforce during runtime.
83 :caption: Base Policy Type definition for onap.policies.Monitoring
86 tosca_definitions_version: tosca_simple_yaml_1_1_0
89 - onap.policies.Monitoring:
90 derived_from: tosca.policies.Root
92 description: a base policy type for all policies that govern monitoring provision
94 The *PolicyTypeImpl* implementation of the *onap.policies.Montoring* Policy Type is generic to support definition of
95 TOSCA *PolicyType* artifacts in the Policy Framework using the Policy Type Design API. Therefore many TOSCA *PolicyType*
96 artifacts will use the same *PolicyTypeImpl* implementation with different property types and towards different targets.
97 This allows dynamically generated DCAE microservice component Policy Types to be created at Design Time.
99 Please be sure to name your Policy Type appropriately by prepending it with **onap.policies.monitoring.Custom**.
100 Notice the lowercase **m** for monitoring, which follows TOSCA conventions. And also notice the capitalized "C" for
101 your analytics policy type name.
104 :caption: Example PolicyType *onap.policies.monitoring.MyDCAEComponent* derived from *onap.policies.Monitoring*
107 tosca_definitions_version: tosca_simple_yaml_1_1_0
109 - onap.policies.monitoring.Mycomponent:
110 derived_from: onap.policies.Monitoring
115 description: A description of this property
117 For more examples of monitoring policy type definitions, please refer to the examples in the `ONAP policy-models gerrit
118 repository <https://github.com/onap/policy-models/tree/master/models-examples/src/main/resources/policytypes>`__. Please
119 note that some of the examples do not adhere to TOSCA naming conventions due to backward compatibility.
122 2 Base Policy Type onap.policies.controlloop.operational.Common
123 ---------------------------------------------------------------
124 This is the new Operational Policy Type introduced in Frankfurt release to fully support TOSCA Policy Type. There are common
125 properties and datatypes that are independent of the PDP engine used to enforce this Policy Type.
127 .. image:: images/Operational.svg
128 :alt: Operational Policy Type Inheritance
130 2.1 onap.policies.controlloop.operational.common.Drools
131 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
133 Drools PDP Control Loop Operational Policy definition extends the base common policy type by adding a property for **controllerName**.
135 Please see the definition of the `Drools Operational Policy Type <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.operational.common.Drools.yaml>`_
138 2.2 onap.policies.controlloop.operational.common.Apex
139 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
141 Apex PDP Control Loop Operational Policy definition extends the base common policy type by adding additional properties.
143 Please see the definition of the `Apex Operational Policy Type <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.operational.common.Apex.yaml>`_
145 3 Base Policy Type: onap.policies.controlloop.guard.Common
146 ----------------------------------------------------------
148 This base policy type is the the type definition for Control Loop guard policies for frequency limiting, blacklisting and
149 min/max guards to help protect runtime Control Loop Actions from doing harm to the network. This policy type is
150 developed using the XACML PDP to support question/answer Policy Decisions during runtime for the Drools and APEX
151 onap.controlloop.Operational policy type implementations.
153 .. image:: images/Guard.svg
154 :alt: Guard Policy Type Inheritance
156 Please see the definition of the `Common Guard Policy Type <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.guard.Common.yaml>`_
158 3.1 Frequency Limiter Guard onap.policies.controlloop.guard.common.FrequencyLimiter
159 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
161 The frequency limiter supports limiting the frequency of actions being taken by an Actor.
163 Please see the definition of the `Guard Frequency Limiter Policy Type <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.guard.common.FrequencyLimiter.yaml>`_
165 3.2 Min/Max Guard onap.policies.controlloop.guard.common.MinMax
166 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
168 The Min/Max Guard supports Min/Max number of entity for scaling operations.
170 Please see the definition of the `Guard Min/Max Policy Type <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.guard.common.MinMax.yaml>`_
172 3.3 Blacklist Guard onap.policies.controlloop.guard.common.Blacklist
173 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
175 The Blacklist Guard Supports blacklisting control loop actions from being performed on specific entity id's.
177 Please see the definition of the `Guard Blacklist Policy Type <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.guard.common.Blacklist.yaml>`_
179 3.4 Filter Guard onap.policies.controlloop.guard.common.Filter
180 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
182 The Filter Guard Supports filtering control loop actions from being performed on specific entity id's.
184 Please see the definition of the `Guard Filter Policy Type <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.guard.common.Filter.yaml>`_
186 4 Optimization onap.policies.Optimization
187 -----------------------------------------
189 The Optimization Base Policy Type supports the OOF optimization policies. The Base policy Type has common properties shared
190 by all its derived policy types.
192 .. image:: images/Optimization.svg
193 :alt: Optimization Policy Type Inheritance
195 Please see the definition of the `Base Optimization Policy Type <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.Optimization.yaml>`_.
197 These Policy Types are unique in that some properties have an additional metadata property **matchable** set to **true**
198 which indicates that this property can be used to support more fine-grained Policy Decisions. For more information,
199 see the :ref:`XACML Optimization application implementation <xacml-optimization-label>`.
201 4.1 Optimization Service Policy Type onap.policies.optimization.Service
202 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
204 This policy type further extends the base onap.policies.Optimization type by defining additional properties specific to
205 a service. For more information:
207 `Service Optimization Base Policy Type <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.optimization.Service.yaml>`_
209 Several additional policy types inherit from the Service Optimization Policy Type. For more information, :ref:`XACML Optimization
210 application implementation <xacml-optimization-label>`.
212 4.2 Optimization Resource Policy Type onap.policies.optimization.Resource
213 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
215 This policy type further extends the base onap.policies.Optimization type by defining additional properties specific to
216 a resource. For more information:
218 `Resource Optimization Base Policy Type <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.optimization.Resource.yaml>`_
220 Several additional policy types inherit from the Resource Optimization Policy Type. For more information, :ref:`XACML Optimization
221 application implementation <xacml-optimization-label>`.
223 5 Naming onap.policies.Naming
224 -----------------------------
226 Naming policies are used in SDNC to enforce which naming policy should be used during instantiation.
228 Policies of this type are composed using the `Naming Policy Type Model <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.Naming.yaml>`_.
230 6 Native Policy Types onap.policies.Native
231 ------------------------------------------
233 This is the Base Policy Type used by PDP engines to support their native language policies. PDP engines inherit from
234 this base policy type to implement support for their own custom policy type:
238 tosca_definitions_version: tosca_simple_yaml_1_1_0
240 onap.policies.Native:
241 derived_from: tosca.policies.Root
242 description: a base policy type for all native PDP policies
245 6.1 Policy Type: onap.policies.native.drools.Controller
246 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
248 This policy type supports creation of native PDP-D controllers via policy. A controller is an abstraction on
249 the PDP-D that groups communication channels, message mapping rules, and
250 any other arbitrary configuration data to realize an application.
252 Policies of this type are composed using the
253 `onap.policies.native.drools.Controller policy type specification
254 <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.native.Drools.yaml>`__ specification.
256 6.2 Policy Type: onap.policies.native.drools.Artifact
257 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
259 This policy type supports the dynamic association of a native PDP-D controller with rules and dependent
260 java libraries. This policy type is used in conjuction with the onap.policies.native.drools.Controller
261 type to create or upgrade a drools application on a live PDP-D.
263 Policies of this type are composed against the
264 `onap.policies.native.drools.Controller policy type specification
265 <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.native.Drools.yaml>`__ specification.
267 6.3 Policy Type: onap.policies.native.Xacml
268 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
270 This policy type supports XACML OASIS 3.0 XML Policies. The policies are URL encoded in order to be easily transported via Lifecycle
271 API json and yaml Content-Types. When deployed to the XACML PDP (PDP-X), they will be managed by the **native** application. The PDP-X
272 will route XACML Request/Response RESTful API calls to the **native** application who manages those decisions.
274 `XACML Native Policy Type <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.native.Xacml.yaml>`_
276 6.4 Policy Type: onap.policies.native.Apex
277 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
279 This policy type supports Apex native policy types.
281 `Apex Native Policy Type <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.native.Apex.yaml>`_