...
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 - Draft for more information on these the Decision APIs.
3. APIs Provided by the Policy Framework
See the Policy Design and API Flow for Model Driven Control Loop - Draft page.
3.1 Policy Design APIs
Chenfei Gao I removed the other subsections that I wrote in Chapter 3 as they are redundant now, the API page has all the info. Is this section redundant as well?
Policy framework provides various APIs for users to create, update, delete (CRUD) various types of policies which include configuration (CONFIG) policies, XACML policies, Drools policies, APEX policies, etc. as well as CRUD of event schemas which are closed tied to policies in an event-driven fashion. CONFIG policies are the ones that contain detailed configurations of policy-enabled components in particular domains, which are basically in the format of key-value pairs. They will be subscribed by DCAE Micro-Services or other policy-enabled components. It is an important area the framework should provide backwards compatibility support when APIs are redesigned and evolving. XACML policies are typically access/admission control policies thus can be seamlessly specified for policy guard. Drools/APEX policies are action policies which will make runtime decisions reacting to particular network events via concrete actions or action guidance. They play a critical role in control loop implementation and management. Event schemas are as important as policies since all the policies are event-driven. Context/situation information are embedded in the input events. By knowing the semantics of events, policy rules can capture the logic of parsing the events, decide what reaction to come up with and how. Changing event schema will somehow impact policy logic. Hence, CRUD of event schemas are taken into account along with policy design.
Policy framework provides multiple options of creating policies to various types of users. Some users might be domain experts with proficient programming skills. They would probably like to compose the policies from scratch (a.k.a. raw policies) and are able to write templates for parametrized policies in particular domains. Providing policy CRUD option for such users is inevitable. There is another type of users who are not capable of writing raw policies and templates but have good understanding of existing templates and know what template they should use and what data to populate into the template in order to support real-world use cases. Hence, exposing APIs for CRUDing template-based policies to such users should also be considered. In addition, designing APIs for CRUDing event schemas is needed as well given event schema design can also be taken as a part of policy design. When user designs a policy, they also design the input and output events to/from the policy. Hence, event schemas will be included in policy payload. To ease re-usability of event schema, in each policy payload, user just needs to specify the names of new/existing schemas they want to use in current policy. Eligibility of specified schemas will be validated by the framework before the policy is being processed.
3.1.1 Data Model for APIs
The very first step of API design is to come up with data models for various API objects. Hence, data models for policy, policy template and event schema are in our scope here.
Data models for the APIs can be downloaded from here: API-MODEL-Policy.json, API-MODEL-Policy_Template.json, API-MODEL-Event_Schema.json
It is worth noting that above listed models are generic ones to support CRUD of various types of policies by various types of users (i.e. DEV users who know how to program policies/templates and know how to package/generate maven artifact and do maven deployment; GUI users who will CRUD template-based policies via GUI only), and have backwards compatibility with existing CONFIG policies and XACML guard policies.
3.1.2 Raw Policy Creation
An important API is to support CRUD of raw policy. The "raw" here means the policy is composed from scratch, not based on any template. We assume such API users are all DEV users who master policy programming using native policy language provided by each policy engine and know how to do maven compilation, artifact generation and deployment given policy will be stored as maven artifact. The sequence diagram is shown below.
The first step is for DEV user to wrap up policy artifact with details included in the note below, submit it to governance process for validation, then deploy it to nexus repository. Next, POST /policy/raw is invoked to create raw policy with payload populated (payload format is in the note below). It is worth noting that since policy contents/rules are already included in the artifact which has been deployed to nexus, there is no need to put them again in the payload "data" field. Hence, only "metadata" is meaningful for the payload here.
After the API is invoked, the first thing is to check the eligibility of event schemas specified in the payload, checking whether each event schema name has one matching entry in DB SCHEMA table. If yes, save policy metadata to Database to keep a record.
3.1.3 Policy Template Creation
DEV users are capable of not only programming raw policies, but programming policy templates which expose several parameters to be populated by GUI users. In other words, we assume templates are being created by only DEV users. The sequence diagram is shown below. Given DEV users know programming and maven deployment, similarly, we require them to deploy template archetype artifact to nexus by themselves as the first step. It is worth noting that template contents would be different for various types of policy. It is also noted below. For example, Drools policy template would be Drools rules with configurable parameters in .drl file; XACML policy template would be xacml policies/rules with configurable parameters in .xml file; APEX policy template would be APEX policy model with configurable parameters in .apex file; CONFIG policy template can be defined as a JSON file with configurable parameters.
Different from policy artifact, in addition to template metadata and contents, template archetype artifact also contains the descriptor of configurable parameters to populate the template, which is stored in archetype.xml, noted below. Also, a new field called "populateDataSchema" is specified in payload which is used to indicate the schema type such as JSON, YAML, TOSCA and so on. TOSCA is referred to existing TOSCA policy schema for backwards compatibility with CONFIG policy.
The rest of the flows are similar. After POST /template API is invoked, event schema eligibility will be checked first. Then template metadata will be saved to Database as a record.
3.1.4 Template-Based Policy Creation by DEV user
Given template archetype artifact is created and deployed to nexus, for the users who want to base the template to create concrete policies, the first step is to review existing templates and select one to work on. The key to create policy based upon a template is to populate the template by required parameter values. It can be done by maven archetype plugin - archetype:generate given template is stored as archetype artifact. Here, we design different flows for different types of users. The sequence diagram for DEV users is shown below. For DEV users who master maven and would like to do programming, they can do API calls GET /templates and GET /template/{template-id} to review existing templates and select one to work on, then use maven archetype generate plugin to populate the template by their own. After wrapping up the policy artifact, DEV users should deploy it to nexus as before, followed by invoking template-based policy creation API to save policy metadata to Database.
3.1.5 Template-Based Policy Creation by GUI user
TBD - No Resources to work on the GUI
Another type of users who prefer to manipulate template-based policies through GUI. Thus, we call them GUI users here, without loss of generality. The sequence diagram is shown below. Basically, all such users' operations are through GUI, including reviewing/selecting existing templates and populating selected template by providing values to fill out configurable parameters in the template. The options to fill configurable parameters should be rendered by GUI. The configurable parameters here include those embedded in the template and the ones in policy metadata like "artifactId", "version" and so on. GUI backend will invoke corresponding API calls and pass in API arguments upon users' input in the GUI. It is worth noting that, in this scenario, all parameter values used to populate the template are specified in the "data" field of the payload and passed in to the API call. PAP will call maven archetype generation plugin to package a policy artifact on top of a populated template and do nexus deployment.
3.1.6 Event Schema Creation
Since all the policies are event-driven, which means they will be triggered by input events and generate necessary output events to downstream actioning systems that will enforce the policies. Thus, designing event schemas is a part of policy design. Corresponding API is provided to CRUD event schema. Sequence diagram is shown below. Note that event schemas need to be specified during policy creation, and their eligibility will be checked. Thus, for the users who want to create a new policy, it is preferred that they know what event schemas are existing and ready to be used or they can create new event schemas to support particular policies and user cases. It is worth noting that before saving new schema to Database, it will be checked if it is a new schema that has not been created before so that it is guaranteed every event schema stored in Database is unique and will not cause ambiguity.
3.1.7 Policy Query via API
Policy query design is still WIP. Initial thoughts are collected in the sequence diagram shown below.
- Should Policy Management Protocol/Policy Deployment Protocol/Policy Monitoring Protocol/Policy Persistence Protocol use DMaaP?
3.1.8 Policy Query via GUI
WIP. Initial results are shown below.
...
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 |
| Policy | An executable policy defined in TOSCA and created using a Policy Type, see the 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 |
...