docs/design/design.rst

   1 .. This work is licensed under a
   2 .. Creative Commons Attribution 4.0 International License.
   3 .. http://creativecommons.org/licenses/by/4.0
   4
   5 .. _design-label:
   6
   7 Policy Design and Development
   8 #############################
   9
  10 .. contents::
  11     :depth: 4
  12
  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.
  16
  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
  20 policy concepts.
  21
  22 .. image:: images/APIsInPolicyFramework.svg
  23
  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.
  27
  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.
  33
  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.
  40
  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*
  44 artifact.
  45
  46 ONAP Policy Types
  47 =================
  48
  49 Policy Type Design manages TOSCA *PolicyType* artifacts and their *PolicyTypeImpl* implementations.
  50
  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.
  54
  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>`.
  58
  59 ============================================             ===============================================================================
  60 **Base Policy Types**                                    **Description**
  61 ============================================             ===============================================================================
  62 onap.policies.Monitoring                                 Base model that supports Policy driven DCAE microservice components used
  63                                                          in Control Loops
  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
  69                                                          native policy type.
  70 ============================================             ===============================================================================
  71
  72 .. note::
  73    The El Alto onap.policies.controlloop.Guard policy types were deprecated and removed in Frankfurt.
  74
  75 1 Base Policy Type: onap.policies.Monitoring
  76 --------------------------------------------
  77
  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.
  81
  82 .. code-block:: yaml
  83   :caption: Base Policy Type definition for onap.policies.Monitoring
  84   :linenos:
  85
  86   tosca_definitions_version: tosca_simple_yaml_1_1_0
  87   topology_template:
  88     policy_types:
  89       - onap.policies.Monitoring:
  90           derived_from: tosca.policies.Root
  91           version: 1.0.0
  92           description: a base policy type for all policies that govern monitoring provision
  93
  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.
  98
  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.
 102
 103 .. code-block:: yaml
 104   :caption: Example PolicyType *onap.policies.monitoring.MyDCAEComponent* derived from *onap.policies.Monitoring*
 105   :linenos:
 106
 107   tosca_definitions_version: tosca_simple_yaml_1_1_0
 108   policy_types:
 109    - onap.policies.monitoring.Mycomponent:
 110         derived_from: onap.policies.Monitoring
 111         version: 1.0.0
 112         properties:
 113             my_property_1:
 114             type: string
 115             description: A description of this property
 116
 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.
 120
 121
 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.
 126
 127 .. image:: images/Operational.svg
 128    :alt:  Operational Policy Type Inheritance
 129
 130 2.1 onap.policies.controlloop.operational.common.Drools
 131 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 132
 133 Drools PDP Control Loop Operational Policy definition extends the base common policy type by adding a property for **controllerName**.
 134
 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>`_
 136
 137
 138 2.2 onap.policies.controlloop.operational.common.Apex
 139 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 140
 141 Apex PDP Control Loop Operational Policy definition extends the base common policy type by adding additional properties.
 142
 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>`_
 144
 145 3 Base Policy Type: onap.policies.controlloop.guard.Common
 146 ----------------------------------------------------------
 147
 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.
 152
 153 .. image:: images/Guard.svg
 154    :alt:  Guard Policy Type Inheritance
 155
 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>`_
 157
 158 3.1 Frequency Limiter Guard onap.policies.controlloop.guard.common.FrequencyLimiter
 159 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 160
 161 The frequency limiter supports limiting the frequency of actions being taken by an Actor.
 162
 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>`_
 164
 165 3.2 Min/Max Guard onap.policies.controlloop.guard.common.MinMax
 166 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 167
 168 The Min/Max Guard supports Min/Max number of entity for scaling operations.
 169
 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>`_
 171
 172 3.3 Blacklist Guard onap.policies.controlloop.guard.common.Blacklist
 173 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 174
 175 The Blacklist Guard Supports blacklisting control loop actions from being performed on specific entity id's.
 176
 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>`_
 178
 179 4 Optimization onap.policies.Optimization
 180 -----------------------------------------
 181
 182 The Optimization Base Policy Type supports the OOF optimization policies. The Base policy Type has common properties shared
 183 by all its derived policy types.
 184
 185 .. image:: images/Optimization.svg
 186    :alt:  Optimization Policy Type Inheritance
 187
 188 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>`_.
 189
 190 These Policy Types are unique in that some properties have an additional metadata property **matchable** set to **true**
 191 which indicates that this property can be used to support more fine-grained Policy Decisions. For more information,
 192 see the :ref:`XACML Optimization application implementation <xacml-optimization-label>`.
 193
 194 4.1 Optimization Service Policy Type onap.policies.optimization.Service
 195 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 196
 197 This policy type further extends the base onap.policies.Optimization type by defining additional properties specific to
 198 a service. For more information:
 199
 200 `Service Optimization Base Policy Type <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.optimization.Service.yaml>`_
 201
 202 Several additional policy types inherit from the Service Optimization Policy Type. For more information, :ref:`XACML Optimization
 203 application implementation <xacml-optimization-label>`.
 204
 205 4.2 Optimization Resource Policy Type onap.policies.optimization.Resource
 206 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 207
 208 This policy type further extends the base onap.policies.Optimization type by defining additional properties specific to
 209 a resource. For more information:
 210
 211 `Resource Optimization Base Policy Type <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.optimization.Resource.yaml>`_
 212
 213 Several additional policy types inherit from the Resource Optimization Policy Type. For more information, :ref:`XACML Optimization
 214 application implementation <xacml-optimization-label>`.
 215
 216 5 Naming onap.policies.Naming
 217 -----------------------------
 218
 219 Naming policies are used in SDNC to enforce which naming policy should be used during instantiation.
 220
 221 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>`_.
 222
 223 6 Native Policy Types onap.policies.Native
 224 ------------------------------------------
 225
 226 This is the Base Policy Type used by PDP engines to support their native language policies. PDP engines inherit from
 227 this base policy type to implement support for their own custom policy type:
 228
 229 ..  code-block:: yaml
 230
 231   tosca_definitions_version: tosca_simple_yaml_1_1_0
 232   policy_types:
 233       onap.policies.Native:
 234           derived_from: tosca.policies.Root
 235           description: a base policy type for all native PDP policies
 236           version: 1.0.0
 237
 238 6.1 Policy Type: onap.policies.native.drools.Controller
 239 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 240
 241 This policy type supports creation of native PDP-D controllers via policy.   A controller is an abstraction on
 242 the PDP-D that groups communication channels, message mapping rules, and
 243 any other arbitrary configuration data to realize an application.
 244
 245 Policies of this type are composed using the
 246 `onap.policies.native.drools.Controller policy type specification
 247 <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.native.Drools.yaml>`__ specification.
 248
 249 6.2 Policy Type: onap.policies.native.drools.Artifact
 250 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 251
 252 This policy type supports the dynamic association of a native PDP-D controller with rules and dependent
 253 java libraries.   This policy type is used in conjuction with the onap.policies.native.drools.Controller
 254 type to create or upgrade a drools application on a live PDP-D.
 255
 256 Policies of this type are composed against the
 257 `onap.policies.native.drools.Controller policy type specification
 258 <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.native.Drools.yaml>`__ specification.
 259
 260 6.3 Policy Type: onap.policies.native.Xacml
 261 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 262
 263 This policy type supports XACML OASIS 3.0 XML Policies. The policies are URL encoded in order to be easily transported via Lifecycle
 264 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
 265 will route XACML Request/Response RESTful API calls to the **native** application who manages those decisions.
 266
 267 `XACML Native Policy Type <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.native.Xacml.yaml>`_
 268
 269 6.4 Policy Type: onap.policies.native.Apex
 270 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 271
 272 This policy type supports Apex native policy types.
 273
 274 `Apex Native Policy Type <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.native.Apex.yaml>`_