...

This document describes the ONAP Policy Framework. It lays out the architecture of the framework and specifies the APIs provided to other components that interwork with the framework. It describes the implementation of the framework, mapping out the components, software strucure, and execution ecosystem of the framework. It goes on to provide examples that illustrate how to write, deploy, and run policies of various types using the framework.

1. Overview

The ONAP Policy Framework is a comprehensive policy design, deployment, and execution environment. The Policy Framework is the decision making component in an ONAP system. It allows you to specify, deploy, and execute the governance of the features and functions in your ONAP system, be they closed loop, orchestration, or more traditional open loop use case implementations. The Policy Framework is the component that is the source of truth for all policy decisions.

...

The ONAP Policy Framework architecture separates policies from the platform that is supporting them. The framework supports development, deployment, and execution of any type of policy in ONAP. The Policy Framework is metadata (model) driven so that policy development, deployment, and execution is as flexible as possible and can support modern rapid development ways of working such as DevOps. A metadata driven approach also allows the amount of programmed support required for policies to be reduced or ideally eliminated.

Another important aim of the architecture of a model driven policy framework is that it enables much more flexible policy specification.

1. A Policy Template is designed by a skilled policy developer in consultation with domain experts. The Policy template is a general implementation of a policy template for a feature. For example, a policy template could be written to manage Service Level Agreements for VPNs.
2. A Domain Policy is designed by a domain expert who uses the Policy Tempate to create a domain policy for their specific domain.
   1. For example, the VPN Policy Template is used to create VPN policies for a bank network, a car dealership network, or a university with many campuses.
   2. In ONAP, specific ONAP Policy Templates are used to create specific policies that drive the ONAP Platform and Components.
3. A Customer Facing Policy allows specific policy instances to be configured with parameters. For example, the SLA values in the car dealership VPN policy instance in a particular dealership are configured with values appropriate for the expected level of activity in that dealership.

The ONAP Policy Framework for building, configuring and deploying PDPs is extendable. It allows the use of ONAP PDPs as is, the extension of ONAP PDPs, and lastly provides the capability for users to create and deploy their own PDPs.

2. Architecture

The diagram below shows the architecture of the ONAP Policy Framework at its highest level.

Image Removed

The PolicyDevelopment component implements the functionality for development of policies, policy templates, and configurations for policies. PolicyDeployment is responsible for the deployment life cycle of policies as well as interworking with the mechanisms required to orchestrate the nodes and containers on which policies run. PolicyExecution is responsible for policies at run time; ensuring that policies are available to users, that policies are executing correctly, and that the state and status of policies is monitored.

PolicyDevelopment creates policy artifacts in Nexus and supporting information in the Policy database. PolicyDeployment reads those artifacts from Nexus and the supporting information from the Policy database whilst deploying policy artifacts. Once the policy artifacts are deployed, they are handed over to PolicyExecution for run-time management. PolicyDeveloment interacts with ONAP design time components, and has no programmatic interface with PolicyDeployment, PolicyExecution or any other run-time ONAP components.

The diagram below shows a more detailed view of the architecture, as inspired by RFC-2753 and RFC-3198..

Image Removed

PolicyDevelopment creates sets of executable policies (ExecutablePolicySet) for a certain domain, which consist of policies (ExecutablePolicy) and parameters for those policies (PolicyParameters) that can execute on PDPs. Executable policies are created from concrete policies (ConcretePolicy) that have been created from template policies (PolicyTemplate).

PolicyDeployment uses the PAP to deploy an ExecutablePolicySet on a PDPGroup, a grouping of PDPs of a certain type using a certain deployment plan.

...

2.1 Policy Design Architecture

This section describes the architecture of the model driven system used to develop policy templates, to derive concrete policies from those policy templates, and to parameterize concrete policies as executable policies.

Policy Template Design

Policy Template Design is the task of creating policy templates that capture the generic and vendor independent aspects of a policy for a particular domain use case. The policy template also specifies and publishes the model information, rules, and logic that it requires to generate concrete policies.

A policy template is written for a certain type of PDP. A policy template is developed for a certain type of PDP (for example XACML oriented for decision policies or Drools rules oriented for ECA policies). The design environment and tool chain for a policy template is specific for the type of policy being designed. The policy template is available as a Maven artifact once it has been designed.

All policy templates must implement the ONAP Policy Framework PolicyTemplate interface. This interface allows the Policy Framework to manage policy templates and to generate concrete policies from policy templates in a uniform way regardless of the domain that the policy template is addressing or the PDP technology that will execute the policy. The interface is used by the Policy Framework to determine the PDP technology of the policy template, the structure, type, and definition of the model information that must be supplied to the policy template to generate a concrete policy, implementation specific rules or logic, and other relevant information.

The ONAP Policy Framework provides an API that allows other components to query policy templates, to determine the model information, rules, or logic that they require, and to generate concrete policies from policy templates.

Consider a policy template created for managing faults on vCPE equipment in a vendor independent way. The policy template captures the generic logic required to manage the faults and specifies the vendor specific information that must be supplied to te template for specific vendor vCPE VFs. The actual concrete vCPE policy that is used for managing particular vCPE equipment is generated using the policy template together with the specific modeled information, rules and logic for that vendor model of vCPE.

Programming Policy Templates

The most straightforward way to create a policy template is to program it. Programming a policy template might simply mean creating and editing text files and manually generating the Maven artifact for the policy template.

A more formal approach is preferred. Programmers use a specific Eclipse project type for developing each type of policy template, a Policy Template SDK. The project is under source control in git. This Eclipse project is structured correctly for creating policies for a specific type of PDP. It includes the correct POM files for generating the policy template as a Maven artifact. It has editors and perspectives that aid the programmer in their work.

Generating Policy Templates

It is also possible to generate policy templates using MDD (Model Driven Development) techniques. Policies are expressed using a DSL (Domain Specific Language) or a policy specification environment for a particular application domain. For example, policies for specifying SLAs could be expressed in a SLA DSL and policies for managing SON features could be generated from a visual SON management tool. The ONAP Policy framework provides an API that allows tool chains to create policy templates.

Policy Design

Policy Design is the task of creating a concrete policy from a policy template.

