blob: 175bb20dc9f9f6b497966a0cb104865502cd5dd7 [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
liamfallon4d1d9832019-05-30 20:53:05 +00005.. _architecture-label:
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -04006
7Architecture
liamfallone62f7112019-05-24 10:50:57 +00008############
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -04009
10Abstract
11
liamfallonc9e27902019-05-28 13:27:04 +000012This document describes the ONAP Policy Framework. It lays out the architecture of the framework and shows the APIs
13provided to other components that interwork with the framework. It describes the implementation of the framework,
14mapping out the components, software structure, and execution ecosystem of the framework.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -040015
16.. contents::
liamfallone62f7112019-05-24 10:50:57 +000017 :depth: 6
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -040018
liamfallone62f7112019-05-24 10:50:57 +0000191. Overview
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -040020===========
21
liamfallonc9e27902019-05-28 13:27:04 +000022The ONAP Policy Framework is a comprehensive policy design, deployment, and execution environment. The Policy Framework
23is the decision making component in `an ONAP system
24<https://www.onap.org/wp-content/uploads/sites/20/2018/11/ONAP_CaseSolution_Architecture_112918FNL.pdf>`__.
25It allows you to specify, deploy, and execute the governance of the features and functions in your ONAP system, be they
26closed loop, orchestration, or more traditional open loop use case implementations. The Policy Framework is the
27component that is the source of truth for all policy decisions.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -040028
liamfallonc9e27902019-05-28 13:27:04 +000029One of the most important goals of the Policy Framework is to support Policy Driven Operational Management during the
30execution of ONAP control loops at run time. In addition, use case implementations such as orchestration and control
31benefit from the ONAP policy Framework because they can use the capabilities of the framework to manage and execute
32their policies rather than embedding the decision making in their applications.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -040033
liamfallonc9e27902019-05-28 13:27:04 +000034The Policy Framework is deployment agnostic, it manages Policy Execution (in PDPs) and Enforcement (in PEPs) regardless
35of how the PDPs and PEPs are deployed. This allows policy execution and enforcement can be deployed in a manner that
36meets the performance requirements of a given application or use case. In one deployment, policy execution could be
37deployed in a separate executing entity in a Docker container. In another, policy execution could be co-deployed with
38an application to increase performance. An example of co-deployment is the Drools PDP Control Loop image, which is a
39Docker image that combines the ONAP Drools use case application and dependencies with the Drools PDP engine.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -040040
liamfallonc9e27902019-05-28 13:27:04 +000041The ONAP Policy Framework architecture separates policies from the platform that is supporting them. The framework
42supports development, deployment, and execution of any type of policy in ONAP. The Policy Framework is metadata (model)
43driven so that policy development, deployment, and execution is as flexible as possible and can support modern rapid
44development ways of working such as DevOps. A metadata driven approach also allows the amount of programmed support
45required for policies to be reduced or ideally eliminated.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -040046
liamfallonc9e27902019-05-28 13:27:04 +000047We have identified five capabilities as being essential for the framework:
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -040048
liamfallonc9e27902019-05-28 13:27:04 +0000491. Most obviously, the framework must be capable of being triggered by an event or invoked, and making decisions at run
50 time.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -040051
liamfallonc9e27902019-05-28 13:27:04 +0000522. It must be deployment agnostic; capable of managing policies for various Policy Decision Points (PDPs) or policy
53 engines.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -040054
liamfallonc9e27902019-05-28 13:27:04 +0000553. 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 -040056
liamfallonc9e27902019-05-28 13:27:04 +0000574. It must provide a flexible model driven policy design approach for policy type programming and specification of
58 policies.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -040059
liamfallonc9e27902019-05-28 13:27:04 +0000605. It must be extensible, allowing straightforward integration of new PDPs, policy formats, and policy development
61 environments.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -040062
liamfallonc9e27902019-05-28 13:27:04 +000063Another important aim of the architecture of a model driven policy framework is that it enables much more flexible
64policy specification. The ONAP Policy Framework complies with the `TOSCA
65<http://docs.oasis-open.org/tosca/TOSCA-Simple-Profile-YAML/v1.1/TOSCA-Simple-Profile-YAML-v1.1.pdf>`__ modelling
66approach for policies, see the :ref:`TOSCA Policy Primer <tosca-label>` for more information on how policies are modeled
67in TOSCA.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -040068
liamfallonc9e27902019-05-28 13:27:04 +0000691. A Policy Type is a general implementation of a policy for a feature. For example, a Policy Type could be written to
70 manage Service Level Agreements for VPNs. The Policy Type is designed by a domain expert, who specifies the
71 parameters, triggers, and actions that the Policy Type will have. The implementation (the logic, rules, and tasks of
72 the Policy Type) is implemented by a skilled policy developer in consultation with domain experts.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -040073
liamfallonc9e27902019-05-28 13:27:04 +000074 a. For example, the VPN Policy Type is used to create VPN policies for a bank network, a car dealership network, or a
75 university with many campuses.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -040076
liamfallonc9e27902019-05-28 13:27:04 +000077 b. In ONAP, specific ONAP Policy Types are used to create specific policies that drive the ONAP Platform and
78 Components.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -040079
liamfallonc9e27902019-05-28 13:27:04 +0000802. A Policy is created by configuring a Policy Type with parameters. For example, the SLA values in the car dealership
81 VPN policy for a particular dealership are configured with values appropriate for the expected level of activity in
82 that dealership.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -040083
liamfallonc9e27902019-05-28 13:27:04 +000084For more detailed information on designing Policy Types and developing an implementation for that policy type, see
85:ref:`Policy Design and Development <design-label>`.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -040086
liamfallonc9e27902019-05-28 13:27:04 +000087The ONAP Policy Framework for building, configuring and deploying PDPs is extendable. It allows the use of ONAP PDPs as
88is, the extension of ONAP PDPs, and lastly provides the capability for users to create and deploy their own PDPs. The
89ONAP Policy Framework provides distributed policy management for **all** policies in ONAP at run time. Not only does
90this provide unified policy access and version control, it provides life cycle control for policies and allows detection
91of conflicts across all policies running in an ONAP installation.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -040092
932. Architecture
94===============
95
liamfallonc9e27902019-05-28 13:27:04 +000096The diagram below shows the architecture of the ONAP Policy Framework at its highest level.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -040097
liamfallon4d1d9832019-05-30 20:53:05 +000098.. image:: images/PFHighestLevel.svg
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -040099
liamfallonc9e27902019-05-28 13:27:04 +0000100The *PolicyDevelopment* component implements the functionality for development of policy types and policies.
101*PolicyAdministration* is responsible for the deployment life cycle of policies as well as interworking with the
102mechanisms required to orchestrate the nodes and containers on which policies run. *PolicyAdministration* is also
103responsible for the administration of policies at run time; ensuring that policies are available to users, that policies
104are executing correctly, and that the state and status of policies is monitored. *PolicyExecution* is the set of PDPs
105running in the ONAP system and is responsible for making policy decisions and for managing the administrative state of
106the PDPs as directed by \ *PolicyAdministration.*
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400107
liamfallonc9e27902019-05-28 13:27:04 +0000108*PolicyDevelopment* creates policy artifacts and supporting information in the policy database. \ *PolicyAdministration*
109reads those artifacts and the supporting information from the policy database whilst deploying policy artifacts. Once
110the policy artifacts are deployed, *PolicyAdministration* handles the run-time management of the PDPs on which the
111policies are running. *PolicyDevelopment* interacts with ONAP design time components, and has no programmatic interface
112with *PolicyAdministration*, *PolicyExecution* or any other run-time ONAP components.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400113
liamfallonc9e27902019-05-28 13:27:04 +0000114The diagram below shows a more detailed view of the architecture, as inspired by
115`RFC-2753 <https://tools.ietf.org/html/rfc2753>`__ and `RFC-3198 <https://tools.ietf.org/html/rfc3198>`__.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400116
liamfallon4d1d9832019-05-30 20:53:05 +0000117.. image:: images/PFDesignAndAdmin.svg
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400118
liamfallonc9e27902019-05-28 13:27:04 +0000119*PolicyDevelopment* provides a `CRUD <https://en.wikipedia.org/wiki/Create,_read,_update_and_delete>`__ API for policy
120types and policies. The policy types and policy artifacts and their metadata (Information about policies, policy types,
121and their interrelations) are stored in the *PolicyDB*. The *PolicyDevGUI*, PolicyDistribution, and other applications
122such as *CLAMP* can use the *PolicyDevelopment* API to create, update, and delete policy types and policies.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400123
124*PolicyAdministration* has two important functions:
125
liamfallonc9e27902019-05-28 13:27:04 +0000126- Management of the life cycle of PDPs in an ONAP installation. PDPs register with *PolicyAdministration* when they come
127 up. *PolicyAdministration* handles the allocation of PDPs to a PDP Groups and PDP Subgroups, so that they can be
128 managed as microservices in Kubernetes.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400129
liamfallonc9e27902019-05-28 13:27:04 +0000130- Management of the deployment of policies to PDPs in an ONAP installation. *PolicyAdministration* gives each PDP group
131 a set of domain policies to execute.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400132
liamfallonc9e27902019-05-28 13:27:04 +0000133*PolicyAdministration* handles PDPs and policy allocation to PDPs using asynchronous messaging over DMaaP. It provides
134three APIs:
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400135
liamfallonc9e27902019-05-28 13:27:04 +0000136- a CRUD API for policy groups and subgroups
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400137
liamfallonc9e27902019-05-28 13:27:04 +0000138- an API that allows the allocation of policies PDP groups and subgroups to be controlled
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400139
liamfallonc9e27902019-05-28 13:27:04 +0000140- an API allows policy execution to be managed, showing the status of policy execution on PDP Groups, subgroups, and
141 individual PDPs as well as the life cycle state of PDPs
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400142
liamfallonc9e27902019-05-28 13:27:04 +0000143*PolicyExecution* is the set of running PDPs that are executing policies, logically partitioned into PDP groups and
144subgroups.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400145
liamfallon4d1d9832019-05-30 20:53:05 +0000146.. image:: images/PolicyExecution.svg
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400147
liamfallonc9e27902019-05-28 13:27:04 +0000148The figure above shows how *PolicyExecution* looks at run time with PDPs running in Kubernetes. A *PDPGroup* is a purely
149logical construct that collects all the PDPs that are running policies for a particular domain together. A *PDPSubGroup*
150is a group of PDPs of the same type that are running the same policies. *A PDPSubGroup* is deployed as a Kubernetes
151`Deployment <https://kubernetes.io/docs/concepts/workloads/controllers/deployment/>`__. PDPs are defined as Kubernetes
152`Pods <https://kubernetes.io/docs/concepts/workloads/pods/pod/>`__. At run time, the actual number of PDPs in each
153*PDPSubGroup* is specified in the configuration of the *Deployment* of that *PDPSubGroup* in Kubernetes. This
154structuring of PDPs is required because, in order to simplify deployment and scaling of PDPs in Kubernetes, we gather
155all the PDPs of the same type that are running the same policies together for deployment.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400156
liamfallonc9e27902019-05-28 13:27:04 +0000157For example, assume we have policies for the SON (Self Organizing Network) and ACPE (Advanced Customer Premises Service)
158domains. For SON,we have XACML, Drools, and APEX policies, and for ACPE we have XACML and Drools policies. The table
159below shows the resulting \ *PDPGroup*, *PDPSubGroup*, and PDP allocations:
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400160
liamfallonc9e27902019-05-28 13:27:04 +0000161============= ================ ========================= ======================================== ================
162**PDP Group** **PDP Subgroup** **Kubernetes Deployment** **Kubernetes Deployment Strategy** **PDPs in Pods**
163============= ================ ========================= ======================================== ================
164SON SON-XACML SON-XACML-Dep Always 2, be geo redundant 2 PDP-X
165\ SON-Drools SON-Drools-Dep At Least 4, scale up on 70% load, >= 4 PDP-D
166 scale down on 40% load, be geo-redundant
167\ SON-APEX SON-APEX-Dep At Least 3, scale up on 70% load, scale >= 3 PDP-A
168 down on 40% load, be geo-redundant
169ACPE ACPE-XACML ACPE-XACML-Dep Always 2 2 PDP-X
170\ ACPE-Drools ACPE-Drools-Dep At Least 2, scale up on 80% load, scale >=2 PDP-D
171 down on 50% load
172============= ================ ========================= ======================================== ================
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400173
liamfallonc9e27902019-05-28 13:27:04 +0000174For more details on *PolicyAdministration* APIs and management of *PDPGroup* and *PDPSubGroup*, see the documentation
175for :ref:`Policy Administration Point (PAP) Architecture <pap-label>`.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400176
1772.1 Policy Framework Object Model
178---------------------------------
179
liamfallonc9e27902019-05-28 13:27:04 +0000180This section describes the structure of and relations between the main concepts in the Policy Framework. This model is
181implemented as a common model and is used by *PolicyDevelopment*, *PolicyDeployment,* and *PolicyExecution.*
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400182
liamfallon4d1d9832019-05-30 20:53:05 +0000183.. image:: images/ClassStructure.svg
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400184
liamfallonc9e27902019-05-28 13:27:04 +0000185The UML class diagram above shows the portion of the Policy Framework Object Model that applies to *PolicyDeployment*
186and *PolicyExecution.*
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400187
liamfallon4d1d9832019-05-30 20:53:05 +0000188.. image:: images/DesignTimeComponents.svg
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400189
liamfallonc9e27902019-05-28 13:27:04 +0000190The UML class diagram above shows the portion of the Policy Framework Object Model that applies to *PolicyDevelopment*
191and *PolicyDeployment.*
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400192
1932.2 Policy Design Architecture
194------------------------------
195
liamfallonc9e27902019-05-28 13:27:04 +0000196This section describes the architecture of the model driven system used to develop policy types and to create concrete
197policies using policy types. The output of Policy Design is deployment-ready artifacts and Policy metadata in the Policy
198Framework database.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400199
liamfallonc9e27902019-05-28 13:27:04 +0000200Policies that are expressed via natural language or a model require some development work ahead of time for them to be
201translated into concrete runtime policies. Some Policy Domains will be set up and available in the platform during
202startup such as Control Loop Operational Policy Models, OOF placement Models, DCAE microservice models. Policy type
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400203implementation development is done by an experienced developer.
204
2052.2.1 Policy Type Design
liamfallone62f7112019-05-24 10:50:57 +0000206^^^^^^^^^^^^^^^^^^^^^^^^
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400207
liamfallonc9e27902019-05-28 13:27:04 +0000208Policy Type Design is the task of creating policy types that capture the generic and vendor independent aspects of a
209policy for a particular domain use case. The policy type implementation specifies the model information, rules, and
210tasks that a policy type requires to generate concrete policies.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400211
liamfallonc9e27902019-05-28 13:27:04 +0000212All policy types must implement the ONAP Policy Framework *PolicyType* interface. This interface allows
213*PolicyDevelopment* to manage policy types and to generate policies from these policy types in a uniform way regardless
214of the domain that the policy type is addressing or the PDP technology that will execute the policy. The interface is
215used by *PolicyDevelopment* to determine the PDP technology of the policy type, the structure, type, and definition of
216the model information that must be supplied to the policy type to generate a concrete policy.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400217
liamfallonc9e27902019-05-28 13:27:04 +0000218A *PolicyTypeImpl* is developed for a certain type of PDP (for example XACML oriented for decision policies or Drools
219rules oriented for ECA policies). The design environment and tool chain for a policy type is specific for the type of
220policy being designed.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400221
liamfallonc9e27902019-05-28 13:27:04 +0000222The *PolicyTypeImpl* implementation (or raw policy) is the specification of the specific rules or tasks, the flow of
223the policy, its internal states and data structures and other relevant information. A *PolicyTypeImpl* is specific to a
224PDP technology, that is XACML, Drools, or APEX. *A PolicyTypeImpl* can be specific to a particular policy type, it can
225be more general, providing the implementation of a class of policy types, or the same policy type may have many
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400226implementations.
227
liamfallonc9e27902019-05-28 13:27:04 +0000228*PolicyDevelopment* provides the RESTful :ref:`Policy Design API <design-label>` which allows other components to query
229policy types and policy type implementations, to determine the model information, rules, or tasks that they require, to
230specialize policy flow, and to generate policies from policy types. This API is used by the ONAP Policy Framework and
231other components such as \ *PolicyDistribution* to create policies from policy types.
232
233Consider a policy type created for managing faults on vCPE equipment in a vendor independent way. The policy type
234captures the generic logic required to manage the faults and specifies the vendor specific information that must be
235supplied to the type for specific vendor vCPE VFs. The actual vCPE policy that is used for managing particular vCPE
236equipment is created by setting the parameters specified in the policy type together with the specific modeled
237information, rules and tasks in the policy type implementation for that vendor model of vCPE.
238
2392.2.1.1 Generating Policy Types
240"""""""""""""""""""""""""""""""
241
242It is possible to generate policy types using MDD (Model Driven Development) techniques. Policy types are expressed
243using a DSL (Domain Specific Language) or a policy specification environment for a particular application domain. For
244example, policy types for specifying SLAs could be expressed in a SLA DSL and policy types for managing SON features
245could be generated from a visual SON management tool. The ONAP Policy framework provides an API that allows tool chains
246to create policy types. SDC uses this approach for generating Policy Types in the Policy Framework, see the
247:ref:`Policy Design and Development <design-label>` page.
248
249The SDC GUI supports several types of policies that can be captured at design time. DCAE micro service configuration
250policies can be onboarded via the DCAE-DS (DCAE Design Studio).
251
252
253.. image:: images/PolicyTypeDesign.svg
254
255The GUI implementation in another ONAP component such as SDC DCAE-DS uses the *API_User* API to create and edit ONAP
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400256policy types.
257
liamfallonc9e27902019-05-28 13:27:04 +00002582.2.1.2 Programming Policy Type Implementations
liamfallone62f7112019-05-24 10:50:57 +0000259"""""""""""""""""""""""""""""""""""""""""""""""
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400260
liamfallonc9e27902019-05-28 13:27:04 +0000261For skilled developers, the most straightforward way to create a policy type is to program it. Programming a policy type
262might simply mean creating and editing text files, thus manually creating the TOSCA Policy Type YAML file and the policy
263type implementation for the policy type.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400264
liamfallonc9e27902019-05-28 13:27:04 +0000265A more formal approach is preferred. For policy type implementations, programmers use a specific Eclipse project type
266for developing each type of implementation, a Policy Type Implementation SDK. The project is under source control in
267git. This Eclipse project is structured correctly for creating implementations for a specific type of PDP. It includes
268the correct POM files for generating the policy type implementation and has editors and perspectives that aid
269programmers in their work
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400270
2712.2.2 Policy Design
liamfallone62f7112019-05-24 10:50:57 +0000272^^^^^^^^^^^^^^^^^^^
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400273
liamfallonc9e27902019-05-28 13:27:04 +0000274The *PolicyCreation* function of *PolicyDevelopment* creates policies from a policy type. The information expressed
275during policy type design is used to parameterize a policy type to create an executable policy. A service designer
276and/or operations team can use tooling that reads the TOSCA Policy Type specifications to express and capture a policy
277at its highest abstraction level. Alternatively, the parameter for the policy can be expressed in a raw JSON or YAML
278file 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 -0400279
liamfallonc9e27902019-05-28 13:27:04 +0000280A number of mechanisms for policy creation are supported in ONAP. The process in *PolicyDevelopment* for creating a
281policy is the same for all mechanisms. The most general mechanism for creating a policy is using the RESTful
282*Policy Design API*, which provides a full interface to the policy creation support of *PolicyDevelopment*. This API may
283be exercised directly using utilities such as *curl*. *PolicyDevelopment* provides a command line tool that is a loose
284wrapper around the API. It also provides a general purpose Policy GUI in the ONAP Portal for policy creation, which
285again is a general purpose wrapper around the policy creation API. The Policy GUI can interpret any TOSCA Model that has
286been loaded into it and flexibly presents a GUI for a user to create policies from. The development of these mechanisms
287will be phased over a number of ONAP releases.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400288
liamfallonc9e27902019-05-28 13:27:04 +0000289A number of ONAP components use policy in manners which are specific to their particular needs. The manner in which the
290policy creation process is triggered and the way in which information required to create a policy is specified and
291accessed is specialized for these ONAP components.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400292
liamfallonc9e27902019-05-28 13:27:04 +0000293The following subsections outline the mechanisms for policy creation and modification supported by the ONAP Policy
294Framework.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400295
2962.2.2.1 Policy Design in the ONAP Policy Framework
liamfallone62f7112019-05-24 10:50:57 +0000297""""""""""""""""""""""""""""""""""""""""""""""""""
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400298
liamfallonc9e27902019-05-28 13:27:04 +0000299Policy creation in *PolicyDevelopment* follows the general sequence shown in the sequence diagram below. An *API_USER*
300is any component that wants to create a policy from a policy type. *PolicyDevelopment* supplies a REST interface that
301exposes the API and also provides a command line tool and general purpose client that wraps the API.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400302
liamfallonc9e27902019-05-28 13:27:04 +0000303.. image:: images/PolicyDesign.svg
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400304
liamfallonc9e27902019-05-28 13:27:04 +0000305An *API_User* first gets a reference to and the metadata for the Policy type for the policy they want to work on from
306*PolicyDevelopment*. *PolicyDevelopment* reads the metadata and artifact for the policy type from the database. The
307*API_User* then asks for a reference and the metadata for the policy. *PolicyDevelopment* looks up the policy in the
308database. If the policy already exists, *PolicyDevelopment* reads the artifact and returns the reference of the existing
309policy to the *API_User* with the metadata for the existing policy. If the policy does not exist, *PolicyDevelopment*
310creates and new reference and metadata and returns that to the *API_User*.
311
312The *API_User* may now proceed with a policy specification session, where the parameters are set for the policy using
313the policy type specification. Once the *API_User* is happy that the policy is completely and correctly specified, it
314requests *PolicyDevelopment* to create the policy. *PolicyDevelopment* creates the policy, stores the created policy
315artifact and its metadata in the database.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400316
3172.2.2.2 Model Driven VF (Virtual Function) Policy Design via VNF SDK Packaging
liamfallone62f7112019-05-24 10:50:57 +0000318""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400319
liamfallonc9e27902019-05-28 13:27:04 +0000320VF vendors express policies such as SLA, Licenses, hardware placement, run-time metric suggestions, etc. These details
321are captured within the VNF SDK and uploaded into the SDC Catalog. The `SDC Distribution APIs
322<https://wiki.onap.org/display/DW/SDC+Distribution+client+AID>`__ are used to interact with SDC. For example, SLA and
323placement policies may be captured via TOSCA specification. License policies can be captured via TOSCA or an XACML
324specification. Run-time metric vendor recommendations can be captured via the VES Standard specification.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400325
liamfallonc9e27902019-05-28 13:27:04 +0000326The sequence diagram below is a high level view of SDC-triggered concrete policy generation for some arbitrary entity
327*EntityA*. The parameters to create a policy are read from a TOSCA Policy specification read from a CSAR received from
328SDC.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400329
liamfallonc9e27902019-05-28 13:27:04 +0000330.. image:: images/ModelDrivenPolicyDesign.svg
331
332*PolicyDesign* uses the *PolicyDistribution* component for managing SDC-triggered policy creation and update requests.
333*PolicyDistribution* is an *API_User*, it uses the Policy Design API for policy creation and update. It reads the
334information 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 -0400335this information to automatically generate a policy.
336
liamfallonc9e27902019-05-28 13:27:04 +0000337Note that SDC provides a wrapper for the SDC API as a Java Client and also provides a TOSCA parser. See the
338documentation for the `Policy Distribution Component
339<https://docs.onap.org/en/latest/submodules/policy/distribution.git/docs/index.html>`__.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400340
liamfallonc9e27902019-05-28 13:27:04 +0000341In Step 4 above, the \ *PolicyDesign* must download the CSAR file. If the policy is to be composed from the TOSCA
342definition, it must also parse the TOSCA definition.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400343
liamfallonc9e27902019-05-28 13:27:04 +0000344In Step 11 above, the \ *PolicyDesign* must send back/publish status events to SDC such as DOWNLOAD_OK, DOWNLOAD_ERROR,
345DEPLOY_OK, DEPLOY_ERROR, NOTIFIED.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400346
liamfallone62f7112019-05-24 10:50:57 +00003472.2.2.3 Scripted Model Driven Policy Design
348"""""""""""""""""""""""""""""""""""""""""""
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400349
liamfallonc9e27902019-05-28 13:27:04 +0000350Service policies such as optimization and placement policies can be specified as a TOSCA Policy at design time. These
351policies use a TOSCA Policy Type specification as their schemas. Therefore, scripts can be used to create TOSCA policies
352using TOSCA Policy Types.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400353
liamfallonc9e27902019-05-28 13:27:04 +0000354.. image:: images/ScriptedPolicyDesign.svg
355
356One straightforward way of generating policies from Policy types is to use directives specified in a script file. The
357command line utility is an *API_User*. The script reads directives from a file. For each directive, it reads the policy
358type using the Policy Type API, and uses the parameters of the directive to prepare a TOSCA Policy. It then uses the
359Policy API to create the policy.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400360
3612.2.3 Policy Design Process
liamfallone62f7112019-05-24 10:50:57 +0000362^^^^^^^^^^^^^^^^^^^^^^^^^^^
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400363
liamfallonc9e27902019-05-28 13:27:04 +0000364All policy types must be certified as being fit for deployment prior to run time deployment. Where design is executed
365using the SDC application, it is assumed the life cycle being implemented by SDC certifies any policy types that
366are declared within the ONAP Service CSAR. For other policy types and policy type implementations, the life cycle
367associated with the applied software development process suffices. Since policy types and their implementations are
368designed and implemented using software development best practices, they can be utilized and configured for various
369environments (eg. development, testing, production) as desired.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400370
3712.3 Policy Runtime Architecture
372-------------------------------
373
liamfallonc9e27902019-05-28 13:27:04 +0000374The Policy Framework Platform components are themselves designed as microservices that are easy to configure and deploy
375via Docker images and K8S both supporting resiliency and scalability if required. PAPs and PDPs are deployed by the
376underlying ONAP management infrastructure and are designed to comply with the ONAP interfaces for deploying containers.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400377
liamfallonc9e27902019-05-28 13:27:04 +0000378The PAPs keep track of PDPs, support the deployment of PDP groups and the deployment of a *policy set* across those PDP
379groups. A PAP is stateless in a RESTful sense. Therefore, if there is more than one PAP deployed, it does not matter
380which PAP a user contacts to handle a request. The PAP uses the database (persistent storage) to keep track of ongoing
381sessions with clients. Policy management on PDPs is the responsibility of PAPs; management of policy sets or policies by
382any other manner is not permitted.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400383
liamfallonc9e27902019-05-28 13:27:04 +0000384In the ONAP Policy Framework, the interfaces to the PDP are designed to be as streamlined as possible. Because the PDP
385is the main unit of scalability in the Policy Framework, the framework is designed to allow PDPs in a PDP group to
386arbitrarily appear and disappear and for policy consistency across all PDPs in a PDP group to be easily maintained.
387Therefore, PDPs have just two interfaces; an interface that users can use to execute policies and interface to the PAP
388for administration, life cycle management and monitoring. The PAP is responsible for controlling the state across the
389PDPs in a PDP group. The PAP interacts with the Policy database and transfers policy sets to PDPs, and may cache the
390policy sets for PDP groups.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400391
liamfallonc9e27902019-05-28 13:27:04 +0000392See also Section 2 of the :ref:`Policy Design and Development <design-label>` page, where the mechanisms for PDP
393Deployment and Registration with PAP are explained.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400394
3952.3.1 Policy Framework Services
liamfallone62f7112019-05-24 10:50:57 +0000396^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400397
liamfallonc9e27902019-05-28 13:27:04 +0000398The ONAP Policy Framework follows the architectural approach for microservices recommended by the `ONAP Architecture
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400399Subcommittee <https://wiki.onap.org/display/DW/Architecture+Subcommittee>`__.
400
liamfallonc9e27902019-05-28 13:27:04 +0000401The ONAP Policy Framework defines `Kubernetes Services
402<https://kubernetes.io/docs/concepts/services-networking/service/>`__ to manage the life cycle of Policy Framework
403executable components at runtime. A Kubernetes service allows, among other parameters, the number of instances (*pods*
404in Kubernetes terminology) that should be deployed for a particular service to be specified and a common endpoint for
405that service to be defined. Once the service is started in Kubernetes, Kubernetes ensures that the specified number of
406instances is always kept running. As requests are received on the common endpoint, they are distributed across the
407service instances. More complex call distribution and instance deployment strategies may be used; please see the
408`Kubernetes Services <https://kubernetes.io/docs/concepts/services-networking/service/>`__ documentation for those
409details.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400410
liamfallonc9e27902019-05-28 13:27:04 +0000411If, for example, a service called *policy-pdpd-control-loop* is defined that runs 5 PDP-D instances. The service has the
412end point *https://policy-pdpd-control-loop.onap/<service-specific-path>*. When the service is started, Kubernetes spins
413up 5 PDP-Ds. Calls to the end point *https://policy-pdpd-control-loop.onap/<service-specific-path>* are distributed
414across the 5 PDP-D instances. Note that the *.onap* part of the service endpoint is the namespace being used and is
415specified for the full ONAP Kubernetes installation.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400416
417The following services will be required for the ONAP Policy Framework:
418
liamfallonc9e27902019-05-28 13:27:04 +0000419================ ============================== =======================================================================
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400420**Service** **Endpoint** **Description**
liamfallonc9e27902019-05-28 13:27:04 +0000421================ ============================== =======================================================================
422PAP https://policy-pap The PAP service, used for policy administration and deployment. See
423 :ref:`Policy Design and Development <design-label>` for details of the
424 API for this service
425PDP-X-\ *domain* https://policy-pdpx-\ *domain* A PDP service is defined for each PDP group. A PDP group is identified
426 by the domain on which it operates.
427
428 For example, there could be two PDP-X domains, one for admission
429 policies for ONAP proper and another for admission policies for VNFs of
430 operator *Supacom*. Two PDP-X services are defined:
431
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400432 | https://policy-pdpx-onap
433 | https://policy-pdpx-\ *supacom*
434PDP-D-\ *domain* https://policy-pdpd-\ *domain*
435PDP-A-\ *domain* https://policy-pdpa-\ *domain*
liamfallonc9e27902019-05-28 13:27:04 +0000436================ ============================== =======================================================================
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400437
liamfallonc9e27902019-05-28 13:27:04 +0000438There is one and only one PAP service, which handles policy deployment, administration, and monitoring for all policies
439in all PDPs and PDP groups in the system. There are multiple PDP services, one PDP service for each domain for which
440there are policies.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400441
4422.3.2 The Policy Framework Information Structure
liamfallone62f7112019-05-24 10:50:57 +0000443^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400444
liamfallonc9e27902019-05-28 13:27:04 +0000445The following diagram captures the relationship between Policy Framework concepts at run time.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400446
liamfallonc9e27902019-05-28 13:27:04 +0000447.. image:: images/RuntimeRelationships.svg
448
449There is a one to one relationship between a PDP SubGroup, a Kubernetes PDP service, and the set of policies assigned to
450run in the PDP subgroup. Each PDP service runs a single PDP subgroup with multiple PDPs, which executes a specific
451Policy Set containing a number of policies that have been assigned to that PDP subgroup. Having and maintaining this
452principle makes policy deployment and administration much more straightforward than it would be if complex relationships
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400453between PDP services, PDP subgroups, and policy sets.
454
liamfallonc9e27902019-05-28 13:27:04 +0000455The 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 -0400456
liamfallonc9e27902019-05-28 13:27:04 +0000457.. image:: images/PolicyDatabase.svg
458
459The diagram above gives an indicative structure of the run time topology information in the Policy Framework database.
460Note that the *PDP_SUBGROUP_STATE* and *PDP_STATE* fields hold state information for life cycle management of PDP groups
461and PDPs.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400462
4632.3.3 Startup, Shutdown and Restart
liamfallone62f7112019-05-24 10:50:57 +0000464^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400465
liamfallonc9e27902019-05-28 13:27:04 +0000466This section describes the interactions between Policy Framework components themselves and with other ONAP components at
467startup, shutdown and restart.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400468
4692.3.3.1 PAP Startup and Shutdown
liamfallone62f7112019-05-24 10:50:57 +0000470""""""""""""""""""""""""""""""""
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400471
472The sequence diagram below shows the actions of the PAP at startup.
473
liamfallonc9e27902019-05-28 13:27:04 +0000474.. image:: images/PAPStartStop.svg
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400475
liamfallonc9e27902019-05-28 13:27:04 +0000476The PAP is the run time point of coordination for the ONAP Policy Framework. When it is started, it initializes itself
477using data from the database. It then waits for periodic PDP status updates and for administration requests.
478
479PAP shutdown is trivial. On receipt or a shutdown request, the PAP completes or aborts any ongoing operations and shuts
480down gracefully.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400481
4822.3.3.2 PDP Startup and Shutdown
liamfallone62f7112019-05-24 10:50:57 +0000483""""""""""""""""""""""""""""""""
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400484
liamfallonc9e27902019-05-28 13:27:04 +0000485The sequence diagram below shows the actions of the PDP at startup. See also Section 4 of the
486:ref:`Policy Design and Development <design-label>` page for the API used to implement this sequence.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400487
liamfallonc9e27902019-05-28 13:27:04 +0000488.. image:: images/PDPStartStop.svg
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400489
liamfallonc9e27902019-05-28 13:27:04 +0000490At startup, the PDP initializes itself. At this point it is in PASSIVE mode. The PDP begins sending periodic Status
491messages to the PAP. The first Status message initializes the process of loading the correct Policy Set on the PDP in
492the PAP.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400493
liamfallonc9e27902019-05-28 13:27:04 +0000494On 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 -0400495
4962.3.4 Policy Execution
liamfallone62f7112019-05-24 10:50:57 +0000497^^^^^^^^^^^^^^^^^^^^^^
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400498
liamfallonc9e27902019-05-28 13:27:04 +0000499Policy execution is the execution of a policy in a PDP. Policy enforcement occurs in the component that receives a
500policy decision.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400501
liamfallon4d1d9832019-05-30 20:53:05 +0000502.. image:: images/PolicyExecutionFlow.svg
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400503
liamfallonc9e27902019-05-28 13:27:04 +0000504Policy execution can be *synchronous* or *asynchronous*. In *synchronous* policy execution, the component requesting a
505policy decision requests a policy decision and waits for the result. The PDP-X and PDP-A implement synchronous policy
506execution. In *asynchronous* policy execution, the component that requests a policy decision does not wait for the
507decision. Indeed, the decision may be passed to another component. The PDP-D and PDP-A implement asynchronous polic
508execution.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400509
liamfallonc9e27902019-05-28 13:27:04 +0000510Policy execution is carried out using the current life cycle mode of operation of the PDP. While the actual
511implementation of the mode may vary somewhat between PDPs of different types, the principles below hold true for all
512PDP types:
513
514================== =====================================================================================================
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400515**Lifecycle Mode** **Behaviour**
liamfallonc9e27902019-05-28 13:27:04 +0000516================== =====================================================================================================
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400517PASSIVE MODE Policy execution is always rejected irrespective of PDP type.
518ACTIVE MODE Policy execution is executed in the live environment by the PDP.
liamfallonc9e27902019-05-28 13:27:04 +0000519SAFE MODE Policy execution proceeds, but changes to domain state or context are not carried out. The PDP
520 returns an indication that it is running in SAFE mode together with the action it would have
521 performed if it was operating in ACTIVE mode. The PDP type and the policy types it is running must
522 support SAFE mode operation.
523TEST MODE Policy execution proceeds and changes to domain and state are carried out in a test or sandbox
524 environment. The PDP returns an indication it is running in TEST mode together with the action it has
525 performed on the test environment. The PDP type and the policy types it is running must support TEST
526 mode operation.
527================== =====================================================================================================
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400528
5292.3.5 Policy Lifecycle Management
liamfallone62f7112019-05-24 10:50:57 +0000530^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400531
liamfallonc9e27902019-05-28 13:27:04 +0000532Policy lifecycle management manages the deployment and life cycle of policies in PDP groups at run time. Policy sets can
533be deployed at run time without restarting PDPs or stopping policy execution. PDPs preserve state for minor/patch
534version upgrades and rollbacks.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400535
5362.3.5.1 Load/Update Policies on PDP
liamfallone62f7112019-05-24 10:50:57 +0000537"""""""""""""""""""""""""""""""""""
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400538
liamfallonc9e27902019-05-28 13:27:04 +0000539The sequence diagram below shows how policies are loaded or updated on a PDP.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400540
liamfallonc9e27902019-05-28 13:27:04 +0000541.. image:: images/DownloadPoliciesToPDP.svg
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400542
liamfallonc9e27902019-05-28 13:27:04 +0000543This sequence can be initiated in two ways; from the PDP or from a user action.
544
5451. A PDP sends regular status update messages to the PAP. If this message indicates that the PDP has no policies or
546 outdated policies loaded, then this sequence is initiated
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400547
5482. A user may explicitly trigger this sequence to load policies on a PDP
549
liamfallonc9e27902019-05-28 13:27:04 +0000550The PAP controls the entire process. The PAP reads the current PDP metadata and the required policy and policy set
551artifacts from the database. It then builds the policy set for the PDP. Once the policies are ready, the PAP sets the
552mode of the PDP to PASSIVE. The Policy Set is transparently passed to the PDP by the PAP. The PDP loads all the policies
553in 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 -0400554
liamfallonc9e27902019-05-28 13:27:04 +0000555Once the Policy Set is loaded, the PAP orders the PDP to enter the life cycle mode that has been specified for it
556(ACTIVE/SAFE/TEST). The PDP begins to execute policies in the specified mode (see section 2.3.4).
557
558.. _policy-rollout:
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400559
5602.3.5.2 Policy Rollout
liamfallone62f7112019-05-24 10:50:57 +0000561""""""""""""""""""""""
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400562
liamfallonc9e27902019-05-28 13:27:04 +0000563A policy set steps through a number of life cycle modes when it is rolled out.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400564
liamfallonc9e27902019-05-28 13:27:04 +0000565.. image:: images/PolicyRollout.svg
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400566
liamfallonc9e27902019-05-28 13:27:04 +0000567The user defines the set of policies for a PDP group. It is deployed to a PDP group and is initially in PASSIVE mode.
568The user sets the PDP Group into TEST mode. The policies are run in a test or sandboxed environment for a period of
569time. The test results are passed back to the user. The user may revert the policy set to PASSIVE mode a number of times
570and upgrade the policy set during test operation.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400571
liamfallonc9e27902019-05-28 13:27:04 +0000572When the user is satisfied with policy set execution and when quality criteria have been reached for the policy set, the
573PDP group is set to run in SAFE mode. In this mode, the policies run on the target environment but do not actually
574exercise any actions or change any context in the target environment. Again, as in TEST mode, the operator may decide to
575revert back to TEST mode or even PASSIVE mode if issues arise with a policy set.
576
577Finally, when the user is satisfied with policy set execution and when quality criteria have been reached, the PDP group
578is set into ACTIVE state and the policy set executes on the target environment. The results of target operation are
579reported. 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 -0400580
5812.3.5.3 Policy Upgrade and Rollback
liamfallone62f7112019-05-24 10:50:57 +0000582"""""""""""""""""""""""""""""""""""
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400583
liamfallonc9e27902019-05-28 13:27:04 +0000584There are a number of approaches for managing policy upgrade and rollback.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400585
liamfallonc9e27902019-05-28 13:27:04 +0000586The most straightforward approach is to use the approach described in section :ref:`policy-rollout` for upgrading and
587rolling back policy sets. In order to upgrade a policy set, one follows the process in :ref:`policy-rollout` with the
588new policy set version. For rollback, one follows the process in :ref:`policy-rollout` with the older policy set, most
589probably setting the old policy set into ACTIVE mode immediately. The advantage of this approach is that the approach is
590straightforward. The obvious disadvantage is that the PDP group is not executing on the target environment while the new
591policy set is in PASSIVE, TEST, and SAFE mode.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400592
liamfallonc9e27902019-05-28 13:27:04 +0000593A second manner to tackle upgrade and rollback is to use a spare-wheel approach. An special upgrade PDP group service is
594set up as a K8S service in parallel with the active one during the upgrade procedure. The spare wheel service is used to
595execute the process described in :ref:`policy-rollout`. When the time comes to activate the policy set, the references
596for the active and spare wheel services are simply swapped. The advantage of this approach is that the down time during
597upgrade is minimized, the spare wheel PDP group can be abandoned at any time without affecting the in service PDP group,
598and the upgrade can be rolled back easily for a period simply by preserving the old service for a time. The disadvantage
599is that this approach is more complex and uses more resources than the first approach.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400600
liamfallonc9e27902019-05-28 13:27:04 +0000601A third approach is to have two policy sets running in each PDP, an active set and a standby set. However such an
602approach would increase the complexity of implementation in PDPs significantly.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400603
6042.3.6 Policy Monitoring
liamfallone62f7112019-05-24 10:50:57 +0000605^^^^^^^^^^^^^^^^^^^^^^^
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400606
liamfallonc9e27902019-05-28 13:27:04 +0000607PDPs provide a periodic report of their status to the PAP. All PDPs report using a standard reporting format that is
608extended to provide information for specific PDP types. PDPs provide at least the information below:
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400609
610===================== ===============================================================================
611**Field** **Description**
612===================== ===============================================================================
613State Lifecycle State (PASSIVE/TEST/SAFE/ACTIVE)
614Timestamp Time the report record was generated
615InvocationCount The number of execution invocations the PDP has processed since the last report
616LastInvocationTime The time taken to process the last execution invocation
617AverageInvocationTime The average time taken to process an invocation since the last report
618StartTime The start time of the PDP
619UpTime The length of time the PDP has been executing
620RealTimeInfo Real time information on running policies.
621===================== ===============================================================================
622
6232.3.7 PEP Registration and Enforcement Guidelines
liamfallone62f7112019-05-24 10:50:57 +0000624^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400625
liamfallonc9e27902019-05-28 13:27:04 +0000626In ONAP there are several applications outside the Policy Framework that enforce policy decisions based on models
627provided to the Policy Framework. These applications are considered Policy Enforcement Engines (PEP) and roles will be
628provided to those applications using AAF/CADI to ensure only those applications can make calls to the Policy Decision
629APIs. Some example PEPs are: DCAE, OOF, and SDNC.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400630
liamfallonc9e27902019-05-28 13:27:04 +0000631See Section 3.4 of the :ref:`Policy Design and Development <design-label>`
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400632for more information on the Decision APIs.
633
6343. APIs Provided by the Policy Framework
635========================================
636
liamfallonc9e27902019-05-28 13:27:04 +0000637See the :ref:`Policy Design and Development <design-label>` page.
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400638
6394. Terminology
640==============
641
liamfallonc9e27902019-05-28 13:27:04 +0000642================================= ==================================================================================
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400643PAP (Policy Administration Point) A component that administers and manages policies
liamfallonc9e27902019-05-28 13:27:04 +0000644================================= ==================================================================================
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400645PDP (Policy Deployment Point) A component that executes a policy artifact (One or many?)
646PDP_<> A specific type of PDP
647PDP Group A group of PDPs that execute the same set of policies
648Policy Development The development environment for policies
liamfallonc9e27902019-05-28 13:27:04 +0000649Policy Type A generic prototype definition of a type of policy in TOSCA, see the
650 :ref:`TOSCA Policy Primer <tosca-label>`
651Policy An executable policy defined in TOSCA and created using a Policy Type, see the
652 :ref:`TOSCA Policy Primer <tosca-label>`
653Policy Set A set of policies that are deployed on a PDP group. One and only one Policy Set is
654 deployed on a PDP group
655================================= ==================================================================================
Pamela Dragosh5fc2fdb2019-05-17 09:42:27 -0400656
657
658End of Document