...
- Most obviously, the framework must be capable of being triggered by an event or invoked, and making decisions at run time.
- It must be deployment agnostic; capable of managing policies for various Policy Decision Points (PDPs) or policy engines.
- It must be metadata driven, allowing policies to be deployed, modified, upgraded, and removed as the system executes.
- It must provide a flexible template model driven policy design approach for template policy type programming and specification of policies.
- It must be extensible, allowing straightforward integration of new PDPs, policy formats, and policy development environments.
...
draw.io Diagram | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
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. PolicyDeveloment PolicyDevelopment interacts with ONAP design time components, and has no programmatic interface with PolicyAdministration, PolicyExecution or any other run-time ONAP components.
...
PolicyDevelopment provides a CRUD API for policy types and policies. The policy types and policy artifacts and their metadata (Information about policies, policy templatestypes, and their interrelations ) are stored in the PolicyDB. The PolicyDevGUI, PolicyDistribution, and other applications such as Portal can use the PolicyDevelopment API to create, update, and delete policy templates types and policies.
PolicyAdministration has two important functions:
...
draw.io Diagram | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
The UML class diagram above shows the portion of the Policy Framework Object Model that applies to PolicyDeployment and PolicyExecution.
draw.io Diagram | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
The UML class diagram above shows the portion of the Policy Framework Object Model that applies to PolicyDevelopment and PolicyDeployment.
...
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 template 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.
...
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.
PlantUML Macro | ||
---|---|---|
| ||
@startuml participant Script <<API_User >> collections DirectiveFile box "PolicyDesign" #LightBlue participant PolicyTypeDesign participant PolicyDesign end box autonumber activate CLIScript loop Script --> DirectiveFile : Read next directive from script file Script --> PolicyTypeDesign : Read Policy Type for directive Script --> Script : Create TOSCA Policy Script --> Script : Read parameters from script file directive Script --> Script : Set Parameters in TOSCA Policy Script --> PolicyDesign : Generate Policy PolicyDesign --> Script : Policy Generation Resultend Script --> ConcretePolicyDesign : Generate Policy ConcretePolicyDesign --> Script : Policy Generation Result end deactivate Script @enduml |
...
2.2.3 Policy Design Process
All policies 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 policies policy types that are declared within the ONAP Service CSAR. For Policy Templates and raw policiesother policy types and policy type implementations, the lifecycle associated with software development process will suffice. Since models, templates and raw policies will be deployed to a Nexus repository, 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.
...
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 Nexus the Policy database and transfers policy sets to PDPs, and may cache the policy sets for PDP groups. If PDPs individually interact directly with Nexus, then a complex three-way consistency between the PDPs, PAP, and Nexus must be maintained. it is much more difficult to maintain consistency across all the PDPs in the PDP group as PDPs spontaneously appear and disappear
See also Sectino 2 of the TO BE DELETED - refer to Dublin Documentation page, where the mechanisms for PDP Deployment and Registration with PAP are explained.
2.3.1 Policy Framework Services
...
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 ans and is specified for the full ONAP Kuberentes installation.
...
Service | Endpoint | Description |
---|---|---|
PAP | https://policy-pap | The PAP service, used for policy administration and deployment. See Section 3.2 TO BE DELETED - refer to Dublin Documentation 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 |
PDP-D-domain | https://policy-pdpd-domain | |
PDP-A-domain | https://policy-pdpa-domain |
...
The following diagram captures the relationship between Policy Framework concepts at run time.
PlantUML Macro |
---|
There is a one to one relationship between a policy service and the policies for a certain domain. Each PDP service is used for a particular policy domain, runs a single PDP group with multiple PDPs, which executes a specific Policy Set containing a number of policies. Having and maintaining this principle makes policy deployment and administration much more straightforward than it would be if complex relationships between PDP services, groups, 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 outlines the structure of the run time topology information in the Policy Framework database. Note that the PDP_GROUP_STATE and PDP_STATE fields hold state information for life cycle management of PDP groups and PDPs. The POLICY_MAVEN_ARTIFACT field holds a reference that a PAP can use to fetch the policy artifact from Maven.
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.
PlantUML Macro | ||
---|---|---|
| ||
@startuml
participant K8S
participant PAP
autonumber
K8S --> PAP : Start PAP
loop forever
ref over PAP: Wait for and\nHandle PDP\nStatus Updates
ref over PAP: Wait for and\nHandle\nAdmin Requests
end
@enduml |
The PAP is the run time point of coordination for the ONAP Policy Framework. When it is started, it initializes itself. 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.
PlantUML Macro | ||
---|---|---|
| ||
@startuml
participant K8S
participant PDP
participant PAP
autonumber
K8S --> PDP : Start PDP
PDP --> PAP: Send Status (initial status) to PAP
ref over PAP, PDP: PAP downloads Policy Set to PDP
loop forever
PDP --> PAP: Send Status to PAP
end
@enduml |
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 (see Section 2.2.5.1).
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.
PlantUML Macro | ||
---|---|---|
| ||
@startuml
participant REQUESTOR
participant RESPONDEE
participant PDP
autonumber
alt Synchronous Invocation
REQUESTOR --> PDP: Execute Policy
activate PDP
hnote over REQUESTOR : wait
PDP --> REQUESTOR: Policy Execution Result
deactivate PDP
else Asynchronous Invocation
REQUESTOR --> PDP: Execute Policy
activate PDP
PDP --> RESPONDEE: Policy Execution Result
deactivate PDP
end
@enduml |
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 uses 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 uses 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:
...
| ||
@startuml
object PDPSubGroup
object PDPService
object PolicySet
object PDP
object PolicyImpl
PDPSubGroup "1" -- "1" PDPService : > Lifecycle\nManaged\nBy
PDPService "1" -- "*" PDP : > Manages\nLifecycle\nOf
PDPService "1" -- "1" PolicySet : > Executes
PolicySet "1" -- "*" PDP : > Executes\nOn
PolicySet "1" -- "*" PolicyImpl : > Contains
@enduml |
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.
PlantUML Macro | ||
---|---|---|
| ||
@startuml
!define table(x) class x << (T,#FFAAAA) >>
!define primary_key(x) <u>x</u>
hide methods
hide stereotypes
table(PDP_SUBGROUP) {
primary_key(PDP_SUBGROUP_ID)
PDP_SUBGROUP_NAME
PDP_SUBGROUP_VERSION
PDP_TYPE
PDP_SERVICE_ENDPOINT
POLICY_SET_ID
PDP_SUBGROUP_STATE
}
table(PDP) {
primary_key(PDP_ID)
PDP_NAME
PDP_VERSION
PDP_TYPE
PDP_ENDPOINT
PDP_SUBGROUP_ID
POLICY_SET_ID
PDP_STATE
}
table(POLICY_SET) {
primary_key(POLICY_SET_ID)
POLICY_SET_NAME
POLICY_SET_VERSION
}
table(POLICYIMPL) {
primary_key(POLICY_IMPL_ID)
POLICY_NAME
POLICY_VERSION
PDP_TYPE
POLICY_ARTIFACT
}
table(POLICY_SET_TO_POLICY_IMPL) {
POLICY_SET_ID
POLICY_IMPL_ID
}
PDP_SUBGROUP::POLICY_SET_ID --> POLICY_SET::POLICY_SET_ID
PDP::PDP_SUBGROUP_ID --> PDP_SUBGROUP::PDP_SUBGROUP_ID
PDP::POLICY_SET_ID --> POLICY_SET::POLICY_SET_ID
POLICY_SET_TO_POLICY_IMPL::POLICY_SET_ID --> POLICY_SET::POLICY_SET_ID
POLICY_SET_TO_POLICY_IMPL::POLICY_IMPLID --> POLICY::POLICY_IMPL_ID
@endum |
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.
PlantUML Macro | ||
---|---|---|
| ||
@startuml
participant K8S
participant PAP
database PolicyDB
autonumber
K8S --> PAP : Start PAP
PAP --> PolicyDB : Read Initial Data
PAP --> PAP : Initialize Policy Administration
activate PAP
deactivate PAP
loop forever
ref over PAP: Wait for and\nHandle PDP\nStatus Updates
ref over PAP: Wait for and\nHandle\nAdmin Requests
end
@enduml |
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 TO BE DELETED - refer to Dublin Documentation page for the API used to implement this sequence.
PlantUML Macro | ||
---|---|---|
| ||
@startuml
participant K8S
participant PDP
participant DMaaP
participant PAP
autonumber
K8S --> PDP : Start PDP
PDP --> PAP: Send Status (initial status) to PAP
ref over PAP, PDP: PAP downloads Policy Set to PDP
loop forever
PDP --> PAP: Send Status to PAP
end
@enduml |
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.
PlantUML Macro | ||
---|---|---|
| ||
@startuml
participant REQUESTOR
participant RESPONDEE
participant PDP
autonumber
alt Synchronous Invocation
REQUESTOR --> PDP: Execute Policy
activate PDP
hnote over REQUESTOR : wait
PDP --> REQUESTOR: Policy Execution Result
deactivate PDP
else Asynchronous Invocation
REQUESTOR --> PDP: Execute Policy
activate PDP
PDP --> RESPONDEE: Policy Execution Result
deactivate PDP
end
@enduml |
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.
PlantUML Macro | ||
---|---|---|
| ||
@startuml
actor User
database PolicyDB
participant PAP
participant DMaaP
participant PDP
autonumber
alt PDP Startup
PDP --> PAP: Send Status (initial status) to PAP
else Update Request from User
User --> PAP : Update Policy on PDP
end
PAP --> PolicyDB: Read PDP metadata and Policy Set
PAP -> PAP: Prepare for PDP update
activate PAP
deactivate PAP
PAP --> PDP: Set PDP mode as PASSIVE
PAP --> PDP: Transfer Policy Set Policies to PDP
activate PDP
PDP --> PDP: Load Policies
deactivate PDP
alt PDP Mode should be ACTIVE
PAP --> PDP : Set PDP mode as ACTIVE
ref over PDP: Execute Policies in\nACTIVE Mode
else PDP Mode should be SAFE
PAP --> PDP : Set PDP mode as SAFE
ref over PDP: Execute Policies in\nSAFE Mode
else PDP Mode should be TEST
PAP --> PDP : Set PDP mode as TEST
ref over PDP: Execute Policies in\nTEST Mode
end
PAP --> PolicyDB: Update PDP metadata
@enduml |
This sequence can be initiated in two ways; from the PDP or from a user action.
- 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
- 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.
PlantUML Macro | ||
---|---|---|
| ||
@startuml
actor User
participant PAP
participant PDP
autonumber
User --> PAP: Create Policy Set for PDP Group
loop over PDP Group
ref over PAP, PDP: PAP downloads Policy Set to PDP
end
User --> PAP: Set PDP Group in Test Mode
loop over PDP Group
PAP --> PDP: Set PDP in TEST mode
end
PDP --> PAP: Report test results
PAP --> User: Report consolidated test results
User --> PAP: Set PDP Group in Safe Mode
loop over PDP Group
PAP --> PDP: Set PDP in SAFE mode
end
PDP --> PAP: Report safe mode operation results
PAP --> User: Report consolidated safe mode operation results
User --> PAP: Set PDP Group in Active Mode
loop over PDP Group
PAP --> PDP: Set PDP in Active mode
end
loop forever
PDP --> PAP: Report active mode operation results
PAP --> User: Report consolidated active mode operation results
end
@enduml |
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 TO BE DELETED - refer to Dublin Documentation for more information on the Decision APIs.
3. APIs Provided by the Policy Framework
See the TO BE DELETED - refer to Dublin Documentation page.
4
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 Download Policy Set to PDP
The sequence diagram below shows how a Policy Set is loaded into a PDP.
PlantUML Macro | ||
---|---|---|
| ||
@startuml
actor User
database PolicyDB
participant Nexus
box "PAP" #LightBlue
participant PAP
participant PDP_PLUGIN
end box
participant PDP
autonumber
alt PDP Startup
PDP --> PAP: Send Status (initial status) to PAP
else PDP Policy Upgrade Available
Nexus --> PAP : Policy Set Artifact Upgrade Available
else Update Request from User
User --> PAP : Update Policy on PDP
end
PAP --> PolicyDB: Read PDP metadata
PAP -> Nexus: Read Policy Set Maven Artifacts
PAP -> PDP_PLUGIN: Unpack Policy Set Policies from Maven Artifact\n(Models, Rules, Tasks, and Flows)
PAP --> PDP: Set PDP mode as PASSIVE
PAP --> PDP: Transfer Policy Set Policies to PDP
activate PDP
PDP --> PDP: Load Policy Set Policies (Models, Rules, Tasks, and Flows)
deactivate PDP
alt PDP Mode should be ACTIVE
PAP --> PDP : Set PDP mode as ACTIVE
ref over PDP: Execute Policies in\nACTIVE Mode
else PDP Mode should be SAFE
PAP --> PDP : Set PDP mode as SAFE
ref over PDP: Execute Policies in\nSAFE Mode
else PDP Mode should be TEST
PAP --> PDP : Set PDP mode as TEST
ref over PDP: Execute Policies in\nTEST Mode
end
PAP --> PolicyDB: Update PDP metadata
@enduml |
This sequence can be initiated in three ways; from the PDP, from Nexus, or from a user action.
- A PDP sends regular status update messages to the PAP. If this message indicates that the PDP has no Policy Set or an outdated Policy Set loaded, then this sequence is initiated
- Nexus triggers the PAP when a new policy set becomes available. The PAP initiates this sequence to upgrade the policy set on all PDPs running that policy set.
- A user may explicitly trigger this sequence to load a policy set on a PDP
The PAP controls the entire process. The PAP reads the current PDP metadata from the database and reads the required policy and policy set artifacts from Nexus. It then uses a PDP Plugin for the specific type of PDP to unpack the artifacts and build the policy set for the PDP in whatever form this type of PDP requires. The PAP supports a Java API that allows plugins to be developed for unpacking and building policies for arbitrary PDPs.
Once the Policy Set has been unpacked and built, 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.
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.2.4).
2.3.5.2 Policy Rollout
A policy set steps through a number of life cycle modes when it is rolled out.
PlantUML Macro | ||
---|---|---|
| ||
@startuml
actor User
participant PAP
participant PDP
autonumber
User --> PAP: Roll out Policy Set
loop over PDP Group
ref over PAP, PDP: PAP downloads Policy Set to PDP
end
User --> PAP: Set PDP Group in Test Mode
loop over PDP Group
PAP --> PDP: Set PDP in TEST mode
end
PDP --> PAP: Report test results
PAP --> User: Report consolidated test results
User --> PAP: Set PDP Group in Safe Mode
loop over PDP Group
PAP --> PDP: Set PDP in SAFE mode
end
PDP --> PAP: Report safe mode operation results
PAP --> User: Report consolidated safe mode operation results
User --> PAP: Set PDP Group in Active Mode
loop over PDP Group
PAP --> PDP: Set PDP in Active mode
end
loop forever
PDP --> PAP: Report active mode operation results
PAP --> User: Report consolidated active mode operation results
end
@enduml |
The user rolls out a policy set. 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:
...
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.
3. APIs Provided by the Policy Framework and how to use them
- Should Policy Management Protocol/Policy Deployment Protocol/Policy Monitoring Protocol/Policy Persistence Protocol use DMaaP?
3.1 Policy Design APIs
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.
3.1.8 Policy Query via GUI
WIP. Initial results are shown below.
3.2 Policy Deployment APIs
PAP to all PDPs in PDP group
...
- Update of policies across PDPs in a PDP group use "eventually consistent" semantics, transactions or ACID semantics will not be supported
- Event though PDPs could listen or monitor Nexus for updates to policies, the PAP should be the component responsible for deciding if and what policy upgrades are propagated to the entire PDP group.
PDP Group Admin in PAP
...
PAP to all PDPs in PDP group
...
- *A policy may be parameterized. There are two ways to handle this
- Combine a raw policy into a parameterized policy and deploy the parameterized policy at run time
- Have the raw policy and its parameters as separate artifacts and deploy them separately
- Do not consider the parameters as an artifact but allow them to be modified directly by users setting them using an interface towards the PAP at run time
Policy Execution (Users to PDP Group pr PDP)
...
- **Applications using the Policy Framework should not be aware of specific PDPs, we should only support this behaviour for existing users and deprecate this usage.
- Load Balancing across PDP group......Stateless PDPs no problem.....set up stateful transfer between PDPs if supported....Address specific PDPs
4. The Policy Framework Implementation
- Database off PAP (PDPs report back to PAP, don’t access database directly)
- Database could be replaced by/interchangeable with some ONAP persistence system (DMaaP or DCAE)?
Observations
- Policy-core has definitions of the Policy protocols and the interfaces for all the interactions between the policy components. It doesn’t have much functional code, it’s mainly the model of the system and to enforce the overall structure and interactions in the system. Some of the current engine goes in there. Implementation of the protocols is in this modules including the Inter-PDP protocol and the generic parts of the Intra-PDP protocol
- PAP functionality extended to do life cycle monitoring and run time monitoring of PDPs, moves out of engine to separate git repository. The Deployment and Monitoring could be separate modules
- Generic PDP functionality is in a separate PDP module, the current generic PDP functionality moves there and is extended to provide generic model driven PDP support for arbitrary PDPs
- PDP-X specific functionality goes to the PDP-X module
- PDP-D and BRMSGW combined in PDP-D (PDP-D related functions in engine and the current drools-pdp combined)
- The drools-applications module generalized to provide interfaces for all the Policy Framework including arbitrary PDPs towards the other ONAP components in the Policy Interactions module. This must have a mechanism to allow model-driven interactions, in other words define interfaces at run time rather than at design time in Java or JAXB.
- All persistence is In the Policy Persistence module in order to keep persistence nastiness out of the other modules, state from PDPs can be persisted by reading state over the Policy Management Protocol. The Policy Management Protocol could use Distributed Hash Maps to share state with Persistence.
- All PDP implementations specialize the generic interfaces from Policy-core and PDP and can extend the Intra-PDP protocol with PDP-specific support, for example for state and context sharing
- Not much thought gone into the Portal as yet except that it will use REST interfaces for interactions.
4.1 Policy Design Implementation
- The Policy GUI Dashboard is created from the ONAP Portal SDK to create a consistent user experience
- The Policy GUI Designer is created from the ONAP SDC SDK to create a consistent user experience
4.2 Policy Deployment Implementation
4.3 Policy Execution Implementation
4.4 Policy Repository Layout
...
Unused in Casablanca
...
The XACML PDP implementation
...
This repo will hold the next generation Apex PDP engine
...
. 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?) policy artifact(s) |
Policy Development | The development environment for policies |
PolicyTemplate | A generic prototype policy that may or may not be executable. It can be stored in Nexus and support a maven archetype interface to be to generate other policy templates and/or concrete policies. They are a way to organize a common set of rules into one place for re-usability. |
DomainPolicy | A specialization of a generic policy for application to a specific domain |
PolicyParameters | Parameters that configure a policy for execution in a PDP group |
Executable Policy | A policy that can be stored in Nexus and can execute on a certain type of PDP. An executable policy is a parameterized policy template or domain policy |
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 |
Executable 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 |
...