Policy Design can occur in several ways during a "design" process. At design time, a service designer and/or operations team can use the models specified on a policy template to express and capture a policy at its highest abstraction level. Alternatively, the logic of the policy can be expressed using a specific policy language if desired.

The information expressed during policy design is used to specialize a policy template to create an executable policy.

Model Driven VF Policy Design via VNF SDK Packaging

VF vendors express policies such as SLA, Licenses, hardware placement, run-time metric suggestions, etc. These details are captured within the VNF SDK and uploaded into the SDC Catalog.

For example, SLA and placement policies may be captured via TOSCA specification. License policies can be captured via TOSCA or XACML specification (TBD). Run-time metric vendor recommendations can be captured via VES Standard specification.

(High level architectural sequence diagram on how this works)

Model Driven Policy Design via SDC GUI

The SDC GUI supports several types of policies that can be captured during design time. DCAE micro service configuration policies can be onboarded via the DCAE-DS (DCAE Design Studio). Service policies such as Optimization, Placement policies can also be captured via TOSCA model during design time. The SDC Distribution APIs are used to interact with SDC.

(High level architectural sequence diagram on how this works)

Model Driven Policy Design via Policy Dashboard (exposed via ONAP Portal SDK)

(High level architectural sequence diagram on how this works)

Policy Design Process

All policies must be certified as being fit for deployment prior to run time deployment. This certification may be performed over the ONAP Policy Framework APIs in the case where other ONAP components such as SDC crete policies. For Policies created directly in the PF, governance of policy certification and testing is supported in the system.
Image Removed

*******

• The Policy GUI Dashboard is created from the ONAP Portal SDK to create a consistent user experience
• The Policy GUI Designer is created from the ONAP SDC SDK to create a consistent user experience

Design Time Capabilities

• Design Time policies should be easy to specify and capture from either the SDC GUI or the Policy GUI
  • High-level Conflict Detection and Resolution tools will be utilized to help identify possible conflicts
• Provide a model-driven Design Time framework for ingestion of models for policies and any optional support code
• Policy Development Environment for designing models and their support code
  
  • Conflict Detection and Resolution for Policies should be available during development and testing phases

1. Policies are easy to specify

Discuss support for SDC.

The platform can consume policy models organically and not require any development work. The Policy GUI should be to interpret any TOSCA Model ingested and flexibly present a GUI for a user to create policies from.

Policy Model/Template/Rule Development and Orchestration - Pamela Dragosh 

Policies that are expressed via natural language or a model require some development work ahead of time for them to be translated into runtime policies. Some Policy Domains will be setup and available in the platform during startup such as Control Loop Operational Policy Models, OOF placement Models, DCAE microservice models. Policy Model/Template/Rule Development is done by an experienced developer.

Policy models/templates/rules will be stored in a Nexus OSS Repository which has the ability to support all major package types and has the flexibility to be configured for various environments such as development vs production. Thus, the production environment can be configured in a strict manner to allow only artifacts being pulled from specific repositories and block other repositories. While the development environment can be separately configured so offline development/testing can be performed with or without production policies.

Model Development

Template Development

Rule Development

TODO: How does an Policy get updated? How the nexus is going to work? How does template development work?

2.2 Policy Deployment Architecture

The Policy Framework Platform components are themselves designed as micro services that are easy to configure and deploy via Docker images and K8S both supporting resiliency and scalability if required. PAPs and PDPs are deployed by the underlying ONAP management infrastructure and are designed to comply with the ONAP interfaces for deploying containers.

The PAPs keep track of PDPs, support the deployment of PDP groups and the deployment of a policy set across those PDP groups. A PAP is stateless in a RESTful sense. Therefore, if there is more than one PAP deployed, it does not matter which PAP a user contacts to handle a request. The PAP uses the database (persistent storage) to keep track of ongoing sessions with clients. Policy management on PDPs is the responsibility of PAPs; management of policy sets or policies by any other manner is not supported. The PAPs are identified in the system using a well known address; in the case where a pool of PAPs exist, requests to PAPs are load balanced across the PAPs.

*******

• Runtime capability to upgrade Policies, change mode of operation for policies (for example: safe mode, test mode) and ability to preserve state for minor/patch version upgrades
  • Runtime modes for safe mode, test mode will be implemented as another line of defense against policy conflicts and resolution

1. Policies are be possible to specify and deploy at run time without restarting components or stopping policy processing

1. PDPs scale horizontally
2. Policies are upgradable with state preserved within the limitations of semantic versioning (State preserved for minor/patch version upgrades), see 2.

The long term architecture view is for policy artifacts to be located in a nexus repository that are pulled by appropriate PDP micro service engines. Dependencies would be set in the policy artifact jar files themselves and not hard coded into the platform as a JSON file.

• Policy API will support Lifecycle management for policies that are deployed such as modes and retirement. This additional requirement is better suited for the new proposed Policy Lifecycle API than the current API.

• The PAP will do life cycle monitoring of policy and context as well as deployment.
• PDPs of all type must scale horizontally under whatever containerization or virtual infrastructure is in use for a given ONAP deployment. Having the PAP scale horizontally probably not a very urgent requirement.

2.3 Policy Execution Architecture

• The PAP will do run time monitoring of policy and context .
• Policy does instance monitoring, monitoring of PDPs in real time etc.

• Inter-PDP protocol is the protocol that instances of any PDP type can use to communicate with each other to manage state and deployment
• Intra-PDP protocol is the protocol that instances of a particular PDP type use to communicate with each other, to manage state and deployment
• Load balancing of events towards PDP pools could be done with DMaap using the underlying Kafka consumer group mechanisms

PEP Registration and Enforcement Guidelines - Pamela Dragosh

How do we set that up?

How do we ensure the API's allow flexibility for getting policy decisions?

PDP specific? May not relevant to drools or apex?

https://ericsson.github.io/apex-docs/policy-guide/pg-policy-matrix.html

3. APIs Provided by the Policy Framework and how to use them

• Should Policy Management Protocol/Policy Deployment Protocol/Policy Monitoring Protocol/Policy Persistence Protocol use DMaaP?

3.1 Policy Design APIs

3.2 Policy Deployment APIs

PAP to all PDPs in PDP group

...

