1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
|
.. This work is licensed under a
.. Creative Commons Attribution 4.0 International License.
.. http://creativecommons.org/licenses/by/4.0
.. _design-label:
Policy Design and Development
#############################
.. contents::
:depth: 4
This document describes the design principles that should be used to write, deploy, and run policies of various types
using the Policy Framework. It explains the APIs that are available for Policy Framework users. It provides copious
examples to illustrate policy design and API usage.
The figure below shows the Artifacts (Blue) in the ONAP Policy Framework, the Activities (Yellow) that manipulate them,
and important components (Salmon) that interact with them. The Policy Framework is fully TOSCA compliant, and uses
TOSCA to model policies. Please see the :ref:`TOSCA Policy Primer <tosca-label>` page for an introduction to TOSCA
policy concepts.
.. image:: images/APIsInPolicyFramework.svg
TOSCA defines the concept of a *PolicyType*, the definition of a type of policy that can be applied to a service. It
also defines the concept of a *Policy*, an instance of a *PolicyType*. In the Policy Framework, we handle and manage
these TOSCA definitions and tie them to real implementations of policies that can run on PDPs.
The diagram above outlines how this is achieved. Each TOSCA *PolicyType* must have a corresponding *PolicyTypeImpl* in
the Policy Framework. The TOSCA *PolicyType* definition can be used to create a TOSCA *Policy* definition, either
directly by the Policy Framework, by CLAMP, or by some other system. Once the *Policy* artifact exists, it can be used
together with the *PolicyTypeImpl* artifact to create a *PolicyImpl* artifact. A *PolicyImpl* artifact is an executable
policy implementation that can run on a PDP.
The TOSCA *PolicyType* artifact defines the external characteristics of the policy; defining its properties, the types
of entities it acts on, and its triggers. A *PolicyTypeImpl* artifact is an XACML, Drools, or APEX implementation of
that policy definition. *PolicyType* and *PolicyTypeImpl* artifacts may be preloaded, may be loaded manually, or may be
created using the Lifecycle API. Alternatively, *PolicyType* definitions may be loaded over the Lifecycle API for
preloaded *PolicyTypeImpl* artifacts. A TOSCA *PolicyType* artifact can be used by clients (such as CLAMP or CLI tools)
to create, parse, serialize, and/or deserialize an actual Policy.
The TOSCA *Policy* artifact is used internally by the Policy Framework, or is input by CLAMP or other systems. This
artifact specifies the values of the properties for the policy and specifies the specific entities the policy acts on.
Policy Design uses the TOSCA *Policy* artifact and the *PolicyTypeImpl* artifact to create an executable *PolicyImpl*
artifact.
ONAP Policy Types
=================
Policy Type Design manages TOSCA *PolicyType* artifacts and their *PolicyTypeImpl* implementations.
A TOSCA *PolicyType* may ultimately be defined by the modeling team but for now are defined by the Policy Framework
project. Various editors and GUIs are available for creating *PolicyTypeImpl* implementations. However, systematic
integration of *PolicyTypeImpl* implementation is outside the scope of the ONAP Dublin release.
The *PolicyType* definitions and implementations listed below can be preloaded so that they are available for use in the
Policy Framework upon platform installation. For a full listing of available preloaded policy types, see the
:ref:`Policy API Preloaded Policy Type List <policy-preload-label>`.
============================================ ===============================================================================
**Base Policy Types** **Description**
============================================ ===============================================================================
onap.policies.Monitoring Base model that supports Policy driven DCAE microservice components used
in Control Loops
onap.policies.controlloop.Operational Legacy actor/action operational policies for control loops (Deprecated)
onap.policies.controlloop.operational.Common Base Control Loop operational policy common definitions
onap.policies.controlloop.guard.Common Control Loop Guard Policy common definitions
onap.policies.Optimization Base OOF Optimization Policy Type definition
onap.policies.Naming Base SDNC Naming Policy Type definition
onap.policies.Native Base Native Policy Type for PDPs to inherit from in order to provide their own
native policy type.
============================================ ===============================================================================
.. note::
The El Alto onap.policies.controlloop.Guard policy types were deprecated and removed in Frankfurt.
1 Base Policy Type: onap.policies.Monitoring
--------------------------------------------
This is a base Policy Type that supports Policy driven DCAE microservice components used in a Control Loops. The
implementation of this Policy Type is done in the XACML PDP. The :ref:`Decision API <decision-api-label>` is used by the DCAE
Policy Handler to retrieve a decision on which policy to enforce during runtime.
.. code-block:: yaml
:caption: Base Policy Type definition for onap.policies.Monitoring
:linenos:
tosca_definitions_version: tosca_simple_yaml_1_1_0
topology_template:
policy_types:
- onap.policies.Monitoring:
derived_from: tosca.policies.Root
version: 1.0.0
description: a base policy type for all policies that govern monitoring provision
The *PolicyTypeImpl* implementation of the *onap.policies.Montoring* Policy Type is generic to support definition of
TOSCA *PolicyType* artifacts in the Policy Framework using the Policy Type Design API. Therefore many TOSCA *PolicyType*
artifacts will use the same *PolicyTypeImpl* implementation with different property types and towards different targets.
This allows dynamically generated DCAE microservice component Policy Types to be created at Design Time.
Please be sure to name your Policy Type appropriately by prepending it with **onap.policies.monitoring.Custom**.
Notice the lowercase **m** for monitoring, which follows TOSCA conventions. And also notice the capitalized "C" for
your analytics policy type name.
.. code-block:: yaml
:caption: Example PolicyType *onap.policies.monitoring.MyDCAEComponent* derived from *onap.policies.Monitoring*
:linenos:
tosca_definitions_version: tosca_simple_yaml_1_1_0
policy_types:
- onap.policies.monitoring.Mycomponent:
derived_from: onap.policies.Monitoring
version: 1.0.0
properties:
my_property_1:
type: string
description: A description of this property
For more examples of monitoring policy type definitions, please refer to the examples in the `ONAP policy-models gerrit
repository <https://github.com/onap/policy-models/tree/master/models-examples/src/main/resources/policytypes>`__. Please
note that some of the examples do not adhere to TOSCA naming conventions due to backward compatibility.
2 Base Policy Type onap.policies.controlloop.operational.Common
---------------------------------------------------------------
This is the new Operational Policy Type introduced in Frankfurt release to fully support TOSCA Policy Type. There are common
properties and datatypes that are independent of the PDP engine used to enforce this Policy Type.
.. image:: images/Operational.svg
:alt: Operational Policy Type Inheritance
2.1 onap.policies.controlloop.operational.common.Drools
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Drools PDP Control Loop Operational Policy definition extends the base common policy type by adding a property for **controllerName**.
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>`_
2.2 onap.policies.controlloop.operational.common.Apex
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Apex PDP Control Loop Operational Policy definition extends the base common policy type by adding additional properties.
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>`_
3 Base Policy Type: onap.policies.controlloop.guard.Common
----------------------------------------------------------
This base policy type is the the type definition for Control Loop guard policies for frequency limiting, blacklisting and
min/max guards to help protect runtime Control Loop Actions from doing harm to the network. This policy type is
developed using the XACML PDP to support question/answer Policy Decisions during runtime for the Drools and APEX
onap.controlloop.Operational policy type implementations.
.. image:: images/Guard.svg
:alt: Guard Policy Type Inheritance
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>`_
3.1 Frequency Limiter Guard onap.policies.controlloop.guard.common.FrequencyLimiter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The frequency limiter supports limiting the frequency of actions being taken by an Actor.
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>`_
3.2 Min/Max Guard onap.policies.controlloop.guard.common.MinMax
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The Min/Max Guard supports Min/Max number of entity for scaling operations.
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>`_
3.3 Blacklist Guard onap.policies.controlloop.guard.common.Blacklist
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The Blacklist Guard Supports blacklisting control loop actions from being performed on specific entity id's.
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>`_
4 Optimization onap.policies.Optimization
-----------------------------------------
The Optimization Base Policy Type supports the OOF optimization policies. The Base policy Type has common properties shared
by all its derived policy types.
.. image:: images/Optimization.svg
:alt: Optimization Policy Type Inheritance
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>`_.
These Policy Types are unique in that some properties have an additional metadata property **matchable** set to **true**
which indicates that this property can be used to support more fine-grained Policy Decisions. For more information,
see the :ref:`XACML Optimization application implementation <xacml-optimization-label>`.
4.1 Optimization Service Policy Type onap.policies.optimization.Service
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This policy type further extends the base onap.policies.Optimization type by defining additional properties specific to
a service. For more information:
`Service Optimization Base Policy Type <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.optimization.Service.yaml>`_
Several additional policy types inherit from the Service Optimization Policy Type. For more information, :ref:`XACML Optimization
application implementation <xacml-optimization-label>`.
4.2 Optimization Resource Policy Type onap.policies.optimization.Resource
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This policy type further extends the base onap.policies.Optimization type by defining additional properties specific to
a resource. For more information:
`Resource Optimization Base Policy Type <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.optimization.Resource.yaml>`_
Several additional policy types inherit from the Resource Optimization Policy Type. For more information, :ref:`XACML Optimization
application implementation <xacml-optimization-label>`.
5 Naming onap.policies.Naming
-----------------------------
Naming policies are used in SDNC to enforce which naming policy should be used during instantiation.
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>`_.
6 Native Policy Types onap.policies.Native
------------------------------------------
This is the Base Policy Type used by PDP engines to support their native language policies. PDP engines inherit from
this base policy type to implement support for their own custom policy type:
.. code-block:: yaml
tosca_definitions_version: tosca_simple_yaml_1_1_0
policy_types:
onap.policies.Native:
derived_from: tosca.policies.Root
description: a base policy type for all native PDP policies
version: 1.0.0
6.1 Policy Type: onap.policies.native.drools.Controller
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This policy type supports creation of native PDP-D controllers via policy. A controller is an abstraction on
the PDP-D that groups communication channels, message mapping rules, and
any other arbitrary configuration data to realize an application.
Policies of this type are composed using the
`onap.policies.native.drools.Controller policy type specification
<https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.native.Drools.yaml>`__ specification.
6.2 Policy Type: onap.policies.native.drools.Artifact
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This policy type supports the dynamic association of a native PDP-D controller with rules and dependent
java libraries. This policy type is used in conjuction with the onap.policies.native.drools.Controller
type to create or upgrade a drools application on a live PDP-D.
Policies of this type are composed against the
`onap.policies.native.drools.Controller policy type specification
<https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.native.Drools.yaml>`__ specification.
6.3 Policy Type: onap.policies.native.Xacml
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This policy type supports XACML OASIS 3.0 XML Policies. The policies are URL encoded in order to be easily transported via Lifecycle
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
will route XACML Request/Response RESTful API calls to the **native** application who manages those decisions.
`XACML Native Policy Type <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.native.Xacml.yaml>`_
6.4 Policy Type: onap.policies.native.Apex
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This policy type supports Apex native policy types.
`Apex Native Policy Type <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.native.Apex.yaml>`_
7 Base Policy Type: onap.policies.controlloop.Operational (Deprecated)
----------------------------------------------------------------------
This policy type is used to support legacy YAML definitions for actor/action operational policies for control loops.
There are two types of implementations for this policy type:
1. Drools implementations that support runtime Control Loop actions taken on components such as SO/APPC/VFC/SDNC/SDNR
2. Implementations using APEX to support Control Loops.
.. note::
This policy type will be deprecated after Frankfurt and is discouraged from being used.
.. code-block:: yaml
:caption: Base Policy Type definition for onap.policies.controlloop.Operational
:linenos:
tosca_definitions_version: tosca_simple_yaml_1_1_0
policy_types:
- onap.policies.controlloop.Operational:
derived_from: tosca.policies.Root
version: 1.0.0
description: Operational Policy for Control Loops
There are no properties defined for this policy type, instead it is expected that the user submit the REST call with a
special JSON format used to bridge the Casablanca Legacy API to the new Lifecycle API introduced in Dublin release.
.. code-block:: json
:caption: Example Policy Payload for onap.policies.controlloop.Operational Policy Type
{
"policy-id" : "operational.restart",
"policy-version" : "1",
"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",
"controllerName" : "frankfurt"
}
For the **"content"** property, please refer to the `YAML Operational Policy format
<https://github.com/onap/policy-models/blob/master/models-interactions/model-yaml/README-v2.0.0.md>`__ to define the
**content** field and URL Encode the yaml.
|
