1 .. This work is licensed under a
2 .. Creative Commons Attribution 4.0 International License.
3 .. http://creativecommons.org/licenses/by/4.0
6 .. _architecture-label:
8 Policy Framework Architecture
9 #############################
13 This document describes the ONAP Policy Framework. It lays out the architecture of the framework and shows the APIs
14 provided to other components that interwork with the framework. It describes the implementation of the framework,
15 mapping out the components, software structure, and execution ecosystem of the framework.
23 The ONAP Policy Framework is a comprehensive policy design, deployment, and execution environment. The Policy Framework
24 is the decision making component in `an ONAP system
25 <https://www.onap.org/wp-content/uploads/sites/20/2018/11/ONAP_CaseSolution_Architecture_112918FNL.pdf>`__.
26 It allows you to specify, deploy, and execute the governance of the features and functions in your ONAP system, be they
27 closed loop, orchestration, or more traditional open loop use case implementations. The Policy Framework is the
28 component that is the source of truth for all policy decisions.
30 One of the most important goals of the Policy Framework is to support Policy Driven Operational Management during the
31 execution of ONAP control loops at run time. In addition, use case implementations such as orchestration and control
32 benefit from the ONAP policy Framework because they can use the capabilities of the framework to manage and execute
33 their policies rather than embedding the decision making in their applications.
35 The Policy Framework is deployment agnostic, it manages Policy Execution (in PDPs) and Enforcement (in PEPs) regardless
36 of how the PDPs and PEPs are deployed. This allows policy execution and enforcement to be deployed in a manner that
37 meets the performance requirements of a given application or use case. In one deployment, policy execution could be
38 deployed in a separate executing entity in a Docker container. In another, policy execution could be co-deployed with
39 an application to increase performance. An example of co-deployment is the Drools PDP Control Loop image, which is a
40 Docker image that combines the ONAP Drools use case application and dependencies with the Drools PDP engine.
42 The ONAP Policy Framework architecture separates policies from the platform that is supporting them. The framework
43 supports development, deployment, and execution of any type of policy in ONAP. The Policy Framework is metadata (model)
44 driven so that policy development, deployment, and execution is as flexible as possible and can support modern rapid
45 development ways of working such as `DevOps
46 <https://en.wikipedia.org/wiki/DevOps>`__. A metadata driven approach also allows the amount of programmed support
47 required for policies to be reduced or ideally eliminated.
49 We have identified five capabilities as being essential for the framework:
51 1. Most obviously, the framework must be capable of being triggered by an event or invoked, and making decisions at run
54 2. It must be deployment agnostic; capable of managing policies for various Policy Decision Points (PDPs) or policy
57 3. It must be metadata driven, allowing policies to be deployed, modified, upgraded, and removed as the system executes.
59 4. It must provide a flexible model driven policy design approach for policy type programming and specification of
62 5. It must be extensible, allowing straightforward integration of new PDPs, policy formats, and policy development
65 Another important aim of the architecture of a model driven policy framework is that it enables much more flexible
66 policy specification. The ONAP Policy Framework complies with the `TOSCA
67 <http://docs.oasis-open.org/tosca/TOSCA-Simple-Profile-YAML/v1.1/TOSCA-Simple-Profile-YAML-v1.1.pdf>`__ modelling
68 approach for policies, see the :ref:`TOSCA Policy Primer <tosca-label>` for more information on how policies are modeled
71 1. A *Policy Type* describes the properties, targets, and triggers that the policy for a feature can have. A Policy type is
72 implementation independent. It is the metadata that specifies:
74 - the *configuration* data that the policy can take. The Policy Type describes each property that a policy of a
75 given type can take. A Policy Type definition also allows the default value, optionality, and the ranges of properties
78 - the *targets* such as network element types, functions, services, or resources on which a policy of the given type
81 - the *triggers* such as the event type, filtered event, scheduled trigger, or conditions that can activate a policy
84 Policy Types are hierarchical, A Policy Type can inherit from a parent Policy Type, inheriting the properties, targets,
85 and triggers of its parent. Policy Types are developed by domain experts in consultation with the developers that
86 implement the logic and rules for the Policy Type.
88 2. A *Policy* is defined using a Policy Type. The Policy defines:
90 - the values for each property of the policy type
91 - the specific targets (network elements, functions, services, resources) on which this policy will act
92 - the specific triggers that trigger this policy.
94 3. A *Policy Type Implementation* or *Raw Policy*, is the logic that implements the policy. It is implemented by a
95 skilled policy developer in consultation with domain experts. The implementation has software that reads the Policy
96 Type and parses the incoming configuration properties. The software has domain logic that is triggered when one of the
97 triggers described in the Policy Type occurs. The software logic executes and acts on the targets specified in the
101 For example, a Policy Type could be written to describe how to manage Service Level Agreements for VPNs. The VPN Policy
102 Type can be used to create VPN policies for a bank network, a car dealership network, or a university with many campuses.
103 The Policy Type has two parameters:
105 - The *maximumDowntime* parameter allows the maximum downtime allowed per year to be specified
106 - The *mitigationStrategy* parameter allows one of three strategies to be selected for downtime breaches
108 - *allocateMoreResources*, which will automatically allocate more resources to mitigate the problem
109 - *report*, which report the downtime breach to a trouble ticketing system
110 - *ignore*, which logs the breach and takes no further action
112 The Policy Type defines a trigger event, an event that is received from an analytics system when the maximum downtime
113 value for a VPN is breached. The target of the policy type is an instance of the VPN service.
115 The Policy Type Implementation is developed that can configure the maximum downtime parameter in an analytics system,
116 can receive a trigger from the analytics system when the maximum downtime is breached, and that can either request more
117 resources, report an issue to a trouble ticketing system, and can log a breach.
119 VPN Policies are created by specifying values for the properties, triggers, and targets specifed in VPN Policy Type.
121 In the case of the bank network, the *maximumDowntime* threshold is specified as 5 minutes downtime per year and the
122 *mitigationStrategy* is defined as *allocateMoreResources*, and the target is specified as being the bank's VPN service
123 ID. When a breach is detected by the analytics system, the policy is executed, the target is identified as being the
124 bank's network, and more resources are allocated by the policy.
126 For the car dealership VPN policy, a less stringent downtime threshold of 60 minutes per year is specified, and the
127 mitigation strategy is to issue a trouble ticket. The university network is best effort, so a downtime of 4 days per
128 year is specified. Breaches are logged and mitigated as routine network administration tasks.
130 In ONAP, specific ONAP Policy Types are used to create specific policies that drive the ONAP Platform and Components.
131 For more detailed information on designing Policy Types and developing an implementation for that policy type, see
132 :ref:`Policy Design and Development <design-label>`.
134 The ONAP Policy Framework for building, configuring and deploying PDPs is extendable. It allows the use of ONAP PDPs as
135 is, the extension of ONAP PDPs, and lastly provides the capability for users to create and deploy their own PDPs. The
136 ONAP Policy Framework provides distributed policy management for **all** policies in ONAP at run time. Not only does
137 this provide unified policy access and version control, it provides life cycle control for policies and allows detection
138 of conflicts across all policies running in an ONAP installation.
143 The diagram below shows the architecture of the ONAP Policy Framework at its highest level.
145 .. image:: images/PFHighestLevel.svg
147 The *PolicyDevelopment* component implements the functionality for development of policy types and policies.
148 *PolicyAdministration* is responsible for the deployment life cycle of policies as well as interworking with the
149 mechanisms required to orchestrate the nodes and containers on which policies run. *PolicyAdministration* is also
150 responsible for the administration of policies at run time; ensuring that policies are available to users, that policies
151 are executing correctly, and that the state and status of policies is monitored. *PolicyExecution* is the set of PDPs
152 running in the ONAP system and is responsible for making policy decisions and for managing the administrative state of
153 the PDPs as directed by \ *PolicyAdministration.*
155 *PolicyDevelopment* provides APIs that allow creation of policy artifacts and supporting information in the policy
156 database. *PolicyAdministration* reads those artifacts and the supporting information from the policy database whilst
157 deploying policy artifacts. Once the policy artifacts are deployed, *PolicyAdministration* handles the run-time
158 management of the PDPs on which the policies are running. *PolicyDevelopment* interacts with the database, and has
159 no programmatic interface with *PolicyAdministration*, *PolicyExecution* or any other run-time ONAP components.
161 The diagram below shows a more detailed view of the architecture, as inspired by
162 `RFC-2753 <https://tools.ietf.org/html/rfc2753>`__ and `RFC-3198 <https://tools.ietf.org/html/rfc3198>`__.
164 .. image:: images/PFDesignAndAdmin.svg
166 *PolicyDevelopment* provides a `CRUD <https://en.wikipedia.org/wiki/Create,_read,_update_and_delete>`__ API for policy
167 types and policies. The policy types and policy artifacts and their metadata (information about policies, policy types,
168 and their interrelations) are stored in the *PolicyDB*. The *PolicyDevGUI*, PolicyDistribution, and other applications
169 such as *CLAMP* can use the *PolicyDevelopment* API to create, update, delete, and read policy types and policies.
171 *PolicyAdministration* has two important functions:
173 - Management of the life cycle of PDPs in an ONAP installation. PDPs register with *PolicyAdministration* when they come
174 up. *PolicyAdministration* handles the allocation of PDPs to PDP Groups and PDP Subgroups, so that they can be
175 managed as microservices in infrastructure management systems such as Kubernetes.
177 - Management of the deployment of policies to PDPs in an ONAP installation. *PolicyAdministration* gives each PDP group
178 a set of domain policies to execute.
180 *PolicyAdministration* handles PDPs and policy allocation to PDPs using asynchronous messaging over DMaaP. It provides
183 - a CRUD API for policy groups and subgroups
185 - an API that allows the allocation of policies to PDP groups and subgroups to be controlled
187 - an API allows policy execution to be managed, showing the status of policy execution on PDP Groups, subgroups, and
188 individual PDPs as well as the life cycle state of PDPs
190 *PolicyExecution* is the set of running PDPs that are executing policies, logically partitioned into PDP groups and
193 .. image:: images/PolicyExecution.svg
195 The figure above shows how *PolicyExecution* looks at run time with PDPs running in Kubernetes. A *PDPGroup* is a purely
196 logical construct that collects all the PDPs that are running policies for a particular domain together. A *PDPSubGroup*
197 is a group of PDPs of the same type that are running the same policies. *A PDPSubGroup* is deployed as a Kubernetes
198 `Deployment <https://kubernetes.io/docs/concepts/workloads/controllers/deployment/>`__. PDPs are defined as Kubernetes
199 `Pods <https://kubernetes.io/docs/concepts/workloads/pods/pod/>`__. At run time, the actual number of PDPs in each
200 *PDPSubGroup* is specified in the configuration of the *Deployment* of that *PDPSubGroup* in Kubernetes. This
201 structuring of PDPs is required because, in order to simplify deployment and scaling of PDPs in Kubernetes, we gather
202 all the PDPs of the same type that are running the same policies together for deployment.
204 For example, assume we have policies for the SON (Self Organizing Network) and ACPS (Advanced Customer Premises Service)
205 domains. For SON,we have XACML, Drools, and APEX policies, and for ACPS we have XACML and Drools policies. The table
206 below shows the resulting \ *PDPGroup*, *PDPSubGroup*, and PDP allocations:
208 ============= ================ ========================= ======================================== ================
209 **PDP Group** **PDP Subgroup** **Kubernetes Deployment** **Kubernetes Deployment Strategy** **PDPs in Pods**
210 ============= ================ ========================= ======================================== ================
211 SON SON-XACML SON-XACML-Dep Always 2, be geo redundant 2 PDP-X
212 \ SON-Drools SON-Drools-Dep At Least 4, scale up on 70% load, >= 4 PDP-D
213 scale down on 40% load, be geo-redundant
214 \ SON-APEX SON-APEX-Dep At Least 3, scale up on 70% load, scale >= 3 PDP-A
215 down on 40% load, be geo-redundant
216 ACPS ACPS-XACML ACPS-XACML-Dep Always 2 2 PDP-X
217 \ ACPS-Drools ACPS-Drools-Dep At Least 2, scale up on 80% load, scale >=2 PDP-D
219 ============= ================ ========================= ======================================== ================
221 For more details on *PolicyAdministration* APIs and management of *PDPGroup* and *PDPSubGroup*, see the documentation
222 for :ref:`Policy Administration Point (PAP) Architecture <pap-label>`.
224 2.1 Policy Framework Object Model
225 ---------------------------------
227 This section describes the structure of and relations between the main concepts in the Policy Framework. This model is
228 implemented as a common model and is used by *PolicyDevelopment*, *PolicyDeployment,* and *PolicyExecution.*
230 .. image:: images/ClassStructure.svg
232 The UML class diagram above shows thePolicy Framework Object Model.
234 2.2 Policy Design Architecture
235 ------------------------------
237 This section describes the architecture of the model driven system used to develop policy types and to create concrete
238 policies using policy types. The output of Policy Design is deployment-ready artifacts and Policy metadata in the Policy
241 Policies that are expressed via natural language or a model require some development work ahead of time for them to be
242 translated into concrete runtime policies. Some Policy Domains will be set up and available in the platform during
243 startup such as Control Loop Operational Policy Models, OOF placement Models, DCAE microservice models. Policy type
244 implementation logic development is done by an experienced developer.
246 2.2.1 Policy Type Design
247 ^^^^^^^^^^^^^^^^^^^^^^^^
249 Policy Type Design is the task of creating policy types that capture the generic and vendor independent aspects of a
250 policy for a particular domain use case. The policy type implementation specifies the model information, rules, and
251 tasks that a policy type requires to generate concrete policies.
253 All policy types are specified in a TOSCA service template. Once policy types are defined and created in the system,
254 *PolicyDevelopment* manages them and uses them to allow policies to be created from these policy types in a uniform
255 way regardless of the domain that the policy type is addressing or the PDP technology that will execute the policy.
257 A *PolicyTypeImpl* is developed for a policy type for a certain type of PDP (for example XACML oriented for decision
258 policies, Drools rules or Apex state machines oriented for ECA policies). While a policy type is implementation
259 independent, a policy type implementation for a policy type is specific for the technology of the PDP on which
260 policies that use that policy type implementation will execute. Further, the design environment and tool chain for
261 a policy type implementation is specific to the technology of the PDP on which policies that use that policy type
262 implementation will use.
264 The *PolicyTypeImpl* implementation (or raw policy) is the specification of the specific rules or tasks, the flow of
265 the policy, its internal states and data structures and other relevant information. *A PolicyTypeImpl* can be specific
266 to a particular policy type, it can be more general, providing the implementation of a class of policy types, or
267 the same policy type may have many implementations.
269 *PolicyDevelopment* provides the RESTful :ref:`Policy Design API <design-label>`, which allows other components to query
270 policy types, Those components can then create policies that specify values for the properties, triggers, and targets
271 specified in a policy type. This API is used by components such as *CLAMP* and *PolicyDistribution* to create policies
274 Consider a policy type created for managing faults on vCPE equipment in a vendor independent way. The policy type
275 implementation captures the generic logic required to manage the faults and specifies the vendor specific information
276 that must be supplied to the type for specific vendor vCPE VFs. The actual vCPE policy that is used for managing
277 particular vCPE equipment is created by setting the properties specified in the policy type for that vendor model
280 2.2.1.1 Generating Policy Types
281 """""""""""""""""""""""""""""""
283 It is possible to generate policy types using MDD (Model Driven Development) techniques. Policy types are expressed
284 using a DSL (Domain Specific Language) or a policy specification environment for a particular application domain. For
285 example, policy types for specifying SLAs could be expressed in a SLA DSL and policy types for managing SON features
286 could be generated from a visual SON management tool. The ONAP Policy framework provides an API that allows tool chains
287 to create policy types. SDC uses this approach for generating Policy Types in the Policy Framework, see the
288 :ref:`Policy Design and Development <design-label>` page.
290 The SDC GUI supports several types of policies that can be captured at design time. DCAE micro service configuration
291 policies can be onboarded via the DCAE-DS (DCAE Design Studio).
294 .. image:: images/PolicyTypeDesign.svg
296 The GUI implementation in another ONAP component such as SDC DCAE-DS uses the *API_User* API to create and edit ONAP
299 2.2.1.2 Programming Policy Type Implementations
300 """""""""""""""""""""""""""""""""""""""""""""""
302 For skilled developers, the most straightforward way to create a policy type is to program it. Programming a policy type
303 might simply mean creating and editing text files, thus manually creating the TOSCA Policy Type YAML file and the policy
304 type implementation for the policy type.
306 A more formal approach is preferred. For policy type implementations, programmers use a specific Eclipse project type
307 for developing each type of implementation, a Policy Type Implementation SDK. The project is under source control in
308 git. This Eclipse project is structured correctly for creating implementations for a specific type of PDP. It includes
309 the correct POM files for generating the policy type implementation and has editors and perspectives that aid
310 programmers in their work
315 The *PolicyCreation* function of *PolicyDevelopment* creates policies from a policy type. The information expressed
316 during policy type design is used to parameterize a policy type to create an executable policy. A service designer
317 and/or operations team can use tooling that reads the TOSCA Policy Type specifications to express and capture a policy
318 at its highest abstraction level. Alternatively, the parameter for the policy can be expressed in a raw JSON or YAML
319 file and posted over the policy design API described on the :ref:`Policy Design and Development <design-label>` page.
321 A number of mechanisms for policy creation are supported in ONAP. The process in *PolicyDevelopment* for creating a
322 policy is the same for all mechanisms. The most general mechanism for creating a policy is using the RESTful
323 *Policy Design API*, which provides a full interface to the policy creation support of *PolicyDevelopment*. This API may
324 be exercised directly using utilities such as *curl*. *PolicyDevelopment* provides a command line tool that is a loose
325 wrapper around the API. It also provides a general purpose Policy GUI in the ONAP Portal for policy creation, which
326 again is a general purpose wrapper around the policy creation API. The Policy GUI can interpret any TOSCA Model that has
327 been loaded into it and flexibly presents a GUI for a user to create policies from. The development of these mechanisms
328 will be phased over a number of ONAP releases.
330 A number of ONAP components use policy in manners which are specific to their particular needs. The manner in which the
331 policy creation process is triggered and the way in which information required to create a policy is specified and
332 accessed is specialized for these ONAP components.
334 The following subsections outline the mechanisms for policy creation and modification supported by the ONAP Policy
337 2.2.2.1 Policy Design in the ONAP Policy Framework
338 """"""""""""""""""""""""""""""""""""""""""""""""""
340 Policy creation in *PolicyDevelopment* follows the general sequence shown in the sequence diagram below. An *API_USER*
341 is any component that wants to create a policy from a policy type. *PolicyDevelopment* supplies a REST interface that
342 exposes the API and also provides a command line tool and general purpose client that wraps the API.
344 .. image:: images/PolicyDesign.svg
346 An *API_User* first gets a reference to and the metadata for the Policy type for the policy they want to work on from
347 *PolicyDevelopment*. *PolicyDevelopment* reads the metadata and artifact for the policy type from the database. The
348 *API_User* then asks for a reference and the metadata for the policy. *PolicyDevelopment* looks up the policy in the
349 database. If the policy already exists, *PolicyDevelopment* reads the artifact and returns the reference of the existing
350 policy to the *API_User* with the metadata for the existing policy. If the policy does not exist, *PolicyDevelopment*
351 creates and new reference and metadata and returns that to the *API_User*.
353 The *API_User* may now proceed with a policy specification session, where the parameters are set for the policy using
354 the policy type specification. Once the *API_User* is happy that the policy is completely and correctly specified, it
355 requests *PolicyDevelopment* to create the policy. *PolicyDevelopment* creates the policy, stores the created policy
356 artifact and its metadata in the database.
358 2.2.2.2 Model Driven VF (Virtual Function) Policy Design via VNF SDK Packaging
359 """"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
361 VF vendors express policies such as SLA, Licenses, hardware placement, run-time metric suggestions, etc. These details
362 are captured within the VNF SDK and uploaded into the SDC Catalog. The `SDC Distribution APIs
363 <https://wiki.onap.org/display/DW/SDC+Distribution+client+AID>`__ are used to interact with SDC. For example, SLA and
364 placement policies may be captured via TOSCA specification. License policies can be captured via TOSCA or an XACML
365 specification. Run-time metric vendor recommendations can be captured via the VES Standard specification.
367 The sequence diagram below is a high level view of SDC-triggered concrete policy generation for some arbitrary entity
368 *EntityA*. The parameters to create a policy are read from a TOSCA Policy specification read from a CSAR received from
371 .. image:: images/ModelDrivenPolicyDesign.svg
373 *PolicyDesign* uses the *PolicyDistribution* component for managing SDC-triggered policy creation and update requests.
374 *PolicyDistribution* is an *API_User*, it uses the Policy Design API for policy creation and update. It reads the
375 information it needs to populate the policy type from a TOSCA specification in a CSAR received from SDC and then uses
376 this information to automatically generate a policy.
378 Note that SDC provides a wrapper for the SDC API as a Java Client and also provides a TOSCA parser. See the
379 documentation for the `Policy Distribution Component
380 <https://docs.onap.org/en/latest/submodules/policy/distribution.git/docs/index.html>`__.
382 In Step 4 above, the \ *PolicyDesign* must download the CSAR file. If the policy is to be composed from the TOSCA
383 definition, it must also parse the TOSCA definition.
385 In Step 11 above, the \ *PolicyDesign* must send back/publish status events to SDC such as DOWNLOAD_OK, DOWNLOAD_ERROR,
386 DEPLOY_OK, DEPLOY_ERROR, NOTIFIED.
388 2.2.2.3 Scripted Model Driven Policy Design
389 """""""""""""""""""""""""""""""""""""""""""
391 Service policies such as optimization and placement policies can be specified as a TOSCA Policy at design time. These
392 policies use a TOSCA Policy Type specification as their schemas. Therefore, scripts can be used to create TOSCA policies
393 using TOSCA Policy Types.
395 .. image:: images/ScriptedPolicyDesign.svg
397 One straightforward way of generating policies from Policy types is to use directives specified in a script file. The
398 command line utility is an *API_User*. The script reads directives from a file. For each directive, it reads the policy
399 type using the Policy Type API, and uses the parameters of the directive to prepare a TOSCA Policy. It then uses the
400 Policy API to create the policy.
402 2.2.3 Policy Design Process
403 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
405 All policy types must be certified as being fit for deployment prior to run time deployment. Where design is executed
406 using the SDC application, it is assumed the life cycle being implemented by SDC certifies any policy types that
407 are declared within the ONAP Service CSAR. For other policy types and policy type implementations, the life cycle
408 associated with the applied software development process suffices. Since policy types and their implementations are
409 designed and implemented using software development best practices, they can be utilized and configured for various
410 environments (eg. development, testing, production) as desired.
412 2.3 Policy Runtime Architecture
413 -------------------------------
415 The Policy Framework Platform components are themselves designed as microservices that are easy to configure and deploy
416 via Docker images and K8S both supporting resiliency and scalability if required. PAPs and PDPs are deployed by the
417 underlying ONAP management infrastructure and are designed to comply with the ONAP interfaces for deploying containers.
419 The PAPs keep track of PDPs, support the deployment of PDP groups and the deployment of a *policy set* across those PDP
420 groups. A PAP is stateless in a RESTful sense. Therefore, if there is more than one PAP deployed, it does not matter
421 which PAP a user contacts to handle a request. The PAP uses the database (persistent storage) to keep track of ongoing
422 sessions with clients. Policy management on PDPs is the responsibility of PAPs; management of policy sets or policies by
423 any other manner is not permitted.
425 In the ONAP Policy Framework, the interfaces to the PDP are designed to be as streamlined as possible. Because the PDP
426 is the main unit of scalability in the Policy Framework, the framework is designed to allow PDPs in a PDP group to
427 arbitrarily appear and disappear and for policy consistency across all PDPs in a PDP group to be easily maintained.
428 Therefore, PDPs have just two interfaces; an interface that users can use to execute policies and interface to the PAP
429 for administration, life cycle management and monitoring. The PAP is responsible for controlling the state across the
430 PDPs in a PDP group. The PAP interacts with the Policy database and transfers policy sets to PDPs, and may cache the
431 policy sets for PDP groups.
433 See also Section 2 of the :ref:`Policy Design and Development <design-label>` page, where the mechanisms for PDP
434 Deployment and Registration with PAP are explained.
436 2.3.1 Policy Framework Services
437 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
439 The ONAP Policy Framework follows the architectural approach for microservices recommended by the `ONAP Architecture
440 Subcommittee <https://wiki.onap.org/display/DW/Architecture+Subcommittee>`__.
442 The ONAP Policy Framework defines `Kubernetes Services
443 <https://kubernetes.io/docs/concepts/services-networking/service/>`__ to manage the life cycle of Policy Framework
444 executable components at runtime. A Kubernetes service allows, among other parameters, the number of instances (*pods*
445 in Kubernetes terminology) that should be deployed for a particular service to be specified and a common endpoint for
446 that service to be defined. Once the service is started in Kubernetes, Kubernetes ensures that the specified number of
447 instances is always kept running. As requests are received on the common endpoint, they are distributed across the
448 service instances. More complex call distribution and instance deployment strategies may be used; please see the
449 `Kubernetes Services <https://kubernetes.io/docs/concepts/services-networking/service/>`__ documentation for those
452 If, for example, a service called *policy-pdpd-control-loop* is defined that runs 5 PDP-D instances. The service has the
453 end point *https://policy-pdpd-control-loop.onap/<service-specific-path>*. When the service is started, Kubernetes spins
454 up 5 PDP-Ds. Calls to the end point *https://policy-pdpd-control-loop.onap/<service-specific-path>* are distributed
455 across the 5 PDP-D instances. Note that the *.onap* part of the service endpoint is the namespace being used and is
456 specified for the full ONAP Kubernetes installation.
458 The following services will be required for the ONAP Policy Framework:
460 ================ ============================== =======================================================================
461 **Service** **Endpoint** **Description**
462 ================ ============================== =======================================================================
463 PAP https://policy-pap The PAP service, used for policy administration and deployment. See
464 :ref:`Policy Design and Development <design-label>` for details of the
466 PDP-X-\ *domain* https://policy-pdpx-\ *domain* A PDP service is defined for each PDP group. A PDP group is identified
467 by the domain on which it operates.
469 For example, there could be two PDP-X domains, one for admission
470 policies for ONAP proper and another for admission policies for VNFs of
471 operator *Supacom*. Two PDP-X services are defined:
473 | https://policy-pdpx-onap
474 | https://policy-pdpx-\ *supacom*
475 PDP-D-\ *domain* https://policy-pdpd-\ *domain*
476 PDP-A-\ *domain* https://policy-pdpa-\ *domain*
477 ================ ============================== =======================================================================
479 There is one and only one PAP service, which handles policy deployment, administration, and monitoring for all policies
480 in all PDPs and PDP groups in the system. There are multiple PDP services, one PDP service for each domain for which
483 2.3.2 The Policy Framework Information Structure
484 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
486 The following diagram captures the relationship between Policy Framework concepts at run time.
488 .. image:: images/RuntimeRelationships.svg
490 There is a one to one relationship between a PDP SubGroup, a Kubernetes PDP service, and the set of policies assigned to
491 run in the PDP subgroup. Each PDP service runs a single PDP subgroup with multiple PDPs, which executes a specific
492 Policy Set containing a number of policies that have been assigned to that PDP subgroup. Having and maintaining this
493 principle makes policy deployment and administration much more straightforward than it would be if complex relationships
494 between PDP services, PDP subgroups, and policy sets.
496 The topology of the PDPs and their policy sets is held in the Policy Framework database and is administered by the PAP service.
498 .. image:: images/PolicyDatabase.svg
500 The diagram above gives an indicative structure of the run time topology information in the Policy Framework database.
501 Note that the *PDP_SUBGROUP_STATE* and *PDP_STATE* fields hold state information for life cycle management of PDP groups
504 2.3.3 Startup, Shutdown and Restart
505 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
507 This section describes the interactions between Policy Framework components themselves and with other ONAP components at
508 startup, shutdown and restart.
510 2.3.3.1 PAP Startup and Shutdown
511 """"""""""""""""""""""""""""""""
513 The sequence diagram below shows the actions of the PAP at startup.
515 .. image:: images/PAPStartStop.svg
517 The PAP is the run time point of coordination for the ONAP Policy Framework. When it is started, it initializes itself
518 using data from the database. It then waits for periodic PDP status updates and for administration requests.
520 PAP shutdown is trivial. On receipt or a shutdown request, the PAP completes or aborts any ongoing operations and shuts
523 2.3.3.2 PDP Startup and Shutdown
524 """"""""""""""""""""""""""""""""
526 The sequence diagram below shows the actions of the PDP at startup. See also Section 4 of the
527 :ref:`Policy Design and Development <design-label>` page for the API used to implement this sequence.
529 .. image:: images/PDPStartStop.svg
531 At startup, the PDP initializes itself. At this point it is in PASSIVE mode. The PDP begins sending periodic Status
532 messages to the PAP. The first Status message initializes the process of loading the correct Policy Set on the PDP in
535 On receipt or a shutdown request, the PDP completes or aborts any ongoing policy executions and shuts down gracefully.
537 2.3.4 Policy Execution
538 ^^^^^^^^^^^^^^^^^^^^^^
540 Policy execution is the execution of a policy in a PDP. Policy enforcement occurs in the component that receives a
543 .. image:: images/PolicyExecutionFlow.svg
545 Policy execution can be *synchronous* or *asynchronous*. In *synchronous* policy execution, the component requesting a
546 policy decision requests a policy decision and waits for the result. The PDP-X and PDP-A implement synchronous policy
547 execution. In *asynchronous* policy execution, the component that requests a policy decision does not wait for the
548 decision. Indeed, the decision may be passed to another component. The PDP-D and PDP-A implement asynchronous polic
551 Policy execution is carried out using the current life cycle mode of operation of the PDP. While the actual
552 implementation of the mode may vary somewhat between PDPs of different types, the principles below hold true for all
555 ================== =====================================================================================================
556 **Lifecycle Mode** **Behaviour**
557 ================== =====================================================================================================
558 PASSIVE MODE Policy execution is always rejected irrespective of PDP type.
559 ACTIVE MODE Policy execution is executed in the live environment by the PDP.
560 SAFE MODE Policy execution proceeds, but changes to domain state or context are not carried out. The PDP
561 returns an indication that it is running in SAFE mode together with the action it would have
562 performed if it was operating in ACTIVE mode. The PDP type and the policy types it is running must
563 support SAFE mode operation.
564 TEST MODE Policy execution proceeds and changes to domain and state are carried out in a test or sandbox
565 environment. The PDP returns an indication it is running in TEST mode together with the action it has
566 performed on the test environment. The PDP type and the policy types it is running must support TEST
568 ================== =====================================================================================================
570 2.3.5 Policy Lifecycle Management
571 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
573 Policy lifecycle management manages the deployment and life cycle of policies in PDP groups at run time. Policy sets can
574 be deployed at run time without restarting PDPs or stopping policy execution. PDPs preserve state for minor/patch
575 version upgrades and rollbacks.
577 2.3.5.1 Load/Update Policies on PDP
578 """""""""""""""""""""""""""""""""""
580 The sequence diagram below shows how policies are loaded or updated on a PDP.
582 .. image:: images/DownloadPoliciesToPDP.svg
584 This sequence can be initiated in two ways; from the PDP or from a user action.
586 1. A PDP sends regular status update messages to the PAP. If this message indicates that the PDP has no policies or
587 outdated policies loaded, then this sequence is initiated
589 2. A user may explicitly trigger this sequence to load policies on a PDP
591 The PAP controls the entire process. The PAP reads the current PDP metadata and the required policy and policy set
592 artifacts from the database. It then builds the policy set for the PDP. Once the policies are ready, the PAP sets the
593 mode of the PDP to PASSIVE. The Policy Set is transparently passed to the PDP by the PAP. The PDP loads all the policies
594 in the policy set including any models, rules, tasks, or flows in the policy set in the policy implementations.
596 Once the Policy Set is loaded, the PAP orders the PDP to enter the life cycle mode that has been specified for it
597 (ACTIVE/SAFE/TEST). The PDP begins to execute policies in the specified mode (see section 2.3.4).
601 2.3.5.2 Policy Rollout
602 """"""""""""""""""""""
604 A policy set steps through a number of life cycle modes when it is rolled out.
606 .. image:: images/PolicyRollout.svg
608 The user defines the set of policies for a PDP group. It is deployed to a PDP group and is initially in PASSIVE mode.
609 The user sets the PDP Group into TEST mode. The policies are run in a test or sandboxed environment for a period of
610 time. The test results are passed back to the user. The user may revert the policy set to PASSIVE mode a number of times
611 and upgrade the policy set during test operation.
613 When the user is satisfied with policy set execution and when quality criteria have been reached for the policy set, the
614 PDP group is set to run in SAFE mode. In this mode, the policies run on the target environment but do not actually
615 exercise any actions or change any context in the target environment. Again, as in TEST mode, the operator may decide to
616 revert back to TEST mode or even PASSIVE mode if issues arise with a policy set.
618 Finally, when the user is satisfied with policy set execution and when quality criteria have been reached, the PDP group
619 is set into ACTIVE state and the policy set executes on the target environment. The results of target operation are
620 reported. The PDP group can be reverted to SAFE, TEST, or even PASSIVE mode at any time if problems arise.
622 2.3.5.3 Policy Upgrade and Rollback
623 """""""""""""""""""""""""""""""""""
625 There are a number of approaches for managing policy upgrade and rollback.
627 The most straightforward approach is to use the approach described in section :ref:`policy-rollout` for upgrading and
628 rolling back policy sets. In order to upgrade a policy set, one follows the process in :ref:`policy-rollout` with the
629 new policy set version. For rollback, one follows the process in :ref:`policy-rollout` with the older policy set, most
630 probably setting the old policy set into ACTIVE mode immediately. The advantage of this approach is that the approach is
631 straightforward. The obvious disadvantage is that the PDP group is not executing on the target environment while the new
632 policy set is in PASSIVE, TEST, and SAFE mode.
634 A second manner to tackle upgrade and rollback is to use a spare-wheel approach. An special upgrade PDP group service is
635 set up as a K8S service in parallel with the active one during the upgrade procedure. The spare wheel service is used to
636 execute the process described in :ref:`policy-rollout`. When the time comes to activate the policy set, the references
637 for the active and spare wheel services are simply swapped. The advantage of this approach is that the down time during
638 upgrade is minimized, the spare wheel PDP group can be abandoned at any time without affecting the in service PDP group,
639 and the upgrade can be rolled back easily for a period simply by preserving the old service for a time. The disadvantage
640 is that this approach is more complex and uses more resources than the first approach.
642 A third approach is to have two policy sets running in each PDP, an active set and a standby set. However such an
643 approach would increase the complexity of implementation in PDPs significantly.
645 2.3.6 Policy Monitoring
646 ^^^^^^^^^^^^^^^^^^^^^^^
648 PDPs provide a periodic report of their status to the PAP. All PDPs report using a standard reporting format that is
649 extended to provide information for specific PDP types. PDPs provide at least the information below:
651 ===================== ===============================================================================
652 **Field** **Description**
653 ===================== ===============================================================================
654 State Lifecycle State (PASSIVE/TEST/SAFE/ACTIVE)
655 Timestamp Time the report record was generated
656 InvocationCount The number of execution invocations the PDP has processed since the last report
657 LastInvocationTime The time taken to process the last execution invocation
658 AverageInvocationTime The average time taken to process an invocation since the last report
659 StartTime The start time of the PDP
660 UpTime The length of time the PDP has been executing
661 RealTimeInfo Real time information on running policies.
662 ===================== ===============================================================================
664 2.3.7 PEP Registration and Enforcement Guidelines
665 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
667 In ONAP there are several applications outside the Policy Framework that enforce policy decisions based on models
668 provided to the Policy Framework. These applications are considered Policy Enforcement Engines (PEP) and roles will be
669 provided to those applications using AAF/CADI to ensure only those applications can make calls to the Policy Decision
670 APIs. Some example PEPs are: DCAE, OOF, and SDNC.
672 See Section 3.4 of the :ref:`Policy Design and Development <design-label>`
673 for more information on the Decision APIs.
675 3. APIs Provided by the Policy Framework
676 ========================================
678 See the :ref:`Policy Design and Development <design-label>` page.
683 ================================= ==================================================================================
684 PAP (Policy Administration Point) A component that administers and manages policies
685 ================================= ==================================================================================
686 PDP (Policy Deployment Point) A component that executes a policy artifact (One or many?)
687 PDP_<> A specific type of PDP
688 PDP Group A group of PDPs that execute the same set of policies
689 Policy Development The development environment for policies
690 Policy Type A generic prototype definition of a type of policy in TOSCA, see the
691 :ref:`TOSCA Policy Primer <tosca-label>`
692 Policy An executable policy defined in TOSCA and created using a Policy Type, see the
693 :ref:`TOSCA Policy Primer <tosca-label>`
694 Policy Set A set of policies that are deployed on a PDP group. One and only one Policy Set is
695 deployed on a PDP group
696 ================================= ==================================================================================