diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/api/api.rst | 14 | ||||
| -rw-r--r-- | docs/architecture/architecture.rst | 817 | ||||
| -rw-r--r-- | docs/architecture/detailed.png | bin | 0 -> 214476 bytes | |||
| -rw-r--r-- | docs/architecture/execution.png | bin | 0 -> 104106 bytes | |||
| -rw-r--r-- | docs/architecture/highest.png | bin | 0 -> 40638 bytes | |||
| -rw-r--r-- | docs/architecture/objectmodel1.png | bin | 0 -> 186880 bytes | |||
| -rw-r--r-- | docs/architecture/objectmodel2.png | bin | 0 -> 170899 bytes | |||
| -rw-r--r-- | docs/design/design.png | bin | 0 -> 230981 bytes | |||
| -rw-r--r-- | docs/design/design.rst | 124 | ||||
| -rw-r--r-- | docs/design/foo.rst | 4898 | ||||
| -rw-r--r-- | docs/design/tosca-policy-primer.rst | 57 | ||||
| -rw-r--r-- | docs/development/development.rst | 328 | ||||
| -rw-r--r-- | docs/drools/drools.rst | 12 | ||||
| -rw-r--r-- | docs/index.rst | 15 | ||||
| -rw-r--r-- | docs/installation/docker.rst | 16 | ||||
| -rw-r--r-- | docs/installation/installation.rst | 18 | ||||
| -rw-r--r-- | docs/installation/oom.rst | 16 | ||||
| -rw-r--r-- | docs/pap/pap.rst | 13 | ||||
| -rw-r--r-- | docs/release-notes.rst | 385 |
19 files changed, 6713 insertions, 0 deletions
diff --git a/docs/api/api.rst b/docs/api/api.rst new file mode 100644 index 00000000..7df880ca --- /dev/null +++ b/docs/api/api.rst @@ -0,0 +1,14 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +.. _api-label: + +Policy Lifecycle API +-------------------- +.. toctree:: + :maxdepth: 1 + + + + + +End of Document diff --git a/docs/architecture/architecture.rst b/docs/architecture/architecture.rst new file mode 100644 index 00000000..e0b40489 --- /dev/null +++ b/docs/architecture/architecture.rst @@ -0,0 +1,817 @@ +.. This work is licensed under a +.. Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + + +Architecture +------------ + +Abstract + +This document describes the ONAP Policy Framework. It lays out the +architecture of the framework and specifies the APIs provided to other +components that interwork with the framework. It describes the +implementation of the framework, mapping out the components, software +structure, and execution ecosystem of the framework. It goes on to +provide examples that illustrate how to write, deploy, and run policies +of various types using the framework. + +.. contents:: + :depth: 4 + +1. Overview +=========== + +The ONAP Policy Framework is a comprehensive policy design, deployment, +and execution environment. The Policy Framework is the decision +making component in `an ONAP +system <https://www.onap.org/wp-content/uploads/sites/20/2017/12/ONAP_CaseSolution_Architecture_120817_FNL.pdf>`__. +It allows you to specify, deploy, and execute the governance of the +features and functions in your ONAP system, be they closed loop, +orchestration, or more traditional open loop use case implementations. +The Policy Framework is the component that is the source of truth for +all policy decisions. + +One of the most important goals of the Policy Framework is to support +Policy Driven Operational Management during the execution of ONAP +control loops at run time. In addition, use case implementations such as +orchestration and control benefit from the ONAP policy Framework because +they can use the capabilities of the framework to manage and execute +their policies rather than embedding the decision making in their +applications. + +The Policy Framework is deployment agnostic, the Policy Framework +manages Policy Execution (in PDPs) and Enforcement (in PEPs) regardless +of how the PDPs and PEPs are deployed. This allows policy execution and +enforcement can be deployed in a manner that meets the performance +requirements of a given application or use case. In one deployment, +policy execution could be deployed in a separate executing entity in a +Docker container. In another, policy execution could be co-deployed with +an application to increase performance. An example of co-deployment is the +Drools PDP Control Loop image, which is a Docker image that combines the ONAP +Drools use case application and dependencies with the Drools PDP engine. + +The ONAP Policy Framework architecture separates policies from the +platform that is supporting them. The framework supports development, +deployment, and execution of any type of policy in ONAP. The Policy +Framework is metadata (model) driven so that policy development, +deployment, and execution is as flexible as possible and can support +modern rapid development ways of working such as DevOps. A metadata +driven approach also allows the amount of programmed support required +for policies to be reduced or ideally eliminated. + +We have identified five capabilities as being essential for the +framework: + +1. Most obviously, the framework must be capable of being triggered by + an event or invoked, and making decisions at run time. + +2. It must be deployment agnostic; capable of managing policies for + various Policy Decision Points (PDPs) or policy engines. + +3. It must be metadata driven, allowing policies to be deployed, + modified, upgraded, and removed as the system executes. + +4. It must provide a flexible model driven policy design approach for + policy type programming and specification of policies. + +5. It must be extensible, allowing straightforward integration of new + PDPs, policy formats, and policy development environments. + +Another important aim of the architecture of a model driven policy +framework is that it enables much more flexible policy specification. +The ONAP Policy Framework complies with the +`TOSCA <http://docs.oasis-open.org/tosca/TOSCA-Simple-Profile-YAML/v1.1/TOSCA-Simple-Profile-YAML-v1.1.pdf>`__ +modelling approach for policies, see the :ref:`TOSCA Policy Primer <tosca-label>` for more +information on how policies are modeled in TOSCA. + +1. A Policy Type is a general implementation of a policy for a feature. + For example, a Policy Type could be written to manage Service Level + Agreements for VPNs. The Policy Type is designed by a domain expert, + who specifies the parameters, triggers, and actions that the Policy + Type will have. The implementation (the logic, rules, and tasks of + the Policy Type) is implemented by a skilled policy developer in + consultation with domain experts. + + 1. For example, the VPN Policy Type is used to create VPN policies + for a bank network, a car dealership network, or a university with + many campuses. + + 2. In ONAP, specific ONAP Policy Types are used to create specific + policies that drive the ONAP Platform and Components. + +2. A Policy is created by configuring a Policy Type with parameters. For + example, the SLA values in the car dealership VPN policy for a + particular dealership are configured with values appropriate for the + expected level of activity in that dealership. + +For more detailed information on designing Policy Types and developing an +implementation for that policy type, see :ref:`Policy Design and Development <design-label>`. + +The ONAP Policy Framework for building, configuring and deploying PDPs +is extendable. It allows the use of ONAP PDPs as is, the extension of +ONAP PDPs, and lastly provides the capability for users to create and +deploy their own PDPs. The ONAP Policy Framework provides distributed +policy management for **all** policies in ONAP at run time. Not only +does this provide unified policy access and version control, it provides +life cycle control for policies and allows detection of conflicts across +all policies running in an ONAP installation. + +2. Architecture +=============== + +The diagram below shows the architecture of the ONAP Policy Framework at +its highest level. + +.. image:: highest.png + +The *PolicyDevelopment* component implements the functionality for +development of policy types and policies. *PolicyAdministration* is +responsible for the deployment life cycle of policies as well as +interworking with the mechanisms required to orchestrate the nodes and +containers on which policies run. *PolicyAdministration* is also +responsible for the administration of policies at run time; ensuring +that policies are available to users, that policies are executing +correctly, and that the state and status of policies is monitored. +*PolicyExecution* is the set of PDPs running in the ONAP system and is +responsible for making policy decisions and for managing the +administrative state of the PDPs as directed +by \ *PolicyAdministration.* + +*PolicyDevelopment* creates policy artifacts and supporting information +in the policy database. \ *PolicyAdministration* reads those artifacts +and the supporting information from the policy database whilst deploying +policy artifacts. Once the policy artifacts are deployed, +*PolicyAdministration* handles the run-time management of the PDPs on +which the policies are running. *PolicyDevelopment* interacts with ONAP +design time components, and has no programmatic interface with +*PolicyAdministration*, *PolicyExecution* or any other run-time ONAP +components. + +The diagram below shows a more detailed view of the architecture, as +inspired by `RFC-2753 <https://tools.ietf.org/html/rfc2753>`__ and +`RFC-3198 <https://tools.ietf.org/html/rfc3198>`__. + +.. image:: detailed.png + +*PolicyDevelopment* provides a +`CRUD <https://en.wikipedia.org/wiki/Create,_read,_update_and_delete>`__ +API for policy types and policies. The policy types and policy artifacts +and their metadata (Information about policies, policy types, and their +interrelations ) are stored in the *PolicyDB*. The *PolicyDevGUI*, +PolicyDistribution, and other applications such as *CLAMP* can use the +*PolicyDevelopment* API to create, update, and delete policy types and +policies. + +*PolicyAdministration* has two important functions: + +- Management of the life cycle of PDPs in an ONAP installation. PDPs + register with *PolicyAdministration* when they come up. + *PolicyAdministration* handles the allocation of PDPs to a PDP Groups + and PDP Subgroups, so that they can be managed as microservices in + Kubernetes. + +- Management of the deployment of policies to PDPs in an ONAP + installation. *PolicyAdministration* gives each PDP group a set of + domain policies to execute. + +*PolicyAdministration* handles PDPs and policy allocation to PDPs using +asynchronous messaging over DMaaP. + +*PolicyAdministation* provides three APIs: + +- a CRUD API for policy groups and subgroups + +- an API that allows the allocation of policies PDP groups and + subgroups to be controlled + +- an API allows policy execution to be managed, showing the status of + policy execution on PDP Groups, subgroups, and individual PDPs as + well as the life cycle state of PDPs + +*PolicyExecution* is the set of running PDPs that are executing +policies, logically partitioned into PDP groups and subgroups. + +.. image:: execution.png + +The figure above shows how *PolicyExecution* looks at run time with PDPs +running in Kubernetes. A *PDPGroup* is a purely logical construct that +collects all the PDPs that are running policies for a particular domain +together. A *PDPSubGroup* is a group of PDPs of the same type that are +running the same policies. *A PDPSubGroup* is deployed as a Kubernetes +`Deployment <https://kubernetes.io/docs/concepts/workloads/controllers/deployment/>`__. +PDPs are defined as Kubernetes +`Pods <https://kubernetes.io/docs/concepts/workloads/pods/pod/>`__. At +run time, the actual number of PDPs in each *PDPSubGroup* is specified +in the configuration of the *Deployment* of that *PDPSubGroup* in +Kubernetes. This structuring of PDPs is required because, in order to +simplify deployment and scaling of PDPs in Kubernetes, we gather all the +PDPs of the same type that are running the same policies together for +deployment. + +For example, assume we have policies for the SON (Self Organizing +Network) and ACPE (Advanced Customer Premises Service) domains. For SON, +we have XACML, Drools, and APEX policies, and for ACPE we have XACML and +Drools policies. The table below shows the resulting\ *PDPGroup*, +*PDPSubGroup*, and PDP allocations: + +============= ================ ========================= ========================================================================== ================ +**PDP Group** **PDP Subgroup** **Kubernetes Deployment** **Kubernetes Deployment Strategy** **PDPs in Pods** +============= ================ ========================= ========================================================================== ================ +SON SON-XACML SON-XACML-Dep Always 2, be geo redundant 2 PDP-X +\ SON-Drools SON-Drools-Dep At Least 4, scale up on 70% load, scale down on 40% load, be geo-redundant >= 4 PDP-D +\ SON-APEX SON-APEX-Dep At Least 3, scale up on 70% load, scale down on 40% load, be geo-redundant >= 3 PDP-A +ACPE ACPE-XACML ACPE-XACML-Dep Always 2 2 PDP-X +\ ACPE-Drools ACPE-Drools-Dep At Least 2, scale up on 80% load, scale down on 50% load >=2 PDP-D +============= ================ ========================= ========================================================================== ================ + +For more details on *PolicyAdministration* API's and management of *PDPGroup* and *PDPSubGroup*, +see the documentation for :ref:`Policy Administration Point (PAP) Architecture <pap-label>`. + +2.1 Policy Framework Object Model +--------------------------------- + +This section describes the structure of and relations between the main +concepts in the Policy Framework. This model is implemented as a common +model and is used by *PolicyDevelopment*, *PolicyDeployment,* and +*PolicyExecution.* + +.. image:: objectmodel1.png + +The UML class diagram above shows the portion of the Policy Framework +Object Model that applies to *PolicyDeployment* and *PolicyExecution.* + +.. image:: objectmodel2.png + +The UML class diagram above shows the portion of the Policy Framework +Object Model that applies to *PolicyDevelopment* and *PolicyDeployment.* + +2.2 Policy Design Architecture +------------------------------ + +This section describes the architecture of the model driven system used +to develop policy types and to create concrete policies using policy +types. The output of Policy Design is deployment-ready artifacts and +Policy metadata in the Policy Framework database. + +Policies that are expressed via natural language or a model require some +development work ahead of time for them to be translated into concrete +runtime policies. Some Policy Domains will be setup and available in the +platform during startup such as Control Loop Operational Policy Models, +OOF placement Models, DCAE microservice models. Policy type +implementation development is done by an experienced developer. + +2.2.1 Policy Type Design +~~~~~~~~~~~~~~~~~~~~~~~~ + +Policy Type Design is the task of creating policy types that capture the +generic and vendor independent aspects of a policy for a particular +domain use case. The policy type implementation specifies the model +information, rules, and tasks that a policy type requires to generate +concrete policies. + +All policy types must implement the ONAP Policy Framework *PolicyType* +interface. This interface allows \ *PolicyDevelopment* to manage policy +types and to generate policies from these policy types in a uniform way +regardless of the domain that the policy type is addressing or the PDP +technology that will execute the policy. The interface is used by +*PolicyDevelopment* to determine the PDP technology of the policy type, +the structure, type, and definition of the model information that must +be supplied to the policy type to generate a concrete policy. + +A \ *PolicyTypeImpl* is developed for a certain type of PDP (for example +XACML oriented for decision policies or Drools rules oriented for ECA +policies). The design environment and tool chain for a policy type is +specific for the type of policy being designed. + +The \ *PolicyTypeImpl* implementation (or raw policy) is the +specification of the specific rules or tasks, the flow of the policy, +its internal states and data structures and other relevant information. +A *PolicyTyp*\ e\ *Impl* is specific to a PDP technology, that is XACML, +Drools, or APEX. *A PolicyTypeImpl* can be specific to a particular +policy type, it can be more general, providing the implementation of a +class of policy types, or the same policy type may have many +implementations. + +*PolicyDevelopment* provides the RESTful `Policy Design +API <https://wiki.onap.org/display/DW/Policy+Design+and+API+Flow+for+Model+Driven+Control+Loop+-+Draft>`__, +which allows other components to query policy types and policy type +implementations, to determine the model information, rules, or tasks +that they require, to specialize policy flow, and to generate policies +from policy types. This API is used by the ONAP Policy Framework and +other components such as \ *PolicyDistribution* to create policies from +policy types. + +Consider a policy type created for managing faults on vCPE equipment in +a vendor independent way. The policy type captures the generic logic +required to manage the faults and specifies the vendor specific +information that must be supplied to the type for specific vendor vCPE +VFs. The actual vCPE policy that is used for managing particular vCPE +equipment is created by setting the parameters specified in the policy +type together with the specific modeled information, rules and tasks in +the policy type implementation for that vendor model of vCPE. + +2.2.1 Generating Policy Types +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +It is possible to generate policy types using MDD (Model Driven +Development) techniques. Policy types are expressed using a DSL (Domain +Specific Language) or a policy specification environment for a +particular application domain. For example, policy types for specifying +SLAs could be expressed in a SLA DSL and policy types for managing SON +features could be generated from a visual SON management tool. The ONAP +Policy framework provides an API that allows tool chains to create +policy types. SDC uses this approach for generating Policy Types in the +Policy Framework, see the `Model driven Control Loop +Design <file://localhost/display/DW/Model+driven+Control+Loop+Design>`__ +page. + +The SDC GUI supports several types of policies that can be captured at +design time. DCAE micro service configuration policies can be onboarded +via the DCAE-DS (DCAE Design Studio). + +The GUI implementation in another ONAP component such as SDC DCAE-DS +uses the *API_User* API to create and edit ONAP policy types. + +2.2.1.2 Programming Policy Type Implementations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For skilled developers, the most straightforward way to create a policy +type is to program it. Programming a policy type might simply mean +creating and editing text files, thus manually creating the TOSCA Policy +Type Yaml file and the policy type implementation for the policy type. + +A more formal approach is preferred. For policy type implementations, +programmers use a specific Eclipse project type for developing each type +of implementation, a Policy Type Implementation SDK. The project is +under source control in git. This Eclipse project is structured +correctly for creating implementations for a specific type of PDP. It +includes the correct POM files for generating the policy type +implementation and has editors and perspectives that aid programmers in +their work + +2.2.2 Policy Design +~~~~~~~~~~~~~~~~~~~ + +The *PolicyCreation* function of *PolicyDevelopment* creates policies +from a policy type. The information expressed during policy type design +is used to parameterize a policy type to create an executable policy. A +service designer and/or operations team can use tooling that reads the +TOSCA Policy Type specifications to express and capture a policy at its +highest abstraction level. Alternatively, the parameter for the policy +can be expressed in a raw JSON or YAML file and posted over the policy +design API described on the `Model driven Control Loop +Design <file://localhost/display/DW/Model+driven+Control+Loop+Design>`__ +page. + +A number of mechanisms for policy creation are supported in ONAP. The +process in *PolicyDevelopment* for creating a policy is the same for all +mechanisms. The most general mechanism for creating a policy is using +the RESTful *Policy Design API*, which provides a full interface to the +policy creation support of *PolicyDevelopment*. This API may be +exercised directly using utilities such as *curl*. \ *PolicyDevelopment* +provides a command line tool that is a loose wrapper around the API. It +also provides a general purpose Policy GUI in the ONAP Portal for policy +creation, which again is a general purpose wrapper around the policy +creation API. The Policy GUI can interpret any TOSCA Model ingested and +flexibly presents a GUI for a user to create policies from. The +development of these mechanisms will be phased over a number of ONAP +releases. + +A number of ONAP components use policy in manners which are specific to +their particular needs. The manner in which the policy creation process +is triggered and the way in which information required to create a +policy is specified and accessed is specialized for these ONAP +components. + +The following subsections outline the mechanisms for policy creation and +modification supported by the ONAP Policy Framework. + +2.2.2.1 Policy Design in the ONAP Policy Framework +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Policy creation in *PolicyDevelopment* follows the general sequence +shown in the sequence diagram below. An *API_USER* is any component that +wants to create a policy from a policy type. *PolicyDevelopment* +supplies a REST interface that exposes the API and also provides a +command line tool and general purpose client that wraps the API. + +A *PolicyDevAPIUser* first gets a reference to and the metadata for the +Policy type for the policy they want to work on from +*PolicyDevelopment*. \ *PolicyDevelopment* reads the metadata and +artifact for the policy type from the database. The *API_User* then asks +for a reference and the metadata for the policy. \ *PolicyDevelopment* +looks up the policy in the database. If the policy already +exists, \ *PolicyDevelopment* reads the artifact and returns the +reference of the existing policy to the \ *PolicyDevAPIUser* with the +metadata for the existing policy. If the policy does not +exist, \ *PolicyDevelopment* creates and new reference and metadata and +returns that to the \ *API_User*. + +The \ *PolicyDevAPIUser* may now proceed with a policy specification +session, where the parameters are set for the policy using the policy +type specification. Once the \ *PolicyDevAPIUser* is happy that the +policy is completely and correctly specified, it +requests \ *PolicyDevelopment* to create the +policy. \ *PolicyDevelopment* creates the policy, stores the created +policy artifact and its metadata in the database. + +2.2.2.2 Model Driven VF (Virtual Function) Policy Design via VNF SDK Packaging +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +VF vendors express policies such as SLA, Licenses, hardware placement, +run-time metric suggestions, etc. These details are captured within the +VNF SDK and uploaded into the SDC Catalog. The `SDC Distribution +APIs <file://localhost/display/DW/SDC+API>`__ are used to interact with +SDC. For example, SLA and placement policies may be captured via TOSCA +specification. License policies can be captured via TOSCA or an XACML +specification. Run-time metric vendor recommendations can be captured +via VES Standard specification. + +The sequence diagram below is a high level view of SDC-triggered +concrete policy generation for some arbitrary entity *EntityA*. The +parameters to create a policy are read from a TOSCA Policy specification +read from a CSAR received from SDC. + +*PolicyDesign* uses the *PolicyDistribution* component for managing +SDC-triggered policy creation and update requests. *PolicyDistribution* +is an *API_User*, it uses the Policy Design API for policy creation and +update. It reads the information it needs to populate the policy type +from a TOSCA specification in a CSAR received from SDC and then uses +this information to automatically generate a policy. + +Note that SDC provides a wrapper for the SDC API as a Java Client and +also provides a TOSCA parser. See `Policy Platform - SDC Service +Distribution Software +Architecture <file://localhost/display/DW/Policy+Platform+-+SDC+Service+Distribution+Software+Architecture>`__ + +In Step 4 above, the \ *PolicyDesign* must download the CSAR file. If +the policy is to be composed from the TOSCA definition, it must also +parse the TOSCA definition. + +In Step 9 above, the \ *PolicyDesign* must send back/publish status +events to SDC such as DOWNLOAD_OK, DOWNLOAD_ERROR, DEPLOY_OK, +DEPLOY_ERROR, NOTIFIED. + +2.2.2.4 Scripted Model Driven Policy Design +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Service policies such as optimization and placement policies can be +specified as a TOSCA Policy at design time. These policies use a TOSCA +Policy Type specification as their schemas. Therefore, scripts can be +used to create TOSCA policies using TOSCA Policy Types. + +One straightforward way of generating policies from Policy types is to +use directives specified in a script file. The command line utility is +an *API_User*. The script reads directives from a file. For each +directive, it reads the policy type using the Policy Type API, and uses +the parameters of the directive to create a TOSCA Policy. It then uses +the Policy API to create the policy. + +2.2.3 Policy Design Process +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +All policy types must be certified as being fit for deployment prior to +run time deployment. In the case of design-time via the SDC application, +it is assumed the lifecycle being implemented by SDC will suffice for +any policy types that are declared within the ONAP Service CSAR. For +other policy types and policy type implementations, the lifecycle +associated with software development process will suffice. Since policy +types and their implementations will be designed and implemented using +software development best practices, they can be utilized and configured +for various environments (eg. development, testing, production) as +desired. + +2.3 Policy Runtime Architecture +------------------------------- + +The Policy Framework Platform components are themselves designed as +micro services that are easy to configure and deploy via Docker images +and K8S both supporting resiliency and scalability if required. PAPs and +PDPs are deployed by the underlying ONAP management infrastructure and +are designed to comply with the ONAP interfaces for deploying +containers. + +The PAPs keep track of PDPs, support the deployment of PDP groups and +the deployment of a policy set across those PDP groups. A PAP is +stateless in a RESTful sense. Therefore, if there is more than one PAP +deployed, it does not matter which PAP a user contacts to handle a +request. The PAP uses the database (persistent storage) to keep track of +ongoing sessions with clients. Policy management on PDPs is the +responsibility of PAPs; management of policy sets or policies by any +other manner is not permitted. + +In the ONAP Policy Framework, the interfaces to the PDP are designed to +be as streamlined as possible. Because the PDP is the main unit of +scalability in the Policy Framework, the PF is designed to allow PDPs in +a PDP group to arbitrarily appear and disappear and for policy +consistency across all PDPs in a PDP group to be easily maintained. +Therefore, PDPs have just two interfaces; an interface that users can +use to execute policies and interface to the PAP for administration, +life cycle management and monitoring. The PAP is responsible for +controlling the state across the PDPs in a PDP group. The PAP interacts +with the Policy database and transfers policy sets to PDPs, and may +cache the policy sets for PDP groups. + +See also Sectino 2 of the `Policy Design and API Flow for Model Driven +Control +Loop <file://localhost/display/DW/Policy+Design+and+API+Flow+for+Model+Driven+Control+Loop>`__ +page, where the mechanisms for PDP Deployment and Registration with PAP +are explained. + +2.3.1 Policy Framework Services +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ONAP Policy Framework follows the architectural approach for micro +services recommended by the `ONAP Architecture +Subcommittee <https://wiki.onap.org/display/DW/Architecture+Subcommittee>`__. + +The ONAP Policy Framework defines `Kubernetes +Services <https://kubernetes.io/docs/concepts/services-networking/service/>`__ +to manage the life cycle of Policy Framework executable components at +runtime. A Kubernetes service allows, among other parameters, the +number of instances (pods in Kubernetes terminology) that should be +deployed for a particular service to be specified and a common endpoint +for that service to be defined. Once the service is started in +Kubernetes, Kubernetes ensures that the specified number of instances is +always kept running. As requests are received on the common endpoint, +they are distributed across the service instances. More complex call +distribution and instance deployment strategies may be used; please see +the `Kubernetes +Services <https://kubernetes.io/docs/concepts/services-networking/service/>`__ +documentation for those details. + +If, for example, a service called *policy-pdpd-control-loop* is defined +that runs 5 PDP-D instances. The service has the end point +*https://policy-pdpd-control-loop.onap/<service-specific-path>*. When +the service is started, Kubernetes spins up 5 PDP-Ds. Calls to the end +point *https://policy-pdpd-control-loop.onap/<service-specific-path>* +are distributed across the 5 PDP-D instances. Note that the *.onap* part +of the service endpoint is the namespace being used and is specified for +the full ONAP Kubernetes installation. + +The following services will be required for the ONAP Policy Framework: + +================ ============================== =============================================================================================================================================================================================================================================================== +**Service** **Endpoint** **Description** +================ ============================== =============================================================================================================================================================================================================================================================== +PAP https://policy-pap The PAP service, used for policy administration and deployment. See `Policy Design and API Flow for Model Driven Control Loop <file://localhost/display/DW/Policy+Design+and+API+Flow+for+Model+Driven+Control+Loop>`__ for details of the API for this service +PDP-X-\ *domain* https://policy-pdpx-\ *domain* A PDP service is defined for each PDP group. A PDP group is identified by the domain on which it operates. + + For example, there could be two PDP-X domains, one for admission policies for ONAP proper and another for admission policies for VNFs of operator *Supacom*. Two PDP-X services are defined: + + | https://policy-pdpx-onap + | https://policy-pdpx-\ *supacom* +PDP-D-\ *domain* https://policy-pdpd-\ *domain* +PDP-A-\ *domain* https://policy-pdpa-\ *domain* +================ ============================== =============================================================================================================================================================================================================================================================== + +There is one and only one PAP service, which handles policy deployment, +administration, and monitoring for all policies in all PDPs and PDP +groups in the system. There are multiple PDP services, one PDP service +for each domain for which there are policies. + +2.3.2 The Policy Framework Information Structure +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following diagram captures the relationship between Policy Framework +concepts at run time. + +There is a one to one relationship between a PDP SubGroup, a Kubernetes +PDP service, and the set of policies assigned to run in the PDP +subgroup. Each PDP service runs a single PDP subgroup with multiple +PDPs, which executes a specific Policy Set containing a number of +policies that have been assigned to that PDP subgroup. Having and +maintaining this principle makes policy deployment and administration +much more straightforward than it would be if complex relationships +between PDP services, PDP subgroups, and policy sets. + +The topology of the PDPs and their policy sets is held in the Policy +Framework database and is administered by the PAP service. + +The diagram above gives an indicative structure of the run time topology +information in the Policy Framework database. Note that +the \ *PDP_SUBGROUP_STATE* and \ *PDP_STATE* fields hold state +information for life cycle management of PDP groups and PDPs. + +2.3.3 Startup, Shutdown and Restart +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This section describes the interactions between Policy Framework +components themselves and with other ONAP components at startup, +shutdown and restart. + +2.3.3.1 PAP Startup and Shutdown +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The sequence diagram below shows the actions of the PAP at startup. + +The PAP is the run time point of coordination for the ONAP Policy +Framework. When it is started, it initializes itself using data from the +database. It then waits for periodic PDP status updates and for +administration requests. + +PAP shutdown is trivial. On receipt or a shutdown request, the PAP +completes or aborts any ongoing operations and shuts down gracefully. + +2.3.3.2 PDP Startup and Shutdown +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The sequence diagram below shows the actions of the PDP at startup. See +also Section 4 of the `Policy Design and API Flow for Model Driven +Control +Loop <file://localhost/display/DW/Policy+Design+and+API+Flow+for+Model+Driven+Control+Loop>`__ +page for the API used to implement this sequence. + +At startup, the PDP initializes itself. At this point it is in PASSIVE +mode. The PDP begins sending periodic Status messages to the PAP. + +The first Status message initializes the process of loading the correct +Policy Set on the PDP in the PAP. + +On receipt or a shutdown request, the PDP completes or aborts any +ongoing policy executions and shuts down gracefully. + +2.3.4 Policy Execution +~~~~~~~~~~~~~~~~~~~~~~ + +Policy execution is the execution of a policy in a PDP. Policy +enforcement occurs in the component that receives a policy decision. + +Policy execution can be *synchronous* or *asynchronous*. In +*synchronous* policy execution, the component requesting a policy +decision requests a policy decision and waits for the result. The PDP-X +and PDP-A use synchronous policy execution. In *asynchronous* policy +execution, the component that requests a policy decision does not wait +for the decision. Indeed, the decision may be passed to another +component. The PDP-D and PDP-A use asynchronous policy execution. + +Policy execution is carried out using the current life cycle mode of +operation of the PDP. While the actual implementation of the mode may +vary somewhat between PDPs of different types, the principles below hold +true for all PDP types: + +================== =========================================================================================================================================================================================================================================================================================================================== +**Lifecycle Mode** **Behaviour** +================== =========================================================================================================================================================================================================================================================================================================================== +PASSIVE MODE Policy execution is always rejected irrespective of PDP type. +ACTIVE MODE Policy execution is executed in the live environment by the PDP. +SAFE MODE Policy execution proceeds, but changes to domain state or context are not carried out. The PDP returns an indication that it is running in SAFE mode together with the action it would have performed if it was operating in ACTIVE mode. The PDP type and the policy types it is running must support SAFE mode operation. +TEST MODE Policy execution proceeds and changes to domain and state are carried out in a test or sandbox environment. The PDP returns an indication it is running in TEST mode together with the action it has performed on the test environment. The PDP type and the policy types it is running must support TEST mode operation. +================== =========================================================================================================================================================================================================================================================================================================================== + +2.3.5 Policy Lifecycle Management +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Policy lifecycle management manages the deployment and life cycle of +policies in PDP groups at run time. Policy sets can be deploy at run +time without restarting PDPs or stopping policy execution. PDPs preserve +state for minor/patch version upgrades and rollbacks. + +2.3.5.1 Load/Update Policies on PDP +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The sequence diagram below shows how policies are loaded or updated on a +PDP. + +This sequence can be initiated in two ways; from the PDP or from a user +action. + +1. A PDP sends regular status update messages to the PAP. If this + message indicates that the PDP has no policies or outdated policies + loaded, then this sequence is initiated + +2. A user may explicitly trigger this sequence to load policies on a PDP + +The PAP controls the entire process. The PAP reads the current PDP +metadata and the required policy and policy set artifacts from the +database. It then builds the policy set for the PDP. Once the policies +are ready, the PAP sets the mode of the PDP to PASSIVE. The Policy Set +is transparently passed to the PDP by the PAP. The PDP loads all the +policies in the policy set including any models, rules, tasks, or flows +in the policy set in the policy implementations. + +Once the Policy Set is loaded, the PAP orders the PDP to enter the life +cycle mode that has been specified for it (ACTIVE/SAFE/TEST). The PDP +beings to execute policies in the specified mode (see section 2.3.4). + +2.3.5.2 Policy Rollout +^^^^^^^^^^^^^^^^^^^^^^ + +A policy set steps through a number of life cycle modes when it is +rolled out. + +The user defines the set of policies for a PDP group. It is deployed to +a PDP group and is initially in PASSIVE mode. The user sets the PDP +Group into TEST mode. The policies are run in a test or sandboxed +environment for a period of time. The test results are passed back to +the user. The user may revert the policy set to PASSIVE mode a number of +times and upgrade the policy set during test operation. + +When the user is satisfied with policy set execution and when quality +criteria have been reached for the policy set, the PDP group is set to +run in SAFE mode. In this mode, the policies run on the actual target +environment but do not actually exercise any actions or change any +context in the target environment. Again, as in TEST mode, the operator +may decide to revert back to TEST mode or even PASSIVE mode if issues +arise with a policy set. + +Finally, when the user is satisfied with policy set execution and when +quality criteria have been reached, the PDP group is set into ACTIVE +state and the policy set executes on the target environment. The results +of target operation are reported. The PDP group can be reverted to SAFE, +TEST, or even PASSIVE mode at any time if problems arise. + +2.3.5.3 Policy Upgrade and Rollback +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +There are a number of approaches for managing policy upgrade and +rollback. + +The most straightforward approach is to use the approach described in +section 2.2.5.2 for upgrading and rolling back policy sets. In order to +upgrade a policy set, one follows the process in 2.2.5.2 with the new +policy set version. For rollback, one follows the process in section +2.2.5.2 with the older policy set, most probably setting the old policy +set into ACTIVE mode immediately. The advantage of this approach is that +the approach is straightforward. The obvious disadvantage is that the +PDP group is not executing on the target environment while the new +policy set is in PASSIVE, TEST, and SAFE mode. + +A second manner to tackle upgrade and rollback is to use a spare-wheel +approach. An special upgrade PDP group service is set up as a K8S +service in parallel with the active one during the upgrade procedure. +The spare wheel service is used to execute the process described in +section 2.2.5.2. When the time comes to activate the policy set, the +references for the active and spare wheel services are simply swapped. +The advantage of this approach is that the down time during upgrade is +minimized, the spare wheel PDP group can be abandoned at any time +without affecting the in service PDP group, and the upgrade can be +rolled back easily for a period simply by preserving the old service for +a time. The disadvantage is that this approach is more complex than the +first approach. + +A third approach is to have two policy sets running in each PDP, an +active set and a standby set. However such an approach would increase +the complexity of implementation in PDPs significantly. + +2.3.6 Policy Monitoring +~~~~~~~~~~~~~~~~~~~~~~~ + +PDPs provide a periodic report of their status to the PAP. All PDPs +report using a standard reporting format that is extended to provide +information for specific PDP types. PDPs provide at least the +information below: + +===================== =============================================================================== +**Field** **Description** +===================== =============================================================================== +State Lifecycle State (PASSIVE/TEST/SAFE/ACTIVE) +Timestamp Time the report record was generated +InvocationCount The number of execution invocations the PDP has processed since the last report +LastInvocationTime The time taken to process the last execution invocation +AverageInvocationTime The average time taken to process an invocation since the last report +StartTime The start time of the PDP +UpTime The length of time the PDP has been executing +RealTimeInfo Real time information on running policies. +===================== =============================================================================== + +2.3.7 PEP Registration and Enforcement Guidelines +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In ONAP there are several applications outside the Policy Framework that +enforce policy decisions based on models provided to the Policy +Framework. These applications are considered Policy Enforcement Engines +(PEP) and roles will be provided to those applications using AAF/CADI to +ensure only those applications can make calls to the Policy Decision +API's. Some example PEP's are: DCAE, OOF, and SDNC. + +See Section 3.4 of the `Policy Design and API Flow for Model Driven +Control +Loop <file://localhost/display/DW/Policy+Design+and+API+Flow+for+Model+Driven+Control+Loop>`__ +for more information on the Decision APIs. + +3. APIs Provided by the Policy Framework +======================================== + +See the `Policy Design and API Flow for Model Driven Control +Loop <file://localhost/display/DW/Policy+Design+and+API+Flow+for+Model+Driven+Control+Loop>`__ +page. + +4. Terminology +============== + +================================= ========================================================================================================================================================= +PAP (Policy Administration Point) A component that administers and manages policies +================================= ========================================================================================================================================================= +PDP (Policy Deployment Point) A component that executes a policy artifact (One or many?) +PDP_<> A specific type of PDP +PDP Group A group of PDPs that execute the same set of policies +Policy Development The development environment for policies +Policy Type A generic prototype definition of a type of policy in TOSCA, see the `TOSCA Policy Primer <file://localhost/display/DW/TOSCA+Policy+Primer>`__ +Policy An executable policy defined in TOSCA and created using a Policy Type, see the `TOSCA Policy Primer <file://localhost/display/DW/TOSCA+Policy+Primer>`__ +Policy Set A set of policies that are deployed on a PDP group. One and only one Policy Set is deployed on a PDP group +================================= ========================================================================================================================================================= + + +End of Document diff --git a/docs/architecture/detailed.png b/docs/architecture/detailed.png Binary files differnew file mode 100644 index 00000000..9ac8cf30 --- /dev/null +++ b/docs/architecture/detailed.png diff --git a/docs/architecture/execution.png b/docs/architecture/execution.png Binary files differnew file mode 100644 index 00000000..4e564856 --- /dev/null +++ b/docs/architecture/execution.png diff --git a/docs/architecture/highest.png b/docs/architecture/highest.png Binary files differnew file mode 100644 index 00000000..bfe07ae8 --- /dev/null +++ b/docs/architecture/highest.png diff --git a/docs/architecture/objectmodel1.png b/docs/architecture/objectmodel1.png Binary files differnew file mode 100644 index 00000000..ef3c7d12 --- /dev/null +++ b/docs/architecture/objectmodel1.png diff --git a/docs/architecture/objectmodel2.png b/docs/architecture/objectmodel2.png Binary files differnew file mode 100644 index 00000000..44f79746 --- /dev/null +++ b/docs/architecture/objectmodel2.png diff --git a/docs/design/design.png b/docs/design/design.png Binary files differnew file mode 100644 index 00000000..e36c1b2c --- /dev/null +++ b/docs/design/design.png diff --git a/docs/design/design.rst b/docs/design/design.rst new file mode 100644 index 00000000..ad91834a --- /dev/null +++ b/docs/design/design.rst @@ -0,0 +1,124 @@ +.. This work is licensed under a +.. Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +.. _design-label: + +Policy Design and Development +----------------------------- + +.. contents:: + :depth: 3 + +The figure below shows the Artifacts (Blue) in the ONAP Policy +Framework, the Activities (Yellow) that manipulate them, and important +components (Pink) that interact with them. + +.. image:: design.png + +Please see the `TOSCA Policy +Primer <tosca-label>`__ page for an +introduction to TOSCA policy concepts. + +TOSCA defines a *PolicyType*, the definition of a type of policy that +can be applied to a service. It also defines a *Policy*, the definition +of an instance of a *PolicyType*. In the Policy Framework, we must +handle and manage these TOSCA definitions and tie them to real +implementations of policies that can run on PDPs. + +The diagram above outlines how this is achieved. Each TOSCA *PolicyType* +must have a corresponding *PolicyTypeImpl* in the Policy Framework. The +TOSCA \ *PolicyType* definition can be used to create a TOSCA *Policy* +definition, either directly by the Policy Framework, by CLAMP, or by +some other system. Once the \ *Policy* artifact exists, it can be used +together with the *PolicyTypeImpl* artifact to create a *PolicyImpl* +artifact. A *PolicyImpl* artifact is an executable policy implementation +that can run on a PDP. + +The TOSCA *PolicyType* artifact defines the external characteristics of +the policy; defining its properties, the types of entities it acts on, +and its triggers. A *PolicyTypeImpl* artifact is an XACML, Drools, or +APEX implementation of that policy definition. *PolicyType* and +*PolicyTypeImpl* artifacts may be preloaded, may be loaded manually, or +may be created using the Lifecycle API. Alternatively, *PolicyType* +definitions may be loaded over the Lifecycle API for preloaded +*PolicyTypeImpl* artifacts. A TOSCA *PolicyType* artifact can be used by +clients (such as CLAMP or CLI tools) to create, parse, serialize, and/or +deserialize an actual Policy. + +The TOSCA *Policy* artifact is used internally by the Policy Framework, +or is input by CLAMP or other systems. This artifact specifies the +values of the properties for the policy and specifies the specific +entities the policy acts on. Policy Design uses the TOSCA *Policy* +artifact and the *PolicyTypeImpl* artifact to create an executable +*PolicyImpl* artifact. + +1 ONAP Policy Types +=================== + +Policy Type Design manages TOSCA *PolicyType* artifacts and their +*PolicyTypeImpl* implementations\ *.* + +*TOSCA PolicyType* may ultimately be defined by the modeling team but +for now are defined by the Policy Framework project. Various editors and +GUIs are available for creating *PolicyTypeImpl* implementations. +However, systematic integration of *PolicyTypeImpl* implementation is +outside the scope of the ONAP Dublin release. + +The \ *PolicyType* definitions and implementations listed below are +preloaded and are always available for use in the Policy Framework. + +====================================== ================================================================================================== +**Policy Type** **Description** +====================================== ================================================================================================== +onap.policies.Monitoring Overarching model that supports Policy driven DCAE microservice components used in a Control Loops +onap.policies.controlloop.Operational Used to support actor/action operational policies for control loops +onap.policies.controlloop.Guard Control Loop guard policies for policing control loops +onap.policies.controlloop.Coordination Control Loop Coordination policies to assist in coordinating multiple control loops at runtime +====================================== ================================================================================================== + +1.1 onap.policies.Monitoring Policy Type +---------------------------------------- + +This is a base Policy Type that supports Policy driven DCAE microservice +components used in a Control Loops. The implementation of this Policy +Type is developed using the XACML PDP to support question/answer Policy +Decisions during runtime for the DCAE Policy Handler. + +**Base Policy Type definition for onap.policies.Monitoring** + +.. codeblock:: yaml + + tosca_definitions_version: tosca_simple_yaml_1_0_0 + topology_template: + policy_types: + - onap.policies.Monitoring: + derived_from: tosca.policies.Root + version: 1.0.0 + description: a base policy type for all policies that govern monitoring provision + +The \ *PolicyTypeImpl* implementation of the *onap.policies.Montoring* +Policy Type is generic to support definition of TOSCA *PolicyType* +artifacts in the Policy Framework using the Policy Type Design API. +Therefore many TOSCA *PolicyType* artifacts will use the same +*PolicyTypeImpl* implementation with different property types and +towards different targets. This allows dynamically generated DCAE +microservice component Policy Types to be created at Design Time. + +DCAE microservice components can generate their own TOSCA \ *PolicyType* +using TOSCA-Lab Control Loop guard policies in SDC (Stretch Goal) or can +do so manually. See `How to generate artefacts for SDC catalog using +Tosca Lab +Tool <file://localhost/display/DW/How+to+generate+artefacts+for+SDC+catalog+using+Tosca+Lab+Tool>`__ +for details on TOSCA-LAB in SDC. For Dublin, the DCAE team is defining +the manual steps required to build policy models \ `Onboarding steps for +DCAE MS through SDC/Policy/CLAMP +(Dublin) <file://localhost/pages/viewpage.action%3fpageId=60883710>`__. + +NOTE: For Dublin, mS Policy Types will be pre-loaded into the SDC +platform and be available as a Normative. The policy framework will +pre-load support for those mS Monitoring policy types. + + +End of Document + diff --git a/docs/design/foo.rst b/docs/design/foo.rst new file mode 100644 index 00000000..e0d461be --- /dev/null +++ b/docs/design/foo.rst @@ -0,0 +1,4898 @@ +.. contents:: + :depth: 3 +.. + +Policy Design and API Flow for Model Driven Control Loop +======================================================== + +This page shows how the Policy Design and API Flow to/from the PAP and +PDPs works to support Model Driven Control Loops in Dublin. + +- `1 Policy Types <#PolicyDesignandAPIFlowforModelDrivenCon>`__ + + - `1.1 onap.policies.Monitoring Policy + Type <#PolicyDesignandAPIFlowforModelDrivenCon>`__ + + - `1.2 onap.policies.controlloop.Operational Policy + Type <#PolicyDesignandAPIFlowforModelDrivenCon>`__ + + - `1.2.1 Operational Policy Type Schema for + Drools <#PolicyDesignandAPIFlowforModelDrivenCon>`__ + + - `1.2.3 Operational Policy Type Schema for APEX (El Alto + proposal) <#PolicyDesignandAPIFlowforModelDrivenCon>`__ + + - `1.3 onap.policies.controlloop.Guard Policy + Type <#PolicyDesignandAPIFlowforModelDrivenCon>`__ + + - `1.3.1 onap.policies.controlloop.guard.FrequencyLimiter Policy + Type <#PolicyDesignandAPIFlowforModelDrivenCon>`__ + + - `1.3.2 onap.policies.controlloop.guard.Blacklist Policy + Type <#PolicyDesignandAPIFlowforModelDrivenCon>`__ + + - `1.3.3 onap.policies.controlloop.guard.MinMax Policy + Type <#PolicyDesignandAPIFlowforModelDrivenCon>`__ + + - `1.3.4 onap.policies.controlloop.Coordination Policy Type + (STRETCH) <#PolicyDesignandAPIFlowforModelDrivenCon>`__ + +- `2 PDP Deployment and Registration with + PAP <#PolicyDesignandAPIFlowforModelDrivenCon>`__ + +- `3. Public APIs <#PolicyDesignandAPIFlowforModelDrivenCon>`__ + + - `3.1 Policy Type Design API for TOSCA Policy + Types <#PolicyDesignandAPIFlowforModelDrivenCon>`__ + + - `3.1.1 Policy Type + query <#PolicyDesignandAPIFlowforModelDrivenCon>`__ + + - `3.1.2 Policy Type + Create/Update <#PolicyDesignandAPIFlowforModelDrivenCon>`__ + + - `3.1.3 Policy Type + Delete <#PolicyDesignandAPIFlowforModelDrivenCon>`__ + + - `3.2 Policy Design + API <#PolicyDesignandAPIFlowforModelDrivenCon>`__ + + - `3.2.1 Policy + query <#PolicyDesignandAPIFlowforModelDrivenCon>`__ + + - `3.2.2 Policy + Create/Update <#PolicyDesignandAPIFlowforModelDrivenCon>`__ + + - `3.2.2.1 Monitoring Policy + Create/Update <#PolicyDesignandAPIFlowforModelDrivenCon>`__ + + - `3.2.2.2.1 Drools Operational Policy + Create/Update <#PolicyDesignandAPIFlowforModelDrivenCon>`__ + + - `3.2.2.2.2 APEX Operational Policy + Create/Update <#PolicyDesignandAPIFlowforModelDrivenCon>`__ + + - `3.2.2.3 Guard Policy + Create/Update <#PolicyDesignandAPIFlowforModelDrivenCon>`__ + + - `3.2.2.4 Policy Lifecycle API - Creating Coordination + Policies <#PolicyDesignandAPIFlowforModelDrivenCon>`__ + + - `3.2.3 Policy + Delete <#PolicyDesignandAPIFlowforModelDrivenCon>`__ + + - `3.3 Policy Administration + API <#PolicyDesignandAPIFlowforModelDrivenCon>`__ + + - `3.3.1 PDP Group + Query <#PolicyDesignandAPIFlowforModelDrivenCon>`__ + + - `3.3.2 PDP Group + Deployment <#PolicyDesignandAPIFlowforModelDrivenCon>`__ + + - `Simple API for CLAMP to deploy one or more policy-id's with + optional + policy-version. <#PolicyDesignandAPIFlowforModelDrivenCon>`__ + + - `Simple API for CLAMP to undeploy a policy-id with optional + policy-version. <#PolicyDesignandAPIFlowforModelDrivenCon>`__ + + - `3.3.3 PDP Group + Delete <#PolicyDesignandAPIFlowforModelDrivenCon>`__ + + - `3.3.4 PDP Group State + Management <#PolicyDesignandAPIFlowforModelDrivenCon>`__ + + - `3.3.5 PDP Group + Statistics <#PolicyDesignandAPIFlowforModelDrivenCon>`__ + + - `3.3.6 PDP Group Health + Check <#PolicyDesignandAPIFlowforModelDrivenCon>`__ + + - `3.4 Policy Decision API - Getting Policy + Decisions <#PolicyDesignandAPIFlowforModelDrivenCon>`__ + + - `3.4.1 Decision API + Schema <#PolicyDesignandAPIFlowforModelDrivenCon>`__ + + - `3.4.2 Decision API + Queries <#PolicyDesignandAPIFlowforModelDrivenCon>`__ + +- `4. Policy Framework Internal + APIs <#PolicyDesignandAPIFlowforModelDrivenCon>`__ + + - `4.1 PAP to PDP API <#PolicyDesignandAPIFlowforModelDrivenCon>`__ + + - `4.1.1 PAP API for + PDPs <#PolicyDesignandAPIFlowforModelDrivenCon>`__ + + - `4.1.2 PDP API for + PAPs <#PolicyDesignandAPIFlowforModelDrivenCon>`__ + + - `4.1.2.1 PDP + Update <#PolicyDesignandAPIFlowforModelDrivenCon>`__ + + - `4.1.2.2 PDP State + Change <#PolicyDesignandAPIFlowforModelDrivenCon>`__ + + - `4.1.2.3 PDP Health + Check <#PolicyDesignandAPIFlowforModelDrivenCon>`__ + + - `4.2 Policy Type Implementations (Native + Policies) <#PolicyDesignandAPIFlowforModelDrivenCon>`__ + + - `4.2.1 Policy Type Implementation + Query <#PolicyDesignandAPIFlowforModelDrivenCon>`__ + + - `4.2.2 Policy Type Implementation + Create/Update <#PolicyDesignandAPIFlowforModelDrivenCon>`__ + + - `4.2.3 Policy Type Implementation + Delete <#PolicyDesignandAPIFlowforModelDrivenCon>`__ + +The figure below shows the Artifacts (Blue) in the ONAP Policy +Framework, the Activities (Yellow) that manipulate them, and important +components (Pink) that interact with them. + +Please see the :ref:`TOSCA Policy +Primer <tosca-policy>`__ page for an +introduction to TOSCA policy concepts. + +TOSCA defines a *PolicyType*, the definition of a type of policy that +can be applied to a service. It also defines a *Policy*, the definition +of an instance of a *PolicyType*. In the Policy Framework, we must +handle and manage these TOSCA definitions and tie them to real +implementations of policies that can run on PDPs. + +The diagram above outlines how this is achieved. Each TOSCA *PolicyType* +must have a corresponding *PolicyTypeImpl* in the Policy Framework. The +TOSCA \ *PolicyType* definition can be used to create a TOSCA *Policy* +definition, either directly by the Policy Framework, by CLAMP, or by +some other system. Once the \ *Policy* artifact exists, it can be used +together with the *PolicyTypeImpl* artifact to create a *PolicyImpl* +artifact. A *PolicyImpl* artifact is an executable policy implementation +that can run on a PDP. + +The TOSCA *PolicyType* artifact defines the external characteristics of +the policy; defining its properties, the types of entities it acts on, +and its triggers. A *PolicyTypeImpl* artifact is an XACML, Drools, or +APEX implementation of that policy definition. *PolicyType* and +*PolicyTypeImpl* artifacts may be preloaded, may be loaded manually, or +may be created using the Lifecycle API. Alternatively, *PolicyType* +definitions may be loaded over the Lifecycle API for preloaded +*PolicyTypeImpl* artifacts. A TOSCA *PolicyType* artifact can be used by +clients (such as CLAMP or CLI tools) to create, parse, serialize, and/or +deserialize an actual Policy. + +The TOSCA *Policy* artifact is used internally by the Policy Framework, +or is input by CLAMP or other systems. This artifact specifies the +values of the properties for the policy and specifies the specific +entities the policy acts on. Policy Design uses the TOSCA *Policy* +artifact and the *PolicyTypeImpl* artifact to create an executable +*PolicyImpl* artifact. + +1 Policy Types +============== + +Policy Type Design manages TOSCA *PolicyType* artifacts and their +*PolicyTypeImpl* implementations\ *.* + +*TOSCA PolicyType* may ultimately be defined by the modeling team but +for now are defined by the Policy Framework project. Various editors and +GUIs are available for creating *PolicyTypeImpl* implementations. +However, systematic integration of *PolicyTypeImpl* implementation is +outside the scope of the ONAP Dublin release. + +The \ *PolicyType* definitions and implementations listed below are +preloaded and are always available for use in the Policy Framework. + +====================================== ================================================================================================== +**Policy Type** **Description** +====================================== ================================================================================================== +onap.policies.Monitoring Overarching model that supports Policy driven DCAE microservice components used in a Control Loops +onap.policies.controlloop.Operational Used to support actor/action operational policies for control loops +onap.policies.controlloop.Guard Control Loop guard policies for policing control loops +onap.policies.controlloop.Coordination Control Loop Coordination policies to assist in coordinating multiple control loops at runtime +====================================== ================================================================================================== + +1.1 onap.policies.Monitoring Policy Type +---------------------------------------- + +This is a base Policy Type that supports Policy driven DCAE microservice +components used in a Control Loops. The implementation of this Policy +Type is developed using the XACML PDP to support question/answer Policy +Decisions during runtime for the DCAE Policy Handler. + +**Base Policy Type definition for onap.policies.Monitoring** + +.. codeblock:: yaml + + tosca_definitions_version: tosca_simple_yaml_1_0_0 + topology_template: + policy_types: + - onap.policies.Monitoring: + derived_from: tosca.policies.Root + version: 1.0.0 + description: a base policy type for all policies that govern monitoring provision + +The \ *PolicyTypeImpl* implementation of the *onap.policies.Montoring* +Policy Type is generic to support definition of TOSCA *PolicyType* +artifacts in the Policy Framework using the Policy Type Design API. +Therefore many TOSCA *PolicyType* artifacts will use the same +*PolicyTypeImpl* implementation with different property types and +towards different targets. This allows dynamically generated DCAE +microservice component Policy Types to be created at Design Time. + +DCAE microservice components can generate their own TOSCA \ *PolicyType* +using TOSCA-Lab Control Loop guard policies in SDC (Stretch Goal) or can +do so manually. See `How to generate artefacts for SDC catalog using +Tosca Lab +Tool <file://localhost/display/DW/How+to+generate+artefacts+for+SDC+catalog+using+Tosca+Lab+Tool>`__ +for details on TOSCA-LAB in SDC. For Dublin, the DCAE team is defining +the manual steps required to build policy models \ `Onboarding steps for +DCAE MS through SDC/Policy/CLAMP +(Dublin) <file://localhost/pages/viewpage.action%3fpageId=60883710>`__. + +NOTE: For Dublin, mS Policy Types will be pre-loaded into the SDC +platform and be available as a Normative. The policy framework will +pre-load support for those mS Monitoring policy types. + +**PolicyType onap.policies.monitoring.MyDCAEComponent derived from +onap.policies.Monitoring** Expand source + +tosca_definitions_version: tosca_simple_yaml_1_0_0 + +policy_types: + +- onap.policies.Monitoring: + +derived_from: tosca.policies.Root + +version: 1.0.0 + +description: a base policy type for all policies that govern monitoring +provision + +- onap.policies.monitoring.MyDCAEComponent: + +derived_from: onap.policies.Monitoring + +version: 1.0.0 + +properties: + +mydcaecomponent_policy: + +type: map + +description: The Policy Body I need + +entry_schema: + +type: onap.datatypes.monitoring.mydatatype + +data_types: + +- onap.datatypes.monitoring.MyDataType: + +derived_from: tosca.datatypes.Root + +properties: + +my_property_1: + +type: string + +description: A description of this property + +constraints: + +- valid_values: + +- value example 1 + +- value example 2 + +TCA Example - Please note that the official version of this will be +located in the SDC repository. + +**Example TCA DCAE microservice** Expand source + +tosca_definitions_version: tosca_simple_yaml_1_0_0 + +policy_types: + +onap.policies.Monitoring: + +derived_from: tosca.policies.Root + +description: a base policy type for all policies that governs monitoring +provisioning + +onap.policy.monitoring.cdap.tca.hi.lo.app: + +derived_from: onap.policies.Monitoring + +version: 1.0.0 + +properties: + +tca_policy: + +type: map + +description: TCA Policy JSON + +entry_schema: + +type: onap.datatypes.monitoring.tca_policy + +data_types: + +onap.datatypes.monitoring.metricsPerEventName: + +derived_from: tosca.datatypes.Root + +properties: + +controlLoopSchemaType: + +type: string + +required: true + +description: Specifies Control Loop Schema Type for the event Name e.g. +VNF, VM + +constraints: + +- valid_values: + +- VM + +- VNF + +eventName: + +type: string + +required: true + +description: Event name to which thresholds need to be applied + +policyName: + +type: string + +required: true + +description: TCA Policy Scope Name + +policyScope: + +type: string + +required: true + +description: TCA Policy Scope + +policyVersion: + +type: string + +required: true + +description: TCA Policy Scope Version + +thresholds: + +type: list + +required: true + +description: Thresholds associated with eventName + +entry_schema: + +type: onap.datatypes.monitoring.thresholds + +onap.datatypes.monitoring.tca_policy: + +derived_from: tosca.datatypes.Root + +properties: + +domain: + +type: string + +required: true + +description: Domain name to which TCA needs to be applied + +default: measurementsForVfScaling + +constraints: + +- equal: measurementsForVfScaling + +metricsPerEventName: + +type: list + +required: true + +description: Contains eventName and threshold details that need to be +applied to given eventName + +entry_schema: + +type: onap.datatypes.monitoring.metricsPerEventName + +onap.datatypes.monitoring.thresholds: + +derived_from: tosca.datatypes.Root + +properties: + +closedLoopControlName: + +type: string + +required: true + +description: Closed Loop Control Name associated with the threshold + +closedLoopEventStatus: + +type: string + +required: true + +description: Closed Loop Event Status of the threshold + +constraints: + +- valid_values: + +- ONSET + +- ABATED + +direction: + +type: string + +required: true + +description: Direction of the threshold + +constraints: + +- valid_values: + +- LESS + +- LESS_OR_EQUAL + +- GREATER + +- GREATER_OR_EQUAL + +- EQUAL + +fieldPath: + +type: string + +required: true + +description: Json field Path as per CEF message which needs to be +analyzed for TCA + +constraints: + +- valid_values: + +- +$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedTotalPacketsDelta + +- +$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedOctetsDelta + +- +$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedUnicastPacketsDelta + +- +$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedMulticastPacketsDelta + +- +$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedBroadcastPacketsDelta + +- +$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedDiscardedPacketsDelta + +- +$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedErrorPacketsDelta + +- +$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedTotalPacketsAccumulated + +- +$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedOctetsAccumulated + +- +$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedUnicastPacketsAccumulated + +- +$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedMulticastPacketsAccumulated + +- +$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedBroadcastPacketsAccumulated + +- +$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedDiscardedPacketsAccumulated + +- +$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedErrorPacketsAccumulated + +- +$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].transmittedTotalPacketsDelta + +- +$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].transmittedOctetsDelta + +- +$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].transmittedUnicastPacketsDelta + +- +$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].transmittedMulticastPacketsDelta + +- +$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].transmittedBroadcastPacketsDelta + +- +$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].transmittedDiscardedPacketsDelta + +- +$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].transmittedErrorPacketsDelta + +- +$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].transmittedTotalPacketsAccumulated + +- +$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].transmittedOctetsAccumulated + +- +$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].transmittedUnicastPacketsAccumulated + +- +$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].transmittedMulticastPacketsAccumulated + +- +$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].transmittedBroadcastPacketsAccumulated + +- +$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].transmittedDiscardedPacketsAccumulated + +- +$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].transmittedErrorPacketsAccumulated + +- $.event.measurementsForVfScalingFields.cpuUsageArray[*].cpuIdle + +- +$.event.measurementsForVfScalingFields.cpuUsageArray[*].cpuUsageInterrupt + +- $.event.measurementsForVfScalingFields.cpuUsageArray[*].cpuUsageNice + +- +$.event.measurementsForVfScalingFields.cpuUsageArray[*].cpuUsageSoftIrq + +- $.event.measurementsForVfScalingFields.cpuUsageArray[*].cpuUsageSteal + +- $.event.measurementsForVfScalingFields.cpuUsageArray[*].cpuUsageSystem + +- $.event.measurementsForVfScalingFields.cpuUsageArray[*].cpuWait + +- $.event.measurementsForVfScalingFields.cpuUsageArray[*].percentUsage + +- $.event.measurementsForVfScalingFields.meanRequestLatency + +- +$.event.measurementsForVfScalingFields.memoryUsageArray[*].memoryBuffered + +- +$.event.measurementsForVfScalingFields.memoryUsageArray[*].memoryCached + +- +$.event.measurementsForVfScalingFields.memoryUsageArray[*].memoryConfigured + +- $.event.measurementsForVfScalingFields.memoryUsageArray[*].memoryFree + +- $.event.measurementsForVfScalingFields.memoryUsageArray[*].memoryUsed + +- +$.event.measurementsForVfScalingFields.additionalMeasurements[*].arrayOfFields[0].value + +severity: + +type: string + +required: true + +description: Threshold Event Severity + +constraints: + +- valid_values: + +- CRITICAL + +- MAJOR + +- MINOR + +- WARNING + +- NORMAL + +thresholdValue: + +type: integer + +required: true + +description: Threshold value for the field Path inside CEF message + +version: + +type: string + +required: true + +description: Version number associated with the threshold + +1.2 onap.policies.controlloop.Operational Policy Type +----------------------------------------------------- + +This policy type is used to support actor/action operational policies +for control loops. There are two types of implementations for this +policy type + +1. Existing Drools implementations that supports runtime Control Loop + actions taken on components such as SO/APPC/VFC/SDNC/SDNR + +2. New implementations using APEX to support Control Loops. + +For Dublin, this policy type will ONLY be used for the Policy Framework +to distinguish the policy type as operational. The contents are still +TBD for El Alto. + +**Base Policy type definition for +onap.policies.controlloop.Operational** Expand source + +tosca_definitions_version: tosca_simple_yaml_1_0_0 + +policy_types: + +onap.policies.controlloop.Operational: + +derived_from: tosca.policies.Root + +version: 1.0.0 + +description: Operational Policy for Control Loops + +Applications should use the following Content-Type when creating +onap.policies.controlloop.Operational policies: + +Content-Type: "application/yaml; vnd.onap.operational" + +1.2.1 Operational Policy Type Schema for Drools +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For Dublin Drools will still support the Casablanca YAML definition of +an Operational Policy for Control Loops. + +Please use the Casablanca version of the YAML Operational Policy format +defined \ https://git.onap.org/policy/drools-applications/tree/controlloop/common/policy-yaml/README-v2.0.0.md. + +1.2.3 Operational Policy Type Schema for APEX (El Alto proposal) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The operational Policy Type schema for for APEX will extend the base +operational Policy Type schema. This Policy Type allows parameters +specific to the APEX PDP to be specified as a TOSCA policy. + +**Operational Policy Model Parameter Schema for APEX** Expand source + +tosca_definitions_version: tosca_simple_yaml_1_0_0 + +# Note: The full APEX PolicyType definition will be developed during the +Dublin + +# timeframe of the ONAP project + +policy_types: + +onap.policies.controlloop.Operational: + +derived_from: tosca.policies.Root + +version: 1.0.0 + +description: Operational Policy for Control Loops + + onap.policies.controloop.operational.Apex: + +derived_from: onap.policies.controlloop.Operational + +version: 1.0.0 + +description: Operational Policy for Control Loops using the APEX PDP + + properties: + +# Some of these properties may be redundant in a Kubernetes deployment + +engine_service: + +type: onap.datatypes.policies.controlloop.operational.apex.EngineService + +description: APEX Engine Service Parameters + +inputs: + +type: map + +description: Inputs for handling events coming into the APEX engine + +entry_schema: + +type: onap.datatypes.policies.controlloop.operational.apex.EventHandler + +outputs: + +type: map + +description: Outputs for handling events going out of the APEX engine + +entry_schema: + +type: onap.datatypes.policies.controlloop.operational.apex.EventHandler + +environment: + +type: list + +description: Envioronmental parameters for the APEX engine + +entry_schema: + +type: onap.datatypes.policies.controlloop.operational.apex.Environment + +data_types: + +onap.datatypes.policies.controlloop.operational.apex.EngineService: + +derived_from: tosca.datatypes.Root + +properties: + +name: + +type: string + +description: Specifies the engine name + +required: false + +default: "ApexEngineService" + +version: + +type: string + +description: Specifies the engine version in double dotted format + +required: false + +default: "1.0.0" + +id: + +type: int + +description: Specifies the engine id + +required: true + +instance_count: + +type: int + +description: Specifies the number of engine threads that should be run + +required: true + +deployment_port: + +type: int + +description: Specifies the port to connect to for engine administration + +required: false + +default: 1 + +policy_model_file_name: + +type: string + +description: The name of the file from which to read the APEX policy +model + +required: false + +default: "" + + policy_type_impl: + +type: string + +description: The policy type implementation from which to read the APEX +policy model + +required: false + +default: "" + +periodic_event_period: + +type: string + +description: The time interval in milliseconds for the periodic scanning + +event, 0 means "don't scan" + +required: false + +default: 0 + +engine: + +type: +onap.datatypes.policies.controlloop.operational.apex.engineservice.Engine + +description: The parameters for all engines in the APEX engine service + +required: true + +onap.datatypes.policies.controlloop.operational.apex.EventHandler: + +derived_from: tosca.datatypes.Root + +properties: + +name: + +type: string + +description: Specifies the event handler name, if not specified this is +set to + +the key name + + required: false + +carrier_technology: + +type: +onap.datatypes.policies.controlloop.operational.apex.CarrierTechnology + +description: Specifies the carrier technology of the event handler (such + +as REST/Web Socket/Kafka) + +required: true + +event_protocol: + +type: onap.datatypes.policies.controlloop.operational.apex.EventProtocol + +description: Specifies the event protocol of events for the event +handler + +(such as Yaml/JSON/XML/POJO) + +required: true + +event_name: + +type: string + +description: Specifies the event name for events on this event handler, +if + +not specified, the event name is read from or written to the event being + +received or sent + +required: false + +event_name_filter: + +type: string + +description: Specifies a filter as a regular expression, events that do + +not match the filter are dropped, the default is to let all events + +through + +required: false + +synchronous_mode: + +type: bool + +description: Specifies the event handler is syncronous (receive event +and + +send response) + +required: false + +default: false + +synchronous_peer: + +type: string + +description: The peer event handler (output for input or input for +output) + +of this event handler in synchronous mode, this parameter is mandatory +if + +the event handler is in synchronous mode + +required: false + +default: "" + +synchronous_timeout: + +type: int + +description: The timeout in milliseconds for responses to be issued by + +APEX torequests, this parameter is mandatory if the event handler is in + +synchronous mode + +required: false + +default: "" + +requestor_mode: + +type: bool + +description: Specifies the event handler is in requestor mode (send +event + +and wait for response mode) + +required: false + +default: false + +requestor_peer: + +type: string + +description: The peer event handler (output for input or input for +output) + +of this event handler in requestor mode, this parameter is mandatory if + +the event handler is in requestor mode + +required: false + +default: "" + +requestor_timeout: + +type: int + +description: The timeout in milliseconds for wait for responses to + +requests, this parameter is mandatory if the event handler is in + +requestor mode + +required: false + +default: "" + +onap.datatypes.policies.controlloop.operational.apex.CarrierTechnology: + +derived_from: tosca.datatypes.Root + +properties: + +label: + +type: string + +description: The label (name) of the carrier technology (such as REST, + +Kafka, WebSocket) + +required: true + +plugin_parameter_class_name: + +type: string + +description: The class name of the class that overrides default handling + +of event input or output for this carrier technology, defaults to the +supplied + +input or output class + +required: false + +onap.datatypes.policies.controlloop.operational.apex.EventProtocol: + +derived_from: tosca.datatypes.Root + +properties: + +label: + +type: string + +description: The label (name) of the event protocol (such as Yaml, + +JSON, XML, or POJO) + +required: true + +event_protocol_plugin_class: + +type: string + +description: The class name of the class that overrides default handling + +of the event protocol for this carrier technology, defaults to the + +supplied event protocol class + +required: false + +onap.datatypes.policies.controlloop.operational.apex.Environmental: + +derived_from: tosca.datatypes.Root + +properties: + +name: + +type: string + +description: The name of the environment variable + +required: true + +value: + +type: string + +description: The value of the environment variable + +required: true + +onap.datatypes.policies.controlloop.operational.apex.engineservice.Engine: + +derived_from: tosca.datatypes.Root + +properties: + +context: + +type: +onap.datatypes.policies.controlloop.operational.apex.engineservice.engine.Context + +description: The properties for handling context in APEX engines, + +defaults to using Java maps for context + +required: false + +executors: + +type: map + +description: The plugins for policy executors used in engines such as + +javascript, MVEL, Jython + +required: true + +entry_schema: + +description: The plugin class path for this policy executor + +type: string + +onap.datatypes.policies.controlloop.operational.apex.engineservice.engine.Context: + +derived_from: tosca.datatypes.Root + +properties: + +distributor: + +type: onap.datatypes.policies.controlloop.operational.apex.Plugin + +description: The plugin to be used for distributing context between + +APEX PDPs at runtime + +required: false + +schemas: + +type: map + +description: The plugins for context schemas available in APEX PDPs + +such as Java and Avro + +required: false + +entry_schema: + +type: onap.datatypes.policies.controlloop.operational.apex.Plugin + +locking: + +type: onap.datatypes.policies.controlloop.operational.apex.plugin + +description: The plugin to be used for locking context in and + +between APEX PDPs at runtime + +required: false + +persistence: + +type: onap.datatypes.policies.controlloop.operational.apex.Plugin + +description: The plugin to be used for persisting context for APEX PDPs + +at runtime + +required: false + +onap.datatypes.policies.controlloop.operational.apex.Plugin: + +derived_from: tosca.datatypes.Root + +properties: + +name: + +type: string + +description: The name of the executor such as Javascript, Jython or MVEL + +required: true + +plugin_class_name: + +type: string + +description: The class path of the plugin class for this executor + +1.3 onap.policies.controlloop.Guard Policy Type +----------------------------------------------- + +This policy type is the the type definition for Control Loop guard +policies for frequency limiting, blacklisting and min/max guards to help +protect runtime Control Loop Actions from doing harm to the network. +This policy type is developed using the XACML PDP to support +question/answer Policy Decisions during runtime for the Drools and APEX +onap.controlloop.Operational policy type implementations. + +The base schema is defined as below: + +**Base Policy type definition for onap.policies.controlloop.Guard** + Expand source + +tosca_definitions_version: tosca_simple_yaml_1_0_0 + +policy_types: + +- onap.policies.controlloop.Guard: + +derived_from: tosca.policies.Root + +version: 1.0.0 + +description: Guard Policies for Control Loop Operational Policies + +As with *onap.policies.Monitoring* policy type, the *PolicyTypeImpl* +implementation of the *onap.policies.controlloop.Guard* Policy Type is +generic to support definition of TOSCA *PolicyType* artifacts in the +Policy Framework using the Policy Type Design API. + +For Dublin, only the following derived Policy Type definitions below are +preloaded in the Policy Framework. However, the creation of policies +will still support the payload from Casablanca. + +**Casablanca Guard Payload** Expand source + +ContentType: "application/json; vnd.onap.guard" + +Accepts: "application/json" + +# + +# Request BODY + +# + +{ + +"policy-id" : "guard.frequency.scaleout", + +"contents" : { + +"actor": "SO", + +"recipe": "scaleOut", + +"targets": ".*", + +"clname": "ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3", + +"limit": "1", + +"timeWindow": "10", + +"timeUnits": "minute", + +"guardActiveStart": "00:00:01-05:00", + +"guardActiveEnd": "23:59:59-05:00" + +} + +} + +# + +# Request RESPONSE + +# + +{ + +"guard.frequency.scaleout": { + +"type": "onap.policies.controlloop.guard.FrequencyLimiter", + +"version": "1.0.0", + +"metadata": { + +"policy-id": "guard.frequency.scaleout", + +"policy-version": 1 + +} + +} + +} + +1.3.1 onap.policies.controlloop.guard.FrequencyLimiter Policy Type +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This is WIP for El Alto for the proposed policy type. + +**Policy Typefor Frequency Limiter Guard Policy** Expand source + +tosca_definitions_version: tosca_simple_yaml_1_0_0 + +policy_types: + +- onap.policies.controlloop.Guard: + +derived_from: tosca.policies.Root + +version: 1.0.0 + +description: Guard Policies for Control Loop Operational Policies + +- onap.policies.controlloop.guard.FrequencyLimiter: + +derived_from: onap.policies.controlloop.Guard + +version: 1.0.0 + +description: Supports limiting the frequency of actions being taken by a +Actor. + +properties: + +frequency_policy: + +type: map + +description: + +entry_schema: + +type: onap.datatypes.guard.FrequencyLimiter + +data_types: + +- onap.datatypes.guard.FrequencyLimiter: + +derived_from: tosca.datatypes.Root + +properties: + +actor: + +type: string + +description: Specifies the Actor + +required: true + +recipe: + +type: string + +description: Specified the Recipe + +required: true + +time_window: + +type: scalar-unit.time + +description: The time window to count the actions against. + +required: true + +limit: + +type: integer + +description: The limit + +required: true + +constraints: + +- greater_than: 0 + +time_range: + +type: tosca.datatypes.TimeInterval + +description: An optional range of time during the day the frequency is +valid for. + +required: false + +controlLoopName: + +type: string + +description: An optional specific control loop to apply this guard to. + +required: false + +target: + +type: string + +description: An optional specific VNF to apply this guard to. + +required: false + +1.3.2 onap.policies.controlloop.guard.Blacklist Policy Type +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**Policy Type for Blacklist Guard Policies** Expand source + +tosca_definitions_version: tosca_simple_yaml_1_0_0 + +policy_types: + +- onap.policies.controlloop.Guard: + +derived_from: tosca.policies.Root + +version: 1.0.0 + +description: Guard Policies for Control Loop Operational Policies + +- onap.policies.controlloop.guard.Blacklist: + +derived_from: onap.policies.controlloop.Guard + +version: 1.0.0 + +description: Supports blacklist of VNF's from performing control loop +actions on. + +properties: + +blacklist_policy: + +type: map + +description: + +entry_schema: + +type: onap.datatypes.guard.Blacklist + +data_types: + +- onap.datatypes.guard.Blacklist: + +derived_from: tosca.datatypes.Root + +properties: + +actor: + +type: string + +description: Specifies the Actor + +required: true + +recipe: + +type: string + +description: Specified the Recipe + +required: true + +time_range: + +type: tosca.datatypes.TimeInterval + +description: An optional range of time during the day the blacklist is +valid for. + +required: false + +controlLoopName: + +type: string + +description: An optional specific control loop to apply this guard to. + +required: false + +blacklist: + +type: list + +description: List of VNF's + +required: true + +1.3.3 onap.policies.controlloop.guard.MinMax Policy Type +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**Policy Type for Min/Max VF Module Policies** Expand source + +policy_types: + +- onap.policies.controlloop.Guard: + +derived_from: tosca.policies.Root + +version: 1.0.0 + +description: Guard Policies for Control Loop Operational Policies + +- onap.policies.controlloop.guard.MinMax: + +derived_from: onap.policies.controlloop.Guard + +version: 1.0.0 + +description: Supports Min/Max number of VF Modules + +properties: + +minmax_policy: + +type: map + +description: + +entry_schema: + +type: onap.datatypes.guard.MinMax + +data_types: + +- onap.datatypes.guard.MinMax: + +derived_from: tosca.datatypes.Root + +properties: + +actor: + +type: string + +description: Specifies the Actor + +required: true + +recipe: + +type: string + +description: Specified the Recipe + +required: true + +time_range: + +type: tosca.datatypes.TimeInterval + +description: An optional range of time during the day the Min/Max limit +is valid for. + +required: false + +controlLoopName: + +type: string + +description: An optional specific control loop to apply this guard to. + +required: false + +min_vf_module_instances: + +type: integer + +required: true + +description: The minimum instances of this VF-Module + +max_vf_module_instances: + +type: integer + +required: false + +description: The maximum instances of this VF-Module + +1.3.4 onap.policies.controlloop.Coordination Policy Type (STRETCH) +------------------------------------------------------------------ + +This policy type defines Control Loop Coordination policies to assist in +coordinating multiple control loops during runtime. This policy type is +developed using XACML PDP to support question/answer policy decisions at +runtime for the onap.policies.controlloop.operational policy types. + +2 PDP Deployment and Registration with PAP +========================================== + +The unit of execution and scaling in the Policy Framework is a +*PolicyImpl* entity. A *PolicyImpl* entity runs on a PDP. As is +explained above a *PolicyImpl* entity is a *PolicyTypeImpl* +implementation parameterized with a TOSCA *Policy*. + +In order to achieve horizontal scalability, we group the PDPs running +instances of a given *PolicyImpl* entity logically together into a +*PDPSubGroup*. The number of PDPs in a *PDPSubGroup* can then be scaled +up and down using Kubernetes. In other words, all PDPs in a subgroup run +the same \ *PolicyImpl*, that is the same policy template implementation +(in XACML, Drools, or APEX) with the same parameters. + +The figure above shows the layout of *PDPGroup* and *PDPSubGroup* +entities. The figure shows examples of PDP groups for Control Loop and +Monitoring policies on the right. + +The health of PDPs is monitored by the PAP in order to alert operations +teams managing policy. The PAP manages the life cycle of policies +running on PDPs. + +The table below shows the methods in which *PolicyImpl* entities can be +deployed to PDP Subgroups + +=============== ================================================================================================================================================================================================================================================================================== ================================================================================================================================================================================ ======================================================================================================================================================================================================================== +**Method** **Description** **Advantages** **Disadvantages** +=============== ================================================================================================================================================================================================================================================================================== ================================================================================================================================================================================ ======================================================================================================================================================================================================================== +Cold Deployment The *PolicyImpl (PolicyTypeImpl* and TOSCA *Policy)* are predeployed on the PDP. The PDP is fully configured and ready to execute when started. No run time configuration required and run time administration is simple. Very restrictive, no run time configuration of PDPs is possible. + + PDPs register with the PAP when they start, providing the *PolicyImpl* they have been predeployed with. +Warm Deployment The *PolicyTypeImpl* entity is predeployed on the PDP. A TOSCA *Policy* may be loaded at startup. The PDP may be configured or reconfigured with a new or updated TOSCA *Policy* at run time. The configuration, parameters, and PDP group of PDPs may be changed at run time by loading or updating a TOSCA *Policy* into the PDP. Administration and management is required. The configuration and life cycle of the TOSCA policies can change at run time and must be administered and managed. + + PDPs register with the PAP when they start, providing the *PolicyImpl* they have been predeployed with if any. The PAP may update the TOSCA *Policy* on a PDP at any time after registration. Lifecycle management of TOSCA *Policy* entities is supported, allowing features such as *PolicyImpl* Safe Mode and \ *Policy*\ Impl retirement. +Hot Deployment The *PolicyImpl (PolicyTypeImpl* and TOSCA *Policy)* are deployed at run time. The *PolicyImpl (PolicyTypeImpl* and TOSCA *Policy)* may be loaded at startup. The PDP may be configured or reconfigured with a new or updated *PolicyTypeImpl* and/or TOSCA *Policy* at run time. The policy logic, rules, configuration, parameters, and PDP group of PDPs may be changed at run time by loading or updating a TOSCA *Policy* and *PolicyTypeImpl* into the PDP. Administration and management is more complex. The *PolicyImpl* itself and its configuration and life cycle as well as the life cycle of the TOSCA policies can change at run time and must be administered and managed. + + PDPs register with the PAP when they start, providing the *PolicyImpl* they have been predeployed with if any. The PAP may update the TOSCA *Policy* and *PolicyTypeImpl* on a PDP at any time after registration. Lifecycle management of TOSCA *Policy* entities and *PolicyTypeImpl* entites is supported, allowing features such as *PolicyImpl* Safe Mode and \ *Policy*\ Impl retirement. +=============== ================================================================================================================================================================================================================================================================================== ================================================================================================================================================================================ ======================================================================================================================================================================================================================== + +3. Public APIs +============== + +The Policy Framework supports the APIs documented in the subsections +below. The APIs in this section are supported for use by external +components. + +3.1 Policy Type Design API for TOSCA Policy Types +------------------------------------------------- + +The purpose of this API is to support CRUD of TOSCA *PolicyType* +entities. This API is provided by the *PolicyDevelopment* component of +the Policy Framework, see `The ONAP Policy +Framework <file://localhost/display/DW/The+ONAP+Policy+Framework>`__ +architecture. + +The API allows applications to create, update, delete, and query +*PolicyType* entities so that they become available for use in ONAP by +applications such as CLAMP\ *.* Some Policy Type entities are preloaded +in the Policy Framework. The TOSCA fields below are valid on API calls: + +============ ======= ======== ========== =============================================================================================================================== +**Field** **GET** **POST** **DELETE** **Comment** +============ ======= ======== ========== =============================================================================================================================== +(name) M M M The definition of the reference to the Policy Type, GET allows ranges to be specified +version O M C GET allows ranges to be specified, must be specified if more than one version of the Policy Type exists +description R O N/A Desciption of the Policy Type +derived_from R C N/A Must be specified when a Policy Type is derived from another Policy Type such as in the case of derived Monitoring Policy Types +metadata R O N/A Metadata for the Policy Type +properties R M N/A This field holds the specification of the specific Policy Type in ONAP +targets R O N/A A list of node types and/or group types to which the Policy Type can be applied +triggers R O N/A Specification of policy triggers, not currently supported in ONAP +============ ======= ======== ========== =============================================================================================================================== + +| Note: On this and subsequent tables, use the following legend: + M-Mandatory, O-Optional, R-Read-only, C-Conditional. Conditional means + the field is mandatory when some other field is present. +| Note: Preloaded policy types may only be queried over this API, + modification or deletion of preloaded policy type implementations is + disabled. +| Note: Policy types that are in use (referenced by defined Policies) + may not be deleted +| Note: The group types of targets in TOSCA are groups of TOSCA nodes, + not PDP groups; the *target* concept in TOSCA is equivalent to the + Policy Enforcement Point (PEP) concept + +3.1.1 Policy Type query +~~~~~~~~~~~~~~~~~~~~~~~ + +The API allows applications (such as CLAMP and Integration) to query +the \ *PolicyType* entities that are available for \ *Policy* creation +using a GET operation. + +*https:{url}:{port}/policy/api/v1/policytypes GET* + +**Policy Type Query - When system comes up before any mS are onboarded** + Expand source + +policy_types: + +- onap.policies.Monitoring: + +version: 1.0.0 + +description: A base policy type for all policies that govern monitoring +provision + +derived_from: tosca.policies.Root + +properties: + +# Omitted for brevity, see Section 1 + + - onap.policies.controlloop.Operational: + +version: 1.0.0 + + description: Operational Policy for Control Loops + +derived_from: tosca.policies.Root + +properties: + +# Omitted for brevity, see Section 1 + +- onap.policies.controloop.operational.Drools: + +version: 1.0.0 + +description: Operational Policy for Control Loops using the Drools PDP + +derived_from: onap.policies.controlloop.Operational + +properties: + +# Omitted for brevity, see Section 1 + +- onap.policies.controloop.operational.Apex: + +version: 1.0.0 + +description: Operational Policy for Control Loops using the APEX PDP + +derived_from: onap.policies.controlloop.Operational + +properties: + +# Omitted for brevity, see Section 1 + + - onap.policies.controlloop.Guard: + +version: 1.0.0 + +description: Operational Policy for Control Loops + +derived_from: tosca.policies.Root + +properties: + +# Omitted for brevity, see Section 1 + +- onap.policies.controlloop.guard.FrequencyLimiter: + +version: 1.0.0 + + description: Supports limiting the frequency of actions being taken by +a Actor. + +derived_from: onap.policies.controlloop.Guard + +properties: + +# Omitted for brevity, see Section 1 + +- onap.policies.controlloop.guard.Blacklist: + +version: 1.0.0 + +description: Supports blacklist of VNF's from performing control loop +actions on. + +derived_from: onap.policies.controlloop.Guard + +properties: + +# Omitted for brevity, see Section 1 + +- onap.policies.controlloop.guard.MinMax: + +version: 1.0.0 + +description: Supports Min/Max number of VF Modules + +derived_from: onap.policies.controlloop.Guard + +properties: + +# Omitted for brevity, see Section 1 + +- onap.policies.controlloop.coordination.TBD: (STRETCH GOALS) + +version: 1.0.0 + +description: Control Loop Coordination policy types + +derived_from: onap.policies.controlloop.Coordination + +properties: + +# Omitted for brevity, see Section 1 + +data_types: + +# Any bespoke data types referenced by policy type definitions + +The table below shows some more examples of GET operations + +======================================================================================================== ================================================================ +**Example** **Description** +======================================================================================================== ================================================================ +*https:{url}:{port}/policy/api/v1/policytypes* Get all Policy Type entities in the system +*https:{url}:{port}/policy/api/v1/policytypes/{policy type id}* Get a specific policy type and all the available versions. + +*eg. +https:{url}:{port}/policy/api/v1/policytypes/onap.policies.monitoring.cdap.tca.hi.lo.app* +*https:{url}:{port}/policy/api/v1/policytypes/{policy type id}/versions/{version id}* Get the specific Policy Type with the specified name and version + +*eg. +https:{url}:{port}/policy/api/v1/policytypes/onap.policies.monitoring.cdap.tca.hi.lo.app/versions/1.0.0* +======================================================================================================== ================================================================ + +3.1.2 Policy Type Create/Update +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The API allows applications and users (such as a DCAE microservice +component developer) to create or update a Policy Type using a POST +operation. This API allows new Policy Types to be created or existing +Policy Types to be modified. POST operations with a new Policy Type name +or a new version of an existing Policy Type name are used to create a +new Policy Type. POST operations with an existing Policy Type name and +version are used to update an existing Policy Type. Many Policy Types +can be created or updated in a single POST operation by specifying more +than one Policy Type on the TOSCA *policy_types* list. + +For example, the POST operation below with the TOSCA body below is used +to create a new Policy type for a DCAE microservice. + +*https:{url}:{port}/policy/api/v1/policytypes POST* + +**Create a new Policy Type for a DCAE microservice** Expand source + +policy_types: + +- onap.policies.monitoring.cdap.tca.hi.lo.app: + +version: 1.0.0 + + derived_from: onap.policies.Monitoring + +description: A DCAE TCA high/low policy type + +properties: + +tca_policy: + +type: map + +description: TCA Policy JSON + +default:'{<JSON omitted for brevity>}' + +entry_schema: + +type: onap.datatypes.monitoring.tca_policy + +data_types: + +<omitted for brevity> + +Following creation of a DCAE TCA policy type operation, the GET call for +Monitoring policies will list the new policy type. + +*https:{url}:{port}/policy/api/v1/policytypes GET* + +**Policy Type Query after DCAE TCA mS Policy Type is created** Expand +source + +policy_types: + +- onap.policies.Monitoring: + +version: 1.0.0 + +derived_from: tosca.policies.Root + +description: A base policy type for all policies that govern monitoring +provision + +- onap.policies.monitoring.cdap.tca.hi.lo.app: + +version: 1.0.0 + + derived_from: onap.policies.Monitoring + +description: A DCAE TCA high/low policy type + +- onap.policies.controlloop.Operational: + +version: 1.0.0 + +description: Operational Policy for Control Loops + +derived_from: tosca.policies.Root + +- onap.policies.controloop.operational.Drools: + +version: 1.0.0 + +description: Operational Policy for Control Loops using the Drools PDP + +derived_from: onap.policies.controlloop.Operational + +- onap.policies.controloop.operational.Apex: + +version: 1.0.0 + +description: Operational Policy for Control Loops using the APEX PDP + +derived_from: onap.policies.controlloop.Operational + +- onap.policies.controlloop.Guard: + +version: 1.0.0 + +description: Operational Policy for Control Loops + +derived_from: tosca.policies.Root + +- onap.policies.controlloop.guard.FrequencyLimiter: + +version: 1.0.0 + +description: Supports limiting the frequency of actions being taken by a +Actor. + +derived_from: onap.policies.controlloop.Guard + +- onap.policies.controlloop.guard.Blacklist: + +version: 1.0.0 + +description: Supports blacklist of VNF's from performing control loop +actions on. + +derived_from: onap.policies.controlloop.Guard + +- onap.policies.controlloop.guard.MinMax: + +version: 1.0.0 + +description: Supports Min/Max number of VF Modules + +derived_from: onap.policies.controlloop.Guard + +- onap.policies.controlloop.coordination.TBD: (STRETCH GOALS) + +version: 1.0.0 + +description: Control Loop Coordination policy types + +derived_from: onap.policies.controlloop.Coordination + +Now the \ *onap.policies.Monitoring.cdap.tca.hi.lo.app* Policy Type is +available to CLAMP for creating concrete policies. See the Yaml +contribution on the \ `Model driven Control Loop +Design <file://localhost/display/DW/Model+driven+Control+Loop+Design>`__ page +for a full listing of the DCAE TCA policy type used in the example +above. + +3.1.3 Policy Type Delete +~~~~~~~~~~~~~~~~~~~~~~~~ + +The API also allows Policy Types to be deleted with a DELETE operation. +The format of the delete operation is as below: + +*https:{url}:{port}/policy/api/v1/policytypes/onap.policies.monitoring.cdap.tca.hi.lo.app/versions/1.0.0 +DELETE* + +| Note: Predefined policy types cannot be deleted +| Note: Policy types that are in use (Parameterized by a TOSCA Policy) + may not be deleted, the parameterizing TOSCA policies must be deleted + first +| Note: The *version* parameter may be omitted on the DELETE operation + if there is only one version of the policy type in the system + +3.2 Policy Design API +--------------------- + +The purpose of this API is to support CRUD of TOSCA *Policy* entities +from TOSCA compliant *PolicyType* definitions. TOSCA *Policy* entities +become the parameters for \ *PolicyTypeImpl* entities, producing +*PolicyImpl* entities that can run on PDPs. This API is provided by the +*PolicyDevelopment* component of the Policy Framework, see `The ONAP +Policy +Framework <file://localhost/display/DW/The+ONAP+Policy+Framework>`__ +architecture. + +This API allows applications (such as CLAMP and Integration) to create, +update, delete, and query *Policy* entities\ *.* The TOSCA fields below +are valid on API calls: + +=========== ======= ======== ========== ================================================================================ +**Field** **GET** **POST** **DELETE** **Comment** +=========== ======= ======== ========== ================================================================================ +(name) M M M The definition of the reference to the Policy, GET allows ranges to be specified +type O M O The Policy Type of the policy, see section 3.1 +description R O O +metadata R O N/A +properties R M N/A This field holds the specification of the specific Policy in ONAP +targets R O N/A A list of nodes and/or groups to which the Policy can be applied +=========== ======= ======== ========== ================================================================================ + +| Note: Policies that are deployed (used on deployed *PolicyImpl* + entities) may not be deleted +| Note: This API is NOT used by DCAE for a decision on what policy the + DCAE PolicyHandler should retrieve and enforce +| Note: The groups of targets in TOSCA are groups of TOSCA nodes, not + PDP groups; the *target* concept in TOSCA is equivalent to the Policy + Enforcement Point (PEP) concept + +YAML is used for illustrative purposes in the examples in this section. +JSON (application/json) will be used as the content type in the +implementation of this API. + +3.2.1 Policy query +~~~~~~~~~~~~~~~~~~ + +The API allows applications (such as CLAMP and Integration) to query +the \ *Policy* entities that are available for deployment using a GET +operation. + +Note: This operation simply returns TOSCA policies that are defined in +the Policy Framework, it does NOT make a decision. + +The table below shows some more examples of GET operations + +==================================================================================================================================================================================================== =================================================================================== +**Example** **Description** +==================================================================================================================================================================================================== =================================================================================== +*https:{url}:{port}/policy/api/v1/policytypes/{policy type id}/versions/{versions}/policies* Get all Policies for a specific Policy Type and version + +*eg. +https:{url}:{port}/policy/api/v1/policytypes/onap.policies.monitoring.cdap.tca.hi.lo.app/versions/1.0.0/policies* +*https://{url}:{port}/policy/api/v1/policytypes/{policy type id}/versions/{version}/policies/{policy name}/versions/{version}* Gets a specific Policy version + +*eg. +https:{url}:{port}/policy/api/v1/policytypes/onap.policies.monitoring.cdap.tca.hi.lo.app/versions/1.0.0/policies/onap.scaleout.tca/versions/1.0.0 GET* +*https:{url}:{port}/policy/api/v1/policytypes/onap.policies.monitoring.cdap.tca.hi.lo.app/versions/1.0.0/policies/onap.scaleout.tca/versions/latest GET* Returns the latest version of a Policy +*https:{url}:{port}/policy/api/v1/policytypes/onap.policies.monitoring.cdap.tca.hi.lo.app/versions/1.0.0/policies/onap.scaleout.tca/deployed GET* Returns the version of the Policy that has been deployed on one or more PDP groups. +*https://{url}:{port}/policy/api/v1/policytypes/onap.policies.monitoring.cdap.tca.hi.lo.app/versions/1.2.3/policies/CL-LBAL-LOW-TRAFFIC-SIG-FB480F95-A453-6F24-B767-FD703241AB1A/versions/1.0.2 GET* Returns a specific version of a monitoring policy +==================================================================================================================================================================================================== =================================================================================== + +3.2.2 Policy Create/Update +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The API allows applications and users (such as CLAMP and Integration) to +create or update a Policy using a POST operation. This API allows new +Policies to be created or existing Policies to be modified. POST +operations with a new Policy name are used to create a new Policy. POST +operations with an existing Policy name are used to update an existing +Policy. Many Policies can be created or updated in a single POST +operation by specifying more than one Policy on the TOSCA *policies* +list. + +3.2.2.1 Monitoring Policy Create/Update +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +While designing a control loop using CLAMP, a Control Loop Designer uses +the Policy Type for a specific DCAE mS component (See Section 3.1.1) to +create a specific Policy. CLAMP then uses this API operation to submit +the Policy to the Policy Framework. + +For example, the POST operation below with the TOSCA body below is used +to create a new scaleout Policy for +the \ *onap.policies.monitoring.cdap.tca.hi.lo.app* microservice. The +name of the policy "onap.scaleout.tca" is up to the user to determine +themselves. + +*https:{url}:{port}/policy/api/v1/policytypes/onap.policies.Monitoring.cdap.tca.hi.lo.app/versions/1.0.0/policies POST* + +**TOSCA Body of a new TCA High/Low Policy** Expand source + +https:{url}:{port}/policy/api/v1/policytypes/onap.policies.monitoring.cdap.tca.hi.lo.app/versions/1.0.0/policies +POST + +Content-Type: application/yaml + +Accept: application/yaml + +#Request Body + +policies: + +- + +onap.scaleout.tca: + + type: onap.policies.monitoring.cdap.tca.hi.lo.app + +version: 1.0.0 + +metadata: + +policy-id: onap.scaleout.tca # SHOULD MATCH THE TOSCA policy-name field +above. DCAE needs this - convenience. + +description: The scaleout policy for vDNS # GOOD FOR CLAMP GUI + +properties: + +domain: measurementsForVfScaling + +metricsPerEventName: + +- + +eventName: vLoadBalancer + +controlLoopSchemaType: VNF + +policyScope: "type=configuration" + +policyName: "onap.scaleout.tca" + +policyVersion: "v0.0.1" + +thresholds: + +- closedLoopControlName: +"CL-LBAL-LOW-TRAFFIC-SIG-FB480F95-A453-6F24-B767-FD703241AB1A" + +closedLoopEventStatus: ONSET + +version: "1.0.2" + +fieldPath: +"$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedBroadcastPacketsAccumulated" + +thresholdValue: 500 + +direction: LESS_OR_EQUAL + +severity: MAJOR + +- + +closedLoopControlName: +"CL-LBAL-LOW-TRAFFIC-SIG-0C5920A6-B564-8035-C878-0E814352BC2B" + +closedLoopEventStatus: ONSET + +version: "1.0.2" + +fieldPath: +"$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedBroadcastPacketsAccumulated" + +thresholdValue: 5000 + +direction: GREATER_OR_EQUAL + +severity: CRITICAL + +#Response Body + +policies: + +- onap.scaleout.tca: + +type: onap.policies.monitoring.cdap.tca.hi.lo.app + +version: 1.0.0 + +metadata: + +# + +# version is managed by Policy Lifecycle and returned + +# back to the caller. + +# + +policy-version: 1 + +# + +# These were passed in, and should not be changed. Will + +# be passed back. + +# + +policy-id: onap.scaleout.tca + +properties: + +domain: measurementsForVfScaling + +metricsPerEventName: + +- + +eventName: vLoadBalancer + +controlLoopSchemaType: VNF + +policyScope: "type=configuration" + +<OMITTED FOR BREVITY> + +Given a return code of success and a "metadata" section that indicates +versioning information. The "metadata" section conforms exactly to how +SDC implements lifecycle management versioning for first class +normatives in the TOSCA Models. The policy platform will implement +lifecycle identically to SDC to ensure conformity for policy creation. +The new metadata fields return versioning details. + +The following new policy will be listed and will have a "metadata" +section as shown below: + +*https:{url}:{port}/policy/api/v1/policytypes/onap.policies.monitoring.cdap.tca.hi.lo.app/versions/1.0.0/policies +GET* + +**Policy with Metadata section for lifecycle management** Expand source + +policies: + +- onap.scaleout.tca: + +type: onap.policies.monitoring.cdap.tca.hi.lo.app + +version: 1.0.0 + +metadata: + +policy-id: onap.scaleout.tca + +policy-version: 1 + +- my.other.policy: + +type: onap.policies.monitoring.cdap.tca.hi.lo.app + +version: 1.0.0 + +metadata: + +invariantUUID: 20ad46cc-6b16-4404-9895-93d2baaa8d25 + +UUID: 4f715117-08b9-4221-9d63-f3fa86919742 + +version: 5 + +name: my.other.policy + +scope: foo=bar;field2=value2 + +description: The policy for some other use case + +- yet.another.policy: + +type: onap.policies.monitoring.cdap.tca.hi.lo.app + +version: 1.0.0 + +metadata: + +invariantUUID: 20ad46cc-6b16-4404-9895-93d2baaa8d25 + +UUID: 4f715117-08b9-4221-9d63-f3fa86919742 + +version: 3 + +name: yet.another.policy + +scope: foo=bar; + +description: The policy for yet another use case + +The contents of the new policy can be retrieved using the ID: + +*https:{url}:{port}/policy/api/v1/policytypes/onap.policies.monitoring.cdap.tca.hi.lo.app/versions/1.0.0/policies/onap.scaleout.tca +GET* + +**Query on a new TCA High/Low Policy** Expand source + +policies: + +- + +onap.scaleout.tca: + +type: onap.policies.monitoring.cdap.tca.hi.lo.app + +version: 1.0.0 + +metadata: + +invariantUUID: 20ad46cc-6b16-4404-9895-93d2baaa8d25 + +UUID: 4f715117-08b9-4221-9d63-f3fa86919742 + +version: 1 + +name: onap.scaleout.tca + +scope: foo=bar; + +description: The scaleout policy for vDNS + +properties: + +domain: measurementsForVfScaling + +<OMMITTED FOR BREVITY> + +**3.2.2.2 Operational Policy Create/Update** + +While designing an operational policy, the designer uses the Policy Type +for the operational policy (See Section 3.1.1) to create a specific +Policy and submits the Policy to the Policy Framework. + +This URL will be fixed for CLAMP in Dublin and the payload will match +updated version of Casablanca YAML that supports VFModules. + +*https:{url}:{port}/policy/api/v1/policytypes/onap.policies.controloop.operational/versions/1.0.0/policies POST* + +*Content-Type: application/yaml; legacy-version* + +FUTURE: Content-Type: application/yaml; tosca + +NOTE: The controlLoopName will be assumed to be the policy-id + +**Create an Operational Policy** Expand source + +tosca_definitions_version: tosca_simple_yaml_1_0_0 + +topology_template: + +policies: + +- + +operational.scaleout: + +type: onap.policies.controlloop.Operational + +version: 1.0.0 + +metadata: + +policy-id: operational.scaleout + +properties: + +controlLoop: + +version: 2.0.0 + +controlLoopName: ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3 + +trigger_policy: unique-policy-id-1-scale-up + +timeout: 1200 + +abatement: false + +policies: + +- id: unique-policy-id-1-scale-up + +name: Create a new VF Module + +description: + +actor: SO + +recipe: VF Module Create + +target: + +type: VNF + +payload: + +requestParameters: '{"usePreload":true,"userParams":[]}' + +configurationParameters: +'[{"ip-addr":"$.vf-module-topology.vf-module-parameters.param[9]","oam-ip-addr":"$.vf-module-topology.vf-module-parameters.param[16]","enabled":"$.vf-module-topology.vf-module-parameters.param[23]"}]' + +retry: 0 + +timeout: 1200 + +success: final_success + +failure: final_failure + +failure_timeout: final_failure_timeout + +failure_retries: final_failure_retries + +failure_exception: final_failure_exception + +failure_guard: final_failure_guard + +**Response from creating Operational Policy** Expand source + +tosca_definitions_version: tosca_simple_yaml_1_0_0 + +topology_template: + +policies: + +- + +operational.scaleout: + +type: onap.policies.controlloop.Operational + +version: 1.0.0 + +metadata: + +policy-id: operational.scaleout + +policy-version: 1 + +properties: + +controlLoop: + +version: 2.0.0 + +controlLoopName: ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3 + +trigger_policy: unique-policy-id-1-scale-up + +timeout: 1200 + +abatement: false + +policies: + +- id: unique-policy-id-1-scale-up + +name: Create a new VF Module + +description: + +actor: SO + +recipe: VF Module Create + +target: + +type: VNF + +payload: + +requestParameters: '{"usePreload":true,"userParams":[]}' + +configurationParameters: +'[{"ip-addr":"$.vf-module-topology.vf-module-parameters.param[9]","oam-ip-addr":"$.vf-module-topology.vf-module-parameters.param[16]","enabled":"$.vf-module-topology.vf-module-parameters.param[23]"}]' + +retry: 0 + +timeout: 1200 + +success: final_success + +failure: final_failure + +failure_timeout: final_failure_timeout + +failure_retries: final_failure_retries + +failure_exception: final_failure_exception + +failure_guard: final_failure_guard + +3.2.2.2.1 Drools Operational Policy Create/Update +''''''''''''''''''''''''''''''''''''''''''''''''' + +TBD `Jorge Hernandez <file://localhost/display/~jhh>`__ + +3.2.2.2.2 APEX Operational Policy Create/Update +''''''''''''''''''''''''''''''''''''''''''''''' + +The POST operation below with the TOSCA body below is used to create a +new Sample Domain test polict for the APEX Sample Domain operational +policy type. + +*https:{url}:{port}/policy/api/v1/policytypes/onap.policies.controloop.operational.apex/versions/1.0.0/policies POST* + +**Create an APEX Policy for a Sample Domain** Expand source + +policies: + +- onap.policy.operational.apex.sampledomain.Test: + +type: onap.policies.controloop.operational.Apex + +properties: + +engine_service: + +name: "MyApexEngine" + +version: "0.0.1" + +id: 45 + +instance_count: 4 + +deployment_port: 12561 + +policy_type_impl: +"onap.policies.controlloop.operational.apex.sampledomain.Impl" + +engine: + +executors: + +JAVASCRIPT: +"org.onap.policy.apex.plugins.executor.javascript.JavascriptExecutorParameters" + +inputs: + +first_consumer: + +carrier_technology: + +label: "RESTCLIENT", + +plugin_parameter_class_name: +"org.onap.policy.apex.plugins.event.carrier.restclient.RestClientCarrierTechnologyParameters", + +parameters: + +url: "https://localhost:32801/EventGenerator/GetEvents" + +event_protocol: + +label: "JSON" + +outputs: + +first_producer: + +carrier_technology: + +label: "RESTCLIENT", + +plugin_parameter_class_name: +"org.onap.policy.apex.plugins.event.carrier.restclient.RestClientCarrierTechnologyParameters", + +parameters: + +url: "https://localhost:32801/EventGenerator/PostEvent" + +event_protocol: + +label: "JSON" + +3.2.2.3 Guard Policy Create/Update +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +TBD `Pamela Dragosh <file://localhost/display/~pdragosh>`__ Similar to +Operational Policies + +3.2.2.4 Policy Lifecycle API - Creating Coordination Policies +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +TBD Similar to Operational Policies, stretch for Dublin + +3.2.3 Policy Delete +~~~~~~~~~~~~~~~~~~~ + +The API also allows Policies to be deleted with a DELETE operation. The +format of the delete operation is as below: + +=========================================================================================================================================== ========================================================================================================================================= +**Example** **Description** +=========================================================================================================================================== ========================================================================================================================================= +*https:{url}:{port}/policy/api/v1/policytypes/onap.policies.monitoring.cdap.tca.hi.lo.app/versions/1.0.0/policies/onap.scaleout.tca DELETE* Deletes a Policy - all versions will be deleted. + + NOTE: The API call will fail if the policy has been deployed in one or more PDP Group. They must be undeployed first from all PDP Groups. +=========================================================================================================================================== ========================================================================================================================================= + +3.3 Policy Administration API +----------------------------- + +The purpose of this API is to support CRUD of PDP groups and subgroups +and to support the deployment and life cycles of *PolicyImpl* entities +(TOSCA *Policy* and *PolicyTypeImpl* entities) on PDP sub groups and +PDPs. See Section 2 for details on policy deployment on PDP groups and +subgroups. This API is provided by the *PolicyAdministration* component +(PAP) of the Policy Framework, see `The ONAP Policy +Framework <file://localhost/display/DW/The+ONAP+Policy+Framework>`__ +architecture. + +PDP groups and subgroups may be prefedined in the system. Predefined +groups and subgroups may not be modified or deleted over this API. +However, the policies running on predefined groups or subgroups as well +as the instance counts and properties may be modified. + +A PDP may be preconfigured with its PDP group, PDP subgroup, and +policies. The PDP sends this information to the PAP when it starts. If +the PDP group, subgroup, or any policy is unknown to the PAP, the PAP +locks the PDP in state PASSIVE. + +The fields below are valid on API calls: + +============= ====================== ======================== ========== ========================================================================= ===================================================================== ============================================================================================== +**Field** **GET** **POST** **DELETE** **Comment** +============= ====================== ======================== ========== ========================================================================= ===================================================================== ============================================================================================== +name M M M The name of the PDP group +version O M C The version of the PDP group +state R N/A N/A The administrative state of the PDP group: PASSIVE, SAFE, TEST, or ACTIVE +description R O N/A The PDP group description +properties R O N/A Specific properties for a PDP group +pdp_subgroups R M N/A A list of PDP subgroups for a PDP group +\ pdp_type R M N/A The PDP type of this PDP subgroup, currently xacml, drools, or apex +\ supported_policy_types R N/A N/A A list of the policy types supported by the PDPs in this PDP subgroup +\ policies R M N/A The list of policies running on the PDPs in this PDP subgroup +\ (name) R M N/A The name of a TOSCA policy running in this PDP subgroup +\ policy_type R N/A N/A The TOSCA policy type of the policy +\ policy_type_version R N/A N/A The version of the TOSCA policy type of the policy +\ policy_type_impl R C N/A The policy type implementation (XACML, Drools Rules, or APEX Model) that implements the policy +\ instance_count R N/A N/A The number of PDP instances running in a PDP subgroup +\ min_instance_count O N/A N/A The minumum number of PDP instances to run in a PDP subgroup +\ properties O N/A N/A Deployment configuration or other properties for the PDP subgroup +\ deployment_info R N/A N/A Information on the deployment for a PDP subgroup +\ instances R N/A N/A A list of PDP instances running in a PDP subgroup +\ instance R N/A N/A The instance ID of a PDP running in a Kuberenetes Pod +\ state R N/A N/A The administrative state of the PDP: PASSIVE, SAFE, TEST, or ACTIVE +\ healthy R N/A N/A The result of the latest health check on the PDP: HEALTHY/NOT_HEALTHY/TEST_IN_PROGRESS +\ message O N/A N/A A status message for the PDP if any +\ deployment_instance_info R N/A N/A Information on the node running the PDP +============= ====================== ======================== ========== ========================================================================= ===================================================================== ============================================================================================== + +Note: In the Dublin release, the *policy_type_impl* of all policy types +in a PDP subgroup must be the same. + +YAML is used for illustrative purposes in the examples in this section. +JSON (application/json) will be used as the content type in the +implementation of this API. + +3.3.1 PDP Group Query +~~~~~~~~~~~~~~~~~~~~~ + +This operation allows the PDP groups and subgroups to be listed together +with the policies that are deployed on each PDP group and subgroup. + +*https:{url}:{port}/policy/pap/v1/pdps GET* + +**PDP Group query for all PDP groups and Subgroups** Expand source + +pdp_groups: + +- name: onap.pdpgroup.controlloop.Operational + +version: 1.0.0 + +state: active + +description: ONAP Control Loop Operational and Guard policies + + properties: + +# PDP group level properties if any + +pdp_subgroups: + +pdp_type: drools + +supported_policy_types: + +- onap.controllloop.operational.drools.vCPE + +- onap.controllloop.operational.drools.vFW + + policies: + +- onap.controllloop.operational.drools.vCPE.eastRegion: + +policy_type: onap.controllloop.operational.drools.vCPE + +policy_type_version: 1.0.0 + +policy_type_impl: onap.controllloop.operational.drools.impl + +- onap.controllloop.operational.drools.vFW.eastRegion: + +policy_type: onap.controllloop.operational.drools.vFW + +policy_type_version: 1.0.0 + +policy_type_impl: onap.controllloop.operational.drools.impl + +min_instance_count: 3 + + instance_count: 3 + +properties: + +# The properties below are for illustration only + +instance_spawn_load_threshold: 70% + +instance_kill_load_threshold: 50% + +instance_geo_redundancy: true + +deployment_info: + +service_endpoint: https://<the drools service endpoint for this PDP +group> + +deployment: A deployment identifier + +# Other deployment info + +instances: + +- instance: drools_1 + +state: active + +healthy: yes + +deployment_instance_info: + +node_address: drools_1_pod + +# Other deployment instance info + +- instance: drools_2 + +state: active + +healthy: yes + + deployment_instance_info: + +node_address: drools_2_pod + +# Other deployment instance info + +- instance: drools_3 + +state: active + +healthy: yes + + deployment_instance_info: + +node_address: drools_3_pod + +# Other deployment instance info + +- pdp_type: apex + +supported_policy_types: + +- onap.controllloop.operational.apex.BBS + +- onap.controllloop.operational.apex.SampleDomain + +policies: + +- onap.controllloop.operational.apex.BBS.eastRegion: + +policy_type: onap.controllloop.operational.apex.BBS + +policy_type_version: 1.0.0 + +policy_type_impl: onap.controllloop.operational.apex.impl + +- onap.controllloop.operational.apex.sampledomain.eastRegion: + +policy_type: onap.controllloop.operational.apex.SampleDomain + +policy_type_version: 1.0.0 + +policy_type_impl: onap.controllloop.operational.apex.impl + +min_instance_count: 2 + + instance_count: 3 + +properties: + +# The properties below are for illustration only + +instance_spawn_load_threshold: 80% + +instance_kill_load_threshold: 60% + +instance_geo_redundancy: true + +deployment_info: + +service_endpoint: https://<the apex service endpoint for this PDP group> + +deployment: A deployment identifier + +# Other deployment info + +instances: + +- instance: apex_1 + +state: active + +healthy: yes + + deployment_instance_info: + +node_address: apex_1_podgroup + +# Other deployment instance info + +- instance: apex_2 + +deployment_instance_info: + +node_address: apex_2_pod + +# Other deployment instance infoCreation + +- instance: apex_3 + +state: active + +healthy: yes + + deployment_instance_info: + +node_address: apex_3_pod + +# Other deployment instance info + +- pdp_type: xacml + +supported_policy_types: + +- onap.policies.controlloop.guard.FrequencyLimiter + + - onap.policies.controlloop.guard.BlackList + +- onap.policies.controlloop.guard.MinMax + +policies: + +- onap.policies.controlloop.guard.frequencylimiter.EastRegion: + +policy_type: onap.policies.controlloop.guard.FrequencyLimiter + +policy_type_version: 1.0.0 + +policy_type_impl: onap.controllloop.guard.impl + +- onap.policies.controlloop.guard.blackList.EastRegion: + +policy_type: onap.policies.controlloop.guard.BlackList + +policy_type_version: 1.0.0 + +policy_type_impl: onap.controllloop.guard.impl + +- onap.policies.controlloop.Guard.MinMax.EastRegion: + +policy_type: onap.policies.controlloop.guard.MinMax + +policy_type_version: 1.0.0 + +policy_type_impl: onap.controllloop.guard.impl + +min_instance_count: 2 + + instance_count: 2 + +properties: + +# The properties below are for illustration only + +instance_geo_redundancy: true + +deployment_info: + +service_endpoint: https://<the XACML service endpoint for this PDP +group> + +deployment: A deployment identifier + +# Other deployment info + +instances: + +- instance: xacml_1 + +state: active + +healthy: yes + + deployment_instance_info: + +node_address: xacml_1_pod + +# Other deployment instance info + +- instance: xacml_2 + +state: active + +healthy: yes + + deployment_instance_info: + +node_address: xacml_2_pod + +# Other deployment instance info + +- name: onap.pdpgroup.monitoring + +version: 2.1.3 + +state: active + +description: DCAE mS Configuration Policies + +properties: + +# PDP group level properties if any + +pdp_subgroups: + +- pdp_type: xacml + +supported_policy_types: + +- onap.policies.monitoring.cdap.tca.hi.lo.app + +policies: + +- onap.scaleout.tca: + +policy_type: onap.policies.monitoring.cdap.tca.hi.lo.app + +policy_type_version: 1.0.0 + +policy_type_impl: onap.policies.monitoring.impl + +min_instance_count: 2 + + instance_count: 2 + +properties: + +# The properties below are for illustration only + +instance_geo_redundancy: true + +deployment_info: + +service_endpoint: https://<the XACML service endpoint for this PDP +group> + +deployment: A deployment identifier + +# Other deployment info + +instances: + +- instance: xacml_1 + +state: active + +healthy: yes + + deployment_instance_info: + +node_address: xacml_1_pod + +# Other deployment instance info + +- instance: xacml_2 + +state: active + +healthy: yes + + deployment_instance_info: + +node_address: xacml_2_pod + +# Other deployment instance info + +The table below shows some more examples of GET operations + +======================================================================================= ================================================================ +**Example** **Description** +======================================================================================= ================================================================ +*https:{url}:{port}/policy/pap/v1/pdps* Get all PDP Groups and subgroups in the system +*https:{url}:{port}/policy/pap/v1/pdps/groups/onap.pdpgroup.controlloop* Get PDP Groups and subgroups that match the supplied name filter +*https:{url}:{port}/policy/pap/v1/pdps/groups/onap.pdpgroup.monitoring/subgroups/xacml* Get the PDP subgroup informtation for the specified subgroup +\ +======================================================================================= ================================================================ + +3.3.2 PDP Group Deployment +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This operation allows the PDP groups and subgroups to be created. A POST +operation is used to create a new PDP group name. A POST operation is +also used to update an existing PDP group. Many PDP groups can be +created or updated in a single POST operation by specifying more than +one PDP group in the POST operation body. + +*https:{url}:{port}/policy/pap/v1/pdps POST* + +**POST body to deploy or update PDP groups** Expand source + +pdp_groups: + +- name: onap.pdpgroup.controlloop.operational + +description: ONAP Control Loop Operational and Guard policies + +pdp_subgroups: + +- pdp_type: drools + +supportedPolicyTypes: + +- onap.controllloop.operational.drools.vcpe.EastRegion + +version: 1.2.3 + +- onap.controllloop.operational.drools.vfw.EastRegion + +version: 1.2.3 + +min_instance_count: 3group + +properties: + +# The properties below are for illustration only + +instance_spawn_load_threshold: 70% + +instance_kill_load_threshold: 50% + +instance_geo_redundancy: true + +- pdp_type: apex + +policies: + +- onap.controllloop.operational.apex.bbs.EastRegion + +version: 1.2.3 + +- onap.controllloop.operational.apex.sampledomain.EastRegion + +version: 1.2.3 + +min_instance_count: 2 + +properties: + +# The properties below are for illustration only + +instance_spawn_load_threshold: 80% + +instance_kill_load_threshold: 60% + +instance_geo_redundancy: true + +- pdp_type: xacml + +policies: + +- onap.policies.controlloop.guard.frequencylimiter.EastRegion + +version: 1.2.3 + +- onap.policies.controlloop.guard.blacklist.EastRegion + +version: 1.2.3 + +- onap.policies.controlloop.guard.minmax.EastRegion + +version: 1.2.3 + +min_instance_count: 2 + +properties: + +# The properties below are for illustration only + +instance_geo_redundancy: true + +- name: onap.pdpgroup.monitoring + +description: DCAE mS Configuration Policies + +properties: + +# PDP group level properties if any + +pdp_subgroups: + +- pdp_type: xacml + +policies: + +- onap.scaleout.tca + +version: 1.2.3 + +min_instance_count: 2 + +properties: + +# The properties below are for illustration only + +instance_geo_redundancy: true + +Other systems such as CLAMP can use this API to deploy policies using a +POST operation with the body below where only mandatory fields are +specified. + +*https:{url}:{port}/policy/pap/v1/pdps POST* + +**POST body to deploy or update PDP groups** Expand source + +pdp_groups: + +- name: onap.pdpgroup.Monitoring + +description: DCAE mS Configuration Policies + +pdp_subgroups: + +- pdp_type: xacml + +policies: + +- onap.scaleout.tca + +Simple API for CLAMP to deploy one or more policy-id's with optional policy-version. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +*https:{url}:{port}/policy/pap/v1/pdps/policies POST* + +Content-Type: application/json + +{ + +"policies" : [ + +{ + +"policy-id": "onap.scaleout.tca", + +"policy-version": 1 + +}, + +{ + +"policy-id": "ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3" + +}, + +{ + +"policy-id": +"guard.frequency.ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3" + +}, + +{ + +"policy-id": +"guard.minmax.ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3" + +} + +] + +} + +HTTP status code indicates success or failure.{ + +"errorDetails": "some error message" + +} + +Simple API for CLAMP to undeploy a policy-id with optional policy-version. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +*https:{url}:{port}/policy/pap/v1/pdps/policies{policy-id} DELETE* + +*https:{url}:{port}/policy/pap/v1/pdps/policies{policy-id}/versions/{policy-version} +DELETE* + +HTTP status code indicates success or failure. + +{ + +"errorDetails": "some error message" + +} + +3.3.3 PDP Group Delete +~~~~~~~~~~~~~~~~~~~~~~ + +The API also allows PDP groups to be deleted with a DELETE operation. +DELETE operations are only permitted on PDP groups in PASSIVE state. The +format of the delete operation is as below: + +*https:{url}:{port}/policy/pap/v1/pdps/groups/onap.pdpgroup.monitoring +DELETE* + +3.3.4 PDP Group State Management +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The state of PDP groups is managed by the API. PDP groups can be in +states PASSIVE, TEST, SAFE, or ACTIVE. For a full description of PDP +group states, see `The ONAP Policy +Framework <file://localhost/display/DW/The+ONAP+Policy+Framework>`__ +architecture page. The state of a PDP group is changed with a PUT +operation. + +The following PUT operation changes a PDP group to ACTIVE: + +*https:{url}:{port}/policy/pap/v1/pdps/groups/onap.pdpgroup.monitoring/state=active* + +There are a number of rules for state management: + +1. Only one version of a PDP group may be ACTIVE at any time + +2. If a PDP group with a certain version is ACTIVE and a later version + of the same PDP group is activated, then the system upgrades the PDP + group + +3. If a PDP group with a certain version is ACTIVE and an earlier + version of the same PDP group is activated, then the system + downgrades the PDP group + +4. There is no restriction on the number of PASSIVE versions of a PDP + group that can exist in the system + +5. <Rules on SAFE/TEST> ? `Pamela + Dragosh <file://localhost/display/~pdragosh>`__ + +3.3.5 PDP Group Statistics +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This operation allows statistics for PDP groups, PDP subgroups, and +individual PDPs to be retrieved. + +*https:{url}:{port}/policy/pap/v1/pdps/statistics GET* + +**Draft Example statistics returned for a PDP Group** Expand source + +report_timestamp: 2019-02-11T15:23:50+00:00 + +pdp_group_count: 2 + +pdp_groups: + +- name: onap.pdpgroup.controlloop.Operational + +state: active + +create_timestamp: 2019-02-11T15:23:50+00:00 + +update_timestamp: 2019-02-12T15:23:50+00:00 + +state_change_timestamp: 2019-02-13T15:23:50+00:00 + +pdp_subgroups: + +- pdp_type: drools + +instance_count: 3 + +deployed_policy_count: 2 + +policy_execution_count: 123 + +policy_execution_ok_count: 121 + +policy_execution_fail_count: 2 + +instances: + +- instance: drools_1 + +start_timestamp: 2019-02-13T15:23:50+00:00 + +policy_execution_count: 50 + +policy_execution_ok_count: 49 + +policy_execution_fail_count: 1 + +- instance: drools_2 + +start_timestamp: 2019-02-13T15:30:50+00:00 + +policy_execution_count: 50 + +policy_execution_ok_count: 49 + +policy_execution_fail_count: 1 + +- instance: drools_3 + +start_timestamp: 2019-02-13T15:33:50+00:00 + +policy_execution_count: 23 + +policy_execution_ok_count: 23 + +policy_execution_fail_count: 0 + +The table below shows some more examples of GET operations for +statistics + +================================================================================================== =================================================================================== +**Example** **Description** +================================================================================================== =================================================================================== +*https:{url}:{port}/policy/pap/v1/pdps/statistics* Get statistics for all PDP Groups and subgroups in the system +*https:{url}:{port}/policy/pap/v1/pdps/groups/onap.pdpgroup.controlloop/statistics* Get statistics for all PDP Groups and subgroups that match the supplied name filter +*https:{url}:{port}/policy/pap/v1/pdps/groups/onap.pdpgroup.monitoring/subgroups/xacml/statistics* Get statistics for the specified subgroup +\ +================================================================================================== =================================================================================== + +3.3.6 PDP Group Health Check +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A PDP group health check allows ordering of health checks on PDP groups +and on individual PDPs. As health checks may be long lived operations, +Health checks are scheduled for execution by this operation. Users check +the result of a health check test by issuing a PDP Group Query operation +(see Section 3.3.1) and checking the *healthy* field of PDPs. + +*https:{url}:{port}/policy/pap/v1/pdps/healthcheck PUT* + +The operation returns a HTTP status code of 202: Accepted if the health +check request has been accepted by the PAP. The PAP then orders +execution of the health check on the PDPs. The health check result is +retrieved with a subsequent GET operation. + +The table below shows some more examples of PUT operations for ordering +health checks + +======================================================================================================= ======================================================================================== +**Example** **Description** +======================================================================================================= ======================================================================================== +*https:{url}:{port}/policy/pap/v1/pdps/healthcheck PUT* Order a health check on all PDP Groups and subgroups in the system +*https:{url}:{port}/policy/pap/v1/pdps/groups/onap.pdpgroup.controlloop/healthcheck PUT* Order a health check on all PDP Groups and subgroups that match the supplied name filter +*https:{url}:{port}/policy/pap/v1/pdps/groups/onap.pdpgroup.monitoring/subgroups/xacml/healthcheck PUT* Order a health check on the specified subgroup +\ +======================================================================================================= ======================================================================================== + +3.4 Policy Decision API - Getting Policy Decisions +-------------------------------------------------- + +Policy decisions are required by ONAP components to support the +policy-driven ONAP architecture. Policy Decisions are implemented using +the XACML PDP. The calling application must provide attributes in order +for the XACML PDP to return a correct decision. + +3.4.1 Decision API Schema +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The schema for the decision API is defined below. + +3.4.2 Decision API Queries +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Decision API queries are implemented with a POST operation with a JSON +body that specifies the filter for the policies to be returned. The JSON +body must comply with the schema sepcified in Section 3.4.1. + +*https:{url}:{port}/decision/v1/ POST* + +* +*\ Description of the JSON Payload for the decision API Call + +================================================================================================================ ======= ======== ========================================================================== +**Field** **R/O** **Type** **Description** +================================================================================================================ ======= ======== ========================================================================== +ONAPName R String Name of the ONAP Project that is making the request. +ONAPComponent O String Name of the ONAP Project component that is making the request. +ONAPInstance O String Optional instance identification for that ONAP component. +action R String The action that the ONAP component is performing on a resource. + + eg. "configure" → DCAE uS onap.Monitoring policy Decisions to configure uS + + "naming" + + "placement" + + "guard" +These sub metadata structures are used to refine which resource the ONAP component is performing an action upon. + +At least one is required in order for Policy to return a Decision. + +Multiple structures may be utilized to help refine a Decision. +policy-type-name String The policy type name. This may be a regular expression. +policy-id String The policy id. This may be a regular expression or an exact value. +\ +\ +\ +================================================================================================================ ======= ======== ========================================================================== + +This example below shows the JSON body of a query for a specify +policy-id + +**Decision API Call - Policy ID** + +{ + +"ONAPName": "DCAE", + +"ONAPComponent": "PolicyHandler", + +"ONAPInstance": "622431a4-9dea-4eae-b443-3b2164639c64", + +"action": "configure", + +"resource": { + +"policy-id": "onap.scaleout.tca" + +} + +} + +**Decision Response - Single Policy ID query** + +{ + +"policies": { + +"onap.scaleout.tca": { + +"type": "onap.policies.monitoring.cdap.tca.hi.lo.app", + +"version": "1.0.0", + +"metadata": { + +"policy-id": "onap.scaleout.tca", + +"policy-version": 1 + +}, + +"properties": { + +"tca_policy": { + +"domain": "measurementsForVfScaling", + +"metricsPerEventName": [ + +{ + +"eventName": "vLoadBalancer", + +"controlLoopSchemaType": "VNF", + +"policyScope": "type=configuration", + +"policyName": "onap.scaleout.tca", + +"policyVersion": "v0.0.1", + +"thresholds": [ + +{ + +"closedLoopControlName": +"ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3", + +"closedLoopEventStatus": "ONSET", + +"version": "1.0.2", + +"fieldPath": +"$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedBroadcastPacketsAccumulated", + +"thresholdValue": 500, + +"direction": "LESS_OR_EQUAL", + +"severity": "MAJOR" + +}, + +{ + +"closedLoopControlName": +"ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3", + +"closedLoopEventStatus": "ONSET", + +"version": "1.0.2", + +"fieldPath": +"$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedBroadcastPacketsAccumulated", + +"thresholdValue": 5000, + +"direction": "GREATER_OR_EQUAL", + +"severity": "CRITICAL" + +} + +] + +} + +] + +} + +} + +} + +} + +} + +* +* + +This example below shows the JSON body of a query for a multiple +policy-id's + +**Decision API Call - Policy ID** + +{ + +"ONAPName": "DCAE", + +"ONAPComponent": "PolicyHandler", + +"ONAPInstance": "622431a4-9dea-4eae-b443-3b2164639c64", + +"action": "configure", + +"resource": { + +"policy-id": [ + +"onap.scaleout.tca", + +"onap.restart.tca" + +] + +} + +} + +The following is the response object: + +**Decision Response - Single Policy ID query** + +{ + +"policies": { + +"onap.scaleout.tca": { + +"type": "onap.policies.monitoring.cdap.tca.hi.lo.app", + +"version": "1.0.0", + +"metadata": { + +"policy-id": "onap.scaleout.tca" + +}, + +"properties": { + +"tca_policy": { + +"domain": "measurementsForVfScaling", + +"metricsPerEventName": [ + +{ + +"eventName": "vLoadBalancer", + +"controlLoopSchemaType": "VNF", + +"policyScope": "type=configuration", + +"policyName": "onap.scaleout.tca", + +"policyVersion": "v0.0.1", + +"thresholds": [ + +{ + +"closedLoopControlName": +"ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3", + +"closedLoopEventStatus": "ONSET", + +"version": "1.0.2", + +"fieldPath": +"$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedBroadcastPacketsAccumulated", + +"thresholdValue": 500, + +"direction": "LESS_OR_EQUAL", + +"severity": "MAJOR" + +}, + +{ + +"closedLoopControlName": +"ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3", + +"closedLoopEventStatus": "ONSET", + +"version": "1.0.2", + +"fieldPath": +"$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedBroadcastPacketsAccumulated", + +"thresholdValue": 5000, + +"direction": "GREATER_OR_EQUAL", + +"severity": "CRITICAL" + +} + +] + +} + +] + +} + +} + +}, + +"onap.restart.tca": { + +"type": "onap.policies.monitoring.cdap.tca.hi.lo.app", + +"version": "1.0.0", + +"metadata": { + +"policy-id": "onap.restart.tca", + +"policy-version": 1 + +}, + +"properties": { + +"tca_policy": { + +"domain": "measurementsForVfScaling", + +"metricsPerEventName": [ + +{ + +"eventName": "Measurement_vGMUX", + +"controlLoopSchemaType": "VNF", + +"policyScope": "DCAE", + +"policyName": "DCAE.Config_tca-hi-lo", + +"policyVersion": "v0.0.1", + +"thresholds": [ + +{ + +"closedLoopControlName": +"ControlLoop-vCPE-48f0c2c3-a172-4192-9ae3-052274181b6e", + +"version": "1.0.2", + +"fieldPath": +"$.event.measurementsForVfScalingFields.additionalMeasurements[*].arrayOfFields[0].value", + +"thresholdValue": 0, + +"direction": "EQUAL", + +"severity": "MAJOR", + +"closedLoopEventStatus": "ABATED" + +}, + +{ + +"closedLoopControlName": +"ControlLoop-vCPE-48f0c2c3-a172-4192-9ae3-052274181b6e", + +"version": "1.0.2", + +"fieldPath": +"$.event.measurementsForVfScalingFields.additionalMeasurements[*].arrayOfFields[0].value", + +"thresholdValue": 0, + +"direction": "GREATER", + +"severity": "CRITICAL", + +"closedLoopEventStatus": "ONSET" + +} + +] + +} + +] + +} + +} + +} + +} + +} + +* +* + +The simple draft example below shows the JSON body of a query in which +all the deployed policies for a specific policy type are returned. + +{ + +"ONAPName": "DCAE", + +"ONAPComponent": "PolicyHandler", + +"ONAPInstance": "622431a4-9dea-4eae-b443-3b2164639c64", + +"action": "configure", + +"resource": { + +"policy-type": "onap.policies.monitoring.cdap.tca.hi.lo.app" + +} + +} + +The query above gives a response similar to the example shown below. + +{ + +"policies": { + +"onap.scaleout.tca": { + +"type": "onap.policies.monitoring.cdap.tca.hi.lo.app", + +"version": "1.0.0", + +"metadata": { + +"policy-id": "onap.scaleout.tca", + +"policy-version": 1, + +}, + +"properties": { + +"tca_policy": { + +"domain": "measurementsForVfScaling", + +"metricsPerEventName": [ + +{ + +"eventName": "vLoadBalancer", + +"controlLoopSchemaType": "VNF", + +"policyScope": "type=configuration", + +"policyName": "onap.scaleout.tca", + +"policyVersion": "v0.0.1", + +"thresholds": [ + +{ + +"closedLoopControlName": +"ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3", + +"closedLoopEventStatus": "ONSET", + +"version": "1.0.2", + +"fieldPath": +"$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedBroadcastPacketsAccumulated", + +"thresholdValue": 500, + +"direction": "LESS_OR_EQUAL", + +"severity": "MAJOR" + +}, + +{ + +"closedLoopControlName": +"ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3", + +"closedLoopEventStatus": "ONSET", + +"version": "1.0.2", + +"fieldPath": +"$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedBroadcastPacketsAccumulated", + +"thresholdValue": 5000, + +"direction": "GREATER_OR_EQUAL", + +"severity": "CRITICAL" + +} + +] + +} + +] + +} + +} + +}, + +"onap.restart.tca": { + +"type": "onap.policies.monitoring.cdap.tca.hi.lo.app", + +"version": "1.0.0", + +"metadata": { + +"policy-id": "onap.restart.tca", + +"policy-version": 1 + +}, + +"properties": { + +"tca_policy": { + +"domain": "measurementsForVfScaling", + +"metricsPerEventName": [ + +{ + +"eventName": "Measurement_vGMUX", + +"controlLoopSchemaType": "VNF", + +"policyScope": "DCAE", + +"policyName": "DCAE.Config_tca-hi-lo", + +"policyVersion": "v0.0.1", + +"thresholds": [ + +{ + +"closedLoopControlName": +"ControlLoop-vCPE-48f0c2c3-a172-4192-9ae3-052274181b6e", + +"version": "1.0.2", + +"fieldPath": +"$.event.measurementsForVfScalingFields.additionalMeasurements[*].arrayOfFields[0].value", + +"thresholdValue": 0, + +"direction": "EQUAL", + +"severity": "MAJOR", + +"closedLoopEventStatus": "ABATED" + +}, + +{ + +"closedLoopControlName": +"ControlLoop-vCPE-48f0c2c3-a172-4192-9ae3-052274181b6e", + +"version": "1.0.2", + +"fieldPath": +"$.event.measurementsForVfScalingFields.additionalMeasurements[*].arrayOfFields[0].value", + +"thresholdValue": 0, + +"direction": "GREATER", + +"severity": "CRITICAL", + +"closedLoopEventStatus": "ONSET" + +} + +] + +} + +] + +} + +} + +}, + +"onap.vfirewall.tca": { + +"type": "onap.policy.monitoring.cdap.tca.hi.lo.app", + +"version": "1.0.0", + +"metadata": { + +"policy-id": "onap.vfirewall.tca", + +"policy-version": 1 + +}, + +"properties": { + +"tca_policy": { + +"domain": "measurementsForVfScaling", + +"metricsPerEventName": [ + +{ + +"eventName": "vLoadBalancer", + +"controlLoopSchemaType": "VNF", + +"policyScope": "resource=vLoadBalancer;type=configuration", + +"policyName": "onap.vfirewall.tca", + +"policyVersion": "v0.0.1", + +"thresholds": [ + +{ + +"closedLoopControlName": +"ControlLoop-vFirewall-d0a1dfc6-94f5-4fd4-a5b5-4630b438850a", + +"closedLoopEventStatus": "ONSET", + +"version": "1.0.2", + +"fieldPath": +"$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedBroadcastPacketsAccumulated", + +"thresholdValue": 500, + +"direction": "LESS_OR_EQUAL", + +"severity": "MAJOR" + +}, + +{ + +"closedLoopControlName": +"ControlLoop-vFirewall-d0a1dfc6-94f5-4fd4-a5b5-4630b438850a", + +"closedLoopEventStatus": "ONSET", + +"version": "1.0.2", + +"fieldPath": +"$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedBroadcastPacketsAccumulated", + +"thresholdValue": 5000, + +"direction": "GREATER_OR_EQUAL", + +"severity": "CRITICAL" + +} + +] + +} + +] + +} + +} + +} + +} + +} + +4. Policy Framework Internal APIs +================================= + +The Policy Framework uses the internal APIs documented in the +subsections below. The APIs in this section are used for internal +communication in the Policy Framework. The APIs are NOT supported for +use by components outside the Policy Framework and are subject to +revision and change at any time. + +4.1 PAP to PDP API +------------------ + +This section describes the API between the PAP and PDPs. The APIs in +this section are implemented using `DMaaP +API <file://localhost/display/DW/DMaaP+API>`__ messaging. There are four +messages on the API: + +1. PDP_STATUS: PDP→PAP, used by PDPs to report to the PAP + +2. PDP_UPDATE: PAP→PDP, used by the PAP to update the policies running + on PDPs, triggers a PDP_STATUS message with the result of the + PDP_UPDATE operation + +3. PDP_STATE_CHANGE: PAP→PDP, used by the PAP to change the state of + PDPs, triggers a PDP_STATUS message with the result of the + PDP_STATE_CHANGE operation + +4. PDP_HEALTH_CHECK: PAP→PDP, used by the PAP to order a heakth check on + PDPs, triggers a PDP_STATUS message with the result of the + PDP_HEALTH_CHECK operation + +The fields below are valid on API calls: + +======================== ============================= ======== ======== ======= ====================================================================================================================================== ================================================================================================================================================================================================== +**Field** **PDP **PDP **PDP **PDP **Comment** + STATUS** UPDATE** STATE HEALTH + CHANGE** CHECK** +======================== ============================= ======== ======== ======= ====================================================================================================================================== ================================================================================================================================================================================================== +(message_name) M M M M pdp_status, pdp_update, pdp_state_change, or pdp_health_check +name M M C C The name of the PDP, for state changes and health checks, the PDP group and subgroup can be used to specify the scope of the operation +version M N/A N/A N/A The version of the PDP +pdp_type M M N/A N/A The type of the PDP, currently xacml, drools, or apex +state M N/A M N/A The administrative state of the PDP group: PASSIVE, SAFE, TEST, ACTIVE, or TERMINATED +healthy M N/A N/A N/A The result of the latest health check on the PDP: HEALTHY/NOT_HEALTHY/TEST_IN_PROGRESS +description O O N/A N/A The description of the PDP +pdp_group O M C C The PDP group to which the PDP belongs, the PDP group and subgroup can be used to specify the scope of the operation +pdp_subgroup O M C C The PDP subgroup to which the PDP belongs, the PDP group and subgroup can be used to specify the scope of the operation +supported_policy_types M N/A N/A N/A A list of the policy types supported by the PDP +policies O M N/A N/A The list of policies running on the PDP +\ (name) O M N/A N/A The name of a TOSCA policy running on the PDP +\ policy_type O M N/A N/A The TOSCA policy type of the policyWhen a PDP starts, it commences periodic sending of *PDP_STATUS* messages on DMaaP. The PAP receives these messages and acts in whatever manner is appropriate. +\ policy_type_version O M N/A N/A The version of the TOSCA policy type of the policy +\ properties O M N/A N/A The properties of the policy for the XACML, Drools, or APEX PDP, see section 3.2 for details +instance M N/A N/A N/A The instance ID of the PDP running in a Kuberenetes Pod +deployment_instance_info M N/A N/A N/A Information on the node running the PDP +properties O O N/A N/A Other properties specific to the PDP +statistics M N/A N/A N/A Statistics on policy execution in the PDP +\ policy_download_count M N/A N/A N/A The number of policies downloaded into the PDP +\ policy_download_success_count M N/A N/A N/A The number of policies successfully downloaded into the PDP +\ policy_download_fail_count M N/A N/A N/A The number of policies downloaded into the PDP where the download failed +\ policy_executed_count M N/A N/A N/A The number of policy executions on the PDP +\ policy_executed_success_count M N/A N/A N/A The number of policy executions on the PDP that completed successfully +\ policy_executed_fail_count M N/A N/A N/A The number of policy executions on the PDP that failed +response O N/A N/A N/A The response to the last operation that the PAP executed on the PDP +\ response_to M N/A N/A N/A The PAP to PDP message to which this is a response +\ response_status M N/A N/A N/A SUCCESS or FAIL +\ response_message O N/A N/A N/A Message giving further information on the successful or failed operation +======================== ============================= ======== ======== ======= ====================================================================================================================================== ================================================================================================================================================================================================== + +YAML is used for illustrative purposes in the examples in this section. +JSON (application/json) is used as the content type in the +implementation of this API. + +| Note: The PAP checks that the set of policy types supported in all + PDPs in a PDP subgroup are identical and will not add a PDP to a PDP + subgroup that has a different set of supported policy types +| Note: The PA checks that the set of policy loaded on all PDPs in a PDP + subgroup are are identical and will not add a PDP to a PDP subgroup + that has a different set of loaded policies + +4.1.1 PAP API for PDPs +~~~~~~~~~~~~~~~~~~~~~~ + +The purpose of this API is for PDPs to provide heartbeat, status. +health, and statistical information to Policy Administration. There is a +single *PDP_STATUS* message on this API. PDPs send this message to the +PAP using the *POLICY_PDP_PAP* DMaaP topic. The PAP listens on this +topic for messages. + +When a PDP starts, it commences periodic sending of *PDP_STATUS* +messages on DMaaP. The PAP receives these messages and acts in whatever +manner is appropriate. *PDP_UPDATE*, *PDP_STATE_CHANGE*, and +*PDP_HEALTH_CHECK* operations trigger a *PDP_STATUS* message as a +response. + +The *PDP_STATUS* message is used for PDP heartbeat monitoring. A PDP +sends a *PDP_STATUS* message with a state of \ *TERMINATED* when it +terminates normally. If a \ *PDP_STATUS* message is not received from a +PDP in a certain configurable time, then the PAP assumes the PDP has +failed. + +A PDP may be preconfigured with its PDP group, PDP subgroup, and +policies. If the PDP group, subgroup, or any policy sent to the PAP in a +*PDP_STATUS* message is unknown to the PAP, the PAP locks the PDP in +state PASSIVE. + +**PDP_STATUS message from an XACML PDP running control loop policies** + Expand source + +pdp_status: + +name: xacml_1 + +version: 1.2.3 + +pdp_type: xacml + +state: active + +healthy: true + + description: XACML PDP running control loop policies + +pdp_group: onap.pdpgroup.controlloop.operational + +pdp_subgroup: xacml + +supported_policy_types: + +- onap.policies.controlloop.guard.FrequencyLimiter + +- onap.policies.controlloop.guard.BlackList + +- onap.policies.controlloop.guard.MinMax + + policies: + +- onap.policies.controlloop.guard.frequencylimiter.EastRegion: + +policy_type: onap.policies.controlloop.guard.FrequencyLimiter + +policy_type_version: 1.0.0 + +properties: + +# Omitted for brevity, see Section 3.2 + + - onap.policies.controlloop.guard.blacklist.eastRegion: + +policy_type: onap.policies.controlloop.guard.BlackList + +policy_type_version: 1.0.0 + +properties: + +# Omitted for brevity, see Section 3.2 + +- onap.policies.controlloop.guard.minmax.eastRegion: + +policy_type: onap.policies.controlloop.guard.MinMax + +policy_type_version: 1.0.0 + +properties: + +# Omitted for brevity, see Section 3.2 + +instance: xacml_1 + +deployment_instance_info: + +node_address: xacml_1_pod + +# Other deployment instance info + +statistics: + +policy_download_count: 0 + +policy_download_success_count: 0 + +policy_download_fail_count: 0 + +policy_executed_count: 123 + +policy_executed_success_count: 122 + +policy_executed_fail_count: 1 + +**PDP_STATUS message from a Drools PDP running control loop policies** + Expand source + +pdp_status: + +name: drools_2 + +version: 2.3.4 + +pdp_type: drools + +state: safe + +healthy: true + + description: Drools PDP running control loop policies + +pdp_group: onap.pdpgroup.controlloop.operational + +pdp_subgroup: drools + +supported_policy_types: + +- onap.controllloop.operational.drools.vCPE + + - onap.controllloop.operational.drools.vFW + +policies: + +- onap.controllloop.operational.drools.vcpe.EastRegion: + +policy_type: onap.controllloop.operational.drools.vCPE + +policy_type_version: 1.0.0 + +properties: + +# Omitted for brevity, see Section 3.2 + +- onap.controllloop.operational.drools.vfw.EastRegion: + +policy_type: onap.controllloop.operational.drools.vFW + +policy_type_version: 1.0.0 + +properties: + +# Omitted for brevity, see Section 3.2 + +instance: drools_2 + +deployment_instance_info: + +node_address: drools_2_pod + +# Other deployment instance info + +statistics: + +policy_download_count: 3 + +policy_download_success_count: 3 + +policy_download_fail_count: 0 + +policy_executed_count: 123 + +policy_executed_success_count: 122 + +policy_executed_fail_count: 1 + +response: + +response_to: PDP_HEALTH_CHECK + +response_status: SUCCESS + +**PDP_STATUS message from an APEX PDP running control loop policies** + Expand source + +pdp_status: + +name: apex_3 + +version: 2.2.1 + +pdp_type: apex + +state: test + +healthy: true + + description: APEX PDP running control loop policies + +pdp_group: onap.pdpgroup.controlloop.operational + +pdp_subgroup: apex + +supported_policy_types: + +- onap.controllloop.operational.apex.BBS + +- onap.controllloop.operational.apex.SampleDomain + +policies: + +- onap.controllloop.operational.apex.bbs.EastRegion: + +policy_type: onap.controllloop.operational.apex.BBS + +policy_type_version: 1.0.0 + +properties: + +# Omitted for brevity, see Section 3.2 + +- onap.controllloop.operational.apex.sampledomain.EastRegion: + +policy_type: onap.controllloop.operational.apex.SampleDomain + +policy_type_version: 1.0.0 + +properties: + +# Omitted for brevity, see Section 3.2 + +instance: apex_3 + +deployment_instance_info:node_address + +node_address: apex_3_pod + +# Other deployment instance info + +statistics: + +policy_download_count: 2 + +policy_download_success_count: 2 + +policy_download_fail_count: 0 + +policy_executed_count: 123 + +policy_executed_success_count: 122 + +policy_executed_fail_count: 1 + +response: + +response_to: PDP_UPDATE + +response_status: FAIL + +response_message: policies specified in update message incompatible with +running policy state + +**PDP_STATUS message from an XACML PDP running monitoring policies** + Expand source + +pdp_status: + + name: xacml_1 + +version: 1.2.3 + +pdp_type: xacml + +state: active + +healthy: true + + description: XACML PDP running monitoring policies + +pdp_group: onap.pdpgroup.Monitoring + +pdp_subgroup: xacml + +supported_policy_types: + +- onap.monitoring.cdap.tca.hi.lo.app + +policies: + +- onap.scaleout.tca:message + +policy_type: onap.policies.monitoring.cdap.tca.hi.lo.app + +policy_type_version: 1.0.0 + +properties: + +# Omitted for brevity, see Section 3.2 + +instance: xacml_1 + +deployment_instance_info: + +node_address: xacml_1_pod + +# Other deployment instance info + +statistics: + +policy_download_count: 0 + +policy_download_success_count: 0 + +policy_download_fail_count: 0 + +policy_executed_count: 123 + +policy_executed_success_count: 122 + +policy_executed_fail_count: 1 + +4.1.2 PDP API for PAPs +~~~~~~~~~~~~~~~~~~~~~~ + +The purpose of this API is for the PAP to load and update policies on +PDPs and to change the state of PDPs. It also allows the PAP to order +health checks to run on PDPs. The PAP sends \ *PDP_UPDATE*, \ *PDP\_* +STATE_CHANGE, and *PDP_HEALTH_CHECK* messages to PDPs using the +*POLICY_PAP_PDP* DMaaP topic. PDPs listens on this topic for messages. + +The PAP can set the scope of STATE_CHANGE, and *PDP_HEALTH_CHECK* +messages: + +- PDP Group: If a PDP group is specified in a message, then the PDPs in + that PDP group respond to the message and all other PDPs ignore it. + +- PDP Group and subgroup: If a PDP group and subgroup are specified in + a message, then only the PDPs of that subgroup in the PDP group + respond to the message and all other PDPs ignore it. + +- Single PDP: If the name of a PDP is specified in a message, then only + that PDP responds to the message and all other PDPs ignore it. + +Note: *PDP_UPDATE* messages must be issued individually to PDPs because +the *PDP_UPDATE* operation can change the PDP group to which a PDP +belongs. + +4.1.2.1 PDP Update +^^^^^^^^^^^^^^^^^^ + +The *PDP_UPDATE* operation allows the PAP to modify the PDP group to +which a PDP belongs and the policies in a PDP. Only PDPs in state +PASSIVE accept this operation. The PAP must change the state of PDPs in +state ACTIVE, TEST, or SAFE to state PASSIVE before issuing a +*PDP_UPDATE* operation on a PDP. + +The following examples illustrate how the operation is used. + +**PDP_UPDATE message to upgrade XACML PDP control loop policies to +versino 1.0.1** Expand source + +pdp_update: + +name: xacml_1 + +pdp_type: xacml + +description: XACML PDP running control loop policies, Upgraded + +pdp_group: onap.pdpgroup.controlloop.operational + +pdp_subgroup: xacml + +policies: + +- onap.policies.controlloop.guard.frequencylimiter.EastRegion: + +policy_type: onap.policies.controlloop.guard.FrequencyLimiter + +policy_type_version: 1.0.1 + +properties: + +# Omitted for brevity, see Section 3.2 + +- onap.policies.controlloop.guard.blackList.EastRegion: + +policy_type: onap.policies.controlloop.guard.BlackList + +policy_type_version: 1.0.1 + +properties: + +# Omitted for brevity, see Section 3.2 + +- onap.policies.controlloop.guard.minmax.EastRegion: + +policy_type: onap.policies.controlloop.guard.MinMax + +policy_type_version: 1.0.1 + +properties: + +# Omitted for brevity, see Section 3.2 + +**PDP_UPDATE message to a Drools PDP to add an extra control loop +policy** Expand source + +pdp_update: + +name: drools_2 + +pdp_type: drools + +description: Drools PDP running control loop policies, extra policy +added + +pdp_group: onap.pdpgroup.controlloop.operational + +pdp_subgroup: drools + +policies: + +- onap.controllloop.operational.drools.vcpe.EastRegion: + +policy_type: onap.controllloop.operational.drools.vCPE + +policy_type_version: 1.0.0 + +properties: + +# Omitted for brevity, see Section 3.2 + +- onap.controllloop.operational.drools.vfw.EastRegion: + +policy_type: onap.controllloop.operational.drools.vFW + +policy_type_version: 1.0.0 + +properties: + +# Omitted for brevity, see Section 3.2 + +- onap.controllloop.operational.drools.vfw.WestRegion: + +policy_type: onap.controllloop.operational.drools.vFW + +policy_type_version: 1.0.0 + +properties: + +# Omitted for brevity, see Section 3.2 + +**PDP_UPDATE message to an APEX PDP to remove a control loop policy** + Expand source + +pdp_update: + +name: apex_3 + +pdp_type: apex + + description: APEX PDP updated to remove a control loop policy + +pdp_group: onap.pdpgroup.controlloop.operational + +pdp_subgroup: apex + +policies: + +- onap.controllloop.operational.apex.bbs.EastRegion: + +policy_type: onap.controllloop.operational.apex.BBS + +policy_type_version: 1.0.0 + +properties: + +# Omitted for brevity, see Section 3.2 + +4.1.2.2 PDP State Change +^^^^^^^^^^^^^^^^^^^^^^^^ + +The *PDP_STATE_CHANGE* operation allows the PAP to order state changes +on PDPs in PDP groups and subgroups. The following examples illustrate +how the operation is used. + +**Change the state of all control loop Drools PDPs to ACTIVE** Expand +source + +pdp_state_change: + +state: active + +pdp_group: onap.pdpgroup.controlloop.Operational + +pdp_subgroup: drools + +**Change the state of all monitoring PDPs to SAFE** Expand source + +pdp_state_change: + +state: safe + +pdp_group: onap.pdpgroup.Monitoring + +**Change the state of a single APEX PDP to TEST** Expand source + +pdp_state_change: + +state: test + +name: apex_3 + +4.1.2.3 PDP Health Check +^^^^^^^^^^^^^^^^^^^^^^^^ + +The *PDP_HEALTH_CHECK* operation allows the PAP to order health checks +on PDPs in PDP groups and subgroups. The following examples illustrate +how the operation is used. + +**Perform a health check on all control loop Drools PDPs** Expand +source + +pdp_health_check: + +pdp_group: onap.pdpgroup.controlloop.Operational + +pdp_subgroup: drools + +**perform a health check on all monitoring PDPs** Expand source + +pdp_health_check: + +pdp_group: onap.pdpgroup.Monitoring + +**Perform a health check on a single APEX PDP** Expand source + +pdp_health_check: + +name: apex_3 + +4.2 Policy Type Implementations (Native Policies) +------------------------------------------------- + +The policy Framework must have implementations for all Policy Type +entities that may be specified in TOSCA. Policy type implementations are +native policies for the various PDPs supported in the Policy Framework. +They may be predefined and preloaded into the Policy Framework. In +addition, they may also be added, modified, queried, or deleted using +this API during runtime. + +The API supports CRUD of *PolicyTypeImpl* policy type implementations, +where the XACML, Drools, and APEX policy type implementations are +supplied as strings. This API is provided by the *PolicyDevelopment* +component of the Policy Framework, see `The ONAP Policy +Framework <file://localhost/display/DW/The+ONAP+Policy+Framework>`__ +architecture. + +| Note that client-side editing support for TOSCA *PolicyType* + definitions or for *PolicyTypeImpl* implementations in XACML, Drools, + or APEX is outside the current scope of the API. +| Note: Preloaded policy type implementations may only be queried over + this API, modification or deletion of preloaded policy type + implementations is disabled. +| Note: Policy type implementations that are in use (referenced by + defined Policies) may not be deleted. + +The fields below are valid on API calls: + +=========== ======= ======== ========== ========================================================================================================================== +**Field** **GET** **POST** **DELETE** **Comment** +=========== ======= ======== ========== ========================================================================================================================== +name M M M The name of the Policy Type implementation +version O M C The version of the Policy Type implementation +policy_type R M N/A The TOSCA policy type that this policy type implementation implements +pdp_type R M N/A The PDP type of this policy type implementation, currently xacml, drools, or apex +description R O N/A The description of the policy type implementation +writable R N/A N/A Writable flag, false for predefined policy type implementations, true for policy type implementations defined over the API +policy_body R M N/A The body (source) of the policy type implementation +properties R O N/A Specific properties for the policy type implementation +=========== ======= ======== ========== ========================================================================================================================== + +4.2.1 Policy Type Implementation Query +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This operation allows the PDP groups and subgroups to be listed together +with the policies that are deployed on each PDP group and subgroup. + +*https:{url}:{port}/policy/api/v1/native/onap.policies.controlloop.operational/impls +GET* + +**Policy Type Implementation Query Result** Expand source + +policy_type_impls: + +- name: onap.policies.controlloop.operational.drools.Impl + +version: 1.0.0 + +policy_type: onap.policies.controlloop.Operational + +pdp_type: drools + +description: Implementation of the drools control loop policies + +writable: false + +- name: onap.policies.controlloop.operational.apex.bbs.Impl + +version: 1.0.0 + +policy_type: onap.policies.controlloop.operational.Apex + +pdp_type: apex + +description: Implementation of the APEX BBS control loop policy + +writable: true + +policy_body: "<policy body>" + +- name: onap.policies.controlloop.operational.apex.sampledomain.Impl + +version: 1.0.0 + +policy_type: onap.policies.controlloop.operational.Apex + +pdp_type: apex + +description: Implementation of the SampleDomain test APEX policy + +writable: true + +policy_body: "<policy body>" + +The table below shows some more examples of GET operations + +========================================================================================================================================================================= ========================================================================================================================================================== +**Example** **Description** +========================================================================================================================================================================= ========================================================================================================================================================== +*https:{url}:{port}/policy/api/v1/native/{policy type id}/impls* Get all Policy Type implementations for the given policy type + +| *eg.* +| *https:{url}:{port}/policy/api/v1/native/onap.policies.monitoring/impls* +| *https:{url}:{port}/policy/api/v1/native/onap.policies.controlloop.operational.apex/impls* +*https:{url}:{port}/policy/api/v1/native/{policy type id}/impls/{policy type impl id}* Get all Policy Type implementation versions that match the policy type and policy type implementation IDs specified + +| *eg.* +| *https:{url}:{port}/policy/api/v1/native/onap.policies.controlloop.operational/impls/onap.policies.controlloop.operational.drools.impl* +| *https:{url}:{port}/policy/api/v1/native/onap.policies.controlloop.operational.apex/impls/onap.policies.controlloop.operational.apex.sampledomain.impl* +*https:{url}:{port}/policy/api/v1/native/{policy type id}/impls/{policy type impl id}/versions/{version id}* Get the specific Policy Type implementation with the specified name and version, if the version ID is specified a *latest*, the latest version is returned + +| *eg.* +| *https:{url}:{port}/policy/api/v1/native/onap.policies.controlloop.operational/impls/onap.policies.controlloop.operational.drools.impl/versions/1.2.3* +| *https:{url}:{port}/policy/api/v1/native/onap.policies.controlloop.operational.apex/impls/onap.policies.controlloop.operational.apex.sampledomain.impl/versions/latest* +========================================================================================================================================================================= ========================================================================================================================================================== + +4.2.2 Policy Type Implementation Create/Update +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The API allows users (such as a policy editor or DevOps system) to +create or update a Policy Type implementation using a POST operation. +This API allows new Policy Type implementations to be created or +existing Policy Type implementations to be modified. POST operations +with a new name or a new version of an existing name are used to create +a new Policy Type implementation. POST operations with an existing name +and version are used to update an existing Policy Type implementations. +Many implementations can be created or updated in a single POST +operation by specifying more than one Policy Type implementation on the +*policy_type_impls* list. + +For example, the POST operation below with the YAML body below is used +to create a new APEX Policy type implementation. + +*https:{url}:{port}/policy/api/v1/native/onap.policies.controlloop.operational.apex/impls +POST* + +**Create a new Policy Type Implementation** Expand source + +policy_type_impls: + +- onap.policies.controlloop.operational.apex.bbs.Impl: + +version: 1.0.0 + +policy_type: onap.policies.controlloop.operational.Apex + +pdp_type: apex + +description: Implementation of the APEX BBS control loop policy + +policy_body: "<policy body>" + +- onap.policies.controlloop.operational.apex.sampledomain.Impl: + +version: 1.0.0 + +policy_type: onap.policies.controlloop.operational.Apex + +pdp_type: apex + +description: Implementation of the APEX SampleDomain control loop policy + +policy_body: "<policy body> + +Once this call is made, the Policy Type query in Section 3.1.2.1 returns +a result with the new Policy Type implementation defined. + +4.2.3 Policy Type Implementation Delete +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The API also allows Policy Type implementations to be deleted with a +DELETE operation. The format of the delete operation is as below: + +*https:{url}:{port}/api/v1/native/onap.policies.controlloop.operational.apex/impls/onap.policies.apex.bbs.impl/versions/1.0.0 +DELETE* + +| Note: Predefined policy type implementations cannot be deleted +| Note: Policy type implementations that are in use (Parameterized by a + TOSCA Policy) may not be deleted, the parameterizing TOSCA policies + must be deleted first +| Note: The *version* parameter may be omitted on the DELETE operation + if there is only one version of the policy type implementation in the + system diff --git a/docs/design/tosca-policy-primer.rst b/docs/design/tosca-policy-primer.rst new file mode 100644 index 00000000..bc35abc7 --- /dev/null +++ b/docs/design/tosca-policy-primer.rst @@ -0,0 +1,57 @@ +.. This work is licensed under a +.. Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +.. _tosca-label: + +TOSCA Policy Primer +------------------- + +.. contents:: + :depth: 1 + +Policy Type +~~~~~~~~~~~ + +A Policy Type is used to specify the types of policies that may be used in a service. The parameter definitions for a policy of this type, the entity types to which it applies, and what triggers policies of this type may be specified. + +The types of policies that are used in a service are defined in the policy_types section of the TOSCA service template as a Policy Type. More formally, TOSCA defines a Policy Type as an artifact that "defines a type of requirement that affects or governs an application or service’s topology at some stage of its lifecycle, but is not explicitly part of the topology itself". In the definition of a Policy Type in TOSCA, you specify: + +* its properties, which define the type of configuration parameters that the policy takes +* its targets, which define the node types and/or groups to which the policy type applies +* its triggers, which specify the conditions in which policies of this type are fired + +Policy +~~~~~~ + +A Policy is used to specify the actual instances of policies that are used in a service. The parameter values of the policy and the actual entities to which it applies may be specified. + +The policies that are used in a service are defined in the policies section of the TOSCA topology template as a Policy. More formally, TOSCA defines a Policy as an artifact that "defines a policy that can be associated with a TOSCA topology or top-level entity definition". In the definition of a Policy in TOSCA, you specify: + +* its properties, which define the values of the configuration parameters that the policy takes +* its targets, which define the node types and/or group types to which the policy type applies + +Note that policy triggers are specified on the Policy Type definition and are not specified on the Policy itself. + +Trigger +~~~~~~~ + +A Trigger defines an event, condition, and action that is used to initiate execution of a policy associated with it. The definition of the Trigger allows specification of the type of events to trigger on, the filters on those events, conditions and constraints for trigger firing, the action to perform on triggering, and various other parameters. + +The triggers that are used in a service are defined as reusable modules in the TOSCA service template as a Trigger. More formally, TOSCA defines a Trigger as an artifact that "defines the event, condition and action that is used to “trigger” a policy it is associated with". In the definition of a Trigger in TOSCA, you specify: + +* its event_type, which defines the name of the event that fires the policy +* its schedule, which defines the time interval in which the trigger is active +* its target_filter, which defines specific filters for firing such as specific characteristics of the nodes or relations for which the trigger should or should not fire +* its condition, which defines extra conditions on the incoming event for firing the trigger +* its constraint, which defines extra conditions on the incoming event for not firing the trigger +* its period, which defines the period to use for evaluating conditions and constraints +* its evaluations, which defines the number of evaluations that must be performed over the period to assert the condition or constraint exists +* its method, the method to use for evaluation of conditions and constraints +* its action, the workflow or operation to invoke when the trigger fires + +Note that how a Trigger actually works with a Policy is not clear from the specification. + + +End of Document + diff --git a/docs/development/development.rst b/docs/development/development.rst new file mode 100644 index 00000000..4f583bf7 --- /dev/null +++ b/docs/development/development.rst @@ -0,0 +1,328 @@ +.. This work is licensed under a +.. Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + + +Policy Platform Development +--------------------------- + +.. contents:: + :depth: 2 + + +This article explains how to build the ONAP Policy Framework for development purposes. To start, the developer should consult the latest ONAP Wiki to familiarize themselves with developer best practices and how-tos to setup their environment, see `https://wiki.onap.org/display/DW/Developer+Best+Practices`. + + +This article assumes that: + +* You are using a *\*nix* operating system such as linux or macOS. +* You are using a directory called *git* off your home directory *(~/git)* for your git repositories +* Your local maven repository is in the location *~/.m2/repository* +* You have added settings to access the ONAP Nexus to your M2 configuration, see `Maven Settings Example <https://wiki.onap.org/display/DW/Setting+Up+Your+Development+Environment>`_ (bottom of the linked page) + +The procedure documented in this article has been verified to work on a MacBook laptop running macOS Yosemite Version 10.10,5, Sierra Version 10.12.6, a HP Z600 desktop running Ubuntu 16.04.3 LTS, and an Unbuntu 16.04 VM. + +Cloning All The Policy Repositories +----------------------------------- + +Run a script such as the script below to clone the required modules from the `ONAP git repository <https://gerrit.onap.org/r/#/admin/projects/?filter=policy>`_. This script clones all the ONAP Policy Framework repositories. + +ONAP Policy Framework has dependencies to the ONAP Parent *oparent* module, the ONAP ECOMP SDK *ecompsdkos* module, and the A&AI Schema module. + + +.. code-block:: bash + :caption: Typical ONAP Policy Framework Clone Script + :linenos: + + #!/usr/bin/env bash + + ## script name for output + MOD_SCRIPT_NAME=`basename $0` + + ## the ONAP clone directory, defaults to "onap" + clone_dir="onap" + + ## the ONAP repos to clone + onap_repos="\ + policy/parent \ + policy/common \ + policy/models \ + policy/docker \ + policy/api \ + policy/pap \ + policy/apex-pdp \ + policy/drools-pdp \ + policy/drools-applications \ + policy/xacml-pdp \ + policy/engine \ + policy/distribution" + + ## + ## Help screen and exit condition (i.e. too few arguments) + ## + Help() + { + echo "" + echo "$MOD_SCRIPT_NAME - clones all required ONAP git repositories" + echo "" + echo " Usage: $MOD_SCRIPT_NAME [-options]" + echo "" + echo " Options" + echo " -d - the ONAP clone directory, defaults to '.'" + echo " -h - this help screen" + echo "" + exit 255; + } + + ## + ## read command line + ## + while [ $# -gt 0 ] + do + case $1 in + #-d ONAP clone directory + -d) + shift + if [ -z "$1" ]; then + echo "$MOD_SCRIPT_NAME: no clone directory" + exit 1 + fi + clone_dir=$1 + shift + ;; + + #-h prints help and exists + -h) + Help;exit 0;; + + *) echo "$MOD_SCRIPT_NAME: undefined CLI option - $1"; exit 255;; + esac + done + + if [ -f "$clone_dir" ]; then + echo "$MOD_SCRIPT_NAME: requested clone directory '$clone_dir' exists as file" + exit 2 + fi + if [ -d "$clone_dir" ]; then + echo "$MOD_SCRIPT_NAME: requested clone directory '$clone_dir' exists as directory" + exit 2 + fi + + mkdir $clone_dir + if [ $? != 0 ] + then + echo cannot clone ONAP repositories, could not create directory '"'$clone_dir'"' + exit 3 + fi + + for repo in $onap_repos + do + repoDir=`dirname "$repo"` + repoName=`basename "$repo"` + + if [ ! -z $dirName ] + then + mkdir "$clone_dir/$repoDir" + if [ $? != 0 ] + then + echo cannot clone ONAP repositories, could not create directory '"'$clone_dir/repoDir'"' + exit 4 + fi + fi + + git clone https://gerrit.onap.org/r/${repo} $clone_dir/$repo + done + + echo ONAP has been cloned into '"'$clone_dir'"' + + +Execution of the script above results in the following directory hierarchy in your *~/git* directory: + + * ~/git/onap + * ~/git/onap/policy + * ~/git/onap/policy/parent + * ~/git/onap/policy/common + * ~/git/onap/policy/models + * ~/git/onap/policy/api + * ~/git/onap/policy/pap + * ~/git/onap/policy/docker + * ~/git/onap/policy/drools-applications + * ~/git/onap/policy/drools-pdp + * ~/git/onap/policy/engine + * ~/git/onap/policy/apex-pdp + * ~/git/onap/policy/xacml-pdp + * ~/git/onap/policy/distribution + + +Building ONAP Policy Framework Components +----------------------------------------- + +**Step 1:** Optionally, for a completely clean build, remove the ONAP built modules from your local repository. + + .. code-block:: bash + + rm -fr ~/.m2/repository/org/onap + rm -fr ~/.m2/repository/org/openecomp + rm -fr ~/.m2/repisotory/com/att + + +**Step 2:** A pom such as the one below can be used to build the ONAP Policy Framework modules. Create the *pom.xml* file in the directory *~/git/onap/policy*. + +.. code-block:: xml + :caption: Typical pom.xml to build the ONAP Policy Framework + :linenos: + + <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> + <modelVersion>4.0.0</modelVersion> + <groupId>org.onap</groupId> + <artifactId>onap-policy</artifactId> + <version>1.0.0-SNAPSHOT</version> + <packaging>pom</packaging> + <name>${project.artifactId}</name> + <inceptionYear>2017</inceptionYear> + <organization> + <name>ONAP</name> + </organization> + + <modules> + <module>parent</module> + <module>common</module> + <module>models</module> + <module>api</module> + <module>pap</module> + <module>apex-pdp</module> + <module>xacml-pdp</module> + <module>drools-pdp</module> + <module>drools-applications</module> + <!-- The engine repo is being deprecated, + and can be ommitted if not working with + legacy api and components. --> + <module>engine</module> + <module>distribution</module> + </modules> + </project> + +Policy Architecture/API Transition +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In Dublin, a new Policy Architecture was introduced. The legacy architecture runs in parallel with the new architecture. It will be deprecated after Frankfurt release. + +If the developer is only interested in working with the new architecture components, the engine sub-module can be ommitted. + + +**Step 3:** You can now build the Policy framework + + .. code-block:: bash + + cd ~/git/onap + mvn clean install + + + +Building the ONAP Policy Framework Docker Images +------------------------------------------------ +The instructions here are based on the instructions in the file *~/git/onap/policy/docker/README.md*. + +TODO - Add the policy/docker step?? + +**Step 1:** Build the Policy API Docker image + +TODO + +**Step 2:** Build the Policy PAP Docker image + +TODO + +**Step 3:** Build the Drools PDP docker image. + +This image is a standalone vanilla Drools engine, which does not contain any pre-built drools rules or applications. + + .. code-block:: bash + + cd ~/git/onap/policy/drools-pdp/packages/docker/target + docker build -t onap/policy-drools policy-drools + +**Step 4:** Build the Drools Application Control Loop image. + +This image has the drools use case application and the supporting software built together with the Drools PDP engine. It is recommended to use this image if you are first working with ONAP Policy and wish to test or learn how the use cases work. + + +TODO + + +**Step 5:** Build the Apex PDP docker image: + + .. code-block:: bash + + cd ~/git/onap/policy/apex-pdp/packages/apex-pdp-docker/target + docker build -t onap/policy-apex-pdp policy-apex-pdp + +**Step 5:** Build the XACML PDP docker image: + + .. code-block:: bash + + cd ~/git/onap/policy/xacml-pdp/packages/xacml-pdp-docker/target + docker build -t onap/policy-xacml-pdp policy-xacml-pdp + +**Step 7:** Build the policy engine docker image (If working with the legacy Policy Architecture/API): + + .. code-block:: bash + + cd ~/git/onap/policy/engine/packages/docker/target + docker build -t onap/policy-pe policy-pe + + +**Step 8:** Build the Policy SDC Distribution docker image: + + .. code-block:: bash + + cd ~/git/onap/policy/distribution/packages + mvn clean install -Pdocker + + +Starting the ONAP Policy Framework Docker Images +------------------------------------------------ + +TODO - update this section + +In order to run the containers, you can use *docker-compose*. This uses the *docker-compose.yml* yaml file to bring up the ONAP Policy Framework. This file is located in the policy/docker repository. + +**Step 1:** Make the file config/drools/drools-tweaks.sh executable. + + .. code-block:: bash + + chmod +x config/drools/drools-tweaks.sh + + +**Step 2:** Set the IP address to use to be an IP address of a suitable interface on your machine. Save the IP address into the file *config/pe/ip_addr.txt*. + + +**Step 3:** Set the environment variable *MTU* to be a suitable MTU size for the application. + + .. code-block:: bash + + export MTU=9126 + + +**Step 4:** Determine if you want policies pre-loaded or not. By default, all the configuration and operational policies will be pre-loaded by the docker compose script. If you do not wish for that to happen, then export this variable: + + .. code-block:: bash + + export PRELOAD_POLICIES=false + + +**Step 5:** Run the system using *docker-compose*. Note that on some systems you may have to run the *docker-compose* command as root or using *sudo*. Note that this command takes a number of minutes to execute on a laptop or desktop computer. + + .. code-block:: bash + + docker-compose up + + +**You now have a full standalone ONAP Policy framework up and running!** + + + + + +End of Document + diff --git a/docs/drools/drools.rst b/docs/drools/drools.rst new file mode 100644 index 00000000..90bd05a5 --- /dev/null +++ b/docs/drools/drools.rst @@ -0,0 +1,12 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +.. _drools-label: + +Policy Drools PDP Engine +------------------------ +.. toctree:: + :maxdepth: 1 + + + +End of Document diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 00000000..36eee8e6 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,15 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +Policy Framework Architecture +----------------------------- +.. toctree:: + :maxdepth: 1 + +architecture/architecture.rst +design/design.rst +installation/installation.rst +development/development.rst +release-notes.rst + + +End of Document diff --git a/docs/installation/docker.rst b/docs/installation/docker.rst new file mode 100644 index 00000000..6652c114 --- /dev/null +++ b/docs/installation/docker.rst @@ -0,0 +1,16 @@ +.. This work is licensed under a +.. Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + + +Policy Docker Installation +-------------------------- + +.. contents:: + :depth: 2 + + + + +End of Document + diff --git a/docs/installation/installation.rst b/docs/installation/installation.rst new file mode 100644 index 00000000..1c3cbd10 --- /dev/null +++ b/docs/installation/installation.rst @@ -0,0 +1,18 @@ +.. This work is licensed under a +.. Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + + +Policy Component Installation +----------------------------- + +.. contents:: + :depth: 2 + + +oom.rst +docker.rst + + +End of Document + diff --git a/docs/installation/oom.rst b/docs/installation/oom.rst new file mode 100644 index 00000000..a22d7b7e --- /dev/null +++ b/docs/installation/oom.rst @@ -0,0 +1,16 @@ +.. This work is licensed under a +.. Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + + +Policy OOM Installation +----------------------- + +.. contents:: + :depth: 2 + + + + +End of Document + diff --git a/docs/pap/pap.rst b/docs/pap/pap.rst new file mode 100644 index 00000000..a7edc64f --- /dev/null +++ b/docs/pap/pap.rst @@ -0,0 +1,13 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +.. _pap-label: + +Policy Administration Point (PAP) Architecture +---------------------------------------------- +.. toctree:: + :maxdepth: 1 + + + + +End of Document diff --git a/docs/release-notes.rst b/docs/release-notes.rst new file mode 100644 index 00000000..618ba297 --- /dev/null +++ b/docs/release-notes.rst @@ -0,0 +1,385 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +Policy Release Notes +==================== + +.. note +.. * This Release Notes must be updated each time the team decides to Release new artifacts. +.. * The scope of these Release Notes are for ONAP POLICY. In other words, each ONAP component has its Release Notes. +.. * This Release Notes is cumulative, the most recently Released artifact is made visible in the top of +.. * this Release Notes. +.. * Except the date and the version number, all the other sections are optional but there must be at least +.. * one section describing the purpose of this new release. +.. * This note must be removed after content has been added. + + +.. ========================== +.. * * * CASABLANCA * * * +.. ========================== + +Version: 3.0.2 +-------------- + +:Release Date: 2019-03-31 (Casablanca Maintenance Release #2) + +The following items were deployed with the Casablanca Maintenance Release: + +**Bug Fixes** + + * [POLICY-1522] - Policy doesn't send "payload" field to APPC + +**Security Fixes** + + * [POLICY-1538] - Upgrade Elasticsearch to 6.4.x to clear security issue + +**License Issues** + + * [POLICY-1433] - Remove proprietary licenses in PSSD test CSAR + + +Version: 3.0.1 +-------------- + +:Release Date: 2019-01-31 (Casablanca Maintenance Release) + +The following items were deployed with the Casablanca Maintenance Release: + +**New Features** + + * [POLICY-1221] - Policy distribution application to support HTTPS communication + * [POLICY-1222] - Apex policy PDP to support HTTPS Communication + +**Bug Fixes** + + * `[POLICY-1282] <https://jira.onap.org/browse/POLICY-1282>`_ - Policy format with some problems + * `[POLICY-1395] <https://jira.onap.org/browse/POLICY-1395>`_ - Apex PDP does not preserve context on model upgrade + + +Version: 3.0.0 +-------------- + +:Release Date: 2018-11-30 (Casablanca Release) + +**New Features** + +The Casablanca release for POLICY delivered the following Epics. For a full list of stories and tasks delivered in the Casablanca release, refer to `JiraPolicyCasablanca`_ (Note: Jira details can also be viewed from this link). + + * [POLICY-701] - This epic covers the work to integrate Policy into the SDC Service Distribution + + The policy team introduced a new application into the framework that provides integration of the Service Distribution Notifications from SDC to Policy. + + * [POLICY-719] - This epic covers the work to build the Policy Lifecycle API + * [POLICY-726] - This epic covers the work to distribute policy from the PAP to the PDPs into the ONAP platform + * [POLICY-876] - This epics covers the work to re-build how the PAP organizes the PDP's into groups. + + The policy team did some forward looking spike work towards re-building the Software Architecture. + + * [POLICY-809] - Maintain and implement performance + * [POLICY-814] - 72 hour stability testing (component and platform) + + The policy team made enhancements to the Drools PDP to further support S3P Performance. + For the new Policy SDC Distribution application and the newly ingested Apex PDP the team established S3P + performance standard and performed 72 hour stability tests. + + * [POLICY-824] - maintain and implement security + + The policy team established AAF Root Certificate for HTTPS communication and CADI/AAF integration into the + MVP applications. In addition, many java dependencies were upgraded to clear CLM security issues. + + * [POLICY-840] - Flexible control loop coordination facility. + + Work towards a POC for control loop coordination policies were implemented. + + * [POLICY-841] - Covers the work required to support HPA + + Enhancements were made to support the HPA use case through the use of the new Policy SDC Service Distribution application. + + * [POLICY-842] - This epic covers the work to support the Auto Scale Out functional requirements + + Enhancements were made to support Scale Out Use Case to enforce new guard policies and updated SO and A&AI APIs. + + * [POLICY-851] - This epic covers the work to bring in the Apex PDP code + + A new Apex PDP engine was ingested into the platform and work was done to ensure code cleared CLM security issues, + sonar issues, and checkstyle. + + * [POLICY-1081] - This epic covers the contribution for the 5G OOF PCI Optimization use case. + + Policy templates changes were submitted that supported the 5G OOF PCI optimization use case. + + * [POLICY-1182] - Covers the work to support CCVPN use case + + Policy templates changes were submitted that supported the CCVPN use case. + +**Bug Fixes** + +The following bug fixes have been deployed with this release: + + * `[POLICY-799] <https://jira.onap.org/browse/POLICY-799>`_ - Policy API Validation Does Not Validate Required Parent Attributes in the Model + * `[POLICY-869] <https://jira.onap.org/browse/POLICY-869>`_ - Control Loop Drools Rules should not have exceptions as well as die upon an exception + * `[POLICY-872] <https://jira.onap.org/browse/POLICY-872>`_ - investigate potential race conditions during rules version upgrades during call loads + * `[POLICY-878] <https://jira.onap.org/browse/POLICY-878>`_ - pdp-d: feature-pooling disables policy-controllers preventing processing of onset events + * `[POLICY-909] <https://jira.onap.org/browse/POLICY-909>`_ - get_ZoneDictionaryDataByName class type error + * `[POLICY-920] <https://jira.onap.org/browse/POLICY-920>`_ - Hard-coded path in junit test + * `[POLICY-921] <https://jira.onap.org/browse/POLICY-921>`_ - XACML Junit test cannot find property file + * `[POLICY-1083] <https://jira.onap.org/browse/POLICY-1083>`_ - Mismatch in action cases between Policy and APPC + + +**Security Notes** + +POLICY code has been formally scanned during build time using NexusIQ and all Critical vulnerabilities have been addressed, items that remain open have been assessed for risk and determined to be false positive. The POLICY open Critical security vulnerabilities and their risk assessment have been documented as part of the `project (Casablanca Release) <https://wiki.onap.org/pages/viewpage.action?pageId=45300864>`_. + +Quick Links: + - `POLICY project page <https://wiki.onap.org/display/DW/Policy+Framework+Project>`_ + + - `Passing Badge information for POLICY <https://bestpractices.coreinfrastructure.org/en/projects/1614>`_ + + - `Project Vulnerability Review Table for POLICY (Casablanca Release) <https://wiki.onap.org/pages/viewpage.action?pageId=45300864>`_ + +**Known Issues** + + * `[POLICY-1277] <https://jira.onap.org/browse/POLICY-1277>`_ - policy config takes too long time to become retrievable in PDP + * `[POLICY-1282] <https://jira.onap.org/browse/POLICY-1282>`_ - Policy format with some problems + + + +.. ======================= +.. * * * BEIJING * * * +.. ======================= + +Version: 2.0.0 +-------------- + +:Release Date: 2018-06-07 (Beijing Release) + +**New Features** + +The Beijing release for POLICY delivered the following Epics. For a full list of stories and tasks delivered in the Beijing release, refer to `JiraPolicyBeijing`_. + + * [POLICY-390] - This epic covers the work to harden the Policy platform software base (incl 50% JUnit coverage) + - POLICY-238 policy/drools-applications: clean up maven structure + - POLICY-336 Address Technical Debt + - POLICY-338 Address JUnit Code Coverage + - POLICY-377 Policy Create API should validate input matches DCAE microservice template + - POLICY-389 Cleanup Jenkin's CI/CD process's + - POLICY-449 Policy API + Console : Common Policy Validation + - POLICY-568 Integration with org.onap AAF project + - POLICY-610 Support vDNS scale out for multiple times in Beijing release + + * [POLICY-391] - This epic covers the work to support Release Planning activities + - POLICY-552 ONAP Licensing Scan - Use Restrictions + + * [POLICY-392] - Platform Maturity Requirements - Performance Level 1 + - POLICY-529 Platform Maturity Performance - Drools PDP + - POLICY-567 Platform Maturity Performance - PDP-X + + * [POLICY-394] - This epic covers the work required to support a Policy developer environment in which Policy Developers can create, update policy templates/rules separate from the policy Platform runtime platform. + - POLICY-488 pap should not add rules to official template provided in drools applications + + * [POLICY-398] - This epic covers the body of work involved in supporting policy that is platform specific. + - POLICY-434 need PDP /getConfig to return an indicator of where to find the config data - in config.content versus config field + + * [POLICY-399] - This epic covers the work required to policy enable Hardware Platform Enablement + - POLICY-622 Integrate OOF Policy Model into Policy Platform + + * [POLICY-512] - This epic covers the work to support Platform Maturity Requirements - Stability Level 1 + - POLICY-525 Platform Maturity Stability - Drools PDP + - POLICY-526 Platform Maturity Stability - XACML PDP + + * [POLICY-513] - Platform Maturity Requirements - Resiliency Level 2 + - POLICY-527 Platform Maturity Resiliency - Policy Engine GUI and PAP + - POLICY-528 Platform Maturity Resiliency - Drools PDP + - POLICY-569 Platform Maturity Resiliency - BRMS Gateway + - POLICY-585 Platform Maturity Resiliency - XACML PDP + - POLICY-586 Platform Maturity Resiliency - Planning + - POLICY-681 Regression Test Use Cases + + * [POLICY-514] - This epic covers the work to support Platform Maturity Requirements - Security Level 1 + - POLICY-523 Platform Maturity Security - CII Badging - Project Website + + * [POLICY-515] - This epic covers the work to support Platform Maturity Requirements - Escalability Level 1 + - POLICY-531 Platform Maturity Scalability - XACML PDP + - POLICY-532 Platform Maturity Scalability - Drools PDP + - POLICY-623 Docker image re-design + + * [POLICY-516] - This epic covers the work to support Platform Maturity Requirements - Manageability Level 1 + - POLICY-533 Platform Maturity Manageability L1 - Logging + - POLICY-534 Platform Maturity Manageability - Instantiation < 1 hour + + * [POLICY-517] - This epic covers the work to support Platform Maturity Requirements - Usability Level 1 + - POLICY-535 Platform Maturity Usability - User Guide + - POLICY-536 Platform Maturity Usability - Deployment Documentation + - POLICY-537 Platform Maturity Usability - API Documentation + + * [POLICY-546] - R2 Beijing - Various enhancements requested by clients to the way we handle TOSCA models. + + +**Bug Fixes** + +The following bug fixes have been deployed with this release: + + * `[POLICY-484] <https://jira.onap.org/browse/POLICY-484>`_ - Extend election handler run window and clean up error messages + * `[POLICY-494] <https://jira.onap.org/browse/POLICY-494>`_ - POLICY EELF Audit.log not in ECOMP Standards Compliance + * `[POLICY-501] <https://jira.onap.org/browse/POLICY-501>`_ - Fix issues blocking election handler and add directed interface for opstate + * `[POLICY-509] <https://jira.onap.org/browse/POLICY-509>`_ - Add IntelliJ file to .gitingore + * `[POLICY-510] <https://jira.onap.org/browse/POLICY-510>`_ - Do not enforce hostname validation + * `[POLICY-518] <https://jira.onap.org/browse/POLICY-518>`_ - StateManagement creation of EntityManagers. + * `[POLICY-519] <https://jira.onap.org/browse/POLICY-519>`_ - Correctly initialize the value of allSeemsWell in DroolsPdpsElectionHandler + * `[POLICY-629] <https://jira.onap.org/browse/POLICY-629>`_ - Fixed a bug on editor screen + * `[POLICY-684] <https://jira.onap.org/browse/POLICY-684>`_ - Fix regex for brmsgw dependency handling + * `[POLICY-707] <https://jira.onap.org/browse/POLICY-707>`_ - ONAO-PAP-REST unit tests fail on first build on clean checkout + * `[POLICY-717] <https://jira.onap.org/browse/POLICY-717>`_ - Fix a bug in checking required fields if the object has include function + * `[POLICY-734] <https://jira.onap.org/browse/POLICY-734>`_ - Fix Fortify Header Manipulation Issue + * `[POLICY-743] <https://jira.onap.org/browse/POLICY-743>`_ - Fixed data name since its name was changed on server side + * `[POLICY-753] <https://jira.onap.org/browse/POLICY-753>`_ - Policy Health Check failed with multi-node cluster + * `[POLICY-765] <https://jira.onap.org/browse/POLICY-765>`_ - junit test for guard fails intermittently + + +**Security Notes** + +POLICY code has been formally scanned during build time using NexusIQ and all Critical vulnerabilities have been addressed, items that remain open have been assessed for risk and determined to be false positive. The POLICY open Critical security vulnerabilities and their risk assessment have been documented as part of the `project <https://wiki.onap.org/pages/viewpage.action?pageId=25437092>`_. + +Quick Links: + - `POLICY project page <https://wiki.onap.org/display/DW/Policy+Framework+Project>`_ + + - `Passing Badge information for POLICY <https://bestpractices.coreinfrastructure.org/en/projects/1614>`_ + + - `Project Vulnerability Review Table for POLICY <https://wiki.onap.org/pages/viewpage.action?pageId=25437092>`_ + +**Known Issues** + +The following known issues will be addressed in a future release: + + * `[POLICY-522] <https://jira.onap.org/browse/POLICY-522>`_ - PAP REST APIs undesired HTTP response body for 500 responses + * `[POLICY-608] <https://jira.onap.org/browse/POLICY-608>`_ - xacml components : remove hardcoded secret key from source code + * `[POLICY-764] <https://jira.onap.org/browse/POLICY-764>`_ - Policy Engine PIP Configuration JUnit Test fails intermittently + * `[POLICY-776] <https://jira.onap.org/browse/POLICY-776>`_ - OOF Policy TOSCA models are not correctly rendered + * `[POLICY-799] <https://jira.onap.org/browse/POLICY-799>`_ - Policy API Validation Does Not Validate Required Parent Attributes in the Model + * `[POLICY-801] <https://jira.onap.org/browse/POLICY-801>`_ - fields mismatch for OOF flavorFeatures between implementation and wiki + * `[POLICY-869] <https://jira.onap.org/browse/POLICY-869>`_ - Control Loop Drools Rules should not have exceptions as well as die upon an exception + * `[POLICY-872] <https://jira.onap.org/browse/POLICY-872>`_ - investigate potential race conditions during rules version upgrades during call loads + + + + +Version: 1.0.2 +-------------- + +:Release Date: 2018-01-18 (Amsterdam Maintenance Release) + +**Bug Fixes** + +The following fixes were deployed with the Amsterdam Maintenance Release: + + * `[POLICY-486] <https://jira.onap.org/browse/POLICY-486>`_ - pdp-x api pushPolicy fails to push latest version + + +Version: 1.0.1 +-------------- + +:Release Date: 2017-11-16 (Amsterdam Release) + +**New Features** + +The Amsterdam release continued evolving the design driven architecture of and functionality for POLICY. The following is a list of Epics delivered with the release. For a full list of stories and tasks delivered in the Amsterdam release, refer to `JiraPolicyAmsterdam`_. + + * [POLICY-31] - Stabilization of Seed Code + - POLICY-25 Replace any remaining openecomp reference by onap + - POLICY-32 JUnit test code coverage + - POLICY-66 PDP-D Feature mechanism enhancements + - POLICY-67 Rainy Day Decision Policy + - POLICY-93 Notification API + - POLICY-158 policy/engine: SQL injection Mitigation + - POLICY-269 Policy API Support for Rainy Day Decision Policy and Dictionaries + + * [POLICY-33] - This epic covers the body of work involved in deploying the Policy Platform components + - POLICY-40 MSB Integration + - POLICY-124 Integration with oparent + - POLICY-41 OOM Integration + - POLICY-119 PDP-D: noop sinks + + * [POLICY-34] - This epic covers the work required to support a Policy developer environment in which Policy Developers can create, update policy templates/rules separate from the policy Platform runtime platform. + - POLICY-57 VF-C Actor code development + - POLICY-43 Amsterdam Use Case Template + - POLICY-173 Deployment of Operational Policies Documentation + + * [POLICY-35] - This epic covers the body of work involved in supporting policy that is platform specific. + - POLICY-68 TOSCA Parsing for nested objects for Microservice Policies + + * [POLICY-36] - This epic covers the work required to capture policy during VNF on-boarding. + + * [POLICY-37] - This epic covers the work required to capture, update, extend Policy(s) during Service Design. + - POLICY-64 CLAMP Configuration and Operation Policies for vFW Use Case + - POLICY-65 CLAMP Configuration and Operation Policies for vDNS Use Case + - POLICY-48 CLAMP Configuration and Operation Policies for vCPE Use Case + - POLICY-63 CLAMP Configuration and Operation Policies for VOLTE Use Case + + * [POLICY-38] - This epic covers the work required to support service distribution by SDC. + + * [POLICY-39] - This epic covers the work required to support the Policy Platform during runtime. + - POLICY-61 vFW Use Case - Runtime + - POLICY-62 vDNS Use Case - Runtime + - POLICY-59 vCPE Use Case - Runtime + - POLICY-60 VOLTE Use Case - Runtime + - POLICY-51 Runtime Policy Update Support + - POLICY-328 vDNS Use Case - Runtime Testing + - POLICY-324 vFW Use Case - Runtime Testing + - POLICY-320 VOLTE Use Case - Runtime Testing + - POLICY-316 vCPE Use Case - Runtime Testing + + * [POLICY-76] - This epic covers the body of work involved in supporting R1 Amsterdam Milestone Release Planning Milestone Tasks. + - POLICY-77 Functional Test case definition for Control Loops + - POLICY-387 Deliver the released policy artifacts + + +**Bug Fixes** + - This is technically the first release of POLICY, previous release was the seed code contribution. As such, the defects fixed in this release were raised during the course of the release. Anything not closed is captured below under Known Issues. For a list of defects fixed in the Amsterdam release, refer to `JiraPolicyAmsterdam`_. + + +**Known Issues** + - The operational policy template has been tested with the vFW, vCPE, vDNS and VOLTE use cases. Additional development may/may not be required for other scenarios. + + - For vLBS Use Case, the following steps are required to setup the service instance: + - Create a Service Instance via VID. + - Create a VNF Instance via VID. + - Preload SDNC with topology data used for the actual VNF instantiation (both base and DNS scaling modules). NOTE: you may want to set “vlb_name_0” in the base VF module data to something unique. This is the vLB server name that DCAE will pass to Policy during closed loop. If the same name is used multiple times, the Policy name-query to AAI will show multiple entries, one for each occurrence of that vLB VM name in the OpenStack zone. Note that this is not a limitation, typically server names in a domain are supposed to be unique. + - Instantiate the base VF module (vLB, vPacketGen, and one vDNS) via VID. NOTE: The name of the VF module MUST start with ``Vfmodule_``. The same name MUST appear in the SDNC preload of the base VF module topology. We’ll relax this naming requirement for Beijing Release. + - Run heatbridge from the Robot VM using ``Vfmodule_`` … as stack name (it is the actual stack name in OpenStack) + - Populate AAI with a dummy VF module for vDNS scaling. + +**Security Issues** + - None at this time + +**Other** + - None at this time + + +.. Links to jira release notes + +.. _JiraPolicyCasablanca: https://jira.onap.org/secure/ReleaseNote.jspa?projectId=10106&version=10446 +.. _JiraPolicyBeijing: https://jira.onap.org/secure/ReleaseNote.jspa?projectId=10106&version=10349 +.. _JiraPolicyAmsterdam: https://jira.onap.org/secure/ReleaseNote.jspa?projectId=10106&version=10300 + + +.. note +.. CHANGE HISTORY +.. 01/17/2019 - Updated for Casablanca Maintenance Release. +.. 11/19/2018 - Updated for Casablanca. Also, fixed bugs is a list of bugs where the "Affected Version" is Beijing. +.. Changed version number to use ONAP versions. +.. 10/08/2018 - Initial document for Casablanca release. +.. Per Jorge, POLICY-785 did not get done in Casablanca (removed). +.. 05/29/2018 - Information for Beijing release. +.. 03/22/2018 - Initial document for Beijing release. +.. 01/15/2018 - Added change for version 1.1.3 to the Amsterdam branch. Also corrected prior version (1.2.0) to (1.1.1) +.. Also, Set up initial information for Beijing. +.. Excluded POLICY-454 from bug list since it doesn't apply to Beijing per Jorge. + + +End of Release Notes + +.. How to notes for SS +.. For initial document: list epic and user stories for each, list user stories with no epics. +.. For Bugs section, list bugs that are not tied to an epic. Remove all items with "Won't Do" resolution. +.. For Known issues, list bugs that are slotted for a future release. + + |