• Update of policies across PDPs in a PDP group use "eventually consistent" semantics, transactions or ACID semantics will not be supported
• Event though PDPs could listen or monitor Nexus for updates to policies, the PAP should be the component responsible for deciding if and what policy upgrades are propagated to the entire PDP group.

PDP Group Admin in PAP

...

• Can a PDP be in more than one PDP group??? .....I hope not!
• We'll assume a single PAP for now.

3.3 Policy Execution APIs

PAP to all PDPs in PDP group

...

• *A policy may be parameterized. There are two ways to handle this
  • Combine a raw policy into a parameterized policy and deploy the parameterized policy at run time
  • Have the raw policy and its parameters as separate artifacts and deploy them separately
  • Do not consider the parameters as an artifact but allow them to be modified directly by users setting them using an interface towards the PAP at run time

Policy Execution (Users to PDP Group pr PDP)

...

We have identified five capabilities as being essential for the framework:

1. Most obviously, the framework must be capable of being triggered by an event or invoked, and making decisions at run time.
2. It must be deployment agnostic; capable of managing policies for various Policy Decision Points (PDPs) or policy engines.
3. It must be metadata driven, allowing policies to be deployed, modified, upgraded, and removed as the system executes.
4. It must provide a flexible model driven policy design approach for policy type programming and specification of policies.
5. It must be extensible, allowing straightforward integration of new PDPs, policy formats, and policy development environments.

Another important aim of the architecture of a model driven policy framework is that it enables much more flexible policy specification. The ONAP Policy Framework complies with the TOSCA modelling approach for policies, see the TOSCA Policy Primer for more information on how policies are modelled in TOSCA.

1. A Policy Type is a general implementation of a policy for a feature. For example, a Policy Type could be written to manage Service Level Agreements for VPNs. The Policy Type is designed by a domain expert, who specifies the parameters, triggers, and actions that the Policy Type will have. The implementation (the logic, rules, and tasks of the Policy Type) is implemented by a skilled policy developer in consultation with domain experts.
   1. For example, the VPN Policy Type is used to create VPN policies for a bank network, a car dealership network, or a university with many campuses.
   2. In ONAP, specific ONAP Policy Types are used to create specific policies that drive the ONAP Platform and Components.
2. A Policy is created by configuring a Policy Type with parameters. For example, the SLA values in the car dealership VPN policy for a particular dealership are configured with values appropriate for the expected level of activity in that dealership.

The ONAP Policy Framework for building, configuring and deploying PDPs is extendable. It allows the use of ONAP PDPs as is, the extension of ONAP PDPs, and lastly provides the capability for users to create and deploy their own PDPs. The ONAP Policy Framework provides distributed policy management for all policies in ONAP at run time. Not only does this provide unified policy access and version control, it provides life cycle control for policies and allows detection of conflicts across all policies running in an ONAP installation.

2. Architecture

The diagram below shows the architecture of the ONAP Policy Framework at its highest level.

The PolicyDevelopment component implements the functionality for development of policy types and policies. PolicyAdministration is responsible for the deployment life cycle of policies as well as interworking with the mechanisms required to orchestrate the nodes and containers on which policies run. PolicyAdministration is also responsible for the administration of policies at run time; ensuring that policies are available to users, that policies are executing correctly, and that the state and status of policies is monitored. PolicyExecution is the set of PDPs running in the ONAP system and is responsible for making policy decisions and for managing the administrative state of the PDPs as directed by PolicyAdministration. 

PolicyDevelopment creates policy artifacts and supporting information in the policy database. PolicyAdministration reads those artifacts and the supporting information from the policy database whilst deploying policy artifacts. Once the policy artifacts are deployed, PolicyAdministration handles the run-time management of the PDPs on which the policies are running. PolicyDevelopment interacts with ONAP design time components, and has no programmatic interface with PolicyAdministration, PolicyExecution or any other run-time ONAP components.

The diagram below shows a more detailed view of the architecture, as inspired by RFC-2753 and RFC-3198.

PolicyDevelopment provides a CRUD API for policy types and policies. The policy types and policy artifacts and their metadata (Information about policies, policy types, and their interrelations ) are stored in the PolicyDB. The PolicyDevGUI, PolicyDistribution, and other applications such as Portal can use the PolicyDevelopment API to create, update, and delete policy types and policies.

PolicyAdministration has two important functions:

• Management of the life cycle of PDPs in an ONAP installation. PDPs register with PolicyAdministration when they come up. PolicyAdministration handles the allocation of PDPs to a PDP Groups and PDP Subgroups, so that they can be managed as microservices in Kubernetes.
• Management of the deployment of policies to PDPs in an ONAP installation. PolicyAdministration gives each PDP group a set of domain policies to execute.

PolicyAdministration handles PDPs and policy allocation to PDPs using asynchronous messaging over DMaaP.

PolicyAdministation provides three APIs:

• a CRUD API for policy groups and subgroups
• an API that allows the allocation of policies PDP groups and subgroups to be controlled
• an API allows policy execution to be managed, showing the status of policy execution on PDP Groups, subgroups, and individual PDPs as well as the life cycle state of PDPs

PolicyExecution is the set of running PDPs that are executing policies, logically partitioned into PDP groups and subgroups.

The figure above shows how PolicyExecution looks at run time with PDPs running in Kubernetes. A PDPGroup is a purely logical construct that collects all the PDPs that are running policies for a particular domain together. A PDPSubGroup is a group of PDPs of the same type that are running the same policies. A PDPSubGroup is deployed as a Kubernetes Deployment. PDPs are defined as Kubernetes Pods. At run time,  the actual number of PDPs in each PDPSubGroup is specified in the configuration of the Deployment of that PDPSubGroup in Kubernetes. This structuring of PDPs is required because, in order to simplify deployment and scaling of PDPs in Kubernetes, we gather all the PDPs of the same type that are running the same policies together for deployment.

For example, assume we have policies for the SON (Self Organizing Network) and ACPE (Advanced Customer Premises Service) domains. For SON, we have XACML, Drools, and APEX policies, and for ACPE we have XACML and Drools policies. The table below shows the resultingPDPGroup, PDPSubGroup, and PDP allocations:

2.1 Policy Framework Object Model

This section describes the structure of and relations between the main concepts in the Policy Framework. This model is implemented as a common model and is used by PolicyDevelopment, PolicyDeployment, and PolicyExecution.

