Official Documentation for Dublin

https://docs.onap.org/en/dublin/submodules/policy/parent.git/docs/design/design.html

This page shows how the Policy Design and API Flow to/from the PAP and PDPs works to support Model Driven Control Loops in Dublin.

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.

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 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.

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

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.

PolicyType onap.policies.monitoring.MyDCAEComponent derived from onap.policies.Monitoring

TCA Example - Please note that the official version of this will be located in the SDC repository.

Example TCA DCAE microservice

1.2 onap.policies.controlloop.Operational Policy Type

This policy type is used to support actor/action operational policies for control loops. There are two types of implementations for this policy type

1. Existing Drools implementations that supports runtime Control Loop actions taken on components such as SO/APPC/VFC/SDNC/SDNR

2. New implementations using APEX to support Control Loops.

For Dublin, this policy type will ONLY be used for the Policy Framework to distinguish the policy type as operational. The contents are still TBD for El Alto.

Base Policy type definition for onap.policies.controlloop.Operational

Applications should use the following Content-Type when creating onap.policies.controlloop.Operational policies:

Content-Type: "application/yaml; vnd.onap.operational"

1.2.1 Operational Policy Type Schema for Drools

For Dublin Drools will still support the Casablanca YAML definition of an Operational Policy for Control Loops.

Please use the Casablanca version of the YAML Operational Policy format defined https://git.onap.org/policy/drools-applications/tree/controlloop/common/policy-yaml/README-v2.0.0.md.

1.2.3 Operational Policy Type Schema for APEX (El Alto proposal)

The operational Policy Type schema for for APEX will extend the base operational Policy Type schema. This Policy Type allows parameters specific to the APEX PDP to be specified as a TOSCA policy.

Operational Policy Model Parameter Schema for APEX

1.3 onap.policies.controlloop.Guard Policy Type

This 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.

The base schema is defined as below:

Base Policy type definition for onap.policies.controlloop.Guard

As with onap.policies.Monitoring policy type, the PolicyTypeImpl implementation of the onap.policies.controlloop.Guard Policy Type is generic to support definition of TOSCA PolicyType artifacts in the Policy Framework using the Policy Type Design API.

For Dublin, only the following derived Policy Type definitions below are preloaded in the Policy Framework. However, the creation of policies will still support the payload from Casablanca.

Casablanca Guard Payload

1.3.1 onap.policies.controlloop.guard.FrequencyLimiter Policy Type

This is WIP for El Alto for the proposed policy type.

Policy Typefor Frequency Limiter Guard Policy

1.3.2 onap.policies.controlloop.guard.Blacklist Policy Type

Policy Type for Blacklist Guard Policies

1.3.3 onap.policies.controlloop.guard.MinMax Policy Type

Policy Type for Min/Max VF Module Policies

1.3.4 onap.policies.controlloop.Coordination Policy Type (STRETCH)

This policy type defines Control Loop Coordination policies to assist in coordinating multiple control loops during runtime. This policy type is developed using XACML PDP to support question/answer policy decisions at runtime for the onap.policies.controlloop.operational policy types.

2 PDP Deployment and Registration with PAP

The unit of execution and scaling in the Policy Framework is a PolicyImpl entity. A PolicyImpl entity runs on a PDP. As is explained above a PolicyImpl entity is a PolicyTypeImpl implementation parameterized with a TOSCA Policy.

In order to achieve horizontal scalability, we group the PDPs running instances of a given PolicyImpl entity logically together into a PDPSubGroup. The number of PDPs in a PDPSubGroup can then be scaled up and down using Kubernetes. In other words, all PDPs in a subgroup run the same PolicyImpl, that is the same policy template implementation (in XACML, Drools, or APEX) with the same parameters.

The figure above shows the layout of PDPGroup and PDPSubGroup entities. The figure shows examples of PDP groups for Control Loop and Monitoring policies on the right.

The health of PDPs is monitored by the PAP in order to alert operations teams managing policy. The PAP manages the life cycle of policies running on PDPs.

The table below shows the methods in which PolicyImpl entities can be deployed to PDP Subgroups

3. Public APIs

The Policy Framework supports the APIs documented in the subsections below. The APIs in this section are supported for use by external components.

3.1 Policy Type Design API for TOSCA Policy Types

The purpose of this API is to support CRUD of TOSCA PolicyType entities. This API is provided by the PolicyDevelopment component of the Policy Framework, see The ONAP Policy Framework architecture.

The API allows applications to create, update, delete, and query PolicyType entities so that they become available for use in ONAP by applications such as CLAMP. Some Policy Type entities are preloaded in the Policy Framework. The TOSCA fields below are valid on API calls:

Note: On this and subsequent tables, use the following legend: M-Mandatory, O-Optional, R-Read-only, C-Conditional. Conditional means the field is mandatory when some other field is present.
Note: Preloaded policy types may only be queried over this API, modification or deletion of preloaded policy type implementations is disabled.
Note: Policy types  that are in use (referenced by defined Policies) may not be deleted
Note: The group types of targets in TOSCA are groups of TOSCA nodes, not PDP groups; the target concept in TOSCA is equivalent to the Policy Enforcement Point (PEP) concept

3.1.1 Policy Type query

The API allows applications (such as CLAMP and Integration) to query the PolicyType entities that are available for Policy creation using a GET operation.

https:{url}:{port}/policy/api/v1/policytypes GET

Policy Type Query - When system comes up before any mS are onboarded

The table below shows some more examples of GET operations

