.. This work is licensed under a
.. Creative Commons Attribution 4.0 International License.
.. http://creativecommons.org/licenses/by/4.0
-.. _architecture:
.. _architecture-label:
their policies rather than embedding the decision making in their applications.
The Policy Framework is deployment agnostic, it 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
+of how the PDPs and PEPs are deployed. This allows policy execution and enforcement to 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
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
+development ways of working such as `DevOps
+<https://en.wikipedia.org/wiki/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:
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. A *Policy Type* describes the properties, targets, and triggers that the policy for a feature can have. A Policy type is
+ implementation independent. It is the metadata that specifies:
- a. 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.
+ - the *configuration* data that the policy can take. The Policy Type describes each property that a policy of a
+ given type can take. A Policy Type definition also allows the default value, optionality, and the ranges of properties
+ to be defined.
- b. In ONAP, specific ONAP Policy Types are used to create specific policies that drive the ONAP Platform and
- Components.
+ - the *targets* such as network element types, functions, services, or resources on which a policy of the given type
+ can act.
-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.
+ - the *triggers* such as the event type, filtered event, scheduled trigger, or conditions that can activate a policy
+ of the given type.
+ Policy Types are hierarchical, A Policy Type can inherit from a parent Policy Type, inheriting the properties, targets,
+ and triggers of its parent. Policy Types are developed by domain experts in consultation with the developers that
+ implement the logic and rules for the Policy Type.
+
+ 2. A *Policy* is defined using a Policy Type. The Policy defines:
+
+ - the values for each property of the policy type
+ - the specific targets (network elements, functions, services, resources) on which this policy will act
+ - the specific triggers that trigger this policy.
+
+ 3. A *Policy Type Implementation* or *Raw Policy*, is the logic that implements the policy. It is implemented by a
+ skilled policy developer in consultation with domain experts. The implementation has software that reads the Policy
+ Type and parses the incoming configuration properties. The software has domain logic that is triggered when one of the
+ triggers described in the Policy Type occurs. The software logic executes and acts on the targets specified in the
+ Policy Type.
+
+
+For example, a Policy Type could be written to describe how to manage Service Level Agreements for VPNs. The VPN Policy
+Type can be used to create VPN policies for a bank network, a car dealership network, or a university with many campuses.
+The Policy Type has two parameters:
+
+ - The *maximumDowntime* parameter allows the maximum downtime allowed per year to be specified
+ - The *mitigationStrategy* parameter allows one of three strategies to be selected for downtime breaches
+
+ - *allocateMoreResources*, which will automatically allocate more resources to mitigate the problem
+ - *report*, which report the downtime breach to a trouble ticketing system
+ - *ignore*, which logs the breach and takes no further action
+
+The Policy Type defines a trigger event, an event that is received from an analytics system when the maximum downtime
+value for a VPN is breached. The target of the policy type is an instance of the VPN service.
+
+The Policy Type Implementation is developed that can configure the maximum downtime parameter in an analytics system,
+can receive a trigger from the analytics system when the maximum downtime is breached, and that can either request more
+resources, report an issue to a trouble ticketing system, and can log a breach.
+
+VPN Policies are created by specifying values for the properties, triggers, and targets specified in VPN Policy Type.
+
+In the case of the bank network, the *maximumDowntime* threshold is specified as 5 minutes downtime per year and the
+*mitigationStrategy* is defined as *allocateMoreResources*, and the target is specified as being the bank's VPN service
+ID. When a breach is detected by the analytics system, the policy is executed, the target is identified as being the
+bank's network, and more resources are allocated by the policy.
+
+For the car dealership VPN policy, a less stringent downtime threshold of 60 minutes per year is specified, and the
+mitigation strategy is to issue a trouble ticket. The university network is best effort, so a downtime of 4 days per
+year is specified. Breaches are logged and mitigated as routine network administration tasks.
+
+In ONAP, specific ONAP Policy Types are used to create specific policies that drive the ONAP Platform and Components.
For more detailed information on designing Policy Types and developing an implementation for that policy type, see
:ref:`Policy Design and Development <design-label>`.
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.
+*PolicyDevelopment* provides APIs that allow creation of 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 the database, 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:: images/PFDesignAndAdmin.svg
*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,
+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.
+such as *CLAMP* can use the *PolicyDevelopment* API to create, update, delete, and read 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.
+ up. *PolicyAdministration* handles the allocation of PDPs to PDP Groups and PDP Subgroups, so that they can be
+ managed as microservices in infrastructure management systems such as 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.
- 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 that allows the allocation of policies to 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
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
+For example, assume we have policies for the SON (Self Organizing Network) and ACPS (Advanced Customer Premises Service)
+domains. For SON,we have XACML, Drools, and APEX policies, and for ACPS we have XACML and Drools policies. The table
below shows the resulting \ *PDPGroup*, *PDPSubGroup*, and PDP allocations:
============= ================ ========================= ======================================== ================
scale down on 40% load, be geo-redundant
\ SON-APEX SON-APEX-Dep At Least 3, scale up on 70% load, scale >= 3 PDP-A
down on 40% load, be geo-redundant
-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 >=2 PDP-D
+ACPS ACPS-XACML ACPS-XACML-Dep Always 2 2 PDP-X
+\ ACPS-Drools ACPS-Drools-Dep At Least 2, scale up on 80% load, scale >=2 PDP-D
down on 50% load
============= ================ ========================= ======================================== ================
.. image:: images/ClassStructure.svg
-The UML class diagram above shows the portion of the Policy Framework Object Model that applies to *PolicyDeployment*
-and *PolicyExecution.*
-
-.. image:: images/DesignTimeComponents.svg
-
-The UML class diagram above shows the portion of the Policy Framework Object Model that applies to *PolicyDevelopment*
-and *PolicyDeployment.*
+The UML class diagram above shows thePolicy Framework Object Model.
2.2 Policy Design Architecture
------------------------------
-This section describes the architecture of the model driven system used to develop policy types and to create concrete
+This section describes the architecture of the model driven system used to develop policy types and to create
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 set up and available in the platform during
+Policy types that are expressed via natural language or a model require an implementation that allows them to be
+translated into runtime policies. Some Policy Type implementations are set up 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.
+implementations can also be loaded and deployed at run time.
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 *PolicyTypeImpl* 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 :ref:`Policy Design API <design-label>` 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.
+policy for a particular domain use case.
+
+All policy types are specified in TOSCA service templates. Once policy types are defined and created in the system,
+*PolicyDevelopment* manages them and uses them to allow policies to be created 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.
+
+A *PolicyTypeImpl* is developed for a policy type for a certain type of PDP (for example XACML oriented for decision
+policies, Drools rules or Apex state machines oriented for ECA policies). While a policy type is implementation
+independent, a policy type implementation for a policy type is specific for the technology of the PDP on which
+policies that use that policy type implementation will execute. A Policy Type may have many implementations. A
+*PolicyTypeImpl* 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 *PolicyTypeImpl* can be specific to a particular policy type
+or it can be more general, providing the implementation of a class of policy types. Further, the design environment
+and tool chain for implementing implementations of policy types is specific to the technology of the PDP on which
+the implementation will run.
+
+In the *xacml-pdp* and *drools-pdp*, an *application* is written for a given category of policy types. Such an
+application may have logic written in Java or another programming language, and may have additional artifacts such
+as scripts and SQL queries. The *application* unmarshals and marshals events going into and out of policies as well
+as handling the sequencing of events for interactions of the policies with other components in ONAP. For example,
+*drools-applications* handles the interactions for operational policies running in the drools PDP. In the
+*apex-pdp*, all unmarshaling, marshaling, and component interactions are captured in the state machine, logic, and
+configuraiton of the policy, a Java application is not used.
+
+*PolicyDevelopment* provides the RESTful :ref:`Policy Design API <design-label>`, which allows other components to query
+policy types, Those components can then create policies that specify values for the properties, triggers, and targets
+specified in a policy type. This API is used by components such as *CLAMP* and *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.
+implementation 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 properties specified in the policy type for that vendor model
+of vCPE.
2.2.1.1 Generating Policy Types
"""""""""""""""""""""""""""""""
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
-:ref:`Policy Design and Development <design-label>` 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).
-
+to create policy types, see the :ref:`Policy Design and Development <design-label>` page.
.. image:: images/PolicyTypeDesign.svg
-The GUI implementation in another ONAP component such as SDC DCAE-DS uses the *API_User* API to create and edit ONAP
-policy types.
+A GUI implementation in another ONAP component (a *PolicyTypeDesignClient*) may use the *API_User* API to create and
+edit ONAP policy types.
2.2.1.2 Programming Policy Type Implementations
"""""""""""""""""""""""""""""""""""""""""""""""
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 that has
-been loaded into it 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.
+be exercised directly using utilities such as *curl*.
+
+In future releases, the Policy Framework may provide a command line tool that will be a loose wrapper around the API. It
+may also provide a general purpose Policy GUI in the ONAP Portal for policy creation, which again would be a general
+purpose wrapper around the policy creation API. The Policy GUI would interpret any TOSCA Model that has been loaded into
+it 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.
+For example, *CLAMP* provides a GUI for creation of Control Loop policies, which reads the Policy Type associated
+with a control loop, presents the properties as fields in its GUI, and creates a policy using the property values entered
+by the user.
+
The following subsections outline the mechanisms for policy creation and modification supported by the ONAP Policy
Framework.
*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 *API_User* 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*.
+informs the *API_User*.
The *API_User* may now proceed with a policy specification session, where the parameters are set for the policy using
the policy type specification. Once the *API_User* is happy that the policy is completely and correctly specified, it
.. image:: images/ScriptedPolicyDesign.svg
-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 prepare a TOSCA Policy. It then uses the
-Policy API to create the policy.
+One straightforward way of generating policies from Policy types is to use commands specified in a script file. A
+command line utility such as *curl* is an *API_User*. Commands read policy types using the Policy Type API, parse the
+policy type and uses the properties of the policy type to prepare a TOSCA Policy. It then issues further commands to use
+the Policy API to create policies.
2.2.3 Policy Design Process
^^^^^^^^^^^^^^^^^^^^^^^^^^^
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
+sessions with PDPs. 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
The ONAP Policy Framework follows the architectural approach for microservices recommended by the `ONAP Architecture
Subcommittee <https://wiki.onap.org/display/DW/Architecture+Subcommittee>`__.
-The ONAP Policy Framework defines `Kubernetes Services
+The ONAP Policy Framework uses an infrastructure such as 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
================== =====================================================================================================
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
+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
+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.
================== =====================================================================================================
+\* SAFE Mode and TEST Mode will be implemented in future versions of the Policy Framework.
+
2.3.5 Policy Lifecycle Management
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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 begins to execute policies in the specified mode (see section 2.3.4).
+(ACTIVE/SAFE*/TEST*). The PDP begins to execute policies in the specified mode (see section 2.3.4).
+
+\* SAFE Mode and TEST Mode will be implemented in future versions of the Policy Framework.
.. _policy-rollout:
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.
+\* SAFE Mode and TEST Mode will be implemented in future versions of the Policy Framework. In current versions, policies
+transition directly from PASSIVE mode to ACTIVE mode.
+
2.3.5.3 Policy Upgrade and Rollback
"""""""""""""""""""""""""""""""""""
-There are a number of approaches for managing policy upgrade and rollback.
+There are a number of approaches for managing policy upgrade and rollback. Upgrade and rollback will be implemented in
+future versions of the Policy Framework.
The most straightforward approach is to use the approach described in section :ref:`policy-rollout` for upgrading and
rolling back policy sets. In order to upgrade a policy set, one follows the process in :ref:`policy-rollout` with the
===================== ===============================================================================
**Field** **Description**
===================== ===============================================================================
-State Lifecycle State (PASSIVE/TEST/SAFE/ACTIVE)
+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
RealTimeInfo Real time information on running policies.
===================== ===============================================================================
+\* SAFE Mode and TEST Mode will be implemented in future versions of the Policy Framework.
+
+Currently, policy monitoring is supported by PAP and by pdp-apex. Policy monitoring for all PDPs will be supported in
+future versions of the Policy Framework.
+
2.3.7 PEP Registration and Enforcement Guidelines
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Code Review / policy / parent.git / blobdiff