You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 207 Next »

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 TypeDescription
onap.policies.MonitoringOverarching 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.GuardControl Loop guard policies for policing control loops
onap.policies.controlloop.CoordinationControl Loop Coordination policies to assist in coordinating multiple control loops at runtime

NOTE: TOSCA does not have a formal way of attaching versions to TOSCA PolicyType, at the moment it is still TBD where version field will be located. In ONAP, a metadata section has been used for nodes and services in order to specify a version. At the moment it has not been addressed if control loop PolicyType will follow the same convention.

1.1 onap.policies.Monitoring Policy Type

This is a base Policy Type that supports Policy driven DCAE microservice components used in a Control Loops. The implementation of this Policy Type is developed using the XACML PDP to support question/answer Policy Decisions during runtime for the DCAE Policy Handler.

Base Policy Type definition for onap.policies.Monitoring 
tosca_definitions_version: tosca_simple_yaml_1_0_0
policy_types:
  - onap.policies.Monitoring:
      derived_from: tosca.policies.Root
      description: a base policy type for all policies that govern monitoring provision

The PolicyTypeImpl implementation of the onap.policies.Montoring Policy Type is generic to support definition of TOSCA PolicyType artifacts in the Policy Framework using the Policy Type Design API. Therefore many TOSCA PolicyType artifacts will use the same PolicyTypeImpl implementation with different property types and towards different targets. This allows dynamically generated DCAE microservice component Policy Types to be created at Design Time.

DCAE microservice components can generate their own TOSCA PolicyType using TOSCA-Lab Control Loop guard policies in SDC (Stretch Goal) or can do so manually. See How to generate artefacts for SDC catalog using Tosca Lab Tool for details on TOSCA-LAB in SDC.

PolicyType onap.policies.Monitoring.MyDCAEComponent derived from onap.policies.Monitoring 
tosca_definitions_version: tosca_simple_yaml_1_0_0
policy_types:
  - onap.policies.Monitoring:
      derived_from: tosca.policies.Root
      description: a base policy type for all policies that govern monitoring provision
  - onap.policies.Monitoring.MyDCAEComponent:
      derived_from: onap.policies.Monitoring
      properties:
        mydcaecomponent_policy:
          type: map
          description: The Policy Body I need
          entry_schema:
            type: onap.datatypes.monitoring.mydatatype
data_types:
  - onap.datatypes.monitoring.mydatatype:
        derived_from: tosca.datatypes.Root
        properties:
          my_property_1:
            type: string
            description: A description of this property
            constraints:
              - valid_values:
                - value example 1
                - value example 2

