Official Documentation for Dublin
https://docs.onap.org/en/dublin/submodules/policy/parent.git/docs/design/design.html
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.
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 TOSCA Policy Primer 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.
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 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).
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.
TCA Example - Please note that the official version of this will be located in the SDC repository.
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
- Existing Drools implementations that supports runtime Control Loop actions taken on components such as SO/APPC/VFC/SDNC/SDNR
- 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.
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.
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:
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.
1.3.1 onap.policies.controlloop.guard.FrequencyLimiter Policy Type
This is WIP for El Alto for the proposed policy type.
1.3.2 onap.policies.controlloop.guard.Blacklist Policy Type
1.3.3 onap.policies.controlloop.guard.MinMax Policy Type
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. PDPs register with the PAP when they start, providing the PolicyImpl they have been predeployed with. | No run time configuration required and run time administration is simple. | Very restrictive, no run time configuration of PDPs is possible. |
| 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. 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. | The configuration, parameters, and PDP group of PDPs may be changed at run time by loading or updating a TOSCA Policy into the PDP. Lifecycle management of TOSCA Policy entities is supported, allowing features such as PolicyImpl Safe Mode and PolicyImpl retirement. | 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. |
| 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. 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. | 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. Lifecycle management of TOSCA Policy entities and PolicyTypeImpl entites is supported, allowing features such as PolicyImpl Safe Mode and PolicyImpl retirement. | 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. |
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 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
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} eg. | Get a specific policy type and all the available versions. |
https:{url}:{port}/policy/api/v1/policytypes/{policy type id}/versions/{version id} eg. | Get the specific Policy Type with the specified name and version |
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
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
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 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 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 eg. | Get all Policies for a specific Policy Type and version |
https://{url}:{port}/policy/api/v1/policytypes/{policy type id}/versions/{version}/policies/{policy name}/versions/{version} eg. | Gets a specific Policy version |
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
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
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
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
3.2.2.2.1 Drools Operational Policy Create/Update
TBD Jorge Hernandez
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
3.2.2.3 Guard Policy Create/Update
TBD Pamela Dragosh 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 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
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
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
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 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:
- Only one version of a PDP group may be ACTIVE at any time
- 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
- 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
- There is no restriction on the number of PASSIVE versions of a PDP group that can exist in the system
- <Rules on SAFE/TEST> ? Pamela Dragosh
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
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
{
"ONAPName": "DCAE",
"ONAPComponent": "PolicyHandler",
"ONAPInstance": "622431a4-9dea-4eae-b443-3b2164639c64",
"action": "configure",
"resource": {
"policy-id": "onap.scaleout.tca"
}
}
{
"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
{
"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:
{
"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 messaging. There are four messages on the API:
- PDP_STATUS: PDP→PAP, used by PDPs to report to the PAP
- 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
- 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
- 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 STATUS | PDP UPDATE | PDP STATE CHANGE | PDP HEALTH CHECK | Comment | |
|---|---|---|---|---|---|---|
| (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.
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.
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.
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.
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 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
The table below shows some more examples of GET operations
| Example | Description |
|---|---|
https:{url}:{port}/policy/api/v1/native/{policy type id}/impls eg. | Get all Policy Type implementations for the given policy type |
https:{url}:{port}/policy/api/v1/native/{policy type id}/impls/{policy type impl id} eg. | Get all Policy Type implementation versions that match the policy type and policy type implementation IDs specified |
https:{url}:{port}/policy/api/v1/native/{policy type id}/impls/{policy type impl id}/versions/{version id} eg. | 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 |
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
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
60 Comments
Jorge Hernandez
Is the "id" field to be used for design time? I see that the <domain,id> provides uniqueness, but <domain, pdp_types[i]> could provide it as well.
Perhaps some of the domains URLs perhaps may be revisited to identify resources without overusing query params, ie: from PUT http:{url}:{port}/api/v1/domains?domain=onap.policy.monitoring.cdap.tca.hi.lo.app&id=dublin.tca to PUT http:{url}:{port}/api/v1/domains/onap.policy.monitoring.cdap.tca.hi.lo.app/dublin.tca. Another aspect to revisit, if the URL shoudl carry in this case "pap" in the context uri.
Could a designer "design" policies, but not "submit" or "deploy" them, just design them, in a scenario where the supporting PDPs supporting have not registered yet with the PAP (and therefore the domain will not show in the list at the time of the PAP query)?
Pamela Dragosh
the "id" needs to be there for both run and design time - domains are created for a specific pdp(s) anyway. We can certainly list that, but I assume there must be some sort of an id to identify that domain policy. It is a java artifact ultimately.
I am focusing this on the work we need to deliver for Dublin, so there has to be a domain available at the moment. We do need to support a vanilla PDP, loading a brand new domain for it, and then create policies (not design) for that domain.
Of course, you should also be able to develop raw policies and load them into a vanilla PDP.
So right now let's finish what it looks like for a domain to be registered, pre-packaged and available. Then add in the other 2 scenarios.
Liam Fallon
I think this comment is resolved now.
Jorge Hernandez
In the Policy Design section:
There are references to "onap.controlloop", but also "onap.policies.controlloop" .. shouldn't it be the same?
A minor comment, the convention on when to capitalize the first letter of a "name" are not very intuitive to me, if there could be some guidelines.
Liam Fallon
The capitalization for naming is not consistent now, let's agree on an approach. Why not just stick with lower case everywhere.
Jorge Hernandez
In the "Policy Design > onap.controlloop.Operational model" subsection. For the drools pdp-type, is the thinking having a schema that matches the current format of Operational Policies?
Jorge Hernandez
In the "PDP Deployment and registration with PAP" section. The identifier should probably the "hostname" which is the ID that the PDP will send when it registers with the PAP.
Not exactly related to this document, I think it may be covered in the Policy Framework, there should be a healthcheck for keeping the list mostly up to date.
Liam Fallon
Jorge Hernandez Can you check if this comment is resolved now?
Jorge Hernandez
One of the things that we need to refine the service endpoint that CLAMP and DCAE will use to communicate with Policy subsystem. I take it that CLAMP will directly talk to the PAP service and never with the PDPs. Is this a correct assumption? No issue there since PAP knows all about "models".
On DCAE, since we may have multiple groups/subgroups over multiple PDP-Xs, the endpoint name may vary. Liam has it in the policy framework wiki page to have well known service endpoints on a per domain (model) basis. I think based on this, we need to refine the endpoint URL a little more, as per the example above, a group may have its PDP-Xs distributed across several subgroups for different purposes.
Pamela Dragosh
CLAMP will be calling the Policy Lifecycle API for CRUD. I suspect we return details in this call for CLAMP to save for both the following 2 calls that need to occur:
CLAMP will be calling the PAP API for deploy/undeploy.
DCAE talks to the decision API, which goes directly to the XACML PDP. Again, I need us to work through the models so the API's all match up.
This is why I created this page to work all of this out.
Liam Fallon
Is this comment closed off now?
Chenfei Gao
Liam, is it necessary to store all the things as separate artifacts in nexus? Maybe we can consolidate PolicyType and PolicyTypeImpl as one artifact going to nexus and PolicyImpl as another artifact. What I am thinking is, there should always be 1-1 mapping between PolicyType and PolicyTypeImpl. Maybe it is more natural to consolidate them together in one artifact? The Policy returned from CLAMP (blue box in the mid of fig.1) is just a set of values for configurable params defined in PolicyType. Is it necessary to store it as a separate artifact?
Liam Fallon
Good question, I thought about that as well. I'll come back with an answer once we have worked through the whole page with the new terminology.
Chenfei Gao
At my first sight of PolicyTypeImpl, I was a bit confused. Then after reading more sentences, it turns out to be just like template with configurable params. Perhaps for other end users, they will feel the confusion too. But not sure what is the perfect vocabulary here. Just a minor comment.
Liam Fallon
yes, its very similar if not the same, I just wanted to align as closely as possible to the TOSCA vocabulary.
Liam Fallon
I have removed any references to Nexus. As this page describes the external facing APIs of the PF, we don't need to mention how we internally store things.
Is this comment resolved now?
Chenfei Gao
Yes. Sorry I was sick these two days. Just see your reply
Chenfei Gao
Some different vocabularies appear in this doc for the same/similar concepts, such as (model, domain, PolicyType), (PolicyTypeImpl, template) and so on. We can work together to sort them out and make consistency everywhere after completion of the design. I was getting quite confused during reading this doc.
Liam Fallon
Please bear with me. I have cleaned up Section 1 and are moving on to section 2. From there on is not cleaned up yet.
Liam Fallon
I have finished cleaning up the vocabulary now, Chenfei Gao can you have a look and see if its OK?
Chenfei Gao
I fixed two missing vocabulary in 3.1.1.1 and 3.2.2.2. Changed "model query" to "Policy Type query"
Alex Shatov
Here is the link to the impact and concerns to/in policy-handling by the DCAE-Controller
impact of the updated PDP API on policy-handling by DCAE-Controller
Pamela Dragosh
Ok but please keep in mind this is all a draft and we will be making modifications based on feedback from DCAE and CLAMP.
Liam Fallon
Alex Shatov Please have a look at this page now.
Alex Shatov
Pamela Dragosh Liam Fallon Vijay Venkatesh Kumar Christopher Rath
I probably need a walk through this new API of 3.4 Policy Decision API - Getting Policy Decisions. The new API looks strikingly different from the old /getConfig API.
policy-id" in your new API already differs from what we were talking about likepolicy_idRE new API
{ "pep": { "name": "DCAE", "instance": "policy-handler-0" }, "action": "configure", "resource": [ { "policy-metadata": { "policy-id": "onap.scaleout.tca" } } ] }Alex Shatov
Pamela Dragosh
Please be patient Alex, we are working on getting everything aligned here. Looks like a typo happened while some changes to the sections were being changed.
Liam Fallon
Alex Shatov Please have a look now.
Pamela Dragosh
Liam Fallon
Fixed!
Vijay Venkatesh Kumar
@Pamela Dragosh - For Dublin, could you confirm once the new API are rolled out by Policy, will there be any usecase that requires DCAE/Policy Handler to support current/old API's also in parallel for Dublin? Esp given CLAMP is moving to use new lifecycle API's.
If parallel API's support are required by the PH or other clients - this would adds complexity as well. Any thoughts?
Jorge Hernandez
In the introduction section Liam Fallon, the figure refers to "drl" in the "PolicyTypeImpl". I think at this point we are saying that PDP-D "native policy" is an Operational Policy. The .drl still is a configurable element but we are moving the emphasis to Operational Policies. For the "drl" support a more sophisticated process that include certification, etc .. have to be put in place. I think that's something that we will come later. The point here is to delete in the diagram the mentioning of the .drl in the PolicyTypeImpl and replace with Operational Policy.
Liam Fallon
Done
Jorge Hernandez
In the PDP Deployment and Registration with PAP, I seem to understand from reading it that the PDP can register PolicyImpl with PAP. I think policy allocation strategies should only be done in the PAP. The PDP Type is OK to be preconfigured, and perhaps desired, as it just reflects what capabilities the PDP offers.
Liam Fallon
I prefer this approach as well.
My understanding was that we had to support preloading of PolicyImpl on PDPs, in other words PDPs come prepackaged with policies and their implementations. The way I thought this would work was that the PAP would already know the IDs of the preloaded Policy implementations. When the PDP registers, it says "hi< i have Policy implementation with ID 12345 loaded, is that OK", then the PAP would say "Sure, I know about policy 12345, go ahead" or "Sorry, I don't know about policy 12345, do not handle policy requests"
My preference would actually be to support only the "Hot Deployment" approach, where the PAP controls everything. This makes the deployment (not to mention the implementation effort) much easier (and cheaper) because then all the complexity is in the PAPs and the PDPs have very simple support for policy administration, they basically do what they are told by the PAP.
Jorge Hernandez
For the Policy Types APIs I favored the following style APIs counterpart of the examples shown in the table which uses query parameters:
GET http:{url}:{port}/api/v1/policytypes - returns all policy types
GET http:{url}:{port}/api/v1/policytypes/onap.policies.Monitoring - returns onap.policies.Monitoring policyType
GET http:{url}:{port}/api/v1/policytypes/onap.policies.Monitoring/versions - returns all versions of onap.policies.Monitoring policyType
GET http:{url}:{port}/api/v1/policytypes/onap.policies.Monitoring/versions/1.0.0 - returns version 1.0.0 of onap.policies.Monitoring policyType
GET http:{url}:{port}/api/v1/policytypes/onap.policy.monitoring.cdap.tca.hi.lo.app/1.0.0
The regex not sure if needed as it can be done in the client and there's not that many entries on the server side perhaps worth to do the filtering there. In any case, I would use a query parameter for the regex instead, ie.
GET http:{url}:{port}/api/v1/policytypes?regex=onap.policies*
Similarly to create/override and delete:
PUT http:{url}:{port}/api/v1/policytypes/onap.policy.monitoring.cdap.tca.hi.lo.app - creates a new policy type onap.policy.monitoring.cdap.tca.hi.lo.app.
DELETE http:{url}:{port}/api/v1/policytypes/onap.policy.monitoring.cdap.tca.hi.lo.app - delete it
I would prefer such kind of hierarchical structuring of resources and APIs rather than relying on complex query parameters. I guess this comment would apply to how all the APIs are structured.
Liam Fallon
Sure, Please treat what's on the page as a suggestion only. Let's work on getting a good structure on them. The focus up to now was more on working out the functionality of the APIs.
Chenfei Gao
I am also more keen on Jorge's suggestion on API paths.
Pamela Dragosh
Yes the hierarchical structure is what I was thinking - not sure how policytypeimpl fits in.
Pamela Dragosh
I'm going to make these changes Liam Fallon
Liam Fallon
Sure, fire away!
The PolicyTypeImpl allows a raw policy to be loaded into the system. I'll try to explain it a bit better on Monday.
Pamela Dragosh
Ahhh - just discussing that with Chenfei on how to do Raw policies. We definitely want to have that support in there. Ok - I'll leave that section alone.
Chenfei Gao
My understanding is PolicyTypeImpl defines a way of how configurable properties in PolicyType can be used and recognized by Policy Engine. Typically, it is raw policy with configurable params/properties which are defined in corresponding PolicyType. We could also support the raw policy without anything configurable, specially for the ones who are confident about their xacml/drool/apex rules (for example) that need not further reconfiguration. Maybe we can leave PolicyTypeImpl section as is and add a new section for raw policy without corresponding support of PolicyType.
Pamela Dragosh
Jorge Hernandez Liam Fallon and Chenfei Gao - can you take a look at the latest changes I made? I need to take off for the day but I'll log back in later this evening and check your feedback.
Jorge Hernandez
See some comments embedded in text on APIs. One minor note is that we should add "policy" to the URLs, this is to distinguish it from other components APIs a bit better, ie. https://<host>:6969/policy/<policy-component>/v1/healthcheck.
Chenfei Gao
A lot of api paths need to be updated to reflect "policy" appended before <policy-component>/v1.
Liam Fallon
Yes, they need to be cleaned up, let's discuss tomorrow how to make the paths consistent.
Liam Fallon
Changes today:
Jim Hahn
Since there are multiple message types transmitted from PAP to PDP, should there be a tag in the message so that PDP knows which type of message it is?
Liam Fallon
Yes, its the first field the (message_name), see the table in Section 4.1. So in Yaml format it'll be either:
pdp_status:
Blah blah blah
pdp_update:
Blah blah blah
pdp_state_change:
Blah blah blah
pdp_health_check:
Blah blah blah
Jim Hahn
Section 3.3.6 says that the REST call will not wait around for the health check reports, but that the reports can be retrieved via a subsequent GET call. Should we limit the number of health checks allowed in a given period of time and always return a cached health check response, as long as it isn't out of date? Or do we want to monitor individual health checks? If so, then that probably means we need to provide some type of id in the PUT response so we can match the GET with the data. (Of course, that means that the id must be included as a parameter in the GET API.) Is there a time limit on how long we need to keep the responses around?
Related questions for the other APIs in section 3.3: Are they intended to block until completion (with a time limit for waiting for PDPs to reply)? Or should they function like the health check, returning some type of id in the PUT/POST response, and then the result retrieved via GET? And if the latter, then is there a time limit on how long we need to keep the responses around?
Jorge Hernandez
I think we need to define what is a healthcheck, a policy-wide healthcheck, as the one that could be issued by "robot" or an operator on demand, and it should check on all components and provide status to the best of its knowledge. 3.3.6 is a good chunk of the health of the system but not all. From the perspective of an administratior, robot, or consult, it seems to me that healtcheck would be much friendlier if the snapshot status is provided all at once (blocking operation from an administrator) instead of 2 steps, first returning a 202 and then querying again.
As an alternative, a slightly stale snapshot of the the health of the components could also be returned, provided that the PDPs are periodically checking in with the PAP, in this case, a snapshot of that knowledge could be returned (this will also bypass the 2 step approach).
Another consideration and specific to PDP groups is what it means to be healthy. PDPs can go up and down in a controlled or uncontrolled fashion on a kubernetes cluster. Therefore, a PDP group to be healthy does not necessarily mean that all PDPs previously registered are up, but instead that for each active policy, there is at least one PDP that can serve it.
Liam Fallon
I think we should do this really simply for Dublin.
Inspired by the Hadoop world, an "eventually consistent" approach is what we could do.
1) A Health check is orders.
2) If the last health check was ordered earlier than the minimum wait time then the order succeeds else it is requested.
3) Anyone can get the health check result at any time. They get the result of the check for all PDPs that the test has completed for and an "in progress" indication if the test has not completed on a PDP
4) A health check is marked as failed by the PDP if it times out after some configurable test time.
This is easy to implement, the PAP just needs to send the request on DMaaP, record the results as they come in from PDPs, and time out any ones that don't respond on a given time.
The PAP responds on get requests by just returning whatever the current status is.
So the health check order is not a 202 response it is a 200. The request to order a health check has succeeded.
The Get health check result is just a get that gets whatever is there, the order and the get are actually independent requests.
Jorge Hernandez
Not sure. My main concerns are: (a) easy to use with integration's robot framework some sort of system level wide healthcheck, and (b) avoiding returning incorrect information -for example if scaling down a PDP (k8s manual operation), a timeout on the descaled PDP is OK (as long as there is another PDP replica that can serve the same policies).
Manoj Nair
Is there any option to trigger a policy via API ? Or is it expected that Policy will be triggered always using events.
Ram Krishna Verma
It depends upon how you design the policy and which pdp engine is used. Policy execution is the responsibility of the individual PDP engines. For example:
In apex-pdp, you can design the engine to start a REST SERVER inside and push triggers/events via REST API calls. You can also design it to start REST CLIENT, in that case it will keep polling the designated rest server for triggers/events.
In xacml-pdp, we have decision API to trigger the policy. Pamela Dragosh Knows it much better than me.
In drools-pdp, I think the current rules are triggered based on incoming events via DMaap. Jorge Hernandez Is there a way to trigger the rules via an API?
Pamela Dragosh
"trigger" isn't the best way to think about policy enforcement.
For Drools - you can use the telemetry api to insert a fact (eg an event) into working memory, which would then "trigger" the enforcement of operational policies during control loops. But it really depends on those policies - in the future multiple factors may be required in order to "trigger" the enforcement of policies.
The Decision API serves other ONAP components who act as enforcement points - so simply calling the Decision API will have the XACML PDP evaluate its set of deployed policies for a decision as to what "policy" should be applied. Sometimes this is an actual policy being returned, other times this is simply a "permit" or "deny". Depends - we support both situations.
Jorge Hernandez
There are REST APIs to exercise policies, in the case of the PDP-D, these APIs could inject precondition objects that satisfy and trigger a rule.
Manoj Nair
Thank you. Is there any example I can refer to ?
Jorge Hernandez
You can start with the "DDF Recording - Overview of Policy Framework Architecture and Demos" video and documentation at the following wiki: ONAP Community Awards: Dublin Release (Demos Only).