X-Git-Url: https://gerrit.onap.org/r/gitweb?a=blobdiff_plain;f=docs%2Fdesign%2Fdesign.rst;h=1080f4de23e347932832991fa3e7fbcb35249108;hb=08cc8426efb540a01e5d7c6a1b11860c3cbde86e;hp=ad91834a79d5bae510d66c0c9a92ddca719b4169;hpb=5fc2fdb0eebfec733acbc26dc9ab933279ea2c83;p=policy%2Fparent.git diff --git a/docs/design/design.rst b/docs/design/design.rst index ad91834a..1080f4de 100644 --- a/docs/design/design.rst +++ b/docs/design/design.rst @@ -5,120 +5,312 @@ .. _design-label: Policy Design and Development ------------------------------ +############################# .. contents:: - :depth: 3 - -The figure below shows the Artifacts (Blue) in the ONAP Policy -Framework, the Activities (Yellow) that manipulate them, and important -components (Pink) that interact with them. - -.. image:: design.png - -Please see the `TOSCA Policy -Primer `__ page for an -introduction to TOSCA policy concepts. - -TOSCA defines a *PolicyType*, the definition of a type of policy that -can be applied to a service. It also defines a *Policy*, the definition -of an instance of a *PolicyType*. In the Policy Framework, we must -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.  - -1 ONAP Policy Types -=================== - -Policy Type Design manages TOSCA *PolicyType* artifacts and their -*PolicyTypeImpl* implementations\ *.* - -*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 are -preloaded and are always available for use in the Policy Framework. - -====================================== ================================================================================================== -**Policy Type** **Description** -====================================== ================================================================================================== -onap.policies.Monitoring Overarching model that supports Policy driven DCAE microservice components used in a Control Loops -onap.policies.controlloop.Operational Used to support actor/action operational policies for control loops -onap.policies.controlloop.Guard Control Loop guard policies for policing control loops -onap.policies.controlloop.Coordination Control Loop Coordination policies to assist in coordinating multiple control loops at runtime -====================================== ================================================================================================== - -1.1 onap.policies.Monitoring Policy Type ----------------------------------------- - -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 developed using the XACML PDP to support question/answer Policy -Decisions during runtime for the DCAE Policy Handler. - -**Base Policy Type definition for onap.policies.Monitoring**   - -.. codeblock:: yaml - - tosca_definitions_version: tosca_simple_yaml_1_0_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. - -DCAE microservice components can generate their own TOSCA \ *PolicyType* -using TOSCA-Lab Control Loop guard policies in SDC (Stretch Goal) or can -do so manually. See `How to generate artefacts for SDC catalog using -Tosca Lab -Tool `__ -for details on TOSCA-LAB in SDC. For Dublin, the DCAE team is defining -the manual steps required to build policy models \ `Onboarding steps for -DCAE MS through SDC/Policy/CLAMP -(Dublin) `__. - -NOTE: For Dublin, mS Policy Types will be pre-loaded into the SDC -platform and be available as a Normative. The policy framework will -pre-load support for those mS Monitoring policy types. - - -End of Document + :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 ` 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 `. + +============================================ =============================================================================== +**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 ` 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 `__. 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 `_ + + +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 `_ + +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 `_ + +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 `_ + +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 `_ + +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 `_ + +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 `_. + +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 `. + +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 `_ + +Several additional policy types inherit from the Service Optimization Policy Type. For more information, :ref:`XACML Optimization +application implementation `. + +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 `_ + +Several additional policy types inherit from the Resource Optimization Policy Type. For more information, :ref:`XACML Optimization +application implementation `. + +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 `_. + +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 +`__ 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 +`__ 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 `_ + +6.4 Policy Type: onap.policies.native.Apex +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This policy type supports Apex native policy types. + +`Apex Native Policy Type `_ + + +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 +`__ to define the +**content** field and URL Encode the yaml.