TOSCA-LAB produces the following example yaml (TBD - it seems the latest code on master doesn't quite generate this):

Example TCA DCAE microservice 
tosca_definitions_version: tosca_simple_yaml_1_0_0
policy_types:
    onap.policies.Monitoring:
        derived_from: tosca.policies.Root
        description: a base policy type for all policies that govern monitoring provision
    onap.policies.monitoring.cdap.tca.hi.lo.app:
        derived_from: onap.policies.Monitoring
        properties:
            tca_policy:
                type: map
                description: TCA Policy JSON
                default: '{"domain":"measurementsForVfScaling","metricsPerEventName":[{"eventName":"Mfvs_eNodeB_RANKPI","controlLoopSchemaType":"VNF","policyScope":"resource=vFirewall;type=configuration","policyName":"configuration.dcae.microservice.tca.xml","policyVersion":"v0.0.1","thresholds":[{"closedLoopControlName":"CL-FRWL-LOW-TRAFFIC-SIG-d925ed73-8231-4d02-9545-db4e101f88f8","closedLoopEventStatus":"ONSET","version":"1.0.2","fieldPath":"$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedBroadcastPacketsAccumulated","thresholdValue":4000,"direction":"LESS_OR_EQUAL","severity":"MAJOR"},{"closedLoopControlName":"CL-FRWL-HIGH-TRAFFIC-SIG-EA36FE84-9342-5E13-A656-EC5F21309A09","closedLoopEventStatus":"ONSET","version":"1.0.2","fieldPath":"$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedBroadcastPacketsAccumulated","thresholdValue":20000,"direction":"GREATER_OR_EQUAL","severity":"CRITICAL"},{"closedLoopControlName":"CL-FRWL-HIGH-TRAFFIC-SIG-EA36FE84-9342-5E13-A656-EC5F21309A09","closedLoopEventStatus":"ABATED","version":"1.0.2","fieldPath":"$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedBroadcastPacketsAccumulated","thresholdValue":0,"direction":"EQUAL","severity":"CRITICAL"}]},{"eventName":"vLoadBalancer","controlLoopSchemaType":"VNF","policyScope":"resource=vLoadBalancer;type=configuration","policyName":"configuration.dcae.microservice.tca.xml","policyVersion":"v0.0.1","thresholds":[{"closedLoopControlName":"CL-LBAL-LOW-TRAFFIC-SIG-FB480F95-A453-6F24-B767-FD703241AB1A","closedLoopEventStatus":"ONSET","version":"1.0.2","fieldPath":"$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedBroadcastPacketsAccumulated","thresholdValue":500,"direction":"LESS_OR_EQUAL","severity":"MAJOR"},{"closedLoopControlName":"CL-LBAL-LOW-TRAFFIC-SIG-0C5920A6-B564-8035-C878-0E814352BC2B","closedLoopEventStatus":"ONSET","version":"1.0.2","fieldPath":"$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedBroadcastPacketsAccumulated","thresholdValue":5000,"direction":"GREATER_OR_EQUAL","severity":"CRITICAL"}]}]}'
                entry_schema:
                    type: onap.datatypes.monitoring.tca_policy
data_types:
    onap.datatypes.monitoring.metricsPerEventName:
        derived_from: tosca.datatypes.Root
        properties:
            controlLoopSchemaType:
                type: string
                description: Specifies Control Loop Schema Type for the
                    event Name e.g. VNF, VM
                constraints:
                  - valid_values:
                      - VM
                      - VNF
            eventName:
                type: string
                description: Event name to which thresholds need to be
                    applied
            policyName:
                type: string
                description: TCA Policy Scope Name
            policyScope:
                type: string
                description: TCA Policy Scope
            policyVersion:
                type: string
                description: TCA Policy Scope Version
            thresholds:
                type: list
                description: Thresholds associated with eventName
                entry_schema:      derived_from: tosca.datatypes.Root
                    type: onap.datatypes.monitoring.thresholds
    onap.datatypes.monitoring.tca_policy:
        derived_from: tosca.datatypes.Root
        properties:
            domain:
                type: string
                description: Domain name to which TCA needs to be applied
                default: measurementsForVfScaling
                constraints:
                  - equal: measurementsForVfScaling
            metricsPerEventName:
                type: list
                description: Contains eventName and threshold details
                    that need to be applied to given eventName
                entry_schema:
                    type: onap.datatypes.monitoring.metricsPerEventName
    onap.datatypes.monitoring.thresholds:
        derived_from: tosca.datatypes.Root
        properties:
            closedLoopControlName:
                type: string
                description: Closed Loop Control Name associated with
                    the threshold
            closedLoopEventStatus:
                type: string
                description: Closed Loop Event Status of the threshold
                constraints:
                  - valid_values:
                      - ONSET
                      - ABATED
            direction:
                type: string
                description: Direction of the threshold
                constraints:
                  - valid_values:
                      - LESS
                      - LESS_OR_EQUAL
                      - GREATER
                      - GREATER_OR_EQUAL
            fieldPath:
                type: string
                description: Json field Path as per CEF message which
                    needs to be analyzed for TCA
            severity:
                type: string
                description: Threshold Event Severity
                constraints:
                  - valid_values:
                      - CRITICAL
                      - MAJOR
                      - MINOR
                      - WARNING
                      - NORMAL
            thresholdValue:
                type: integer
                description: Threshold value for the field Path inside
                    CEF message
            version:
                type: string
                description: Version number associated with the threshold

1.2 onap.policies.controlloop.Operational Policy Type

This policy type is used to support actor/action operational policies for control loops. There are two types of implementations for this policy type

  1. Existing Drools implementations that supports runtime Control Loop actions taken on components such as SO/APPC/VFC/SDNC/SDNR
  2. New implementations using APEX to support Control Loops.
Base Policy type definition for onap.policies.controlloop.Operational 
tosca_definitions_version: tosca_simple_yaml_1_0_0
policy_types:
  onap.policies.controlloop.Operation:
    derived_from: tosca.policies.Root
    description: Operational Policy for Control Loops

1.2.1 Operational Policy Typer Schema for Drools

TBD

NOTE: For Dublin Drools will still support the Casablanca YAML definition of an Operational Policy for Control Loops. 

1.2.3 Operational Policy Type Schema for APEX

The operational Policy Type schema for for APEX extend the base operational Policy Type schema. This Policy Type allows parameters specific to the APEX PDP to be specified as a TOSCA policy.

Operational Policy Model Parameter Schema for APEX 
tosca_definitions_version: tosca_simple_yaml_1_0_0
# Note: The full APEX PolicyType definition will be developed during the Dublin
# timeframe of the ONAP project
policy_types:
  onap.policies.controlloop.Operation:
    derived_from: tosca.policies.Root
    description: Operational Policy for Control Loops

 onap.policies.controloop.Operation.apex:
    derived_from: onap.policies.controlloop.Operation
    version: 1.0.0
    description: Operational Policy for Control Loops using the APEX PDP
    properties:
      # Some of these properties may be redundant in K8S
      engine_service:
        type: onap.datatypes.policies.controlloop.operation.apex.engine_service
        description: APEX Engine Service Parameters
      inputs:
        type: map
        description: Inputs for handling events coming into the APEX engine
        entry_schema:
          type: onap.datatypes.policies.controlloop.operation.apex.event_handler
      outputs:
        type: map
        description: Outputs for handling events going out of the APEX engine
        entry_schema:
          type: onap.datatypes.policies.controlloop.operation.apex.event_handler
      environment:
        type: list
        description: Envioronmental parameters for the APEX engine
        entry_schema:
          type: onap.datatypes.policies.controlloop.operation.apex.environment

data_types:
  onap.datatypes.policies.controlloop.operation.apex.engine_service:
  derived_from: tosca.datatypes.Root
  properties:
    name:
      type: string
      description: Specifies the engine name
      required: false
      default: "ApexEngineService"
    version:
      type: string
      description: Specifies the engine version in double dotted format
      required: false
      default: "1.0.0"
    id:
      type: int
      description: Specifies the engine id
      required: true
    instance_count:
      type: int
      description: Specifies the number of engine threads that should be run
      required: true
    deployment_port:
      type: int
      description: Specifies the port to connect to for engine administration
      required: false
      default: 1
    policy_model_file_name:
      type: string
      description: The name of the file from which to read the APEX policy model
      required: false
      default: ""
    policy_type_impl:
      type: string
      description: The policy type implementation from which to read the APEX policy model
      required: false
      default: ""
    periodic_event_period:
      type: string
      description: The time interval in milliseconds for the periodic scanning
       event, 0 means "don't scan"
      required: false
      default: 0
    engine:
      type: onap.datatypes.policies.controlloop.operation.apex.engine_service.engine
      description: The parameters for all engines in the APEX engine service
      required: true

  onap.datatypes.policies.controlloop.operation.apex.event_handler:
  derived_from: tosca.datatypes.Root
  properties:
    name:
      type: string
      description: Specifies the event handler name, if not specified this is set to
       the key name
      required: false
    carrier_technology:
      type: onap.datatypes.policies.controlloop.operation.apex.carrier_technology
      description: Specifies the carrier technology of the event handler (such
       as REST/Web Socket/Kafka)
      required: true
    event_protocol:
      type: onap.datatypes.policies.controlloop.operation.apex.event_protocol
      description: Specifies the event protocol of events for the event handler
       (such as Yaml/JSON/XML/POJO)
      required: true
    event_name:
      type: string
      description: Specifies the event name for events on this event handler, if
       not specified, the event name is read from or written to the event being
       received or sent
      required: false
    event_name_filter:
      type: string
      description: Specifies a filter as a regular expression, events that do
       not match the filter are dropped, the default is to let all events
       through
      required: false
    synchronous_mode:
      type: bool
      description: Specifies the event handler is syncronous (receive event and
       send response)
      required: false
      default: false
    synchronous_peer:
      type: string
      description: The peer event handler (output for input or input for output)
       of this event handler in synchronous mode, this parameter is mandatory if
       the event handler is in synchronous mode
      required: false
      default: ""
    synchronous_timeout:
      type: int
      description: The timeout in milliseconds for responses to be issued by
       APEX torequests, this parameter is mandatory if the event handler is in
       synchronous mode
      required: false
      default: ""
    requestor_mode:
      type: bool
      description: Specifies the event handler is in requestor mode (send event
       and wait for response mode)
      required: false
      default: false
    requestor_peer:
      type: string
      description: The peer event handler (output for input or input for output)
       of this event handler in requestor mode, this parameter is mandatory if
       the event handler is in requestor mode
      required: false
      default: ""
    requestor_timeout:
      type: int
      description: The timeout in milliseconds for wait for responses to
       requests, this parameter is mandatory if the event handler is in
       requestor mode
      required: false
      default: ""

  onap.datatypes.policies.controlloop.operation.apex.carrier_technology:
  derived_from: tosca.datatypes.Root
  properties:
    label:
      type: string
      description: The label (name) of the carrier technology (such as REST,
       Kafka, WebSocket)
      required: true
    plugin_parameter_class_name:
      type: string
      description: The class name of the class that overrides default handling
        of event input or output for this carrier technology, defaults to the supplied
        input or output class
      required: false

  onap.datatypes.policies.controlloop.operation.apex.event_protocol:
  derived_from: tosca.datatypes.Root
  properties:
    label:
      type: string
      description: The label (name) of the event protocol (such as Yaml,
       JSON, XML, or POJO)
      required: true
    event_protocol_plugin_class:
      type: string
      description: The class name of the class that overrides default handling
        of the event protocol for this carrier technology, defaults to the
        supplied event protocol class
      required: false

  onap.datatypes.policies.controlloop.operation.apex.environmental:
  derived_from: tosca.datatypes.Root
  properties:
    name:
      type: string
      description: The name of the environment variable
      required: true
    value:
      type: string
      description: The value of the environment variable
      required: true

  onap.datatypes.policies.controlloop.operation.apex.engine_service.engine:
  derived_from: tosca.datatypes.Root
  properties:
    context:
      type: onap.datatypes.policies.controlloop.operation.apex.engine_service.engine.context
      description: The properties for handling context in APEX engines,
       defaults to using Java maps for context
      required: false
    executors:
      type: map
      description: The plugins for policy executors used in engines such as
       javascript, MVEL, Jython
      required: true
      entry_schema:
        description: The plugin class path for this policy executor
        type: string

  onap.datatypes.policies.controlloop.operation.apex.engine_service.engine.context:
  derived_from: tosca.datatypes.Root
  properties:
    distributor:
      type: onap.datatypes.policies.controlloop.operation.apex.plugin
      description: The plugin to be used for distributing context between
       APEX PDPs at runtime
      required: false
    schemas:
      type: map
      description: The plugins for context schemas available in APEX PDPs
       such as Java and Avro
      required: false
      entry_schema:
        type: onap.datatypes.policies.controlloop.operation.apex.plugin
    locking:
      type: onap.datatypes.policies.controlloop.operation.apex.plugin
      description: The plugin to be used for locking context in and
       between APEX PDPs at runtime
      required: false
    persistence:
      type: onap.datatypes.policies.controlloop.operation.apex.plugin
      description: The plugin to be used for persisting context for APEX PDPs
       at runtime
      required: false

  onap.datatypes.policies.controlloop.operation.apex.plugin:
  derived_from: tosca.datatypes.Root
  properties:
    name:
      type: string
      description: The name of the executor such as Javascript, Jython or MVEL
      required: true
    plugin_class_name:
      type: string
      description: The class path of the plugin class for this executor

1.3 onap.policies.controlloop.Guard Policy Type

This policy type is the the type definition for Control Loop guard policies for frequency limiting, blacklisting and min/max guards to help protect runtime Control Loop Actions from doing harm to the network. This policy type is developed using the XACML PDP to support question/answer Policy Decisions during runtime for the Drools and APEX onap.controlloop.Operational policy type implementations.

The base schema is defined as below:

Base Policy type definition for onap.policies.controlloop.Guard 
tosca_definitions_version: tosca_simple_yaml_1_0_0
policy_types:
  - onap.policies.controlloop.Guard:
      derived_from: tosca.policies.Root
      description: Guard Policies for Control Loop Operational Policies

As with onap.policies.Monitoring policy type, the PolicyTypeImpl implementation of the onap.policies.controlloop.Guard Policy Type is generic to support definition of TOSCA PolicyType artifacts in the Policy Framework using the Policy Type Design API.

The derived Policy Type definitions below are preloaded in the Policy Framework.

1.3.1 onap.policies.controlloop.Guard.FrequencyLimiter Policy Type

Policy Typefor Frequency Limiter Guard Policy 
tosca_definitions_version: tosca_simple_yaml_1_0_0
policy_types:
  - onap.policies.controlloop.Guard:
      derived_from: tosca.policies.Root
      description: Guard Policies for Control Loop Operational Policies
  - onap.policies.controlloop.Guard.FrequencyLimiter:
      derived_from: onap.policies.controlloop.Guard
      description: Supports limiting the frequency of actions being taken by a Actor.
      properties:
        frequency_policy:
          type: map
          description:
          entry_schema:
            type: onap.datatypes.Guard.FrequencyLimiter
data_types:
  - onap.datatypes.Guard.FrequencyLimiter:
      derived_from: tosca.datatypes.Root
      properties:
        actor:
          type: string
          description: Specifies the Actor
          required: true
        recipe:
          type: string
          description: Specified the Recipe
          required: true
        time_window:
          type: scalar-unit.time
          description: The time window to count the actions against.
          required: true
        limit:
          type: integer
          description: The limit
          required: true
          constraints:
            - greater_than: 0
        time_range:
          type: tosca.datatypes.TimeInterval
          description: An optional range of time during the day the frequency is valid for.
          required: false
        controlLoopName:
          type: string
          description: An optional specific control loop to apply this guard to.
          required: false
        target:
          type: string
          description: An optional specific VNF to apply this guard to.
          required: false

1.3.2 onap.policies.controlloop.Guard.Blacklist Policy Type

Policy Type for Blacklist Guard Policies 
tosca_definitions_version: tosca_simple_yaml_1_0_0
policy_types:
 - onap.policies.controlloop.Guard:
     derived_from: tosca.policies.Root
     description: Guard Policies for Control Loop Operational Policies
  - onap.policies.controlloop.Guard.Blacklist:
      derived_from: onap.policies.controlloop.Guard
      description: Supports blacklist of VNF's from performing control loop actions on.
      properties:
        blacklist_policy:
          type: map
          description:
          entry_schema:
            type: onap.datatypes.Guard.Blacklist
data_types:
  - onap.datatypes.Guard.Blacklist:
      derived_from: tosca.datatypes.Root
      properties:https://wiki.onap.org/display/DW/Policy+Types
        actor:
          type: string
          description: Specifies the Actor
          required: true
        recipe:
          type: string
          description: Specified the Recipe
          required: true
        time_range:
          type: tosca.datatypes.TimeInterval
          description: An optional range of time during the day the blacklist is valid for.
          required: false
        controlLoopName:
          type: string
          description: An optional specific control loop to apply this guard to.
          required: false
        blacklist:
          type: list
          description: List of VNF's
          required: true

1.3.3 onap.policies.controlloop.Guard.MinMax Policy Type

Policy Type for Min/Max VF Module Policies 
policy_types:
  - onap.policies.controlloop.Guard:
      derived_from: tosca.policies.Root
      description: Guard Policies for Control Loop Operational Policies
  - onap.policies.controlloop.Guard.MinMax:
      derived_from: onap.policies.controlloop.Guard
      description: Supports Min/Max number of VF Modules
      properties:
        minmax_policy:
          type: map
          description:
          entry_schema:
            type: onap.datatypes.Guard.MinMax
data_types:
  - onap.datatypes.Guard.MinMax:
      derived_from: tosca.datatypes.Root
      properties:
        actor:
          type: stringhttps://wiki.onap.org/display/DW/Policy+Types
          description: Specifies the Actor
          required: true
        recipe:
          type: string
          description: Specified the Recipe
          required: true
        time_range:
          type: tosca.datatypes.TimeInterval
          description: An optional range of time during the day the Min/Max limit is valid for.
          required: false
        controlLoopName:
          type: string
          description: An optional specific control loop to apply this guard to.
          required: false
        min_vf_module_instances:
          type: integer
          required: true
          description: The minimum instances of this VF-Module

        max_vf_module_instances:
          type: integer
          required: false
          description: The maximum instances of this VF-Module

1.3.4 onap.policies.controlloop.Coordination Policy Type (STRETCH)

This policy type defines Control Loop Coordination policies to assist in coordinating multiple control loops during runtime. This policy type is developed using XACML PDP to support question/answer policy decisions at runtime for the onap.policies.controlloop.operational policy types.

2 PDP Deployment and Registration with PAP

The unit of execution and scaling in the Policy Framework is a PolicyImpl entity. A PolicyImpl entity runs on a PDP. As is explained above a PolicyImpl entity is a PolicyTypeImpl implementation parameterized with a TOSCA Policy.

In order to achieve horizontal scalability, we group the PDPs running instances of a given PolicyImpl entity logically together into a PDPSubGroup. The number of PDPs in a PDPSubGroup can then be scaled up and down using Kubernetes. In other words, all PDPs in a subgroup run the same PolicyImpl, that is the same policy template implementation (in XACML, Drools, or APEX) with the same parameters.

The figure above shows the layout of PDPGroup and PDPSubGroup entities. The figure shows examples of PDP groups for Control Loop and Monitoring policies on the right.

The health of PDPs is monitored by the PAP in order to alert operations teams managing policy. The PAP manages the life cycle of policies running on PDPs.

The table below shows the methods in which PolicyImpl entities can be deployed to PDP Subgroups

MethodDescriptionAdvantagesDisadvantages
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 and parameters of the PDPs in a PDP group may be changed at run time by loading or updating the TOSCA Policy of the PDP Group at run time.

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, and parameters of the PDPs in a PDP group may be changed at run time by loading or updating the PolicyTypeImpl and TOSCA Policy of the PDP Group at run time.

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. APIs

The Policy Framework supports the APIs documented in the subsections below.

3.1 Policy Type Design API

The purpose of this API is to support CRUD of TOSCA PolicyType entities. It also 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.

3.1.1 TOSCA Policy Types

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:

FieldGETPOSTDELETEComment
(name)MMMThe definition of the reference to the Policy Type, GET allows ranges to be specified
versionOMCGET allows ranges to be specified, must be specified if more than one version of the Policy Type exists
descriptionRON/ADesciption of the Policy Type
derived_fromRCN/AMust be specified when a Policy Type is derived from another Policy Type such as in the case of derived Monitoring Policy Types
metadataRON/AMetadata for the Policy Type
propertiesRMN/AThis field holds the specification of the specific Policy Type in ONAP
targetsRON/AA list of node types and/or group types to which the Policy Type can be applied
triggersRON/ASpecification of policy triggers, not currently supported in ONAP

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.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.

http:{url}:{port}/api/v1/policytypes GET

Policy Type Query - When system comes up before any mS are onboarded 
policy_types:
  - onap.policies.Monitoring:
      version: 1.0.0
      description: A base policy type for all policies that govern monitoring provision
      derived_from: tosca.policies.Root

  - onap.policies.controlloop.Operational:
      version: 1.0.0
      description: Operational Policy for Control Loops
      derived_from: tosca.policies.Root

  - onap.policies.controloop.Operation.drools:
      version: 1.0.0
      description: Operational Policy for Control Loops using the Drools PDP
      derived_from: onap.policies.controlloop.Operation

  - onap.policies.controloop.Operation.apex:
      version: 1.0.0
      description: Operational Policy for Control Loops using the APEX PDP
      derived_from: onap.policies.controlloop.Operation

 - onap.policies.controlloop.Guard:
      version: 1.0.0
      description: Operational Policy for Control Loops
      derived_from: tosca.policies.Root

  - onap.policies.controlloop.Guard.FrequencyLimiter:
      version: 1.0.0
      description: Supports limiting the frequency of actions being taken by a Actor.
      derived_from: onap.policies.controlloop.Guard

  - onap.policies.controlloop.guard.blacklist:
      version: 1.0.0
      description: Supports blacklist of VNF's from performing control loop actions on.
      derived_from: onap.policies.controlloop.Guard

  - onap.policies.controlloop.guard.minmax:
      version: 1.0.0
      description: Supports Min/Max number of VF Modules
      derived_from: onap.policies.controlloop.Guard

  - onap.policies.controlloop.Coordination.TBD: (STRETCH GOALS) 
      version: 1.0.0
      description: Control Loop Coordination policy types
      derived_from: tosca.policies.Root 


The table below shows some more examples of GET operations

ExampleDescription
http:{url}:{port}/api/v1/policytypesGet all Policy Type entities in the system

http:{url}:{port}/api/v1/policytypes/{policy type id}

eg.

http:{url}:{port}/api/v1/policytypes/onap.policies.Monitoring.cdap.tca.hi.lo.app


Get a specific policy type and all the available versions.


http:{url}:{port}/api/v1/policytypes/{policy type id}/versions/{version id}


eg.

http:{url}:{port}/api/v1/policytypes/onap.policies.Monitoring.cdap.tca.hi.lo.app/versions/1.0.0



Get the specific Policy Type with the specified name and version

3.1.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.

http:{url}:{port}/api/v1/policytypes POST

Create a new Policy Type for a DCAE microservice 
policy_types:
  - onap.policies.monitoring.cdap.tca.hi.lo.app:
      version: 1.0.0
      derived_from: onap.policies.Monitoring
      description: A DCAE TCA high/low policy type
      properties:
        tca_policy:
          type: map
          description: TCA Policy JSON
          default:'{<JSON omitted for brevity>}'
          entry_schema:
            type: onap.datatypes.monitoring.tca_policy

data_types:
  <omitted for brevity>

Following creation of a DCAE TCA policy type operation, the GET call for Monitoring policies will list the new policy type. 

http:{url}:{port}/api/v1/policytypes GET

Policy Type Query after DCAE TCA mS Policy Type is created 
policy_types:
  - onap.policies.Monitoring:
      version: 1.0.0
      derived_from: tosca.policies.Root
      description: A base policy type for all policies that govern monitoring provision
  - onap.policies.Monitoring.cdap.tca.hi.lo.app:
      version: 1.0.0
      derived_from: onap.policies.Monitoring
      description: A DCAE TCA high/low policy type


  - onap.policies.controlloop.Operational:

      version: 1.0.0
      description: Operational Policy for Control Loops
      derived_from: tosca.policies.Root

  - onap.policies.controloop.Operation.drools:
      version: 1.0.0
      description: Operational Policy for Control Loops using the Drools PDP
      derived_from: onap.policies.controlloop.Operation

  - onap.policies.controloop.Operation.apex:
      version: 1.0.0
      description: Operational Policy for Control Loops using the APEX PDP
      derived_from: onap.policies.controlloop.Operation

 - onap.policies.controlloop.Guard:
      version: 1.0.0
      description: Operational Policy for Control Loops
      derived_from: tosca.policies.Root

  - onap.policies.controlloop.Guard.FrequencyLimiter:
      version: 1.0.0
      description: Supports limiting the frequency of actions being taken by a Actor.
      derived_from: onap.policies.controlloop.Guard

  - onap.policies.controlloop.guard.blacklist:
      version: 1.0.0
      description: Supports blacklist of VNF's from performing control loop actions on.
      derived_from: onap.policies.controlloop.Guard

  - onap.policies.controlloop.guard.minmax:
      version: 1.0.0
      description: Supports Min/Max number of VF Modules
      derived_from: onap.policies.controlloop.Guard

  - onap.policies.controlloop.Coordination.TBD: (STRETCH GOALS) 
      version: 1.0.0
      description: Control Loop Coordination policy types
      derived_from: tosca.policies.Root

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.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:

http:{url}:{port}/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.1.2 Policy Type Implementations

The policy Framework must have implementations for all Policy Type entities that may be specified in TOSCA. Policy type implementations 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.

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:

FieldGETPOSTDELETEComment
nameMMMThe name of the Policy Type implementation
versionOMCThe version of the Policy Type implementation
policy_typeRMN/AThe TOSCA policy type that this policy type implementation implements
pdp_typeRMN/AThe PDP type of this policy type implementation, currently xacml, drools, or apex
descriptionRON/AThe description of the policy type implementation
writableRN/AN/AWritable flag, false for predefined policy type implementations, true for policy type implementations defined over the API
policy_bodyRMN/AThe body (source) of the policy type implementation
propertiesRON/ASpecific properties for the policy type implementation

3.1.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.

http:{url}:{port}/api/v1/policytypeimpl GET

Policy Type Implementation Query Result 
policy_type_impls:
  - name: onap.policies.monitoring.impl
    version: 1.0.0
    policy_type: onap.policies.monitoring
    pdp_type: xacml
    description: Implementation of the XACML monitoring policy
    writable: false

  - name: onap.policies.controlloop.guard.impl
    version: 1.0.0
    policy_type: onap.policies.controlloop.guard
    pdp_type: xacml
    description: Implementation of the XACML control loop guard policies
    writable: false

  - name: onap.policies.operation.drools.impl
    version: 1.0.0
    policy_type: onap.policies.operation
    pdp_type: drools
    description: Implementation of the drools control loop policies
    writable: false

  - name: onap.policies.operational.apex.bbs.impl
    version: 1.0.0
    policy_type: onap.policies.operation.apex
    pdp_type: apex
    description: Implementation of the APEX BBS control loop policy
    writable: true
    policy_body: "<policy body>"

  - name: onap.policies.operational.apex.sampledomain.impl
    version: 1.0.0
    policy_type: onap.policies.operation.apex
    pdp_type: apex
    description: Implementation of the SampleDomain test APEX policy
    writable: true
    policy_body: "<policy body>"

The table below shows some more examples of GET operations

ExampleDescription
http:{url}:{port}/api/v1/policytypeimplGet all Policy Type implementation entities in the system

http:{url}:{port}/api/v1/policytypeimpl?name=onap.monitoring*

Get all Policy Type implementations that match the name wildcard supplied

http:{url}:{port}/api/v1/policytypeimpl?name=onap.policies.monitoring.impl&version=1.0.0

Get the specific Policy Type implementation with the specified name and version

3.1.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.

http:{url}:{port}/api/v1/policytypeimpl POST

Create a new Policy Type Implementation 
policy_type_impls:
  - onap.policies.operational.apex.bbs.impl:
      version: 1.0.0
      policy_type: onap.policies.operation.apex
      pdp_type: apex
      description: Implementation of the APEX BBS control loop policy
      policy_body: "<policy body>"
  - onap.policies.operational.apex.sampledomain.impl:
      version: 1.0.0
      policy_type: onap.policies.operation.apex
      pdp_type: apex
      description: Implementation of the APEX SampleDomain control loop policy
      policy_body: "<policy body>

Once this call is made, the Policy Type query in Section 3.1.2.1 returns a result with the new Policy Type implementation defined.

3.1.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:

http:{url}:{port}/api/v1/policytypeimpl?name=onap.policies.apex.bbs.impl&version=1.0.0

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

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:

FieldGETPOSTDELETEComment
(name)MMMThe definition of the reference to the Policy, GET allows ranges to be specified
typeOMOThe Policy Type of the policy, see section 3.1
descriptionROO
metadataRON/A
propertiesRMN/AThis field holds the specification of the specific Policy in ONAP
targetsRON/AA 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

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.

http:{url}:{port}/api/v1/policy GET

The table below shows some more examples of GET operations

ExampleDescription

http:{url}:{port}/api/v1/policytypes/{policy type id}/versions/{versions}/policies

eg

http:{url}:{port}/api/v1/policytypes/onap.policies.Monitoring.cdap.tca.hi.lo.app/versions/1.0.0/policies

Get all Policies for a specific Policy Type and version

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.

http:{url}:{port}/api/v1/policytypes/onap.policies.Monitoring.cdap.tca.hi.lo.app/versions/1.0.0/policies POST

TOSCA Body of a new TCA High/Low Policy 
policies:
  - onap.scaleout.tca:
      type: onap.policies.monitoring.cdap.tca.hi.lo.app
      properties:
        domain: measurementsForVfScaling
        metricsPerEventName: 
          - 
            eventName: vLoadBalancer
            controlLoopSchemaType: VNF
            policyScope: "type=configuration"
            policyName: "onap.scaleout.tca"
            policyVersion: "v0.0.1"
            thresholds: 
              - closedLoopControlName: "CL-LBAL-LOW-TRAFFIC-SIG-FB480F95-A453-6F24-B767-FD703241AB1A"
                closedLoopEventStatus: ONSET
                version: "1.0.2"
                fieldPath: "$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedBroadcastPacketsAccumulated"
                thresholdValue: 500
                direction: LESS_OR_EQUAL
                severity: MAJOR
              - 
                closedLoopControlName: "CL-LBAL-LOW-TRAFFIC-SIG-0C5920A6-B564-8035-C878-0E814352BC2B"
                closedLoopEventStatus: ONSET
                version: "1.0.2"
                fieldPath: "$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedBroadcastPacketsAccumulated"
                thresholdValue: 5000
                direction: GREATER_OR_EQUAL
                severity: CRITICAL

Given a return code of success, the following policy will be listed:

http:{url}:{port}/api/v1/policytypes/onap.policies.Monitoring.cdap.tca.hi.lo.app/versions/1.0.0/policies GET

policies:
  - onap.scaleout.tca:
      type: onap.policies.monitoring.cdap.tca.hi.lo.app
      version: 1

And the contents can be retrieved using the ID:

http:{url}:{port}/api/v1/policytypes/onap.policies.Monitoring.cdap.tca.hi.lo.app/versions/1.0.0/policies/onap.scaleout.tca GET

versions:
 -
  version: 1
  status:
    deployed: false
  policy:
    onap.scaleout.tca:
      type: onap.policies.monitoring.cdap.tca.hi.lo.app
      properties:
        domain: measurementsForVfScaling
        metricsPerEventName: 
          - 
            eventName: vLoadBalancer
            controlLoopSchemaType: VNF
            policyScope: "type=configuration"
            policyName: "onap.scaleout.tca"
            policyVersion: "v0.0.1"
            thresholds: 
              - closedLoopControlName: "CL-LBAL-LOW-TRAFFIC-SIG-FB480F95-A453-6F24-B767-FD703241AB1A"
                closedLoopEventStatus: ONSET
                version: "1.0.2"
                fieldPath: "$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedBroadcastPacketsAccumulated"
                thresholdValue: 500
                direction: LESS_OR_EQUAL
                severity: MAJOR
              - 
                closedLoopControlName: "CL-LBAL-LOW-TRAFFIC-SIG-0C5920A6-B564-8035-C878-0E814352BC2B"
                closedLoopEventStatus: ONSET
                version: "1.0.2"
                fieldPath: "$.event.measurementsForVfScalingFields.vNicPerformanceArray[*].receivedBroadcastPacketsAccumulated"
                thresholdValue: 5000
                direction: GREATER_OR_EQUAL
                severity: CRITICAL

Some other examples on how the policy versions can be retrieved:

ExampleDescription

http:{url}:{port}/api/v1/policytypes/{policy type id}/versions/{versions}/policies

eg

http:{url}:{port}/api/v1/policytypes/onap.policies.Monitoring.cdap.tca.hi.lo.app/versions/1.0.0/policies/onap.scaleout.tca&version=1 GET


Gets a specific Policy version

http:{url}:{port}/api/v1/policytypes/onap.policies.Monitoring.cdap.tca.hi.lo.app/versions/1.0.0/policies/onap.scaleout.tca&latest GET

Returns the latest version of a Policy

http:{url}:{port}/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.

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.

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 <???> Policy for the <????> APEX operational policy type.

http:{url}:{port}/api/v1/policy POST

Create an APEX Policy for a Sample Domain 
policies:
  - onap.policy.operational.apex.sampledomain.test:
      type: onap.policies.controloop.operation.apex
      properties:
        engine_service:
          name: "MyApexEngine"
          version: "0.0.1"
          id: 45
          instance_count: 4
          deployment_port: 12561
          policy_type_impl: "onap.policies.operational.apex.sampledomain.impl"
          engine:
            executors:
                JAVASCRIPT: "org.onap.policy.apex.plugins.executor.javascript.JavascriptExecutorParameters"

        inputs:
          first_consumer:
            carrier_technology:
              label: "RESTCLIENT",
              plugin_parameter_class_name: "org.onap.policy.apex.plugins.event.carrier.restclient.RestClientCarrierTechnologyParameters",
              parameters:
                url: "http://localhost:32801/EventGenerator/GetEvents"
            event_protocol:
              label: "JSON"

        outputs:
          first_producer:
            carrier_technology:
              label: "RESTCLIENT",
              plugin_parameter_class_name: "org.onap.policy.apex.plugins.event.carrier.restclient.RestClientCarrierTechnologyParameters",
              parameters:
                url: "http://localhost:32801/EventGenerator/PostEvent"
            event_protocol:
              label: "JSON"

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 Policy Design and API Flow for Model Driven Control Loop - Draft 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:

http:{url}:{port}/api/v1/policy?name=onap.scaleout.tca DELETE


ExampleDescription

http:{url}:{port}/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.

The fields below are valid on API calls:

FieldGETPOSTDELETEComment
nameMMMThe name of the PDP group
versionOMCThe version of the PDP group
stateRN/AN/AThe administrative state of the PDP group: PASSIVE, SAFE, TEST, or ACTIVE
descriptionRON/AThe PDP group desciption
propertiesRON/ASpecific properties for a PDP group
pdp_subgroupsRMN/AA list of PDP subgroups for a PDP group

pdp_typeRMN/AThe PDP type of this PDP subgroup, currently xacml, drools, or apex

policiesRMN/AThe list of policies running on the PDPs in this PDP subgroup


(name)RMN/AThe name of a TOSCA policy running in this PDP subgroup


policy_typeRN/AN/AThe TOSCA policy type of the policy


policy_type_versionRN/AN/AThe version of the TOSCA policy type of the policy


policy_type_implRCN/AThe policy type implementation (XACML, Drools Rules, or APEX Model) that implements the policy

instance_countRN/AN/AThe number of PDP instances running in a PDP subgroup

min_instance_countON/AN/AThe minumum number of PDP instances to run in a PDP subgroup

propertiesON/AN/ADeployment configuration or other properties for the PDP subgroup

kubernetes_infoRN/AN/AInformation on the Kubernetes service and deployment for a PDP subgroup

instancesRN/AN/AA list of PDP instances running in a PDP subgroup


instanceRN/AN/AThe instance ID of a PDP running in a Kuberenetes Pod


kubernetes_instance_info
RN/AN/AInformation on the Kubernetes Pod running the PDP

Note: In the Dublin release, the policy_type_impl of all policy types in a PDP subgroup must be the same.

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.

http:{url}:{port}/pap/v1/pdps GET

PDP Group query for all PDP groups and Subgroups 
pdp_groups:
  - name: onap.pdpgroup.controlloop.operational
    version: 1.0.0
    state: active
    description: ONAP Control Loop Operational and Guard policies
    properties:
      # PDP group level properties if any
    pdp_subgroups:
      - pdp_type: drools
        policies:
          - onap.controllloop.operational.drools.vCPE.eastRegion:
              policy_type: onap.controllloop.operational.drools.vCPE
              policy_type_version: 1.0.0
              policy_type_impl: onap.controllloop.operational.drools.impl
          - onap.controllloop.operational.drools.vFW.eastRegion:
              policy_type: onap.controllloop.operational.drools.vFW
              policy_type_version: 1.0.0
              policy_type_impl: onap.controllloop.operational.drools.impl
        min_instance_count: 3
        instance_count: 3
        properties:
          # The properties below are for illustration only
          instance_spawn_load_threshold: 70%
          instance_kill_load_threshold: 50%
          instance_geo_redundancy: true
        kubernetes_info:
          service_endpoint: https://<the drools service endpoint for this PDP group>
          deployment: Kubernetes deployment identifier
          # Other K8S info
        instances:
          - instance: drools_1
            kubernetes_instance_info:
              pod_id: drools_1_pod
              # Other K8S instance info
          - instance: drools_2
            kubernetes_instance_info:
              pod_id: drools_2_pod
              # Other K8S instance info
          - instance: drools_3
            kubernetes_instance_info:
              pod_id: drools_3_pod
              # Other K8S instance info

      - pdp_type: apex
        policies:
          - onap.controllloop.operational.apex.BBS.eastRegion:
              policy_type: onap.controllloop.operational.apex.BBS
              policy_type_version: 1.0.0
              policy_type_impl: onap.controllloop.operational.apex.impl
          - onap.controllloop.operational.apex.sampledomain.eastRegion:
              policy_type: onap.controllloop.operational.apex.sampledomain
              policy_type_version: 1.0.0
              policy_type_impl: onap.controllloop.operational.apex.impl
        min_instance_count: 2
        instance_count: 3
        properties:
          # The properties below are for illustration only
          instance_spawn_load_threshold: 80%
          instance_kill_load_threshold: 60%
          instance_geo_redundancy: true
        kubernetes_info:
          service_endpoint: https://<the apex service endpoint for this PDP group>
          deployment: Kubernetes deployment identifier
          # Other K8S info
        instances:
          - instance: apex_1
            kubernetes_instance_info:
              pod_id: apex_1_pod
              # Other K8S instance info
          - instance: apex_2
            kubernetes_instance_info:
              pod_id: apex_2_pod
              # Other K8S instance infoCreation
          - instance: apex_3
            kubernetes_instance_info:
              pod_id: apex_3_pod
              # Other K8S instance info

      - pdp_type: xacml
        policies:
          - onap.policies.controlloop.Guard.FrequencyLimiter.eastRegion:
              policy_type: onap.policies.controlloop.Guard.FrequencyLimiter
              policy_type_version: 1.0.0
              policy_type_impl: onap.controllloop.guard.impl
          - onap.policies.controlloop.Guard.BlackList.eastRegion:
              policy_type: onap.policies.controlloop.Guard.BlackList
              policy_type_version: 1.0.0
              policy_type_impl: onap.controllloop.guard.impl
          - onap.policies.controlloop.Guard.MinMax.eastRegion:
              policy_type: onap.policies.controlloop.Guard.MinMax
              policy_type_version: 1.0.0
              policy_type_impl: onap.controllloop.guard.impl
        min_instance_count: 2
        instance_count: 2
        properties:
          # The properties below are for illustration only
          instance_geo_redundancy: true
        kubernetes_info:
          service_endpoint: https://<the XACML service endpoint for this PDP group>
          deployment: Kubernetes deployment identifier
          # Other K8S info
        instances:
          - instance: xacml_1
            kubernetes_instance_info:
              pod_id: xacml_1_pod
              # Other K8S instance info
          - instance: xacml_2
            kubernetes_instance_info:
              pod_id: xacml_2_pod
              # Other K8S instance info

  - name: onap.pdpgroup.monitoring
    version: 2.1.3
    state: active
    description: DCAE mS Configuration Policies
    properties:
      # PDP group level properties if any
    pdp_subgroups:
      - pdp_type: xacml
        policies:
          - onap.scaleout.tca:
              policy_type: onap.policies.monitoring.cdap.tca.hi.lo.app
              policy_type_version: 1.0.0
              policy_type_impl: onap.policies.monitoring.impl
        min_instance_count: 2
        instance_count: 2
        properties:
          # The properties below are for illustration only
          instance_geo_redundancy: true
        kubernetes_info:
          service_endpoint: https://<the XACML service endpoint for this PDP group>
          deployment: Kubernetes deployment identifier
          # Other K8S info
        instances:
          - instance: xacml_1
            kubernetes_instance_info:
              pod_id: xacml_1_pod
              # Other K8S instance info
          - instance: xacml_2
            kubernetes_instance_info:
              pod_id: xacml_2_pod
              # Other K8S instance info

The table below shows some more examples of GET operations

ExampleDescription

http:{url}:{port}/pap/v1/pdps

Get all PDP Groups and subgroups in the system
http:{url}:{port}/pap/v1/pdps?group=onap.pdpgroup.controlloop*
Get PDP Groups and subgroups that match the supplied name filter

http:{url}:{port}/pap/v1/pdps?group=onap.pdpgroup.monitoring&version=2.1.3

Get the PDP group with the specified name and version

http:{url}:{port}/pap/v1/pdps?group=onap.pdpgroup.monitoring&subgroup=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 and deployed together with their policies. A POST operation is used to create a new PDP group name or a new PDP group version. A POST operation is also used to update an existing PDP group, but the PDP group must be in state PASSIVE or the operation is rejected. 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.

http:{url}:{port}/pap/v1/pdps POST

POST body to deploy or update PDP groups 
pdp_groups:
  - name: onap.pdpgroup.controlloop.operational
    version: 1.0.0
    description: ONAP Control Loop Operational and Guard policies
    pdp_subgroups:
      - pdp_type: drools
        policies:
          - onap.controllloop.operational.drools.vCPE.eastRegion
          - onap.controllloop.operational.drools.vFW.eastRegion
        min_instance_count: 3
        properties:
          # The properties below are for illustration only
          instance_spawn_load_threshold: 70%
          instance_kill_load_threshold: 50%
          instance_geo_redundancy: true

      - pdp_type: apex
        policies:
          - onap.controllloop.operational.apex.BBS.eastRegion
          - onap.controllloop.operational.apex.SampleDomain.eastRegion
        min_instance_count: 2
        properties:
          # The properties below are for illustration only
          instance_spawn_load_threshold: 80%
          instance_kill_load_threshold: 60%
          instance_geo_redundancy: true

      - pdp_type: xacml
        policies:
          - onap.policies.controlloop.Guard.FrequencyLimiter.eastRegion
          - onap.policies.controlloop.Guard.BlackList.eastRegion
          - onap.policies.controlloop.Guard.MinMax.eastRegion
        min_instance_count: 2
        properties:
          # The properties below are for illustration only
          instance_geo_redundancy: true

  - name: onap.pdpgroup.monitoring
    version: 2.1.3
    description: DCAE mS Configuration Policies
    properties:
      # PDP group level properties if any
    pdp_subgroups:
      - pdp_type: xacml
        policies:
          - onap.scaleout.tca
        min_instance_count: 2
        properties:
          # The properties below are for illustration only
          instance_geo_redundancy: true

Other systems such as CLAMP can use this API to deploy policies using a POST operation with the body below where only mandatory fields are specified.

http:{url}:{port}/pap/v1/pdps POST

POST body to deploy or update PDP groups 
pdp_groups:
  - name: onap.pdpgroup.monitoring
    version: 2.1.3
    description: DCAE mS Configuration Policies
    pdp_subgroups:
      - pdp_type: xacml
        policies:
          - onap.scaleout.tca

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. In cases where more than one version of a PDP group exist, the version parameter must be specified on the DELETE operation. The format of the delete operation is as below:

http:{url}:{port}/pap/v1/pdps?name=onap.pdpgroup.monitoring&version=2.1.3 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:

http:{url}:{port}/pap/v1/pdps?name=onap.pdpgroup.monitoring&version=2.1.3&state=ACTIVE

There are a number of rules for state management:

  1. Only one version of a PDP group may be ACTIVE at any time
  2. If a PDP group with a certain version is ACTIVE and a later version of the same PDP group is activated, then the system upgrades the PDP group
  3. If a PDP group with a certain version is ACTIVE and an earlier version of the same PDP group is activated, then the system downgrades the PDP group
  4. There is no restriction on the number of PASSIVE versions of a PDP group that can exist in the system
  5. <Rules on SAFE/TEST> ? Pamela Dragosh

3.3.5 PDP Group Statistics

This operation allows statistics for PDP groups, PDP subgroups, and individual PDPs to be retrieved.

http:{url}:{port}/pap/v1/pdps/statistics GET

Draft Example statistics returned for a PDP Group 
report_timestamp: 2019-02-11T15:23:50+00:00
pdp_group_count: 2
pdp_groups:
  - name: onap.pdpgroup.controlloop.operational
    state: active
    create_timestamp: 2019-02-11T15:23:50+00:00
    update_timestamp: 2019-02-12T15:23:50+00:00
    state_change_timestamp: 2019-02-13T15:23:50+00:00
    pdp_subgroups:
      - pdp_type: drools
        instance_count: 3
        deployed_policy_count: 2
        policy_execution_count: 123
        policy_execution_ok_count: 121
        policy_execution_fail_count: 2
        instances:
          - instance: drools_1
              start_timestamp: 2019-02-13T15:23:50+00:00
              policy_execution_count: 50
              policy_execution_ok_count: 49
              policy_execution_fail_count: 1
          - instance: drools_2
              start_timestamp: 2019-02-13T15:30:50+00:00
              policy_execution_count: 50
              policy_execution_ok_count: 49
              policy_execution_fail_count: 1
          - instance: drools_3
              start_timestamp: 2019-02-13T15:33:50+00:00
              policy_execution_count: 23
              policy_execution_ok_count: 23
              policy_execution_fail_count: 0

The table below shows some more examples of GET operations fpr statistics

ExampleDescription

http:{url}:{port}/pap/v1/pdps/statistics

Get statistics for all PDP Groups and subgroups in the system
http:{url}:{port}/pap/v1/pdps/statistics ?group=onap.pdpgroup.controlloop*
Get statistics for all PDP Groups and subgroups that match the supplied name filter

http:{url}:{port}/pap/v1/pdps/statistics ?group=onap.pdpgroup.monitoring&version=2.1.3

Get statistics for all the PDP group with the specified name and version

http:{url}:{port}/pap/v1/pdps/statistics ?group=onap.pdpgroup.monitoring&subgroup=xacml

Get statistics for 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.

*** some sections/fields are optional, we need to mark these ***

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.

http:{url}:{port}/decision/v1/ POST

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.

The simple draft example below shows the JSON body of a query in which a specific policy (the latest deployed version) is returned.
The query above gives a response similar to the example shown below.
The  draft example below shows the JSON body of a query in which all possible query fields are specified. This is the most fine-grained query one can create.


  • No labels