The UML class diagram above shows the portion of the Policy Framework Object Model that applies to PolicyDeployment and PolicyExecution.

The UML class diagram above shows the portion of the Policy Framework Object Model that applies to PolicyDevelopment and PolicyDeployment.

2.2 Policy Design Architecture

This section describes the architecture of the model driven system used to develop policy types and to create concrete policies using policy types. The output of Policy Design is deployment-ready artifacts and Policy metadata in the Policy Framework database.

Policies that are expressed via natural language or a model require some development work ahead of time for them to be translated into concrete runtime policies. Some Policy Domains will be setup and available in the platform during startup such as Control Loop Operational Policy Models, OOF placement Models, DCAE microservice models. Policy type implementation development is done by an experienced developer.

2.2.1 Policy Type Design

Policy Type Design is the task of creating policy types that capture the generic and vendor independent aspects of a policy for a particular domain use case. The policy type implementation specifies the model information, rules, and tasks that a policy type requires to generate concrete policies.

All policy types must implement the ONAP Policy Framework PolicyType interface. This interface allows PolicyDevelopment to manage policy types and to generate policies from these policy types in a uniform way regardless of the domain that the policy type is addressing or the PDP technology that will execute the policy. The interface is used by PolicyDevelopment to determine the PDP technology of the policy type, the structure, type, and definition of the model information that must be supplied to the policy type to generate a concrete policy.

A PolicyTypeImpl is developed for a certain type of PDP (for example XACML oriented for decision policies or Drools rules oriented for ECA policies). The design environment and tool chain for a policy type is specific for the type of policy being designed.

The PolicyTypeImpl  implementation (or raw policy) is the specification of the specific rules or tasks, the flow of the policy, its internal states and data structures and other relevant information. A PolicyTypeImpl is specific to a PDP technology, that is XACML, Drools, or APEX. A PolicyTypeImpl can be specific to a particular policy type, it can be more general, providing the implementation of a class of policy types, or the same policy type may have many implementations.

PolicyDevelopment provides the RESTful Policy Design API, which allows other components to query policy types and policy type implementations, to determine the model information, rules, or tasks that they require, to specialize policy flow, and to generate policies from policy types. This API is used by the ONAP Policy Framework and other components such as PolicyDistribution to create policies from policy types.

Consider a policy type created for managing faults on vCPE equipment in a vendor independent way. The policy type captures the generic logic required to manage the faults and specifies the vendor specific information that must be supplied to the type for specific vendor vCPE VFs. The actual  vCPE policy that is used for managing particular vCPE equipment is created by setting the parameters specified in the policy type together with the specific modeled information, rules and tasks in the policy type implementation for that vendor model of vCPE.

2.2.1 Generating Policy Types

It is possible to generate policy types using MDD (Model Driven Development) techniques. Policy types are expressed using a DSL (Domain Specific Language) or a policy specification environment for a particular application domain. For example, policy types for specifying SLAs could be expressed in a SLA DSL and policy types for managing SON features could be generated from a visual SON management tool. The ONAP Policy framework provides an API that allows tool chains to create policy types. SDC uses this approach for generating Policy Types in the Policy Framework, see the Model driven Control Loop Design page.

The SDC GUI supports several types of policies that can be captured at design time. DCAE micro service configuration policies can be onboarded via the DCAE-DS (DCAE Design Studio).

@startuml
participant DCAE_DS <<API_User >>

box "PolicyDesign" #LightBlue
  participant PolicyTypeDesign
end box

autonumber

DCAE_DS --> PolicyTypeDesign : Get Policy Type Reference and Metadata
PolicyTypeDesign --> PolicyDB : Get Policy Type Metadata\nand Artifact
alt Policy Type Artifact exists
  PolicyTypeDesign --> DCAE_DS : Return Policy Type Reference and Metadata
else Policy Artifact does not exist
  PolicyTypeDesign --> DCAE_DS : Return New Policy Type Reference and Empty Metadata
end

DCAE_DS --> DCAE_DS : Policy Type Editing and Generation Session
activate DCAE_DS
deactivate DCAE_DS

DCAE_DS --> PolicyTypeDesign : Create Policy Type and Metadata
PolicyTypeDesign --> DCAE_DS : Policy Generation Result


@enduml

The GUI implementation in another ONAP component such as SDC DCAE-DS uses the API_User API to create and edit ONAP policy types.

2.2.1.2 Programming Policy Type Implementations

For skilled developers, the most straightforward way to create a policy type is to program it. Programming a policy type might simply mean creating and editing text files, thus manually creating the TOSCA Policy Type Yaml file and the policy type implementation for the policy type.

A more formal approach is preferred. For policy type implementations, programmers use a specific Eclipse project type for developing each type of implementation, a Policy Type Implementation SDK. The project is under source control in git. This Eclipse project is structured correctly for creating implementations for a specific type of PDP. It includes the correct POM files for generating the policy type implementation and has editors and perspectives that aid  programmers in their work

2.2.2 Policy Design

The PolicyCreation function of PolicyDevelopment creates policies from a policy type.  The information expressed during policy type design is used to parameterize a policy type to create an executable policy. A service designer and/or operations team can use tooling that reads the TOSCA Policy Type specifications to express and capture a policy at its highest abstraction level. Alternatively, the parameter for the policy can be expressed in a raw JSON or YAML file and posted over the policy design API described on the Model driven Control Loop Design page.

A number of mechanisms for  policy creation are supported in ONAP. The process in PolicyDevelopment for creating a policy is the same for all mechanisms. The most general mechanism for creating a policy is using the RESTful Policy Design API, which provides a full interface to the policy creation support of PolicyDevelopment. This API may be exercised directly using utilities such as curl. PolicyDevelopment provides a command line tool that is a loose wrapper around the API. It also provides a general purpose Policy GUI in the ONAP Portal for policy creation, which again is a general purpose wrapper around the policy creation API. The Policy GUI can interpret any TOSCA Model ingested and flexibly presents a GUI for a user to create policies from. The development of these mechanisms will be phased over a number of ONAP releases.

A number of ONAP components use policy in manners which are specific to their particular needs. The manner in which the policy creation process is triggered and the way in which information required to create a policy is specified and accessed is specialized for these ONAP components.

