blob: cc597b116283c3bff7ba69d2cafa6b34695ec6c0 [file] [log] [blame]
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -04001.. This work is licensed under a
2.. Creative Commons Attribution 4.0 International License.
3.. http://creativecommons.org/licenses/by/4.0
4
Pamela Dragosh9fcabd02020-05-13 07:54:15 -04005.. DO NOT REMOVE THIS LABEL - EVEN IF IT GENERATES A WARNING
6.. _architecture:
7
8.. THIS IS USED INTERNALLY IN POLICY ONLY
liamfallon4d1d9832019-05-30 20:53:05 +00009.. _architecture-label:
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -040010
Pamela Dragosh5f3716b2019-06-03 12:19:22 -040011Policy Framework Architecture
12#############################
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -040013
14Abstract
15
liamfallonc9e27902019-05-28 13:27:04 +000016This document describes the ONAP Policy Framework. It lays out the architecture of the framework and shows the APIs
17provided to other components that interwork with the framework. It describes the implementation of the framework,
18mapping out the components, software structure, and execution ecosystem of the framework.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -040019
20.. contents::
liamfallone62f7112019-05-24 10:50:57 +000021 :depth: 6
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -040022
Pamela Dragosh6eec8752020-05-21 11:06:03 -040023.. toctree::
24 :caption: References
25 :maxdepth: 1
26
27 tosca-policy-primer
28
29
liamfallone62f7112019-05-24 10:50:57 +0000301. Overview
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -040031===========
32
liamfallonc9e27902019-05-28 13:27:04 +000033The ONAP Policy Framework is a comprehensive policy design, deployment, and execution environment. The Policy Framework
34is the decision making component in `an ONAP system
35<https://www.onap.org/wp-content/uploads/sites/20/2018/11/ONAP_CaseSolution_Architecture_112918FNL.pdf>`__.
36It allows you to specify, deploy, and execute the governance of the features and functions in your ONAP system, be they
37closed loop, orchestration, or more traditional open loop use case implementations. The Policy Framework is the
38component that is the source of truth for all policy decisions.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -040039
liamfallonc9e27902019-05-28 13:27:04 +000040One of the most important goals of the Policy Framework is to support Policy Driven Operational Management during the
41execution of ONAP control loops at run time. In addition, use case implementations such as orchestration and control
42benefit from the ONAP policy Framework because they can use the capabilities of the framework to manage and execute
43their policies rather than embedding the decision making in their applications.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -040044
liamfallonc9e27902019-05-28 13:27:04 +000045The Policy Framework is deployment agnostic, it manages Policy Execution (in PDPs) and Enforcement (in PEPs) regardless
liamfallonc5d11f02020-04-07 12:41:34 +010046of how the PDPs and PEPs are deployed. This allows policy execution and enforcement to be deployed in a manner that
liamfallonc9e27902019-05-28 13:27:04 +000047meets the performance requirements of a given application or use case. In one deployment, policy execution could be
48deployed in a separate executing entity in a Docker container. In another, policy execution could be co-deployed with
49an application to increase performance. An example of co-deployment is the Drools PDP Control Loop image, which is a
50Docker image that combines the ONAP Drools use case application and dependencies with the Drools PDP engine.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -040051
liamfallonc9e27902019-05-28 13:27:04 +000052The ONAP Policy Framework architecture separates policies from the platform that is supporting them. The framework
53supports development, deployment, and execution of any type of policy in ONAP. The Policy Framework is metadata (model)
54driven so that policy development, deployment, and execution is as flexible as possible and can support modern rapid
liamfallonc5d11f02020-04-07 12:41:34 +010055development ways of working such as `DevOps
56<https://en.wikipedia.org/wiki/DevOps>`__. A metadata driven approach also allows the amount of programmed support
liamfallonc9e27902019-05-28 13:27:04 +000057required for policies to be reduced or ideally eliminated.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -040058
liamfallonc9e27902019-05-28 13:27:04 +000059We have identified five capabilities as being essential for the framework:
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -040060
liamfallonc9e27902019-05-28 13:27:04 +0000611. Most obviously, the framework must be capable of being triggered by an event or invoked, and making decisions at run
62 time.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -040063
liamfallonc9e27902019-05-28 13:27:04 +0000642. It must be deployment agnostic; capable of managing policies for various Policy Decision Points (PDPs) or policy
65 engines.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -040066
liamfallonc9e27902019-05-28 13:27:04 +0000673. It must be metadata driven, allowing policies to be deployed, modified, upgraded, and removed as the system executes.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -040068
liamfallonc9e27902019-05-28 13:27:04 +0000694. It must provide a flexible model driven policy design approach for policy type programming and specification of
70 policies.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -040071
liamfallonc9e27902019-05-28 13:27:04 +0000725. It must be extensible, allowing straightforward integration of new PDPs, policy formats, and policy development
73 environments.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -040074
liamfallonc9e27902019-05-28 13:27:04 +000075Another important aim of the architecture of a model driven policy framework is that it enables much more flexible
76policy specification. The ONAP Policy Framework complies with the `TOSCA
77<http://docs.oasis-open.org/tosca/TOSCA-Simple-Profile-YAML/v1.1/TOSCA-Simple-Profile-YAML-v1.1.pdf>`__ modelling
78approach for policies, see the :ref:`TOSCA Policy Primer <tosca-label>` for more information on how policies are modeled
79in TOSCA.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -040080
liamfallonc5d11f02020-04-07 12:41:34 +010081 1. A *Policy Type* describes the properties, targets, and triggers that the policy for a feature can have. A Policy type is
82 implementation independent. It is the metadata that specifies:
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -040083
liamfallonc5d11f02020-04-07 12:41:34 +010084 - the *configuration* data that the policy can take. The Policy Type describes each property that a policy of a
85 given type can take. A Policy Type definition also allows the default value, optionality, and the ranges of properties
86 to be defined.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -040087
liamfallonc5d11f02020-04-07 12:41:34 +010088 - the *targets* such as network element types, functions, services, or resources on which a policy of the given type
89 can act.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -040090
liamfallonc5d11f02020-04-07 12:41:34 +010091 - the *triggers* such as the event type, filtered event, scheduled trigger, or conditions that can activate a policy
92 of the given type.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -040093
liamfallonc5d11f02020-04-07 12:41:34 +010094 Policy Types are hierarchical, A Policy Type can inherit from a parent Policy Type, inheriting the properties, targets,
95 and triggers of its parent. Policy Types are developed by domain experts in consultation with the developers that
96 implement the logic and rules for the Policy Type.
97
98 2. A *Policy* is defined using a Policy Type. The Policy defines:
99
100 - the values for each property of the policy type
101 - the specific targets (network elements, functions, services, resources) on which this policy will act
102 - the specific triggers that trigger this policy.
103
104 3. A *Policy Type Implementation* or *Raw Policy*, is the logic that implements the policy. It is implemented by a
105 skilled policy developer in consultation with domain experts. The implementation has software that reads the Policy
liamfallon091a2262020-04-09 08:13:45 +0100106 Type and parses the incoming configuration properties. The software has domain logic that is triggered when one of the
liamfallonc5d11f02020-04-07 12:41:34 +0100107 triggers described in the Policy Type occurs. The software logic executes and acts on the targets specified in the
108 Policy Type.
109
110
111For example, a Policy Type could be written to describe how to manage Service Level Agreements for VPNs. The VPN Policy
112Type can be used to create VPN policies for a bank network, a car dealership network, or a university with many campuses.
113The Policy Type has two parameters:
114
115 - The *maximumDowntime* parameter allows the maximum downtime allowed per year to be specified
116 - The *mitigationStrategy* parameter allows one of three strategies to be selected for downtime breaches
117
118 - *allocateMoreResources*, which will automatically allocate more resources to mitigate the problem
119 - *report*, which report the downtime breach to a trouble ticketing system
120 - *ignore*, which logs the breach and takes no further action
121
122The Policy Type defines a trigger event, an event that is received from an analytics system when the maximum downtime
123value for a VPN is breached. The target of the policy type is an instance of the VPN service.
124
125The Policy Type Implementation is developed that can configure the maximum downtime parameter in an analytics system,
126can receive a trigger from the analytics system when the maximum downtime is breached, and that can either request more
127resources, report an issue to a trouble ticketing system, and can log a breach.
128
liamfallon1c7c5202020-04-14 13:42:34 +0100129VPN Policies are created by specifying values for the properties, triggers, and targets specified in VPN Policy Type.
liamfallonc5d11f02020-04-07 12:41:34 +0100130
131In the case of the bank network, the *maximumDowntime* threshold is specified as 5 minutes downtime per year and the
132*mitigationStrategy* is defined as *allocateMoreResources*, and the target is specified as being the bank's VPN service
133ID. When a breach is detected by the analytics system, the policy is executed, the target is identified as being the
134bank's network, and more resources are allocated by the policy.
135
136For the car dealership VPN policy, a less stringent downtime threshold of 60 minutes per year is specified, and the
137mitigation strategy is to issue a trouble ticket. The university network is best effort, so a downtime of 4 days per
138year is specified. Breaches are logged and mitigated as routine network administration tasks.
139
140In ONAP, specific ONAP Policy Types are used to create specific policies that drive the ONAP Platform and Components.
liamfallonc9e27902019-05-28 13:27:04 +0000141For more detailed information on designing Policy Types and developing an implementation for that policy type, see
142:ref:`Policy Design and Development <design-label>`.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400143
liamfallonc9e27902019-05-28 13:27:04 +0000144The ONAP Policy Framework for building, configuring and deploying PDPs is extendable. It allows the use of ONAP PDPs as
145is, the extension of ONAP PDPs, and lastly provides the capability for users to create and deploy their own PDPs. The
146ONAP Policy Framework provides distributed policy management for **all** policies in ONAP at run time. Not only does
147this provide unified policy access and version control, it provides life cycle control for policies and allows detection
148of conflicts across all policies running in an ONAP installation.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400149
1502. Architecture
151===============
152
liamfallonc9e27902019-05-28 13:27:04 +0000153The diagram below shows the architecture of the ONAP Policy Framework at its highest level.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400154
liamfallon4d1d9832019-05-30 20:53:05 +0000155.. image:: images/PFHighestLevel.svg
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400156
liamfallonc9e27902019-05-28 13:27:04 +0000157The *PolicyDevelopment* component implements the functionality for development of policy types and policies.
158*PolicyAdministration* is responsible for the deployment life cycle of policies as well as interworking with the
159mechanisms required to orchestrate the nodes and containers on which policies run. *PolicyAdministration* is also
160responsible for the administration of policies at run time; ensuring that policies are available to users, that policies
161are executing correctly, and that the state and status of policies is monitored. *PolicyExecution* is the set of PDPs
162running in the ONAP system and is responsible for making policy decisions and for managing the administrative state of
163the PDPs as directed by \ *PolicyAdministration.*
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400164
liamfallon091a2262020-04-09 08:13:45 +0100165*PolicyDevelopment* provides APIs that allow creation of policy artifacts and supporting information in the policy
166database. *PolicyAdministration* reads those artifacts and the supporting information from the policy database whilst
167deploying policy artifacts. Once the policy artifacts are deployed, *PolicyAdministration* handles the run-time
168management of the PDPs on which the policies are running. *PolicyDevelopment* interacts with the database, and has
169no programmatic interface with *PolicyAdministration*, *PolicyExecution* or any other run-time ONAP components.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400170
liamfallonc9e27902019-05-28 13:27:04 +0000171The diagram below shows a more detailed view of the architecture, as inspired by
172`RFC-2753 <https://tools.ietf.org/html/rfc2753>`__ and `RFC-3198 <https://tools.ietf.org/html/rfc3198>`__.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400173
liamfallon4d1d9832019-05-30 20:53:05 +0000174.. image:: images/PFDesignAndAdmin.svg
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400175
liamfallonc9e27902019-05-28 13:27:04 +0000176*PolicyDevelopment* provides a `CRUD <https://en.wikipedia.org/wiki/Create,_read,_update_and_delete>`__ API for policy
liamfallon091a2262020-04-09 08:13:45 +0100177types and policies. The policy types and policy artifacts and their metadata (information about policies, policy types,
liamfallonc9e27902019-05-28 13:27:04 +0000178and their interrelations) are stored in the *PolicyDB*. The *PolicyDevGUI*, PolicyDistribution, and other applications
liamfallon091a2262020-04-09 08:13:45 +0100179such as *CLAMP* can use the *PolicyDevelopment* API to create, update, delete, and read policy types and policies.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400180
181*PolicyAdministration* has two important functions:
182
liamfallonc9e27902019-05-28 13:27:04 +0000183- Management of the life cycle of PDPs in an ONAP installation. PDPs register with *PolicyAdministration* when they come
liamfallon091a2262020-04-09 08:13:45 +0100184 up. *PolicyAdministration* handles the allocation of PDPs to PDP Groups and PDP Subgroups, so that they can be
185 managed as microservices in infrastructure management systems such as Kubernetes.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400186
liamfallonc9e27902019-05-28 13:27:04 +0000187- Management of the deployment of policies to PDPs in an ONAP installation. *PolicyAdministration* gives each PDP group
188 a set of domain policies to execute.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400189
liamfallonc9e27902019-05-28 13:27:04 +0000190*PolicyAdministration* handles PDPs and policy allocation to PDPs using asynchronous messaging over DMaaP. It provides
191three APIs:
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400192
liamfallonc9e27902019-05-28 13:27:04 +0000193- a CRUD API for policy groups and subgroups
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400194
liamfallon091a2262020-04-09 08:13:45 +0100195- an API that allows the allocation of policies to PDP groups and subgroups to be controlled
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400196
liamfallonc9e27902019-05-28 13:27:04 +0000197- an API allows policy execution to be managed, showing the status of policy execution on PDP Groups, subgroups, and
198 individual PDPs as well as the life cycle state of PDPs
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400199
liamfallonc9e27902019-05-28 13:27:04 +0000200*PolicyExecution* is the set of running PDPs that are executing policies, logically partitioned into PDP groups and
201subgroups.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400202
liamfallon4d1d9832019-05-30 20:53:05 +0000203.. image:: images/PolicyExecution.svg
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400204
liamfallonc9e27902019-05-28 13:27:04 +0000205The figure above shows how *PolicyExecution* looks at run time with PDPs running in Kubernetes. A *PDPGroup* is a purely
206logical construct that collects all the PDPs that are running policies for a particular domain together. A *PDPSubGroup*
207is a group of PDPs of the same type that are running the same policies. *A PDPSubGroup* is deployed as a Kubernetes
208`Deployment <https://kubernetes.io/docs/concepts/workloads/controllers/deployment/>`__. PDPs are defined as Kubernetes
209`Pods <https://kubernetes.io/docs/concepts/workloads/pods/pod/>`__. At run time, the actual number of PDPs in each
210*PDPSubGroup* is specified in the configuration of the *Deployment* of that *PDPSubGroup* in Kubernetes. This
211structuring of PDPs is required because, in order to simplify deployment and scaling of PDPs in Kubernetes, we gather
212all the PDPs of the same type that are running the same policies together for deployment.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400213
liamfallon091a2262020-04-09 08:13:45 +0100214For example, assume we have policies for the SON (Self Organizing Network) and ACPS (Advanced Customer Premises Service)
215domains. For SON,we have XACML, Drools, and APEX policies, and for ACPS we have XACML and Drools policies. The table
liamfallonc9e27902019-05-28 13:27:04 +0000216below shows the resulting \ *PDPGroup*, *PDPSubGroup*, and PDP allocations:
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400217
liamfallonc9e27902019-05-28 13:27:04 +0000218============= ================ ========================= ======================================== ================
219**PDP Group** **PDP Subgroup** **Kubernetes Deployment** **Kubernetes Deployment Strategy** **PDPs in Pods**
220============= ================ ========================= ======================================== ================
221SON SON-XACML SON-XACML-Dep Always 2, be geo redundant 2 PDP-X
222\ SON-Drools SON-Drools-Dep At Least 4, scale up on 70% load, >= 4 PDP-D
223 scale down on 40% load, be geo-redundant
224\ SON-APEX SON-APEX-Dep At Least 3, scale up on 70% load, scale >= 3 PDP-A
225 down on 40% load, be geo-redundant
liamfallon091a2262020-04-09 08:13:45 +0100226ACPS ACPS-XACML ACPS-XACML-Dep Always 2 2 PDP-X
227\ ACPS-Drools ACPS-Drools-Dep At Least 2, scale up on 80% load, scale >=2 PDP-D
liamfallonc9e27902019-05-28 13:27:04 +0000228 down on 50% load
229============= ================ ========================= ======================================== ================
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400230
liamfallonc9e27902019-05-28 13:27:04 +0000231For more details on *PolicyAdministration* APIs and management of *PDPGroup* and *PDPSubGroup*, see the documentation
232for :ref:`Policy Administration Point (PAP) Architecture <pap-label>`.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400233
2342.1 Policy Framework Object Model
235---------------------------------
236
liamfallonc9e27902019-05-28 13:27:04 +0000237This section describes the structure of and relations between the main concepts in the Policy Framework. This model is
238implemented as a common model and is used by *PolicyDevelopment*, *PolicyDeployment,* and *PolicyExecution.*
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400239
liamfallon4d1d9832019-05-30 20:53:05 +0000240.. image:: images/ClassStructure.svg
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400241
liamfallon091a2262020-04-09 08:13:45 +0100242The UML class diagram above shows thePolicy Framework Object Model.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400243
2442.2 Policy Design Architecture
245------------------------------
246
liamfallon1c7c5202020-04-14 13:42:34 +0100247This section describes the architecture of the model driven system used to develop policy types and to create
liamfallonc9e27902019-05-28 13:27:04 +0000248policies using policy types. The output of Policy Design is deployment-ready artifacts and Policy metadata in the Policy
249Framework database.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400250
liamfallon1c7c5202020-04-14 13:42:34 +0100251Policy types that are expressed via natural language or a model require an implementation that allows them to be
252translated into runtime policies. Some Policy Type implementations are set up and available in the platform during
liamfallonc9e27902019-05-28 13:27:04 +0000253startup such as Control Loop Operational Policy Models, OOF placement Models, DCAE microservice models. Policy type
liamfallon1c7c5202020-04-14 13:42:34 +0100254implementations can also be loaded and deployed at run time.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400255
2562.2.1 Policy Type Design
liamfallone62f7112019-05-24 10:50:57 +0000257^^^^^^^^^^^^^^^^^^^^^^^^
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400258
liamfallonc9e27902019-05-28 13:27:04 +0000259Policy Type Design is the task of creating policy types that capture the generic and vendor independent aspects of a
liamfallon1c7c5202020-04-14 13:42:34 +0100260policy for a particular domain use case.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400261
liamfallon1c7c5202020-04-14 13:42:34 +0100262All policy types are specified in TOSCA service templates. Once policy types are defined and created in the system,
liamfallon091a2262020-04-09 08:13:45 +0100263*PolicyDevelopment* manages them and uses them to allow policies to be created from these policy types in a uniform
264way regardless of the domain that the policy type is addressing or the PDP technology that will execute the policy.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400265
liamfallon091a2262020-04-09 08:13:45 +0100266A *PolicyTypeImpl* is developed for a policy type for a certain type of PDP (for example XACML oriented for decision
267policies, Drools rules or Apex state machines oriented for ECA policies). While a policy type is implementation
268independent, a policy type implementation for a policy type is specific for the technology of the PDP on which
liamfallon1c7c5202020-04-14 13:42:34 +0100269policies that use that policy type implementation will execute. A Policy Type may have many implementations. A
270*PolicyTypeImpl* is the specification of the specific rules or tasks, the flow of the policy, its internal states
271and data structures and other relevant information. A *PolicyTypeImpl* can be specific to a particular policy type
272or it can be more general, providing the implementation of a class of policy types. Further, the design environment
273and tool chain for implementing implementations of policy types is specific to the technology of the PDP on which
274the implementation will run.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400275
liamfallon3602c182020-04-16 09:29:45 +0100276In the *xacml-pdp* and *drools-pdp*, an *application* is written for a given category of policy types. Such an
277application may have logic written in Java or another programming language, and may have additional artifacts such
278as scripts and SQL queries. The *application* unmarshals and marshals events going into and out of policies as well
279as handling the sequencing of events for interactions of the policies with other components in ONAP. For example,
280*drools-applications* handles the interactions for operational policies running in the drools PDP. In the
281*apex-pdp*, all unmarshaling, marshaling, and component interactions are captured in the state machine, logic, and
282configuraiton of the policy, a Java application is not used.
283
liamfallon091a2262020-04-09 08:13:45 +0100284*PolicyDevelopment* provides the RESTful :ref:`Policy Design API <design-label>`, which allows other components to query
285policy types, Those components can then create policies that specify values for the properties, triggers, and targets
286specified in a policy type. This API is used by components such as *CLAMP* and *PolicyDistribution* to create policies
287from policy types.
liamfallonc9e27902019-05-28 13:27:04 +0000288
289Consider a policy type created for managing faults on vCPE equipment in a vendor independent way. The policy type
liamfallon091a2262020-04-09 08:13:45 +0100290implementation captures the generic logic required to manage the faults and specifies the vendor specific information
291that must be supplied to the type for specific vendor vCPE VFs. The actual vCPE policy that is used for managing
292particular vCPE equipment is created by setting the properties specified in the policy type for that vendor model
293of vCPE.
liamfallonc9e27902019-05-28 13:27:04 +0000294
2952.2.1.1 Generating Policy Types
296"""""""""""""""""""""""""""""""
297
298It is possible to generate policy types using MDD (Model Driven Development) techniques. Policy types are expressed
299using a DSL (Domain Specific Language) or a policy specification environment for a particular application domain. For
300example, policy types for specifying SLAs could be expressed in a SLA DSL and policy types for managing SON features
301could be generated from a visual SON management tool. The ONAP Policy framework provides an API that allows tool chains
liamfallon1c7c5202020-04-14 13:42:34 +0100302to create policy types, see the :ref:`Policy Design and Development <design-label>` page.
liamfallonc9e27902019-05-28 13:27:04 +0000303
304.. image:: images/PolicyTypeDesign.svg
305
liamfallon1c7c5202020-04-14 13:42:34 +0100306A GUI implementation in another ONAP component (a *PolicyTypeDesignClient*) may use the *API_User* API to create and
307edit ONAP policy types.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400308
liamfallonc9e27902019-05-28 13:27:04 +00003092.2.1.2 Programming Policy Type Implementations
liamfallone62f7112019-05-24 10:50:57 +0000310"""""""""""""""""""""""""""""""""""""""""""""""
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400311
liamfallonc9e27902019-05-28 13:27:04 +0000312For skilled developers, the most straightforward way to create a policy type is to program it. Programming a policy type
313might simply mean creating and editing text files, thus manually creating the TOSCA Policy Type YAML file and the policy
314type implementation for the policy type.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400315
liamfallonc9e27902019-05-28 13:27:04 +0000316A more formal approach is preferred. For policy type implementations, programmers use a specific Eclipse project type
317for developing each type of implementation, a Policy Type Implementation SDK. The project is under source control in
318git. This Eclipse project is structured correctly for creating implementations for a specific type of PDP. It includes
319the correct POM files for generating the policy type implementation and has editors and perspectives that aid
320programmers in their work
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400321
3222.2.2 Policy Design
liamfallone62f7112019-05-24 10:50:57 +0000323^^^^^^^^^^^^^^^^^^^
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400324
liamfallonc9e27902019-05-28 13:27:04 +0000325The *PolicyCreation* function of *PolicyDevelopment* creates policies from a policy type. The information expressed
326during policy type design is used to parameterize a policy type to create an executable policy. A service designer
327and/or operations team can use tooling that reads the TOSCA Policy Type specifications to express and capture a policy
328at its highest abstraction level. Alternatively, the parameter for the policy can be expressed in a raw JSON or YAML
329file and posted over the policy design API described on the :ref:`Policy Design and Development <design-label>` page.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400330
liamfallonc9e27902019-05-28 13:27:04 +0000331A number of mechanisms for policy creation are supported in ONAP. The process in *PolicyDevelopment* for creating a
332policy is the same for all mechanisms. The most general mechanism for creating a policy is using the RESTful
333*Policy Design API*, which provides a full interface to the policy creation support of *PolicyDevelopment*. This API may
liamfallon1c7c5202020-04-14 13:42:34 +0100334be exercised directly using utilities such as *curl*.
335
336In future releases, the Policy Framework may provide a command line tool that will be a loose wrapper around the API. It
337may also provide a general purpose Policy GUI in the ONAP Portal for policy creation, which again would be a general
338purpose wrapper around the policy creation API. The Policy GUI would interpret any TOSCA Model that has been loaded into
339it and flexibly presents a GUI for a user to create policies from. The development of these mechanisms will be phased
340over a number of ONAP releases.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400341
liamfallonc9e27902019-05-28 13:27:04 +0000342A number of ONAP components use policy in manners which are specific to their particular needs. The manner in which the
343policy creation process is triggered and the way in which information required to create a policy is specified and
344accessed is specialized for these ONAP components.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400345
liamfallon1c7c5202020-04-14 13:42:34 +0100346For example, *CLAMP* provides a GUI for creation of Control Loop policies, which reads the Policy Type associated
347with a control loop, presents the properties as fields in its GUI, and creates a policy using the property values entered
348by the user.
349
liamfallonc9e27902019-05-28 13:27:04 +0000350The following subsections outline the mechanisms for policy creation and modification supported by the ONAP Policy
351Framework.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400352
3532.2.2.1 Policy Design in the ONAP Policy Framework
liamfallone62f7112019-05-24 10:50:57 +0000354""""""""""""""""""""""""""""""""""""""""""""""""""
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400355
liamfallonc9e27902019-05-28 13:27:04 +0000356Policy creation in *PolicyDevelopment* follows the general sequence shown in the sequence diagram below. An *API_USER*
357is any component that wants to create a policy from a policy type. *PolicyDevelopment* supplies a REST interface that
358exposes the API and also provides a command line tool and general purpose client that wraps the API.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400359
liamfallonc9e27902019-05-28 13:27:04 +0000360.. image:: images/PolicyDesign.svg
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400361
liamfallonc9e27902019-05-28 13:27:04 +0000362An *API_User* first gets a reference to and the metadata for the Policy type for the policy they want to work on from
363*PolicyDevelopment*. *PolicyDevelopment* reads the metadata and artifact for the policy type from the database. The
364*API_User* then asks for a reference and the metadata for the policy. *PolicyDevelopment* looks up the policy in the
365database. If the policy already exists, *PolicyDevelopment* reads the artifact and returns the reference of the existing
366policy to the *API_User* with the metadata for the existing policy. If the policy does not exist, *PolicyDevelopment*
liamfallon1c7c5202020-04-14 13:42:34 +0100367informs the *API_User*.
liamfallonc9e27902019-05-28 13:27:04 +0000368
369The *API_User* may now proceed with a policy specification session, where the parameters are set for the policy using
370the policy type specification. Once the *API_User* is happy that the policy is completely and correctly specified, it
371requests *PolicyDevelopment* to create the policy. *PolicyDevelopment* creates the policy, stores the created policy
372artifact and its metadata in the database.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400373
3742.2.2.2 Model Driven VF (Virtual Function) Policy Design via VNF SDK Packaging
liamfallone62f7112019-05-24 10:50:57 +0000375""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400376
liamfallonc9e27902019-05-28 13:27:04 +0000377VF vendors express policies such as SLA, Licenses, hardware placement, run-time metric suggestions, etc. These details
378are captured within the VNF SDK and uploaded into the SDC Catalog. The `SDC Distribution APIs
379<https://wiki.onap.org/display/DW/SDC+Distribution+client+AID>`__ are used to interact with SDC. For example, SLA and
380placement policies may be captured via TOSCA specification. License policies can be captured via TOSCA or an XACML
381specification. Run-time metric vendor recommendations can be captured via the VES Standard specification.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400382
liamfallonc9e27902019-05-28 13:27:04 +0000383The sequence diagram below is a high level view of SDC-triggered concrete policy generation for some arbitrary entity
384*EntityA*. The parameters to create a policy are read from a TOSCA Policy specification read from a CSAR received from
385SDC.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400386
liamfallonc9e27902019-05-28 13:27:04 +0000387.. image:: images/ModelDrivenPolicyDesign.svg
388
389*PolicyDesign* uses the *PolicyDistribution* component for managing SDC-triggered policy creation and update requests.
390*PolicyDistribution* is an *API_User*, it uses the Policy Design API for policy creation and update. It reads the
391information it needs to populate the policy type from a TOSCA specification in a CSAR received from SDC and then uses
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400392this information to automatically generate a policy.
393
liamfallonc9e27902019-05-28 13:27:04 +0000394Note that SDC provides a wrapper for the SDC API as a Java Client and also provides a TOSCA parser. See the
395documentation for the `Policy Distribution Component
Jim Hahn182f20f2021-03-30 15:02:36 -0400396<https://docs.onap.org/projects/onap-policy-parent/en/honolulu/distribution/distribution.html>`__.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400397
liamfallonc9e27902019-05-28 13:27:04 +0000398In Step 4 above, the \ *PolicyDesign* must download the CSAR file. If the policy is to be composed from the TOSCA
399definition, it must also parse the TOSCA definition.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400400
liamfallonc9e27902019-05-28 13:27:04 +0000401In Step 11 above, the \ *PolicyDesign* must send back/publish status events to SDC such as DOWNLOAD_OK, DOWNLOAD_ERROR,
402DEPLOY_OK, DEPLOY_ERROR, NOTIFIED.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400403
liamfallone62f7112019-05-24 10:50:57 +00004042.2.2.3 Scripted Model Driven Policy Design
405"""""""""""""""""""""""""""""""""""""""""""
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400406
liamfallonc9e27902019-05-28 13:27:04 +0000407Service policies such as optimization and placement policies can be specified as a TOSCA Policy at design time. These
408policies use a TOSCA Policy Type specification as their schemas. Therefore, scripts can be used to create TOSCA policies
409using TOSCA Policy Types.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400410
liamfallonc9e27902019-05-28 13:27:04 +0000411.. image:: images/ScriptedPolicyDesign.svg
412
liamfallon1c7c5202020-04-14 13:42:34 +0100413One straightforward way of generating policies from Policy types is to use commands specified in a script file. A
414command line utility such as *curl* is an *API_User*. Commands read policy types using the Policy Type API, parse the
415policy type and uses the properties of the policy type to prepare a TOSCA Policy. It then issues further commands to use
416the Policy API to create policies.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400417
4182.2.3 Policy Design Process
liamfallone62f7112019-05-24 10:50:57 +0000419^^^^^^^^^^^^^^^^^^^^^^^^^^^
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400420
liamfallonc9e27902019-05-28 13:27:04 +0000421All policy types must be certified as being fit for deployment prior to run time deployment. Where design is executed
422using the SDC application, it is assumed the life cycle being implemented by SDC certifies any policy types that
423are declared within the ONAP Service CSAR. For other policy types and policy type implementations, the life cycle
424associated with the applied software development process suffices. Since policy types and their implementations are
425designed and implemented using software development best practices, they can be utilized and configured for various
426environments (eg. development, testing, production) as desired.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400427
4282.3 Policy Runtime Architecture
429-------------------------------
430
liamfallonc9e27902019-05-28 13:27:04 +0000431The Policy Framework Platform components are themselves designed as microservices that are easy to configure and deploy
432via Docker images and K8S both supporting resiliency and scalability if required. PAPs and PDPs are deployed by the
433underlying ONAP management infrastructure and are designed to comply with the ONAP interfaces for deploying containers.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400434
liamfallonc9e27902019-05-28 13:27:04 +0000435The PAPs keep track of PDPs, support the deployment of PDP groups and the deployment of a *policy set* across those PDP
436groups. A PAP is stateless in a RESTful sense. Therefore, if there is more than one PAP deployed, it does not matter
437which PAP a user contacts to handle a request. The PAP uses the database (persistent storage) to keep track of ongoing
liamfallon3602c182020-04-16 09:29:45 +0100438sessions with PDPs. Policy management on PDPs is the responsibility of PAPs; management of policy sets or policies by
liamfallonc9e27902019-05-28 13:27:04 +0000439any other manner is not permitted.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400440
liamfallonc9e27902019-05-28 13:27:04 +0000441In the ONAP Policy Framework, the interfaces to the PDP are designed to be as streamlined as possible. Because the PDP
442is the main unit of scalability in the Policy Framework, the framework is designed to allow PDPs in a PDP group to
443arbitrarily appear and disappear and for policy consistency across all PDPs in a PDP group to be easily maintained.
444Therefore, PDPs have just two interfaces; an interface that users can use to execute policies and interface to the PAP
445for administration, life cycle management and monitoring. The PAP is responsible for controlling the state across the
446PDPs in a PDP group. The PAP interacts with the Policy database and transfers policy sets to PDPs, and may cache the
447policy sets for PDP groups.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400448
liamfallonc9e27902019-05-28 13:27:04 +0000449See also Section 2 of the :ref:`Policy Design and Development <design-label>` page, where the mechanisms for PDP
450Deployment and Registration with PAP are explained.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400451
4522.3.1 Policy Framework Services
liamfallone62f7112019-05-24 10:50:57 +0000453^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400454
liamfallonc9e27902019-05-28 13:27:04 +0000455The ONAP Policy Framework follows the architectural approach for microservices recommended by the `ONAP Architecture
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400456Subcommittee <https://wiki.onap.org/display/DW/Architecture+Subcommittee>`__.
457
liamfallon3602c182020-04-16 09:29:45 +0100458The ONAP Policy Framework uses an infrastructure such as Kubernetes `Services
liamfallonc9e27902019-05-28 13:27:04 +0000459<https://kubernetes.io/docs/concepts/services-networking/service/>`__ to manage the life cycle of Policy Framework
460executable components at runtime. A Kubernetes service allows, among other parameters, the number of instances (*pods*
461in Kubernetes terminology) that should be deployed for a particular service to be specified and a common endpoint for
462that service to be defined. Once the service is started in Kubernetes, Kubernetes ensures that the specified number of
463instances is always kept running. As requests are received on the common endpoint, they are distributed across the
464service instances. More complex call distribution and instance deployment strategies may be used; please see the
465`Kubernetes Services <https://kubernetes.io/docs/concepts/services-networking/service/>`__ documentation for those
466details.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400467
liamfallonc9e27902019-05-28 13:27:04 +0000468If, for example, a service called *policy-pdpd-control-loop* is defined that runs 5 PDP-D instances. The service has the
469end point *https://policy-pdpd-control-loop.onap/<service-specific-path>*. When the service is started, Kubernetes spins
470up 5 PDP-Ds. Calls to the end point *https://policy-pdpd-control-loop.onap/<service-specific-path>* are distributed
471across the 5 PDP-D instances. Note that the *.onap* part of the service endpoint is the namespace being used and is
472specified for the full ONAP Kubernetes installation.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400473
474The following services will be required for the ONAP Policy Framework:
475
liamfallonc9e27902019-05-28 13:27:04 +0000476================ ============================== =======================================================================
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400477**Service** **Endpoint** **Description**
liamfallonc9e27902019-05-28 13:27:04 +0000478================ ============================== =======================================================================
479PAP https://policy-pap The PAP service, used for policy administration and deployment. See
480 :ref:`Policy Design and Development <design-label>` for details of the
481 API for this service
482PDP-X-\ *domain* https://policy-pdpx-\ *domain* A PDP service is defined for each PDP group. A PDP group is identified
483 by the domain on which it operates.
484
485 For example, there could be two PDP-X domains, one for admission
486 policies for ONAP proper and another for admission policies for VNFs of
487 operator *Supacom*. Two PDP-X services are defined:
488
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400489 | https://policy-pdpx-onap
490 | https://policy-pdpx-\ *supacom*
491PDP-D-\ *domain* https://policy-pdpd-\ *domain*
492PDP-A-\ *domain* https://policy-pdpa-\ *domain*
liamfallonc9e27902019-05-28 13:27:04 +0000493================ ============================== =======================================================================
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400494
liamfallonc9e27902019-05-28 13:27:04 +0000495There is one and only one PAP service, which handles policy deployment, administration, and monitoring for all policies
496in all PDPs and PDP groups in the system. There are multiple PDP services, one PDP service for each domain for which
497there are policies.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400498
4992.3.2 The Policy Framework Information Structure
liamfallone62f7112019-05-24 10:50:57 +0000500^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400501
liamfallonc9e27902019-05-28 13:27:04 +0000502The following diagram captures the relationship between Policy Framework concepts at run time.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400503
liamfallonc9e27902019-05-28 13:27:04 +0000504.. image:: images/RuntimeRelationships.svg
505
506There is a one to one relationship between a PDP SubGroup, a Kubernetes PDP service, and the set of policies assigned to
507run in the PDP subgroup. Each PDP service runs a single PDP subgroup with multiple PDPs, which executes a specific
508Policy Set containing a number of policies that have been assigned to that PDP subgroup. Having and maintaining this
509principle makes policy deployment and administration much more straightforward than it would be if complex relationships
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400510between PDP services, PDP subgroups, and policy sets.
511
liamfallonc9e27902019-05-28 13:27:04 +0000512The topology of the PDPs and their policy sets is held in the Policy Framework database and is administered by the PAP service.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400513
liamfallonc9e27902019-05-28 13:27:04 +0000514.. image:: images/PolicyDatabase.svg
515
516The diagram above gives an indicative structure of the run time topology information in the Policy Framework database.
517Note that the *PDP_SUBGROUP_STATE* and *PDP_STATE* fields hold state information for life cycle management of PDP groups
518and PDPs.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400519
5202.3.3 Startup, Shutdown and Restart
liamfallone62f7112019-05-24 10:50:57 +0000521^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400522
liamfallonc9e27902019-05-28 13:27:04 +0000523This section describes the interactions between Policy Framework components themselves and with other ONAP components at
524startup, shutdown and restart.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400525
5262.3.3.1 PAP Startup and Shutdown
liamfallone62f7112019-05-24 10:50:57 +0000527""""""""""""""""""""""""""""""""
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400528
529The sequence diagram below shows the actions of the PAP at startup.
530
liamfallonc9e27902019-05-28 13:27:04 +0000531.. image:: images/PAPStartStop.svg
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400532
liamfallonc9e27902019-05-28 13:27:04 +0000533The PAP is the run time point of coordination for the ONAP Policy Framework. When it is started, it initializes itself
534using data from the database. It then waits for periodic PDP status updates and for administration requests.
535
536PAP shutdown is trivial. On receipt or a shutdown request, the PAP completes or aborts any ongoing operations and shuts
537down gracefully.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400538
5392.3.3.2 PDP Startup and Shutdown
liamfallone62f7112019-05-24 10:50:57 +0000540""""""""""""""""""""""""""""""""
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400541
liamfallonc9e27902019-05-28 13:27:04 +0000542The sequence diagram below shows the actions of the PDP at startup. See also Section 4 of the
543:ref:`Policy Design and Development <design-label>` page for the API used to implement this sequence.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400544
liamfallonc9e27902019-05-28 13:27:04 +0000545.. image:: images/PDPStartStop.svg
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400546
liamfallonc9e27902019-05-28 13:27:04 +0000547At startup, the PDP initializes itself. At this point it is in PASSIVE mode. The PDP begins sending periodic Status
548messages to the PAP. The first Status message initializes the process of loading the correct Policy Set on the PDP in
549the PAP.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400550
liamfallonc9e27902019-05-28 13:27:04 +0000551On receipt or a shutdown request, the PDP completes or aborts any ongoing policy executions and shuts down gracefully.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400552
5532.3.4 Policy Execution
liamfallone62f7112019-05-24 10:50:57 +0000554^^^^^^^^^^^^^^^^^^^^^^
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400555
liamfallonc9e27902019-05-28 13:27:04 +0000556Policy execution is the execution of a policy in a PDP. Policy enforcement occurs in the component that receives a
557policy decision.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400558
liamfallon4d1d9832019-05-30 20:53:05 +0000559.. image:: images/PolicyExecutionFlow.svg
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400560
liamfallonc9e27902019-05-28 13:27:04 +0000561Policy execution can be *synchronous* or *asynchronous*. In *synchronous* policy execution, the component requesting a
562policy decision requests a policy decision and waits for the result. The PDP-X and PDP-A implement synchronous policy
563execution. In *asynchronous* policy execution, the component that requests a policy decision does not wait for the
564decision. Indeed, the decision may be passed to another component. The PDP-D and PDP-A implement asynchronous polic
565execution.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400566
liamfallonc9e27902019-05-28 13:27:04 +0000567Policy execution is carried out using the current life cycle mode of operation of the PDP. While the actual
568implementation of the mode may vary somewhat between PDPs of different types, the principles below hold true for all
569PDP types:
570
571================== =====================================================================================================
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400572**Lifecycle Mode** **Behaviour**
liamfallonc9e27902019-05-28 13:27:04 +0000573================== =====================================================================================================
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400574PASSIVE MODE Policy execution is always rejected irrespective of PDP type.
575ACTIVE MODE Policy execution is executed in the live environment by the PDP.
liamfallon3602c182020-04-16 09:29:45 +0100576SAFE MODE* Policy execution proceeds, but changes to domain state or context are not carried out. The PDP
liamfallonc9e27902019-05-28 13:27:04 +0000577 returns an indication that it is running in SAFE mode together with the action it would have
578 performed if it was operating in ACTIVE mode. The PDP type and the policy types it is running must
579 support SAFE mode operation.
liamfallon3602c182020-04-16 09:29:45 +0100580TEST MODE* Policy execution proceeds and changes to domain and state are carried out in a test or sandbox
liamfallonc9e27902019-05-28 13:27:04 +0000581 environment. The PDP returns an indication it is running in TEST mode together with the action it has
582 performed on the test environment. The PDP type and the policy types it is running must support TEST
583 mode operation.
584================== =====================================================================================================
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400585
liamfallon3602c182020-04-16 09:29:45 +0100586\* SAFE Mode and TEST Mode will be implemented in future versions of the Policy Framework.
587
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -04005882.3.5 Policy Lifecycle Management
liamfallone62f7112019-05-24 10:50:57 +0000589^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400590
liamfallonc9e27902019-05-28 13:27:04 +0000591Policy lifecycle management manages the deployment and life cycle of policies in PDP groups at run time. Policy sets can
592be deployed at run time without restarting PDPs or stopping policy execution. PDPs preserve state for minor/patch
593version upgrades and rollbacks.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400594
5952.3.5.1 Load/Update Policies on PDP
liamfallone62f7112019-05-24 10:50:57 +0000596"""""""""""""""""""""""""""""""""""
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400597
liamfallonc9e27902019-05-28 13:27:04 +0000598The sequence diagram below shows how policies are loaded or updated on a PDP.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400599
liamfallonc9e27902019-05-28 13:27:04 +0000600.. image:: images/DownloadPoliciesToPDP.svg
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400601
liamfallonc9e27902019-05-28 13:27:04 +0000602This sequence can be initiated in two ways; from the PDP or from a user action.
603
6041. A PDP sends regular status update messages to the PAP. If this message indicates that the PDP has no policies or
605 outdated policies loaded, then this sequence is initiated
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400606
6072. A user may explicitly trigger this sequence to load policies on a PDP
608
liamfallonc9e27902019-05-28 13:27:04 +0000609The PAP controls the entire process. The PAP reads the current PDP metadata and the required policy and policy set
610artifacts from the database. It then builds the policy set for the PDP. Once the policies are ready, the PAP sets the
611mode of the PDP to PASSIVE. The Policy Set is transparently passed to the PDP by the PAP. The PDP loads all the policies
612in the policy set including any models, rules, tasks, or flows in the policy set in the policy implementations.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400613
liamfallonc9e27902019-05-28 13:27:04 +0000614Once the Policy Set is loaded, the PAP orders the PDP to enter the life cycle mode that has been specified for it
liamfallon3602c182020-04-16 09:29:45 +0100615(ACTIVE/SAFE*/TEST*). The PDP begins to execute policies in the specified mode (see section 2.3.4).
616
617\* SAFE Mode and TEST Mode will be implemented in future versions of the Policy Framework.
liamfallonc9e27902019-05-28 13:27:04 +0000618
619.. _policy-rollout:
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400620
6212.3.5.2 Policy Rollout
liamfallone62f7112019-05-24 10:50:57 +0000622""""""""""""""""""""""
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400623
liamfallonc9e27902019-05-28 13:27:04 +0000624A policy set steps through a number of life cycle modes when it is rolled out.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400625
liamfallonc9e27902019-05-28 13:27:04 +0000626.. image:: images/PolicyRollout.svg
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400627
liamfallonc9e27902019-05-28 13:27:04 +0000628The user defines the set of policies for a PDP group. It is deployed to a PDP group and is initially in PASSIVE mode.
629The user sets the PDP Group into TEST mode. The policies are run in a test or sandboxed environment for a period of
630time. The test results are passed back to the user. The user may revert the policy set to PASSIVE mode a number of times
631and upgrade the policy set during test operation.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400632
liamfallonc9e27902019-05-28 13:27:04 +0000633When the user is satisfied with policy set execution and when quality criteria have been reached for the policy set, the
634PDP group is set to run in SAFE mode. In this mode, the policies run on the target environment but do not actually
635exercise any actions or change any context in the target environment. Again, as in TEST mode, the operator may decide to
636revert back to TEST mode or even PASSIVE mode if issues arise with a policy set.
637
638Finally, when the user is satisfied with policy set execution and when quality criteria have been reached, the PDP group
639is set into ACTIVE state and the policy set executes on the target environment. The results of target operation are
640reported. The PDP group can be reverted to SAFE, TEST, or even PASSIVE mode at any time if problems arise.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400641
liamfallon3602c182020-04-16 09:29:45 +0100642\* SAFE Mode and TEST Mode will be implemented in future versions of the Policy Framework. In current versions, policies
643transition directly from PASSIVE mode to ACTIVE mode.
644
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -04006452.3.5.3 Policy Upgrade and Rollback
liamfallone62f7112019-05-24 10:50:57 +0000646"""""""""""""""""""""""""""""""""""
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400647
liamfallon3602c182020-04-16 09:29:45 +0100648There are a number of approaches for managing policy upgrade and rollback. Upgrade and rollback will be implemented in
649future versions of the Policy Framework.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400650
liamfallonc9e27902019-05-28 13:27:04 +0000651The most straightforward approach is to use the approach described in section :ref:`policy-rollout` for upgrading and
652rolling back policy sets. In order to upgrade a policy set, one follows the process in :ref:`policy-rollout` with the
653new policy set version. For rollback, one follows the process in :ref:`policy-rollout` with the older policy set, most
654probably setting the old policy set into ACTIVE mode immediately. The advantage of this approach is that the approach is
655straightforward. The obvious disadvantage is that the PDP group is not executing on the target environment while the new
656policy set is in PASSIVE, TEST, and SAFE mode.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400657
liamfallonc9e27902019-05-28 13:27:04 +0000658A second manner to tackle upgrade and rollback is to use a spare-wheel approach. An special upgrade PDP group service is
659set up as a K8S service in parallel with the active one during the upgrade procedure. The spare wheel service is used to
660execute the process described in :ref:`policy-rollout`. When the time comes to activate the policy set, the references
661for the active and spare wheel services are simply swapped. The advantage of this approach is that the down time during
662upgrade is minimized, the spare wheel PDP group can be abandoned at any time without affecting the in service PDP group,
663and the upgrade can be rolled back easily for a period simply by preserving the old service for a time. The disadvantage
664is that this approach is more complex and uses more resources than the first approach.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400665
liamfallonc9e27902019-05-28 13:27:04 +0000666A third approach is to have two policy sets running in each PDP, an active set and a standby set. However such an
667approach would increase the complexity of implementation in PDPs significantly.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400668
6692.3.6 Policy Monitoring
liamfallone62f7112019-05-24 10:50:57 +0000670^^^^^^^^^^^^^^^^^^^^^^^
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400671
liamfallonc9e27902019-05-28 13:27:04 +0000672PDPs provide a periodic report of their status to the PAP. All PDPs report using a standard reporting format that is
673extended to provide information for specific PDP types. PDPs provide at least the information below:
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400674
675===================== ===============================================================================
676**Field** **Description**
677===================== ===============================================================================
liamfallon3602c182020-04-16 09:29:45 +0100678State Lifecycle State (PASSIVE/TEST*/SAFE*/ACTIVE)
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400679Timestamp Time the report record was generated
680InvocationCount The number of execution invocations the PDP has processed since the last report
681LastInvocationTime The time taken to process the last execution invocation
682AverageInvocationTime The average time taken to process an invocation since the last report
683StartTime The start time of the PDP
684UpTime The length of time the PDP has been executing
685RealTimeInfo Real time information on running policies.
686===================== ===============================================================================
687
liamfallon3602c182020-04-16 09:29:45 +0100688\* SAFE Mode and TEST Mode will be implemented in future versions of the Policy Framework.
689
690Currently, policy monitoring is supported by PAP and by pdp-apex. Policy monitoring for all PDPs will be supported in
691future versions of the Policy Framework.
692
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -04006932.3.7 PEP Registration and Enforcement Guidelines
liamfallone62f7112019-05-24 10:50:57 +0000694^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400695
liamfallonc9e27902019-05-28 13:27:04 +0000696In ONAP there are several applications outside the Policy Framework that enforce policy decisions based on models
697provided to the Policy Framework. These applications are considered Policy Enforcement Engines (PEP) and roles will be
698provided to those applications using AAF/CADI to ensure only those applications can make calls to the Policy Decision
699APIs. Some example PEPs are: DCAE, OOF, and SDNC.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400700
liamfallonc9e27902019-05-28 13:27:04 +0000701See Section 3.4 of the :ref:`Policy Design and Development <design-label>`
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400702for more information on the Decision APIs.
703
7043. APIs Provided by the Policy Framework
705========================================
706
liamfallonc9e27902019-05-28 13:27:04 +0000707See the :ref:`Policy Design and Development <design-label>` page.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400708
7094. Terminology
710==============
711
liamfallonc9e27902019-05-28 13:27:04 +0000712================================= ==================================================================================
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400713PAP (Policy Administration Point) A component that administers and manages policies
liamfallonc9e27902019-05-28 13:27:04 +0000714================================= ==================================================================================
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400715PDP (Policy Deployment Point) A component that executes a policy artifact (One or many?)
716PDP_<> A specific type of PDP
717PDP Group A group of PDPs that execute the same set of policies
718Policy Development The development environment for policies
liamfallonc9e27902019-05-28 13:27:04 +0000719Policy Type A generic prototype definition of a type of policy in TOSCA, see the
720 :ref:`TOSCA Policy Primer <tosca-label>`
721Policy An executable policy defined in TOSCA and created using a Policy Type, see the
722 :ref:`TOSCA Policy Primer <tosca-label>`
723Policy Set A set of policies that are deployed on a PDP group. One and only one Policy Set is
724 deployed on a PDP group
725================================= ==================================================================================
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400726
727
728End of Document