Policy Design and Development

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 TOSCA Policy Primer page for an introduction to TOSCA policy concepts.

../_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 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.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 Decision API is used by the DCAE Policy Handler to retrieve a decision on which policy to enforce during runtime.

Base Policy Type definition for onap.policies.Monitoring
1tosca_definitions_version: tosca_simple_yaml_1_1_0
2topology_template:
3  policy_types:
4    - onap.policies.Monitoring:
5        derived_from: tosca.policies.Root
6        version: 1.0.0
7        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.

Example PolicyType onap.policies.monitoring.MyDCAEComponent derived from onap.policies.Monitoring
1tosca_definitions_version: tosca_simple_yaml_1_1_0
2policy_types:
3 - onap.policies.monitoring.Mycomponent:
4      derived_from: onap.policies.Monitoring
5      version: 1.0.0
6      properties:
7          my_property_1:
8          type: string
9          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.

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.

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

3.4 Filter Guard onap.policies.controlloop.guard.common.Filter

The Filter Guard Supports filtering control loop actions from being performed on specific entity id’s.

Please see the definition of the Guard Filter 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.

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 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, 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, 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:

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