Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 1 | .. This work is licensed under a |
| 2 | .. Creative Commons Attribution 4.0 International License. |
| 3 | .. http://creativecommons.org/licenses/by/4.0 |
| 4 | |
liamfallon | 4d1d983 | 2019-05-30 20:53:05 +0000 | [diff] [blame^] | 5 | .. _architecture-label: |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 6 | |
| 7 | Architecture |
liamfallon | e62f711 | 2019-05-24 10:50:57 +0000 | [diff] [blame] | 8 | ############ |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 9 | |
| 10 | Abstract |
| 11 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 12 | This document describes the ONAP Policy Framework. It lays out the architecture of the framework and shows the APIs |
| 13 | provided to other components that interwork with the framework. It describes the implementation of the framework, |
| 14 | mapping out the components, software structure, and execution ecosystem of the framework. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 15 | |
| 16 | .. contents:: |
liamfallon | e62f711 | 2019-05-24 10:50:57 +0000 | [diff] [blame] | 17 | :depth: 6 |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 18 | |
liamfallon | e62f711 | 2019-05-24 10:50:57 +0000 | [diff] [blame] | 19 | 1. Overview |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 20 | =========== |
| 21 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 22 | The ONAP Policy Framework is a comprehensive policy design, deployment, and execution environment. The Policy Framework |
| 23 | is 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>`__. |
| 25 | It allows you to specify, deploy, and execute the governance of the features and functions in your ONAP system, be they |
| 26 | closed loop, orchestration, or more traditional open loop use case implementations. The Policy Framework is the |
| 27 | component that is the source of truth for all policy decisions. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 28 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 29 | One of the most important goals of the Policy Framework is to support Policy Driven Operational Management during the |
| 30 | execution of ONAP control loops at run time. In addition, use case implementations such as orchestration and control |
| 31 | benefit from the ONAP policy Framework because they can use the capabilities of the framework to manage and execute |
| 32 | their policies rather than embedding the decision making in their applications. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 33 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 34 | The Policy Framework is deployment agnostic, it manages Policy Execution (in PDPs) and Enforcement (in PEPs) regardless |
| 35 | of how the PDPs and PEPs are deployed. This allows policy execution and enforcement can be deployed in a manner that |
| 36 | meets the performance requirements of a given application or use case. In one deployment, policy execution could be |
| 37 | deployed in a separate executing entity in a Docker container. In another, policy execution could be co-deployed with |
| 38 | an application to increase performance. An example of co-deployment is the Drools PDP Control Loop image, which is a |
| 39 | Docker image that combines the ONAP Drools use case application and dependencies with the Drools PDP engine. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 40 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 41 | The ONAP Policy Framework architecture separates policies from the platform that is supporting them. The framework |
| 42 | supports development, deployment, and execution of any type of policy in ONAP. The Policy Framework is metadata (model) |
| 43 | driven so that policy development, deployment, and execution is as flexible as possible and can support modern rapid |
| 44 | development ways of working such as DevOps. A metadata driven approach also allows the amount of programmed support |
| 45 | required for policies to be reduced or ideally eliminated. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 46 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 47 | We have identified five capabilities as being essential for the framework: |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 48 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 49 | 1. Most obviously, the framework must be capable of being triggered by an event or invoked, and making decisions at run |
| 50 | time. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 51 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 52 | 2. It must be deployment agnostic; capable of managing policies for various Policy Decision Points (PDPs) or policy |
| 53 | engines. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 54 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 55 | 3. It must be metadata driven, allowing policies to be deployed, modified, upgraded, and removed as the system executes. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 56 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 57 | 4. It must provide a flexible model driven policy design approach for policy type programming and specification of |
| 58 | policies. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 59 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 60 | 5. It must be extensible, allowing straightforward integration of new PDPs, policy formats, and policy development |
| 61 | environments. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 62 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 63 | Another important aim of the architecture of a model driven policy framework is that it enables much more flexible |
| 64 | policy 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 |
| 66 | approach for policies, see the :ref:`TOSCA Policy Primer <tosca-label>` for more information on how policies are modeled |
| 67 | in TOSCA. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 68 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 69 | 1. 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 Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 73 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 74 | 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 Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 76 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 77 | b. In ONAP, specific ONAP Policy Types are used to create specific policies that drive the ONAP Platform and |
| 78 | Components. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 79 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 80 | 2. 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 Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 83 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 84 | For 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 Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 86 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 87 | The ONAP Policy Framework for building, configuring and deploying PDPs is extendable. It allows the use of ONAP PDPs as |
| 88 | is, the extension of ONAP PDPs, and lastly provides the capability for users to create and deploy their own PDPs. The |
| 89 | ONAP Policy Framework provides distributed policy management for **all** policies in ONAP at run time. Not only does |
| 90 | this provide unified policy access and version control, it provides life cycle control for policies and allows detection |
| 91 | of conflicts across all policies running in an ONAP installation. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 92 | |
| 93 | 2. Architecture |
| 94 | =============== |
| 95 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 96 | The diagram below shows the architecture of the ONAP Policy Framework at its highest level. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 97 | |
liamfallon | 4d1d983 | 2019-05-30 20:53:05 +0000 | [diff] [blame^] | 98 | .. image:: images/PFHighestLevel.svg |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 99 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 100 | The *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 |
| 102 | mechanisms required to orchestrate the nodes and containers on which policies run. *PolicyAdministration* is also |
| 103 | responsible for the administration of policies at run time; ensuring that policies are available to users, that policies |
| 104 | are executing correctly, and that the state and status of policies is monitored. *PolicyExecution* is the set of PDPs |
| 105 | running in the ONAP system and is responsible for making policy decisions and for managing the administrative state of |
| 106 | the PDPs as directed by \ *PolicyAdministration.* |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 107 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 108 | *PolicyDevelopment* creates policy artifacts and supporting information in the policy database. \ *PolicyAdministration* |
| 109 | reads those artifacts and the supporting information from the policy database whilst deploying policy artifacts. Once |
| 110 | the policy artifacts are deployed, *PolicyAdministration* handles the run-time management of the PDPs on which the |
| 111 | policies are running. *PolicyDevelopment* interacts with ONAP design time components, and has no programmatic interface |
| 112 | with *PolicyAdministration*, *PolicyExecution* or any other run-time ONAP components. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 113 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 114 | The 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 Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 116 | |
liamfallon | 4d1d983 | 2019-05-30 20:53:05 +0000 | [diff] [blame^] | 117 | .. image:: images/PFDesignAndAdmin.svg |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 118 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 119 | *PolicyDevelopment* provides a `CRUD <https://en.wikipedia.org/wiki/Create,_read,_update_and_delete>`__ API for policy |
| 120 | types and policies. The policy types and policy artifacts and their metadata (Information about policies, policy types, |
| 121 | and their interrelations) are stored in the *PolicyDB*. The *PolicyDevGUI*, PolicyDistribution, and other applications |
| 122 | such as *CLAMP* can use the *PolicyDevelopment* API to create, update, and delete policy types and policies. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 123 | |
| 124 | *PolicyAdministration* has two important functions: |
| 125 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 126 | - 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 Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 129 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 130 | - 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 Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 132 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 133 | *PolicyAdministration* handles PDPs and policy allocation to PDPs using asynchronous messaging over DMaaP. It provides |
| 134 | three APIs: |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 135 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 136 | - a CRUD API for policy groups and subgroups |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 137 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 138 | - an API that allows the allocation of policies PDP groups and subgroups to be controlled |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 139 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 140 | - 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 Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 142 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 143 | *PolicyExecution* is the set of running PDPs that are executing policies, logically partitioned into PDP groups and |
| 144 | subgroups. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 145 | |
liamfallon | 4d1d983 | 2019-05-30 20:53:05 +0000 | [diff] [blame^] | 146 | .. image:: images/PolicyExecution.svg |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 147 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 148 | The figure above shows how *PolicyExecution* looks at run time with PDPs running in Kubernetes. A *PDPGroup* is a purely |
| 149 | logical construct that collects all the PDPs that are running policies for a particular domain together. A *PDPSubGroup* |
| 150 | is 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 |
| 154 | structuring of PDPs is required because, in order to simplify deployment and scaling of PDPs in Kubernetes, we gather |
| 155 | all the PDPs of the same type that are running the same policies together for deployment. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 156 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 157 | For example, assume we have policies for the SON (Self Organizing Network) and ACPE (Advanced Customer Premises Service) |
| 158 | domains. For SON,we have XACML, Drools, and APEX policies, and for ACPE we have XACML and Drools policies. The table |
| 159 | below shows the resulting \ *PDPGroup*, *PDPSubGroup*, and PDP allocations: |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 160 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 161 | ============= ================ ========================= ======================================== ================ |
| 162 | **PDP Group** **PDP Subgroup** **Kubernetes Deployment** **Kubernetes Deployment Strategy** **PDPs in Pods** |
| 163 | ============= ================ ========================= ======================================== ================ |
| 164 | SON 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 |
| 169 | ACPE 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 Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 173 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 174 | For more details on *PolicyAdministration* APIs and management of *PDPGroup* and *PDPSubGroup*, see the documentation |
| 175 | for :ref:`Policy Administration Point (PAP) Architecture <pap-label>`. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 176 | |
| 177 | 2.1 Policy Framework Object Model |
| 178 | --------------------------------- |
| 179 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 180 | This section describes the structure of and relations between the main concepts in the Policy Framework. This model is |
| 181 | implemented as a common model and is used by *PolicyDevelopment*, *PolicyDeployment,* and *PolicyExecution.* |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 182 | |
liamfallon | 4d1d983 | 2019-05-30 20:53:05 +0000 | [diff] [blame^] | 183 | .. image:: images/ClassStructure.svg |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 184 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 185 | The UML class diagram above shows the portion of the Policy Framework Object Model that applies to *PolicyDeployment* |
| 186 | and *PolicyExecution.* |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 187 | |
liamfallon | 4d1d983 | 2019-05-30 20:53:05 +0000 | [diff] [blame^] | 188 | .. image:: images/DesignTimeComponents.svg |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 189 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 190 | The UML class diagram above shows the portion of the Policy Framework Object Model that applies to *PolicyDevelopment* |
| 191 | and *PolicyDeployment.* |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 192 | |
| 193 | 2.2 Policy Design Architecture |
| 194 | ------------------------------ |
| 195 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 196 | This section describes the architecture of the model driven system used to develop policy types and to create concrete |
| 197 | policies using policy types. The output of Policy Design is deployment-ready artifacts and Policy metadata in the Policy |
| 198 | Framework database. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 199 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 200 | Policies that are expressed via natural language or a model require some development work ahead of time for them to be |
| 201 | translated into concrete runtime policies. Some Policy Domains will be set up and available in the platform during |
| 202 | startup such as Control Loop Operational Policy Models, OOF placement Models, DCAE microservice models. Policy type |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 203 | implementation development is done by an experienced developer. |
| 204 | |
| 205 | 2.2.1 Policy Type Design |
liamfallon | e62f711 | 2019-05-24 10:50:57 +0000 | [diff] [blame] | 206 | ^^^^^^^^^^^^^^^^^^^^^^^^ |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 207 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 208 | Policy Type Design is the task of creating policy types that capture the generic and vendor independent aspects of a |
| 209 | policy for a particular domain use case. The policy type implementation specifies the model information, rules, and |
| 210 | tasks that a policy type requires to generate concrete policies. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 211 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 212 | All 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 |
| 214 | of the domain that the policy type is addressing or the PDP technology that will execute the policy. The interface is |
| 215 | used by *PolicyDevelopment* to determine the PDP technology of the policy type, the structure, type, and definition of |
| 216 | the model information that must be supplied to the policy type to generate a concrete policy. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 217 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 218 | A *PolicyTypeImpl* is developed for a certain type of PDP (for example XACML oriented for decision policies or Drools |
| 219 | rules oriented for ECA policies). The design environment and tool chain for a policy type is specific for the type of |
| 220 | policy being designed. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 221 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 222 | The *PolicyTypeImpl* implementation (or raw policy) is the specification of the specific rules or tasks, the flow of |
| 223 | the policy, its internal states and data structures and other relevant information. A *PolicyTypeImpl* is specific to a |
| 224 | PDP technology, that is XACML, Drools, or APEX. *A PolicyTypeImpl* can be specific to a particular policy type, it can |
| 225 | be more general, providing the implementation of a class of policy types, or the same policy type may have many |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 226 | implementations. |
| 227 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 228 | *PolicyDevelopment* provides the RESTful :ref:`Policy Design API <design-label>` which allows other components to query |
| 229 | policy types and policy type implementations, to determine the model information, rules, or tasks that they require, to |
| 230 | specialize policy flow, and to generate policies from policy types. This API is used by the ONAP Policy Framework and |
| 231 | other components such as \ *PolicyDistribution* to create policies from policy types. |
| 232 | |
| 233 | Consider a policy type created for managing faults on vCPE equipment in a vendor independent way. The policy type |
| 234 | captures the generic logic required to manage the faults and specifies the vendor specific information that must be |
| 235 | supplied to the type for specific vendor vCPE VFs. The actual vCPE policy that is used for managing particular vCPE |
| 236 | equipment is created by setting the parameters specified in the policy type together with the specific modeled |
| 237 | information, rules and tasks in the policy type implementation for that vendor model of vCPE. |
| 238 | |
| 239 | 2.2.1.1 Generating Policy Types |
| 240 | """"""""""""""""""""""""""""""" |
| 241 | |
| 242 | It is possible to generate policy types using MDD (Model Driven Development) techniques. Policy types are expressed |
| 243 | using a DSL (Domain Specific Language) or a policy specification environment for a particular application domain. For |
| 244 | example, policy types for specifying SLAs could be expressed in a SLA DSL and policy types for managing SON features |
| 245 | could be generated from a visual SON management tool. The ONAP Policy framework provides an API that allows tool chains |
| 246 | to 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 | |
| 249 | The SDC GUI supports several types of policies that can be captured at design time. DCAE micro service configuration |
| 250 | policies can be onboarded via the DCAE-DS (DCAE Design Studio). |
| 251 | |
| 252 | |
| 253 | .. image:: images/PolicyTypeDesign.svg |
| 254 | |
| 255 | The GUI implementation in another ONAP component such as SDC DCAE-DS uses the *API_User* API to create and edit ONAP |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 256 | policy types. |
| 257 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 258 | 2.2.1.2 Programming Policy Type Implementations |
liamfallon | e62f711 | 2019-05-24 10:50:57 +0000 | [diff] [blame] | 259 | """"""""""""""""""""""""""""""""""""""""""""""" |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 260 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 261 | For skilled developers, the most straightforward way to create a policy type is to program it. Programming a policy type |
| 262 | might simply mean creating and editing text files, thus manually creating the TOSCA Policy Type YAML file and the policy |
| 263 | type implementation for the policy type. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 264 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 265 | A more formal approach is preferred. For policy type implementations, programmers use a specific Eclipse project type |
| 266 | for developing each type of implementation, a Policy Type Implementation SDK. The project is under source control in |
| 267 | git. This Eclipse project is structured correctly for creating implementations for a specific type of PDP. It includes |
| 268 | the correct POM files for generating the policy type implementation and has editors and perspectives that aid |
| 269 | programmers in their work |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 270 | |
| 271 | 2.2.2 Policy Design |
liamfallon | e62f711 | 2019-05-24 10:50:57 +0000 | [diff] [blame] | 272 | ^^^^^^^^^^^^^^^^^^^ |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 273 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 274 | The *PolicyCreation* function of *PolicyDevelopment* creates policies from a policy type. The information expressed |
| 275 | during policy type design is used to parameterize a policy type to create an executable policy. A service designer |
| 276 | and/or operations team can use tooling that reads the TOSCA Policy Type specifications to express and capture a policy |
| 277 | at its highest abstraction level. Alternatively, the parameter for the policy can be expressed in a raw JSON or YAML |
| 278 | file and posted over the policy design API described on the :ref:`Policy Design and Development <design-label>` page. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 279 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 280 | A number of mechanisms for policy creation are supported in ONAP. The process in *PolicyDevelopment* for creating a |
| 281 | policy 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 |
| 283 | be exercised directly using utilities such as *curl*. *PolicyDevelopment* provides a command line tool that is a loose |
| 284 | wrapper around the API. It also provides a general purpose Policy GUI in the ONAP Portal for policy creation, which |
| 285 | again is a general purpose wrapper around the policy creation API. The Policy GUI can interpret any TOSCA Model that has |
| 286 | been loaded into it and flexibly presents a GUI for a user to create policies from. The development of these mechanisms |
| 287 | will be phased over a number of ONAP releases. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 288 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 289 | A number of ONAP components use policy in manners which are specific to their particular needs. The manner in which the |
| 290 | policy creation process is triggered and the way in which information required to create a policy is specified and |
| 291 | accessed is specialized for these ONAP components. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 292 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 293 | The following subsections outline the mechanisms for policy creation and modification supported by the ONAP Policy |
| 294 | Framework. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 295 | |
| 296 | 2.2.2.1 Policy Design in the ONAP Policy Framework |
liamfallon | e62f711 | 2019-05-24 10:50:57 +0000 | [diff] [blame] | 297 | """""""""""""""""""""""""""""""""""""""""""""""""" |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 298 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 299 | Policy creation in *PolicyDevelopment* follows the general sequence shown in the sequence diagram below. An *API_USER* |
| 300 | is any component that wants to create a policy from a policy type. *PolicyDevelopment* supplies a REST interface that |
| 301 | exposes the API and also provides a command line tool and general purpose client that wraps the API. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 302 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 303 | .. image:: images/PolicyDesign.svg |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 304 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 305 | An *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 |
| 308 | database. If the policy already exists, *PolicyDevelopment* reads the artifact and returns the reference of the existing |
| 309 | policy to the *API_User* with the metadata for the existing policy. If the policy does not exist, *PolicyDevelopment* |
| 310 | creates and new reference and metadata and returns that to the *API_User*. |
| 311 | |
| 312 | The *API_User* may now proceed with a policy specification session, where the parameters are set for the policy using |
| 313 | the policy type specification. Once the *API_User* is happy that the policy is completely and correctly specified, it |
| 314 | requests *PolicyDevelopment* to create the policy. *PolicyDevelopment* creates the policy, stores the created policy |
| 315 | artifact and its metadata in the database. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 316 | |
| 317 | 2.2.2.2 Model Driven VF (Virtual Function) Policy Design via VNF SDK Packaging |
liamfallon | e62f711 | 2019-05-24 10:50:57 +0000 | [diff] [blame] | 318 | """""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 319 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 320 | VF vendors express policies such as SLA, Licenses, hardware placement, run-time metric suggestions, etc. These details |
| 321 | are 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 |
| 323 | placement policies may be captured via TOSCA specification. License policies can be captured via TOSCA or an XACML |
| 324 | specification. Run-time metric vendor recommendations can be captured via the VES Standard specification. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 325 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 326 | The 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 |
| 328 | SDC. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 329 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 330 | .. 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 |
| 334 | information it needs to populate the policy type from a TOSCA specification in a CSAR received from SDC and then uses |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 335 | this information to automatically generate a policy. |
| 336 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 337 | Note that SDC provides a wrapper for the SDC API as a Java Client and also provides a TOSCA parser. See the |
| 338 | documentation for the `Policy Distribution Component |
| 339 | <https://docs.onap.org/en/latest/submodules/policy/distribution.git/docs/index.html>`__. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 340 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 341 | In Step 4 above, the \ *PolicyDesign* must download the CSAR file. If the policy is to be composed from the TOSCA |
| 342 | definition, it must also parse the TOSCA definition. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 343 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 344 | In Step 11 above, the \ *PolicyDesign* must send back/publish status events to SDC such as DOWNLOAD_OK, DOWNLOAD_ERROR, |
| 345 | DEPLOY_OK, DEPLOY_ERROR, NOTIFIED. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 346 | |
liamfallon | e62f711 | 2019-05-24 10:50:57 +0000 | [diff] [blame] | 347 | 2.2.2.3 Scripted Model Driven Policy Design |
| 348 | """"""""""""""""""""""""""""""""""""""""""" |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 349 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 350 | Service policies such as optimization and placement policies can be specified as a TOSCA Policy at design time. These |
| 351 | policies use a TOSCA Policy Type specification as their schemas. Therefore, scripts can be used to create TOSCA policies |
| 352 | using TOSCA Policy Types. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 353 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 354 | .. image:: images/ScriptedPolicyDesign.svg |
| 355 | |
| 356 | One straightforward way of generating policies from Policy types is to use directives specified in a script file. The |
| 357 | command line utility is an *API_User*. The script reads directives from a file. For each directive, it reads the policy |
| 358 | type using the Policy Type API, and uses the parameters of the directive to prepare a TOSCA Policy. It then uses the |
| 359 | Policy API to create the policy. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 360 | |
| 361 | 2.2.3 Policy Design Process |
liamfallon | e62f711 | 2019-05-24 10:50:57 +0000 | [diff] [blame] | 362 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 363 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 364 | All policy types must be certified as being fit for deployment prior to run time deployment. Where design is executed |
| 365 | using the SDC application, it is assumed the life cycle being implemented by SDC certifies any policy types that |
| 366 | are declared within the ONAP Service CSAR. For other policy types and policy type implementations, the life cycle |
| 367 | associated with the applied software development process suffices. Since policy types and their implementations are |
| 368 | designed and implemented using software development best practices, they can be utilized and configured for various |
| 369 | environments (eg. development, testing, production) as desired. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 370 | |
| 371 | 2.3 Policy Runtime Architecture |
| 372 | ------------------------------- |
| 373 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 374 | The Policy Framework Platform components are themselves designed as microservices that are easy to configure and deploy |
| 375 | via Docker images and K8S both supporting resiliency and scalability if required. PAPs and PDPs are deployed by the |
| 376 | underlying ONAP management infrastructure and are designed to comply with the ONAP interfaces for deploying containers. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 377 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 378 | The PAPs keep track of PDPs, support the deployment of PDP groups and the deployment of a *policy set* across those PDP |
| 379 | groups. A PAP is stateless in a RESTful sense. Therefore, if there is more than one PAP deployed, it does not matter |
| 380 | which PAP a user contacts to handle a request. The PAP uses the database (persistent storage) to keep track of ongoing |
| 381 | sessions with clients. Policy management on PDPs is the responsibility of PAPs; management of policy sets or policies by |
| 382 | any other manner is not permitted. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 383 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 384 | In the ONAP Policy Framework, the interfaces to the PDP are designed to be as streamlined as possible. Because the PDP |
| 385 | is the main unit of scalability in the Policy Framework, the framework is designed to allow PDPs in a PDP group to |
| 386 | arbitrarily appear and disappear and for policy consistency across all PDPs in a PDP group to be easily maintained. |
| 387 | Therefore, PDPs have just two interfaces; an interface that users can use to execute policies and interface to the PAP |
| 388 | for administration, life cycle management and monitoring. The PAP is responsible for controlling the state across the |
| 389 | PDPs in a PDP group. The PAP interacts with the Policy database and transfers policy sets to PDPs, and may cache the |
| 390 | policy sets for PDP groups. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 391 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 392 | See also Section 2 of the :ref:`Policy Design and Development <design-label>` page, where the mechanisms for PDP |
| 393 | Deployment and Registration with PAP are explained. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 394 | |
| 395 | 2.3.1 Policy Framework Services |
liamfallon | e62f711 | 2019-05-24 10:50:57 +0000 | [diff] [blame] | 396 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 397 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 398 | The ONAP Policy Framework follows the architectural approach for microservices recommended by the `ONAP Architecture |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 399 | Subcommittee <https://wiki.onap.org/display/DW/Architecture+Subcommittee>`__. |
| 400 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 401 | The ONAP Policy Framework defines `Kubernetes Services |
| 402 | <https://kubernetes.io/docs/concepts/services-networking/service/>`__ to manage the life cycle of Policy Framework |
| 403 | executable components at runtime. A Kubernetes service allows, among other parameters, the number of instances (*pods* |
| 404 | in Kubernetes terminology) that should be deployed for a particular service to be specified and a common endpoint for |
| 405 | that service to be defined. Once the service is started in Kubernetes, Kubernetes ensures that the specified number of |
| 406 | instances is always kept running. As requests are received on the common endpoint, they are distributed across the |
| 407 | service 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 |
| 409 | details. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 410 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 411 | If, for example, a service called *policy-pdpd-control-loop* is defined that runs 5 PDP-D instances. The service has the |
| 412 | end point *https://policy-pdpd-control-loop.onap/<service-specific-path>*. When the service is started, Kubernetes spins |
| 413 | up 5 PDP-Ds. Calls to the end point *https://policy-pdpd-control-loop.onap/<service-specific-path>* are distributed |
| 414 | across the 5 PDP-D instances. Note that the *.onap* part of the service endpoint is the namespace being used and is |
| 415 | specified for the full ONAP Kubernetes installation. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 416 | |
| 417 | The following services will be required for the ONAP Policy Framework: |
| 418 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 419 | ================ ============================== ======================================================================= |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 420 | **Service** **Endpoint** **Description** |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 421 | ================ ============================== ======================================================================= |
| 422 | PAP 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 |
| 425 | PDP-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 Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 432 | | https://policy-pdpx-onap |
| 433 | | https://policy-pdpx-\ *supacom* |
| 434 | PDP-D-\ *domain* https://policy-pdpd-\ *domain* |
| 435 | PDP-A-\ *domain* https://policy-pdpa-\ *domain* |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 436 | ================ ============================== ======================================================================= |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 437 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 438 | There is one and only one PAP service, which handles policy deployment, administration, and monitoring for all policies |
| 439 | in all PDPs and PDP groups in the system. There are multiple PDP services, one PDP service for each domain for which |
| 440 | there are policies. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 441 | |
| 442 | 2.3.2 The Policy Framework Information Structure |
liamfallon | e62f711 | 2019-05-24 10:50:57 +0000 | [diff] [blame] | 443 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 444 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 445 | The following diagram captures the relationship between Policy Framework concepts at run time. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 446 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 447 | .. image:: images/RuntimeRelationships.svg |
| 448 | |
| 449 | There is a one to one relationship between a PDP SubGroup, a Kubernetes PDP service, and the set of policies assigned to |
| 450 | run in the PDP subgroup. Each PDP service runs a single PDP subgroup with multiple PDPs, which executes a specific |
| 451 | Policy Set containing a number of policies that have been assigned to that PDP subgroup. Having and maintaining this |
| 452 | principle makes policy deployment and administration much more straightforward than it would be if complex relationships |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 453 | between PDP services, PDP subgroups, and policy sets. |
| 454 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 455 | The topology of the PDPs and their policy sets is held in the Policy Framework database and is administered by the PAP service. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 456 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 457 | .. image:: images/PolicyDatabase.svg |
| 458 | |
| 459 | The diagram above gives an indicative structure of the run time topology information in the Policy Framework database. |
| 460 | Note that the *PDP_SUBGROUP_STATE* and *PDP_STATE* fields hold state information for life cycle management of PDP groups |
| 461 | and PDPs. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 462 | |
| 463 | 2.3.3 Startup, Shutdown and Restart |
liamfallon | e62f711 | 2019-05-24 10:50:57 +0000 | [diff] [blame] | 464 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 465 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 466 | This section describes the interactions between Policy Framework components themselves and with other ONAP components at |
| 467 | startup, shutdown and restart. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 468 | |
| 469 | 2.3.3.1 PAP Startup and Shutdown |
liamfallon | e62f711 | 2019-05-24 10:50:57 +0000 | [diff] [blame] | 470 | """""""""""""""""""""""""""""""" |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 471 | |
| 472 | The sequence diagram below shows the actions of the PAP at startup. |
| 473 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 474 | .. image:: images/PAPStartStop.svg |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 475 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 476 | The PAP is the run time point of coordination for the ONAP Policy Framework. When it is started, it initializes itself |
| 477 | using data from the database. It then waits for periodic PDP status updates and for administration requests. |
| 478 | |
| 479 | PAP shutdown is trivial. On receipt or a shutdown request, the PAP completes or aborts any ongoing operations and shuts |
| 480 | down gracefully. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 481 | |
| 482 | 2.3.3.2 PDP Startup and Shutdown |
liamfallon | e62f711 | 2019-05-24 10:50:57 +0000 | [diff] [blame] | 483 | """""""""""""""""""""""""""""""" |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 484 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 485 | The 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 Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 487 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 488 | .. image:: images/PDPStartStop.svg |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 489 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 490 | At startup, the PDP initializes itself. At this point it is in PASSIVE mode. The PDP begins sending periodic Status |
| 491 | messages to the PAP. The first Status message initializes the process of loading the correct Policy Set on the PDP in |
| 492 | the PAP. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 493 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 494 | On receipt or a shutdown request, the PDP completes or aborts any ongoing policy executions and shuts down gracefully. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 495 | |
| 496 | 2.3.4 Policy Execution |
liamfallon | e62f711 | 2019-05-24 10:50:57 +0000 | [diff] [blame] | 497 | ^^^^^^^^^^^^^^^^^^^^^^ |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 498 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 499 | Policy execution is the execution of a policy in a PDP. Policy enforcement occurs in the component that receives a |
| 500 | policy decision. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 501 | |
liamfallon | 4d1d983 | 2019-05-30 20:53:05 +0000 | [diff] [blame^] | 502 | .. image:: images/PolicyExecutionFlow.svg |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 503 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 504 | Policy execution can be *synchronous* or *asynchronous*. In *synchronous* policy execution, the component requesting a |
| 505 | policy decision requests a policy decision and waits for the result. The PDP-X and PDP-A implement synchronous policy |
| 506 | execution. In *asynchronous* policy execution, the component that requests a policy decision does not wait for the |
| 507 | decision. Indeed, the decision may be passed to another component. The PDP-D and PDP-A implement asynchronous polic |
| 508 | execution. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 509 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 510 | Policy execution is carried out using the current life cycle mode of operation of the PDP. While the actual |
| 511 | implementation of the mode may vary somewhat between PDPs of different types, the principles below hold true for all |
| 512 | PDP types: |
| 513 | |
| 514 | ================== ===================================================================================================== |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 515 | **Lifecycle Mode** **Behaviour** |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 516 | ================== ===================================================================================================== |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 517 | PASSIVE MODE Policy execution is always rejected irrespective of PDP type. |
| 518 | ACTIVE MODE Policy execution is executed in the live environment by the PDP. |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 519 | SAFE 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. |
| 523 | TEST 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 Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 528 | |
| 529 | 2.3.5 Policy Lifecycle Management |
liamfallon | e62f711 | 2019-05-24 10:50:57 +0000 | [diff] [blame] | 530 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 531 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 532 | Policy lifecycle management manages the deployment and life cycle of policies in PDP groups at run time. Policy sets can |
| 533 | be deployed at run time without restarting PDPs or stopping policy execution. PDPs preserve state for minor/patch |
| 534 | version upgrades and rollbacks. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 535 | |
| 536 | 2.3.5.1 Load/Update Policies on PDP |
liamfallon | e62f711 | 2019-05-24 10:50:57 +0000 | [diff] [blame] | 537 | """"""""""""""""""""""""""""""""""" |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 538 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 539 | The sequence diagram below shows how policies are loaded or updated on a PDP. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 540 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 541 | .. image:: images/DownloadPoliciesToPDP.svg |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 542 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 543 | This sequence can be initiated in two ways; from the PDP or from a user action. |
| 544 | |
| 545 | 1. 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 Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 547 | |
| 548 | 2. A user may explicitly trigger this sequence to load policies on a PDP |
| 549 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 550 | The PAP controls the entire process. The PAP reads the current PDP metadata and the required policy and policy set |
| 551 | artifacts from the database. It then builds the policy set for the PDP. Once the policies are ready, the PAP sets the |
| 552 | mode of the PDP to PASSIVE. The Policy Set is transparently passed to the PDP by the PAP. The PDP loads all the policies |
| 553 | in the policy set including any models, rules, tasks, or flows in the policy set in the policy implementations. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 554 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 555 | Once 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 Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 559 | |
| 560 | 2.3.5.2 Policy Rollout |
liamfallon | e62f711 | 2019-05-24 10:50:57 +0000 | [diff] [blame] | 561 | """""""""""""""""""""" |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 562 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 563 | A policy set steps through a number of life cycle modes when it is rolled out. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 564 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 565 | .. image:: images/PolicyRollout.svg |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 566 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 567 | The user defines the set of policies for a PDP group. It is deployed to a PDP group and is initially in PASSIVE mode. |
| 568 | The user sets the PDP Group into TEST mode. The policies are run in a test or sandboxed environment for a period of |
| 569 | time. The test results are passed back to the user. The user may revert the policy set to PASSIVE mode a number of times |
| 570 | and upgrade the policy set during test operation. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 571 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 572 | When the user is satisfied with policy set execution and when quality criteria have been reached for the policy set, the |
| 573 | PDP group is set to run in SAFE mode. In this mode, the policies run on the target environment but do not actually |
| 574 | exercise any actions or change any context in the target environment. Again, as in TEST mode, the operator may decide to |
| 575 | revert back to TEST mode or even PASSIVE mode if issues arise with a policy set. |
| 576 | |
| 577 | Finally, when the user is satisfied with policy set execution and when quality criteria have been reached, the PDP group |
| 578 | is set into ACTIVE state and the policy set executes on the target environment. The results of target operation are |
| 579 | reported. The PDP group can be reverted to SAFE, TEST, or even PASSIVE mode at any time if problems arise. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 580 | |
| 581 | 2.3.5.3 Policy Upgrade and Rollback |
liamfallon | e62f711 | 2019-05-24 10:50:57 +0000 | [diff] [blame] | 582 | """"""""""""""""""""""""""""""""""" |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 583 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 584 | There are a number of approaches for managing policy upgrade and rollback. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 585 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 586 | The most straightforward approach is to use the approach described in section :ref:`policy-rollout` for upgrading and |
| 587 | rolling back policy sets. In order to upgrade a policy set, one follows the process in :ref:`policy-rollout` with the |
| 588 | new policy set version. For rollback, one follows the process in :ref:`policy-rollout` with the older policy set, most |
| 589 | probably setting the old policy set into ACTIVE mode immediately. The advantage of this approach is that the approach is |
| 590 | straightforward. The obvious disadvantage is that the PDP group is not executing on the target environment while the new |
| 591 | policy set is in PASSIVE, TEST, and SAFE mode. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 592 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 593 | A second manner to tackle upgrade and rollback is to use a spare-wheel approach. An special upgrade PDP group service is |
| 594 | set up as a K8S service in parallel with the active one during the upgrade procedure. The spare wheel service is used to |
| 595 | execute the process described in :ref:`policy-rollout`. When the time comes to activate the policy set, the references |
| 596 | for the active and spare wheel services are simply swapped. The advantage of this approach is that the down time during |
| 597 | upgrade is minimized, the spare wheel PDP group can be abandoned at any time without affecting the in service PDP group, |
| 598 | and the upgrade can be rolled back easily for a period simply by preserving the old service for a time. The disadvantage |
| 599 | is that this approach is more complex and uses more resources than the first approach. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 600 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 601 | A third approach is to have two policy sets running in each PDP, an active set and a standby set. However such an |
| 602 | approach would increase the complexity of implementation in PDPs significantly. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 603 | |
| 604 | 2.3.6 Policy Monitoring |
liamfallon | e62f711 | 2019-05-24 10:50:57 +0000 | [diff] [blame] | 605 | ^^^^^^^^^^^^^^^^^^^^^^^ |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 606 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 607 | PDPs provide a periodic report of their status to the PAP. All PDPs report using a standard reporting format that is |
| 608 | extended to provide information for specific PDP types. PDPs provide at least the information below: |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 609 | |
| 610 | ===================== =============================================================================== |
| 611 | **Field** **Description** |
| 612 | ===================== =============================================================================== |
| 613 | State Lifecycle State (PASSIVE/TEST/SAFE/ACTIVE) |
| 614 | Timestamp Time the report record was generated |
| 615 | InvocationCount The number of execution invocations the PDP has processed since the last report |
| 616 | LastInvocationTime The time taken to process the last execution invocation |
| 617 | AverageInvocationTime The average time taken to process an invocation since the last report |
| 618 | StartTime The start time of the PDP |
| 619 | UpTime The length of time the PDP has been executing |
| 620 | RealTimeInfo Real time information on running policies. |
| 621 | ===================== =============================================================================== |
| 622 | |
| 623 | 2.3.7 PEP Registration and Enforcement Guidelines |
liamfallon | e62f711 | 2019-05-24 10:50:57 +0000 | [diff] [blame] | 624 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 625 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 626 | In ONAP there are several applications outside the Policy Framework that enforce policy decisions based on models |
| 627 | provided to the Policy Framework. These applications are considered Policy Enforcement Engines (PEP) and roles will be |
| 628 | provided to those applications using AAF/CADI to ensure only those applications can make calls to the Policy Decision |
| 629 | APIs. Some example PEPs are: DCAE, OOF, and SDNC. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 630 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 631 | See Section 3.4 of the :ref:`Policy Design and Development <design-label>` |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 632 | for more information on the Decision APIs. |
| 633 | |
| 634 | 3. APIs Provided by the Policy Framework |
| 635 | ======================================== |
| 636 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 637 | See the :ref:`Policy Design and Development <design-label>` page. |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 638 | |
| 639 | 4. Terminology |
| 640 | ============== |
| 641 | |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 642 | ================================= ================================================================================== |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 643 | PAP (Policy Administration Point) A component that administers and manages policies |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 644 | ================================= ================================================================================== |
Pamela Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 645 | PDP (Policy Deployment Point) A component that executes a policy artifact (One or many?) |
| 646 | PDP_<> A specific type of PDP |
| 647 | PDP Group A group of PDPs that execute the same set of policies |
| 648 | Policy Development The development environment for policies |
liamfallon | c9e2790 | 2019-05-28 13:27:04 +0000 | [diff] [blame] | 649 | Policy Type A generic prototype definition of a type of policy in TOSCA, see the |
| 650 | :ref:`TOSCA Policy Primer <tosca-label>` |
| 651 | Policy An executable policy defined in TOSCA and created using a Policy Type, see the |
| 652 | :ref:`TOSCA Policy Primer <tosca-label>` |
| 653 | Policy 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 Dragosh | 5fc2fdb | 2019-05-17 09:42:27 -0400 | [diff] [blame] | 656 | |
| 657 | |
| 658 | End of Document |