.. _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 <tosca-label>`__ 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 <file://localhost/display/DW/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) <file://localhost/pages/viewpage.action%3fpageId=60883710>`__.
-
-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 <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.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>`_
Code Review / policy / parent.git / blobdiff