The following subsections outline the mechanisms for policy creation and modification supported by the ONAP Policy Framework.

2.2.2.1 Policy Design in the ONAP Policy Framework

Policy creation in PolicyDevelopment follows the general sequence shown in the sequence diagram below. An API_USER is any component that wants to create a policy from a policy type. PolicyDevelopment supplies a REST interface that exposes the API and also provides a command line tool and general purpose client that wraps the API.

@startuml
participant API_User

box "PolicyDesign" #LightBlue
  participant PolicyDesign
  database PolicyDB
end box

autonumber

API_User --> PolicyDesign : Get Policy Type Reference
PolicyDesign --> PolicyDB : Get Policy Type Artifact and Metadata
PolicyDesign --> API_User : Return Policy Type Reference and Metadata
API_User --> PolicyDesign : Get Policy Reference and Metadata
PolicyDesign --> PolicyDB : Get Policy Metadata
alt Policy Artifact exists
  PolicyDesign --> API_User : Return Policy Reference and Metadata
else Policy Artifact does not exist
  PolicyDesign --> API_User : Return New Policy Reference and Empty Metadata
end

API_User --> API_User : Policy Editing and Generation Session\nto get Policy Parameters from user
activate API_User
deactivate API_User

loop
  API_User --> PolicyDesign : Use Policy Type specification
API_User --> PolicyDesign : Create Policy
PolicyDesign --> PolicyDesign : Create Policy
activate PolicyDesign
deactivate PolicyDesign
PolicyDesign --> PolicyDB : Save Policy Artifact and Metadata
PolicyDesign --> API_User : Policy Creation Result
@enduml

A PolicyDevAPIUser first gets a reference to and the metadata for the Policy type for the policy they want to work on from PolicyDevelopment. PolicyDevelopment reads the metadata and artifact for the policy type from the database. The API_User then asks for a reference and the metadata for the policy. PolicyDevelopment looks up the policy in the database. If the policy already exists, PolicyDevelopment reads the artifact and returns the reference of the existing policy to the PolicyDevAPIUser with the metadata for the existing policy. If the policy does not exist, PolicyDevelopment creates and new reference and metadata and returns that to the API_User.

The PolicyDevAPIUser may now proceed with a policy specification session, where the parameters are set for the policy using the policy type specification. Once the PolicyDevAPIUser is happy that the policy is completely and correctly specified, it requests PolicyDevelopment to create the policy. PolicyDevelopment creates the policy, stores the created policy artifact and its metadata in the database.

2.2.2.2 Model Driven VF (Virtual Function) Policy Design via VNF SDK Packaging

VF vendors express policies such as SLA, Licenses, hardware placement, run-time metric suggestions, etc. These details are captured within the VNF SDK and uploaded into the SDC Catalog. The SDC Distribution APIs are used to interact with SDC. For example, SLA and placement policies may be captured via TOSCA specification. License policies can be captured via TOSCA or an XACML specification. Run-time metric vendor recommendations can be captured via VES Standard specification.

The sequence diagram below is a high level view of SDC-triggered concrete policy generation for some arbitrary entity EntityA. The parameters to create a policy are read from a TOSCA Policy specification read from a CSAR received from SDC.

@startuml

participant SDC
participant DMaaP

box "PolicyDesign" #LightBlue
  participant PolicyDistribution << API_User >>
  participant PolicyDesign
end box

autonumber
PolicyDistribution --> DMaaP : Subscribe for SDC Notifications\non Entries of Interest
SDC --> DMaaP : New Entry of Interest: EntityA
DMaaP --> PolicyDistribution : New Entry of Interest: EntityA

PolicyDistribution --> PolicyDesign : Get Policy Reference
PolicyDesign --> PolicyDistribution : Return Policy Reference and Metadata

PolicyDistribution --> PolicyDistribution : Create Policy Editing and Generation Session
activate PolicyDistribution
loop
  PolicyDistribution --> PolicyDesign : Use Policy Type specification to\nread Policy Parameters\nfrom TOSCA specification in CSAR
end
PolicyDistribution --> PolicyDesign : Create Policy
PolicyDesign --> PolicyDistribution : Policy Creation Result
deactivate PolicyDistribution

@enduml

PolicyDesign uses the PolicyDistribution component for managing SDC-triggered  policy creation and update requests. PolicyDistribution is an API_User, it uses the Policy Design API for policy creation and update. It reads the information it needs to populate the policy type from a TOSCA specification in a CSAR received from SDC and then uses this information to automatically generate a policy.

Note that SDC provides a wrapper for the SDC API as a Java Client and also provides a TOSCA parser. See Policy Platform - SDC Service Distribution Software Architecture

In Step 4 above, the PolicyDesign must download the CSAR file. If the policy is to be composed from the TOSCA definition, it must also parse the TOSCA definition.

In Step 9 above, the PolicyDesign must send back/publish status events to SDC such as DOWNLOAD_OK, DOWNLOAD_ERROR, DEPLOY_OK, DEPLOY_ERROR, NOTIFIED.

2.2.2.4 Scripted Model Driven Policy Design

Service policies such as optimization and placement policies can be specified as a TOSCA Policy at design time. These policies use a TOSCA Policy Type specification as their schemas. Therefore, scripts can be used to create TOSCA policies using TOSCA Policy Types.

@startuml
participant Script <<API_User >>
collections DirectiveFile

box "PolicyDesign" #LightBlue
  participant PolicyTypeDesign
  participant PolicyDesign
end box

autonumber

activate Script
loop
  Script --> DirectiveFile : Read next directive from script file
  Script --> PolicyTypeDesign : Read Policy Type for directive
  Script --> Script : Create TOSCA Policy
  Script --> Script : Read parameters from script file directive
  Script --> Script : Set Parameters in TOSCA Policy
  Script --> PolicyDesign : Generate Policy
  PolicyDesign --> Script : Policy Generation Resultend
  Script --> ConcretePolicyDesign : Generate Policy
  ConcretePolicyDesign --> Script : Policy Generation Result
end
deactivate Script

@enduml

One straightforward way of generating policies from Policy types is to use directives specified in a script file. The command line utility is an API_User. The script reads directives from a file. For each directive, it reads the policy type using the Policy Type API, and uses the parameters of the directive to create a TOSCA Policy. It then uses the Policy API to create the policy.