3.1.2 Policy Type Create/Update

The API allows applications and users (such as a DCAE microservice component developer) to create or update a Policy Type using a POST operation. This API allows new Policy Types to be created or existing Policy Types to be modified. POST operations with a new Policy Type name or a new version of an existing Policy Type name are used to create a new Policy Type. POST operations with an existing Policy Type name and version are used to update an existing Policy Type. Many Policy Types can be created or updated in a single POST operation by specifying more than one Policy Type on the TOSCA policy_types list.

For example, the POST operation below with the TOSCA body below is used to create a new Policy type for a DCAE microservice.

https:{url}:{port}/policy/api/v1/policytypes POST

Create a new Policy Type for a DCAE microservice

Following creation of a DCAE TCA policy type operation, the GET call for Monitoring policies will list the new policy type. 

https:{url}:{port}/policy/api/v1/policytypes GET

Policy Type Query after DCAE TCA mS Policy Type is created

Now the onap.policies.Monitoring.cdap.tca.hi.lo.app Policy Type is available to CLAMP for creating concrete policies. See the Yaml contribution on the Model driven Control Loop Design page for a full listing of the DCAE TCA policy type used in the example above.

3.1.3 Policy Type Delete

The API also allows Policy Types to be deleted with a DELETE operation. The format of the delete operation is as below:

https:{url}:{port}/policy/api/v1/policytypes/onap.policies.monitoring.cdap.tca.hi.lo.app/versions/1.0.0 DELETE

Note: Predefined policy types cannot be deleted
Note: Policy types that are in use (Parameterized by a TOSCA Policy) may not be deleted, the parameterizing TOSCA policies must be deleted first
Note: The version parameter may be omitted on the DELETE operation if there is only one version of the policy type in the system

3.2 Policy Design API

The purpose of this API is to support CRUD of TOSCA Policy entities from TOSCA compliant PolicyType definitions. TOSCA Policy entities become the parameters for PolicyTypeImpl entities, producing PolicyImpl entities that can run on PDPs. This API is provided by the PolicyDevelopment component of the Policy Framework, see The ONAP Policy Framework architecture.

This API allows applications (such as CLAMP and Integration) to create, update, delete, and query Policy entities. The TOSCA fields below are valid on API calls:

Note: Policies that are deployed (used on deployed PolicyImpl entities) may not be deleted
Note: This API is NOT used by DCAE for a decision on what policy the DCAE PolicyHandler should retrieve and enforce
Note: The groups of targets in TOSCA are groups of TOSCA nodes, not PDP groups; the target concept in TOSCA is equivalent to the Policy Enforcement Point (PEP) concept

YAML is used for illustrative purposes in the examples in this section. JSON (application/json) will be used as the content type in the implementation of this API.

3.2.1 Policy query

The API allows applications (such as CLAMP and Integration) to query the Policy entities that are available for deployment using a GET operation.

Note: This operation simply returns TOSCA policies that are defined in the Policy Framework, it does NOT make a decision.

The table below shows some more examples of GET operations

3.2.2 Policy Create/Update

The API allows applications and users (such as CLAMP and Integration) to create or update a Policy using a POST operation. This API allows new Policies to be created or existing Policies to be modified. POST operations with a new Policy name are used to create a new Policy. POST operations with an existing Policy name are used to update an existing Policy. Many Policies can be created or updated in a single POST operation by specifying more than one Policy on the TOSCA policies list.

3.2.2.1 Monitoring Policy Create/Update

While designing a control loop using CLAMP, a Control Loop Designer uses the Policy Type for a specific DCAE mS component (See Section 3.1.1) to create a specific Policy. CLAMP then uses this API operation to submit the Policy to the Policy Framework.

For example, the POST operation below with the TOSCA body below is used to create a new scaleout Policy for the onap.policies.monitoring.cdap.tca.hi.lo.app microservice. The name of the policy "onap.scaleout.tca" is up to the user to determine themselves.

https:{url}:{port}/policy/api/v1/policytypes/onap.policies.Monitoring.cdap.tca.hi.lo.app/versions/1.0.0/policies POST

TOSCA Body of a new TCA High/Low Policy

Given a return code of success and a "metadata" section that indicates versioning information. The "metadata" section conforms exactly to how SDC implements lifecycle management versioning for first class normatives in the TOSCA Models. The policy platform will implement lifecycle identically to SDC to ensure conformity for policy creation. The new metadata fields return versioning details.

The following new policy will be listed and will have a "metadata" section as shown below:

https:{url}:{port}/policy/api/v1/policytypes/onap.policies.monitoring.cdap.tca.hi.lo.app/versions/1.0.0/policies GET

Policy with Metadata section for lifecycle management

The contents of the new policy can be retrieved using the ID:

https:{url}:{port}/policy/api/v1/policytypes/onap.policies.monitoring.cdap.tca.hi.lo.app/versions/1.0.0/policies/onap.scaleout.tca GET

Query on a new TCA High/Low Policy

3.2.2.2 Operational Policy Create/Update

While designing an operational policy, the designer uses the Policy Type for the operational policy (See Section 3.1.1) to create a specific Policy and submits the Policy to the Policy Framework.

This URL will be fixed for CLAMP in Dublin and the payload will match updated version of Casablanca YAML that supports VFModules.

https:{url}:{port}/policy/api/v1/policytypes/onap.policies.controloop.operational/versions/1.0.0/policies POST

Content-Type: application/yaml; legacy-version