docs/architecture/architecture.rst

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