2.2.3 Policy Design Process

All policy types must be certified as being fit for deployment prior to run time deployment. In the case of design-time via the SDC application, it is assumed the lifecycle being implemented by SDC will suffice for any policy types that are declared within the ONAP Service CSAR. For other policy types and policy type implementations, the lifecycle associated with software development process will suffice. Since policy types and their implementations will be designed and implemented using software development best practices, they can be utilized and configured for various environments (eg. development, testing, production) as desired.

2.3 Policy Runtime Architecture

The Policy Framework Platform components are themselves designed as micro services that are easy to configure and deploy via Docker images and K8S both supporting resiliency and scalability if required. PAPs and PDPs are deployed by the underlying ONAP management infrastructure and are designed to comply with the ONAP interfaces for deploying containers.

The PAPs keep track of PDPs, support the deployment of PDP groups and the deployment of a policy set across those PDP groups. A PAP is stateless in a RESTful sense. Therefore, if there is more than one PAP deployed, it does not matter which PAP a user contacts to handle a request. The PAP uses the database (persistent storage) to keep track of ongoing sessions with clients. Policy management on PDPs is the responsibility of PAPs; management of policy sets or policies by any other manner is not permitted.

In the ONAP Policy Framework, the interfaces to the PDP are designed to be as streamlined as possible. Because the PDP is the main unit of scalability in the Policy Framework, the PF is designed to allow PDPs in a PDP group to arbitrarily appear and disappear and for policy consistency across all PDPs in a PDP group to be easily maintained. Therefore, PDPs have just two interfaces; an interface that users can use to execute policies and interface to the PAP for administration, life cycle management and monitoring. The PAP is responsible for controlling the state across the PDPs in a PDP group. The PAP interacts with the Policy database and transfers policy sets to PDPs, and may cache the policy sets for PDP groups.

See also Sectino 2 of the TO BE DELETED - refer to Dublin Documentation page, where the mechanisms for PDP Deployment and Registration with PAP are explained.

2.3.1 Policy Framework Services

The ONAP Policy Framework follows the architectural approach for micro services recommended by the ONAP Architecture Subcommittee.

The ONAP Policy Framework defines Kubernetes Services to manage the life cycle of Policy Framework executable components at runtime. A Kubernetes service allows, among other parameters,  the number of instances (pods in Kubernetes terminology) that should be deployed for a particular service to be specified and a common endpoint for that service to be defined. Once the service is started in Kubernetes, Kubernetes ensures that the specified number of instances is always kept running. As requests are received on the common endpoint, they are distributed across the service instances. More complex call distribution and instance deployment strategies may be used; please see the Kubernetes Services documentation for those details.

If, for example, a service called policy-pdpd-control-loop is defined that runs 5 PDP-D instances. The service has the end point https://policy-pdpd-control-loop.onap/<service-specific-path>. When the service is started, Kubernetes spins up 5 PDP-Ds. Calls to the end point https://policy-pdpd-control-loop.onap/<service-specific-path> are distributed across the 5 PDP-D instances. Note that the .onap part of the service endpoint is the namespace being used and is specified for the full ONAP Kuberentes installation.

The following services will be required for the ONAP Policy Framework:

There is one and only one PAP service, which handles policy deployment, administration, and monitoring for all policies in all PDPs and PDP groups in the system. There are multiple PDP services, one PDP service for each domain for which there are policies.

2.3.2 The Policy Framework Information Structure

The following diagram captures the relationship between Policy Framework concepts at run time.

@startuml

object PDPSubGroup
object PDPService
object PolicySet
object PDP
object PolicyImpl

PDPSubGroup "1" -- "1" PDPService : > Lifecycle\nManaged\nBy
PDPService "1" -- "*" PDP : > Manages\nLifecycle\nOf
PDPService "1" -- "1" PolicySet : > Executes
PolicySet "1" -- "*" PDP : > Executes\nOn
PolicySet "1" -- "*" PolicyImpl : > Contains

@enduml

There is a one to one relationship between a PDP SubGroup, a Kubernetes PDP service, and the set of policies assigned to run in the PDP subgroup. Each PDP service runs a single PDP subgroup with multiple PDPs, which executes a specific Policy Set containing a number of policies that have been assigned to that PDP subgroup. Having and maintaining this principle makes policy deployment and administration much more straightforward than it would be if complex relationships between PDP services, PDP subgroups, and policy sets.

The topology of the PDPs and their policy sets is held in the Policy Framework database and is administered by the PAP service.

@startuml

