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                    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
  70                                                          native policy type.
  71 ============================================             ===============================================================================
  72
  73 .. note::
  74    The El Alto onap.policies.controlloop.Guard policy types were deprecated and removed in Frankfurt.
  75
  76 1 Base Policy Type: onap.policies.Monitoring
  77 --------------------------------------------
  78
  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.
  82
  83 .. code-block:: yaml
  84   :caption: Base Policy Type definition for onap.policies.Monitoring
  85   :linenos:
  86
  87   tosca_definitions_version: tosca_simple_yaml_1_1_0
  88   topology_template:
  89     policy_types:
  90       - onap.policies.Monitoring:
  91           derived_from: tosca.policies.Root
  92           version: 1.0.0
  93           description: a base policy type for all policies that govern monitoring provision
  94
  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.
  99
 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.
 103
 104 .. code-block:: yaml
 105   :caption: Example PolicyType *onap.policies.monitoring.MyDCAEComponent* derived from *onap.policies.Monitoring*
 106   :linenos:
 107
 108   tosca_definitions_version: tosca_simple_yaml_1_1_0
 109   policy_types:
 110    - onap.policies.monitoring.Mycomponent:
 111         derived_from: onap.policies.Monitoring
 112         version: 1.0.0
 113         properties:
 114             my_property_1:
 115             type: string
 116             description: A description of this property
 117
 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.
 121
 122
 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.
 127
 128 .. image:: images/Operational.svg
 129    :alt:  Operational Policy Type Inheritance
 130
 131 2.1 onap.policies.controlloop.operational.common.Drools
 132 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 133
 134 Drools PDP Control Loop Operational Policy definition extends the base common policy type by adding a property for **controllerName**.
 135
 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>`_
 137
 138
 139 2.2 onap.policies.controlloop.operational.common.Apex
 140 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 141
 142 Apex PDP Control Loop Operational Policy definition extends the base common policy type by adding additional properties.
 143
 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>`_
 145
 146 3 Base Policy Type: onap.policies.controlloop.guard.Common
 147 ----------------------------------------------------------
 148
 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.
 153
 154 .. image:: images/Guard.svg
 155    :alt:  Guard Policy Type Inheritance
 156
 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>`_
 158
 159 3.1 Frequency Limiter Guard onap.policies.controlloop.guard.common.FrequencyLimiter
 160 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 161
 162 The frequency limiter supports limiting the frequency of actions being taken by an Actor.
 163
 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>`_
 165
 166 3.2 Min/Max Guard onap.policies.controlloop.guard.common.MinMax
 167 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 168
 169 The Min/Max Guard supports Min/Max number of entity for scaling operations.
 170
 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>`_
 172
 173 3.3 Blacklist Guard onap.policies.controlloop.guard.common.Blacklist
 174 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 175
 176 The Blacklist Guard Supports blacklisting control loop actions from being performed on specific entity id's.
 177
 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>`_
 179
 180 4 Optimization onap.policies.Optimization
 181 -----------------------------------------
 182
 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.
 185
 186 .. image:: images/Optimization.svg
 187    :alt:  Optimization Policy Type Inheritance
 188
 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>`_.
 190
 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>`.
 194
 195 4.1 Optimization Service Policy Type onap.policies.optimization.Service
 196 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 197
 198 This policy type further extends the base onap.policies.Optimization type by defining additional properties specific to
 199 a service. For more information:
 200
 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>`_
 202
 203 Several additional policy types inherit from the Service Optimization Policy Type. For more information, :ref:`XACML Optimization
 204 application implementation <xacml-optimization-label>`.
 205
 206 4.2 Optimization Resource Policy Type onap.policies.optimization.Resource
 207 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 208
 209 This policy type further extends the base onap.policies.Optimization type by defining additional properties specific to
 210 a resource. For more information:
 211
 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>`_
 213
 214 Several additional policy types inherit from the Resource Optimization Policy Type. For more information, :ref:`XACML Optimization
 215 application implementation <xacml-optimization-label>`.
 216
 217 5 Naming onap.policies.Naming
 218 -----------------------------
 219
 220 Naming policies are used in SDNC to enforce which naming policy should be used during instantiation.
 221
 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>`_.
 223
 224 6 Native Policy Types onap.policies.Native
 225 ------------------------------------------
 226
 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:
 229
 230 ..  code-block:: yaml
 231
 232   tosca_definitions_version: tosca_simple_yaml_1_1_0
 233   policy_types:
 234       onap.policies.Native:
 235           derived_from: tosca.policies.Root
 236           description: a base policy type for all native PDP policies
 237           version: 1.0.0
 238
 239 6.1 Policy Type: onap.policies.native.drools.Controller
 240 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 241
 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.
 245
 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.
 249
 250 6.2 Policy Type: onap.policies.native.drools.Artifact
 251 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 252
 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.
 256
 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.
 260
 261 6.3 Policy Type: onap.policies.native.Xacml
 262 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 263
 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.
 267
 268 `XACML Native Policy Type <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.native.Xacml.yaml>`_
 269
 270 6.4 Policy Type: onap.policies.native.Apex
 271 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 272
 273 This policy type supports Apex native policy types.
 274
 275 `Apex Native Policy Type <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.native.Apex.yaml>`_
 276
 277
 278 7 Base Policy Type: onap.policies.controlloop.Operational (Deprecated)
 279 ----------------------------------------------------------------------
 280
 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:
 283
 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.
 286
 287 .. note::
 288   This policy type will be deprecated after Frankfurt and is discouraged from being used.
 289
 290 .. code-block:: yaml
 291   :caption: Base Policy Type definition for onap.policies.controlloop.Operational
 292   :linenos:
 293
 294   tosca_definitions_version: tosca_simple_yaml_1_1_0
 295   policy_types:
 296     - onap.policies.controlloop.Operational:
 297         derived_from: tosca.policies.Root
 298         version: 1.0.0
 299         description: Operational Policy for Control Loops
 300
 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.
 303
 304 .. code-block:: json
 305   :caption: Example Policy Payload for onap.policies.controlloop.Operational Policy Type
 306
 307   {
 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"
 312   }
 313
 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.