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 Legacy actor/action operational policies for control loops (Deprecated)
65 onap.policies.controlloop.operational.Common Base Control Loop operational policy common definitions
66 onap.policies.controlloop.guard.Common Control Loop Guard Policy common definitions
67 onap.policies.Optimization Base OOF Optimization Policy Type definition
68 onap.policies.Naming Base SDNC Naming Policy Type definition
69 onap.policies.Native Base Native Policy Type for PDPs to inherit from in order to provide their own
71 ============================================ ===============================================================================
74 The El Alto onap.policies.controlloop.Guard policy types were deprecated and removed in Frankfurt.
76 1 Base Policy Type: onap.policies.Monitoring
77 --------------------------------------------
79 This is a base Policy Type that supports Policy driven DCAE microservice components used in a Control Loops. The
80 implementation of this Policy Type is done in the XACML PDP. The :ref:`Decision API <decision-api-label>` is used by the DCAE
81 Policy Handler to retrieve a decision on which policy to enforce during runtime.
84 :caption: Base Policy Type definition for onap.policies.Monitoring
87 tosca_definitions_version: tosca_simple_yaml_1_1_0
90 - onap.policies.Monitoring:
91 derived_from: tosca.policies.Root
93 description: a base policy type for all policies that govern monitoring provision
95 The *PolicyTypeImpl* implementation of the *onap.policies.Montoring* Policy Type is generic to support definition of
96 TOSCA *PolicyType* artifacts in the Policy Framework using the Policy Type Design API. Therefore many TOSCA *PolicyType*
97 artifacts will use the same *PolicyTypeImpl* implementation with different property types and towards different targets.
98 This allows dynamically generated DCAE microservice component Policy Types to be created at Design Time.
100 Please be sure to name your Policy Type appropriately by prepending it with **onap.policies.monitoring.Custom**.
101 Notice the lowercase **m** for monitoring, which follows TOSCA conventions. And also notice the capitalized "C" for
102 your analytics policy type name.
105 :caption: Example PolicyType *onap.policies.monitoring.MyDCAEComponent* derived from *onap.policies.Monitoring*
108 tosca_definitions_version: tosca_simple_yaml_1_1_0
110 - onap.policies.monitoring.Mycomponent:
111 derived_from: onap.policies.Monitoring
116 description: A description of this property
118 For more examples of monitoring policy type definitions, please refer to the examples in the `ONAP policy-models gerrit
119 repository <https://github.com/onap/policy-models/tree/master/models-examples/src/main/resources/policytypes>`__. Please
120 note that some of the examples do not adhere to TOSCA naming conventions due to backward compatibility.
123 2 Base Policy Type onap.policies.controlloop.operational.Common
124 ---------------------------------------------------------------
125 This is the new Operational Policy Type introduced in Frankfurt release to fully support TOSCA Policy Type. There are common
126 properties and datatypes that are independent of the PDP engine used to enforce this Policy Type.
128 .. image:: images/Operational.svg
129 :alt: Operational Policy Type Inheritance
131 2.1 onap.policies.controlloop.operational.common.Drools
132 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
134 Drools PDP Control Loop Operational Policy definition extends the base common policy type by adding a property for **controllerName**.
136 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>`_
139 2.2 onap.policies.controlloop.operational.common.Apex
140 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
142 Apex PDP Control Loop Operational Policy definition extends the base common policy type by adding additional properties.
144 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>`_
146 3 Base Policy Type: onap.policies.controlloop.guard.Common
147 ----------------------------------------------------------
149 This base policy type is the the type definition for Control Loop guard policies for frequency limiting, blacklisting and
150 min/max guards to help protect runtime Control Loop Actions from doing harm to the network. This policy type is
151 developed using the XACML PDP to support question/answer Policy Decisions during runtime for the Drools and APEX
152 onap.controlloop.Operational policy type implementations.
154 .. image:: images/Guard.svg
155 :alt: Guard Policy Type Inheritance
157 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>`_
159 3.1 Frequency Limiter Guard onap.policies.controlloop.guard.common.FrequencyLimiter
160 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
162 The frequency limiter supports limiting the frequency of actions being taken by an Actor.
164 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>`_
166 3.2 Min/Max Guard onap.policies.controlloop.guard.common.MinMax
167 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
169 The Min/Max Guard supports Min/Max number of entity for scaling operations.
171 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>`_
173 3.3 Blacklist Guard onap.policies.controlloop.guard.common.Blacklist
174 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
176 The Blacklist Guard Supports blacklisting control loop actions from being performed on specific entity id's.
178 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>`_
180 4 Optimization onap.policies.Optimization
181 -----------------------------------------
183 The Optimization Base Policy Type supports the OOF optimization policies. The Base policy Type has common properties shared
184 by all its derived policy types.
186 .. image:: images/Optimization.svg
187 :alt: Optimization Policy Type Inheritance
189 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>`_.
191 These Policy Types are unique in that some properties have an additional metadata property **matchable** set to **true**
192 which indicates that this property can be used to support more fine-grained Policy Decisions. For more information,
193 see the :ref:`XACML Optimization application implementation <xacml-optimization-label>`.
195 4.1 Optimization Service Policy Type onap.policies.optimization.Service
196 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
198 This policy type further extends the base onap.policies.Optimization type by defining additional properties specific to
199 a service. For more information:
201 `Service Optimization Base Policy Type <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.optimization.Service.yaml>`_
203 Several additional policy types inherit from the Service Optimization Policy Type. For more information, :ref:`XACML Optimization
204 application implementation <xacml-optimization-label>`.
206 4.2 Optimization Resource Policy Type onap.policies.optimization.Resource
207 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
209 This policy type further extends the base onap.policies.Optimization type by defining additional properties specific to
210 a resource. For more information:
212 `Resource Optimization Base Policy Type <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.optimization.Resource.yaml>`_
214 Several additional policy types inherit from the Resource Optimization Policy Type. For more information, :ref:`XACML Optimization
215 application implementation <xacml-optimization-label>`.
217 5 Naming onap.policies.Naming
218 -----------------------------
220 Naming policies are used in SDNC to enforce which naming policy should be used during instantiation.
222 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>`_.
224 6 Native Policy Types onap.policies.Native
225 ------------------------------------------
227 This is the Base Policy Type used by PDP engines to support their native language policies. PDP engines inherit from
228 this base policy type to implement support for their own custom policy type:
232 tosca_definitions_version: tosca_simple_yaml_1_1_0
234 onap.policies.Native:
235 derived_from: tosca.policies.Root
236 description: a base policy type for all native PDP policies
239 6.1 Policy Type: onap.policies.native.drools.Controller
240 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
242 This policy type supports creation of native PDP-D controllers via policy. A controller is an abstraction on
243 the PDP-D that groups communication channels, message mapping rules, and
244 any other arbitrary configuration data to realize an application.
246 Policies of this type are composed using the
247 `onap.policies.native.drools.Controller policy type specification
248 <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.native.Drools.yaml>`__ specification.
250 6.2 Policy Type: onap.policies.native.drools.Artifact
251 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
253 This policy type supports the dynamic association of a native PDP-D controller with rules and dependent
254 java libraries. This policy type is used in conjuction with the onap.policies.native.drools.Controller
255 type to create or upgrade a drools application on a live PDP-D.
257 Policies of this type are composed against the
258 `onap.policies.native.drools.Controller policy type specification
259 <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.native.Drools.yaml>`__ specification.
261 6.3 Policy Type: onap.policies.native.Xacml
262 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
264 This policy type supports XACML OASIS 3.0 XML Policies. The policies are URL encoded in order to be easily transported via Lifecycle
265 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
266 will route XACML Request/Response RESTful API calls to the **native** application who manages those decisions.
268 `XACML Native Policy Type <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.native.Xacml.yaml>`_
270 6.4 Policy Type: onap.policies.native.Apex
271 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
273 This policy type supports Apex native policy types.
275 `Apex Native Policy Type <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.native.Apex.yaml>`_
278 7 Base Policy Type: onap.policies.controlloop.Operational (Deprecated)
279 ----------------------------------------------------------------------
281 This policy type is used to support legacy YAML definitions for actor/action operational policies for control loops.
282 There are two types of implementations for this policy type:
284 1. Drools implementations that support runtime Control Loop actions taken on components such as SO/APPC/VFC/SDNC/SDNR
285 2. Implementations using APEX to support Control Loops.
288 This policy type will be deprecated after Frankfurt and is discouraged from being used.
291 :caption: Base Policy Type definition for onap.policies.controlloop.Operational
294 tosca_definitions_version: tosca_simple_yaml_1_1_0
296 - onap.policies.controlloop.Operational:
297 derived_from: tosca.policies.Root
299 description: Operational Policy for Control Loops
301 There are no properties defined for this policy type, instead it is expected that the user submit the REST call with a
302 special JSON format used to bridge the Casablanca Legacy API to the new Lifecycle API introduced in Dublin release.
305 :caption: Example Policy Payload for onap.policies.controlloop.Operational Policy Type
308 "policy-id" : "operational.restart",
309 "policy-version" : "1",
310 "content" : "controlLoop%3A%0A%20%20version%3A%202.0.0%0A%20%20controlLoopName%3A%20ControlLoop-vCPE-48f0c2c3-a172-4192-9ae3-052274181b6e%0A%20%20trigger_policy%3A%20unique-policy-id-1-restart%0A%20%20timeout%3A%203600%0A%20%20abatement%3A%20true%0A%20%0Apolicies%3A%0A%20%20-%20id%3A%20unique-policy-id-1-restart%0A%20%20%20%20name%3A%20Restart%20the%20VM%0A%20%20%20%20description%3A%0A%20%20%20%20actor%3A%20APPC%0A%20%20%20%20recipe%3A%20Restart%0A%20%20%20%20target%3A%0A%20%20%20%20%20%20type%3A%20VM%0A%20%20%20%20retry%3A%203%0A%20%20%20%20timeout%3A%201200%0A%20%20%20%20success%3A%20final_success%0A%20%20%20%20failure%3A%20final_failure%0A%20%20%20%20failure_timeout%3A%20final_failure_timeout%0A%20%20%20%20failure_retries%3A%20final_failure_retries%0A%20%20%20%20failure_exception%3A%20final_failure_exception%0A%20%20%20%20failure_guard%3A%20final_failure_guard",
311 "controllerName" : "frankfurt"
314 For the **"content"** property, please refer to the `YAML Operational Policy format
315 <https://github.com/onap/policy-models/blob/master/models-interactions/model-yaml/README-v2.0.0.md>`__ to define the
316 **content** field and URL Encode the yaml.