!define table(x) class x << (T,#FFAAAA) >>
!define primary_key(x) <u>x</u>
hide methods
hide stereotypes

table(PDP_SUBGROUP) {
  primary_key(PDP_SUBGROUP_ID)
  PDP_SUBGROUP_NAME
  PDP_SUBGROUP_VERSION
  PDP_TYPE
  PDP_SERVICE_ENDPOINT
  POLICY_SET_ID
  PDP_SUBGROUP_STATE
}

table(PDP) {
  primary_key(PDP_ID)
  PDP_NAME
  PDP_VERSION
  PDP_TYPE
  PDP_ENDPOINT
  PDP_SUBGROUP_ID
  POLICY_SET_ID
  PDP_STATE
}

table(POLICY_SET) {
  primary_key(POLICY_SET_ID)
  POLICY_SET_NAME
  POLICY_SET_VERSION
}

table(POLICYIMPL) {
  primary_key(POLICY_IMPL_ID)
  POLICY_NAME
  POLICY_VERSION
  PDP_TYPE
  POLICY_ARTIFACT
}

table(POLICY_SET_TO_POLICY_IMPL) {
  POLICY_SET_ID
  POLICY_IMPL_ID
}

PDP_SUBGROUP::POLICY_SET_ID --> POLICY_SET::POLICY_SET_ID
PDP::PDP_SUBGROUP_ID --> PDP_SUBGROUP::PDP_SUBGROUP_ID
PDP::POLICY_SET_ID --> POLICY_SET::POLICY_SET_ID
POLICY_SET_TO_POLICY_IMPL::POLICY_SET_ID --> POLICY_SET::POLICY_SET_ID
POLICY_SET_TO_POLICY_IMPL::POLICY_IMPLID --> POLICY::POLICY_IMPL_ID
@endum

The diagram above gives an indicative structure of the run time topology information in the Policy Framework database. Note that the PDP_SUBGROUP_STATE and PDP_STATE fields hold state information for life cycle management of PDP groups and PDPs.

2.3.3 Startup, Shutdown and Restart

This section describes the interactions between Policy Framework components themselves and with other ONAP components at startup, shutdown and restart.

2.3.3.1 PAP Startup and Shutdown

The sequence diagram below shows the actions of the PAP at startup.

@startuml
participant K8S
participant PAP
database PolicyDB

autonumber
K8S --> PAP : Start PAP

PAP --> PolicyDB : Read Initial Data

PAP --> PAP : Initialize Policy Administration
activate PAP
deactivate PAP

loop forever
    ref over PAP: Wait for and\nHandle PDP\nStatus Updates
    ref over PAP: Wait for and\nHandle\nAdmin Requests
end
@enduml

The PAP is the run time point of coordination for the ONAP Policy Framework. When it is started, it initializes itself using data from the database.  It then waits for periodic PDP status updates and for administration requests.

PAP shutdown is trivial. On receipt or a shutdown request, the PAP completes or aborts any ongoing operations and shuts down gracefully.

2.3.3.2 PDP Startup and Shutdown

The sequence diagram below shows the actions of the PDP at startup. See also Section 4 of the TO BE DELETED - refer to Dublin Documentation page for the API used to implement this sequence.

@startuml
participant K8S
participant PDP
participant DMaaP
participant PAP

autonumber
K8S --> PDP : Start PDP

PDP --> PAP: Send Status (initial status) to PAP

ref over PAP, PDP: PAP downloads Policy Set to PDP

loop forever
    PDP --> PAP: Send Status to PAP
end
@enduml

At startup, the PDP initializes itself.  At this point it is in PASSIVE mode. The PDP begins sending periodic Status messages to the PAP.

The first Status message initializes the process of loading the correct Policy Set on the PDP in the PAP.

On receipt or a shutdown request, the PDP completes or aborts any ongoing policy executions and shuts down gracefully.

2.3.4 Policy Execution

Policy execution is the execution of a policy in a PDP. Policy enforcement occurs in the component that receives a policy decision.

@startuml
participant REQUESTOR
participant RESPONDEE
participant PDP

autonumber

alt Synchronous Invocation
    REQUESTOR --> PDP: Execute Policy
    activate PDP
    hnote over REQUESTOR : wait
    PDP --> REQUESTOR: Policy Execution Result
    deactivate PDP
else Asynchronous Invocation
    REQUESTOR --> PDP: Execute Policy
    activate PDP
    PDP --> RESPONDEE: Policy Execution Result
    deactivate PDP
end
@enduml

Policy execution can be synchronous or asynchronous. In synchronous policy execution, the component requesting a policy decision requests a policy decision and waits for the result. The PDP-X and PDP-A use synchronous policy execution. In asynchronous policy execution, the component that requests a policy decision does not wait for the decision. Indeed, the decision may be passed to another component. The PDP-D and PDP-A use asynchronous policy execution.

Policy execution is carried out using the current life cycle mode of operation of the PDP. While the actual implementation of the mode may vary somewhat between PDPs of different types, the principles below hold true for all PDP types:

2.3.5 Policy Lifecycle Management

Policy lifecycle management manages the deployment and life cycle of policies in PDP groups at run time. Policy sets can be deploy at run time without restarting PDPs or stopping policy execution. PDPs preserve state for minor/patch version upgrades and rollbacks.

2.3.5.1 Load/Update Policies on PDP

The sequence diagram below shows how policies are loaded or updated on a PDP.

@startuml
actor User
database PolicyDB
participant PAP
participant DMaaP
participant PDP

autonumber
alt PDP Startup
    PDP --> PAP: Send Status (initial status) to PAP
else Update Request from User
    User --> PAP : Update Policy on PDP
end

PAP --> PolicyDB: Read PDP metadata and Policy Set
PAP -> PAP: Prepare for PDP update
activate PAP
deactivate PAP

PAP --> PDP: Set PDP mode as PASSIVE

PAP --> PDP: Transfer Policy Set Policies to PDP
activate PDP
PDP --> PDP: Load Policies
deactivate PDP

alt PDP Mode should be ACTIVE
    PAP --> PDP : Set PDP mode as ACTIVE
    ref over PDP: Execute Policies in\nACTIVE Mode
else PDP Mode should be SAFE
    PAP --> PDP : Set PDP mode as SAFE
    ref over PDP: Execute Policies in\nSAFE Mode
else PDP Mode should be TEST
    PAP --> PDP : Set PDP mode as TEST
    ref over PDP: Execute Policies in\nTEST Mode
end
PAP --> PolicyDB: Update PDP metadata
@enduml

This sequence can be initiated in two ways; from the PDP or from a user action.

1. A PDP sends regular status update messages to the PAP. If this message indicates that the PDP has no policies or outdated policies loaded, then this sequence is initiated
2. A user may explicitly trigger this sequence to load policies on a PDP

The PAP controls the entire process. The PAP reads the current PDP metadata and the required policy and policy set artifacts from the database. It then builds the policy set for the PDP. Once the policies are ready, the PAP sets the mode of the PDP to PASSIVE. The Policy Set is transparently passed to the PDP by the PAP. The PDP loads all the policies in the policy set including any models, rules, tasks, or flows in the policy set in the policy implementations.

Once the Policy Set is loaded, the PAP orders the PDP to enter the life cycle mode that has been specified for it (ACTIVE/SAFE/TEST). The PDP beings to execute policies in the specified mode (see section 2.3.4).

2.3.5.2 Policy Rollout

A policy set steps through a number of life cycle modes when it is rolled out.

@startuml
actor User
participant PAP
participant PDP

autonumber

User --> PAP: Create Policy Set for PDP Group

loop over PDP Group
    ref over PAP, PDP: PAP downloads Policy Set to PDP
end

User --> PAP: Set PDP Group in Test Mode
loop over PDP Group
    PAP --> PDP: Set PDP in TEST mode
end
    
PDP --> PAP: Report test results
PAP --> User: Report consolidated test results

User --> PAP: Set PDP Group in Safe Mode
loop over PDP Group
    PAP --> PDP: Set PDP in SAFE mode
end
    
PDP --> PAP: Report safe mode operation results
PAP --> User: Report consolidated safe mode operation results

User --> PAP: Set PDP Group in Active Mode
loop over PDP Group
    PAP --> PDP: Set PDP in Active mode
end

loop forever
    PDP --> PAP: Report active mode operation results
    PAP --> User: Report consolidated active mode operation results
end

@enduml

The user defines the set of policies for a PDP group. It is deployed to a PDP group and is initially in PASSIVE mode. The user sets the PDP Group into TEST mode. The policies are run in a test or sandboxed environment for a period of time. The test results are passed back to the user. The user may revert the policy set to PASSIVE mode a number of times and upgrade the policy set during test operation.

When the user is satisfied with policy set execution and when quality criteria have been reached for the policy set, the PDP group is set to run in SAFE mode. In this mode, the policies run on the actual target environment but do not actually exercise any actions or change any context in the target environment. Again, as in TEST mode, the operator may decide to revert back to TEST mode or even PASSIVE mode if issues arise with a policy set.

Finally, when the user is satisfied with policy set execution and when quality criteria have been reached, the PDP group is set into ACTIVE state and the policy set executes on the target environment. The results of target operation are reported. The PDP group can be reverted to SAFE, TEST, or even PASSIVE mode at any time if problems arise.

2.3.5.3 Policy Upgrade and Rollback

There are a number of approaches for managing policy upgrade and rollback.

The most straightforward approach is to use the approach described in section 2.2.5.2 for upgrading and rolling back policy sets. In order to upgrade a policy set, one follows the process in 2.2.5.2 with the new policy set version. For rollback, one follows the process in section 2.2.5.2 with the older policy set, most probably setting the old policy set into ACTIVE mode immediately. The advantage of this approach is that the approach is straightforward. The obvious disadvantage is that the PDP group is not executing on the target environment while the new policy set is in PASSIVE, TEST, and SAFE mode. 

A second manner to tackle upgrade and rollback is to use a spare-wheel approach. An special upgrade PDP group service is set up as a K8S service in parallel with the active one during the upgrade procedure. The spare wheel service is used to execute the process described in section 2.2.5.2. When the time comes to activate the policy set, the references for the active and spare wheel services are simply swapped. The advantage of this approach is that the down time during upgrade is minimized, the spare wheel PDP group can be abandoned at any time without affecting the in service PDP group, and the upgrade can be rolled back easily for a period simply by preserving the old service for a time. The disadvantage is that this approach is more complex than the first approach.

A third approach is to have two policy sets running in each PDP, an active set and a standby set. However such an approach would increase the complexity of implementation in PDPs significantly.

2.3.6 Policy Monitoring

PDPs provide a periodic report of their status to the PAP. All PDPs report using a standard reporting format that is extended to provide information for specific PDP types. PDPs provide at least the information below:

2.3.7 PEP Registration and Enforcement Guidelines

In ONAP there are several applications outside the Policy Framework that enforce policy decisions based on models provided to the Policy Framework. These applications are considered Policy Enforcement Engines (PEP) and roles will be provided to those applications using AAF/CADI to ensure only those applications can make calls to the Policy Decision API's. Some example PEP's are: DCAE, OOF, and SDNC.

See Section 3.4 of the TO BE DELETED - refer to Dublin Documentation for more information on the Decision APIs.

3. APIs Provided by the Policy Framework

See the TO BE DELETED - refer to Dublin Documentation page.

4

• **Applications using the Policy Framework should not be aware of specific PDPs, we should only support this behaviour for existing users and deprecate this usage.
• Load Balancing across PDP group......Stateless PDPs no problem.....set up stateful transfer between PDPs if supported....Address specific PDPs

Image Removed

4. The Policy Framework Implementation

• Database off PAP (PDPs report back to PAP, don’t access database directly)
• Database could be replaced by/interchangeable with some ONAP persistence system (DMaaP or DCAE)?

Image Removed

Observations

• Policy-core has definitions of the Policy protocols and the interfaces for all the interactions between the policy components. It doesn’t have much functional code, it’s mainly the model of the system and to enforce the overall structure and interactions in the system. Some of the current engine goes in there. Implementation of the protocols is in this modules including the Inter-PDP protocol and the generic parts of the Intra-PDP protocol
• PAP functionality extended to do life cycle monitoring and run time monitoring of PDPs, moves out of engine to separate git repository. The Deployment and Monitoring could be separate modules
• Generic PDP functionality is in a separate PDP module, the current generic PDP functionality moves there and is extended to provide generic model driven PDP support for arbitrary PDPs
• PDP-X specific functionality goes to the PDP-X module
• PDP-D and BRMSGW combined in PDP-D (PDP-D related functions in engine and the current drools-pdp combined)
• The drools-applications module generalized to provide interfaces for all the Policy Framework including arbitrary PDPs towards the other ONAP components in the Policy Interactions module. This must have a mechanism to allow model-driven interactions, in other words define interfaces at run time rather than at design time in Java or JAXB.
• All persistence is In the Policy Persistence module in order to keep persistence nastiness out of the other modules, state from PDPs can be persisted by reading state over the Policy Management Protocol. The Policy Management Protocol could use Distributed Hash Maps to share state with Persistence.
• All PDP implementations specialize the generic interfaces from Policy-core and PDP and can extend the Intra-PDP protocol with PDP-specific support, for example for state and context sharing
• Not much thought gone into the Portal as yet except that it will use REST interfaces for interactions.

4.1 Policy Design Implementation

4.2 Policy Deployment Implementation

4.3 Policy Execution Implementation

5. Writing, Deploying, and Running Policies

How to create policies (how the customers use the platform) - Chenfei Gao will collect details on this regarding current problems

5.1 Writing a policy

5.2 Deploying a Policy

5.3 Running a Policy

6. The PDP SDK: Designing and Deploying your own PDP

PDP Microservice Architecture??

TODO: How to build your own PDP and/or how to extend existing PDP.

TOOD: How a PDP expresses its capabilities and configurability

6.1 Configuring the ONAP PDPs

6.2 Customizing the ONAP PDPs

6.3 Developing your own PDP

7. Summary and Conclusions

...

. Terminology

...