docs/design/design.rst

   1 .. This work is licensed under a
   2 .. Creative Commons Attribution 4.0 International License.
   3 .. http://creativecommons.org/licenses/by/4.0
   4
   5 .. _design-label:
   6
   7 Policy Design and Development
   8 #############################
   9
  10 .. contents::
  11     :depth: 3
  12
  13 This document describes the design principles that should be used to write, deploy, and run policies of various types
  14 using the Policy Framework. It explains the APIs that are available for Policy Framework users. It provides copious
  15 examples to illustrate policy design and API usage.
  16
  17 1 Introduction
  18 ==============
  19
  20 The figure below shows the Artifacts (Blue) in the ONAP Policy Framework, the Activities (Yellow) that manipulate them,
  21 and important components (Salmon) that interact with them. The Policy Framework is fully TOSCA compliant, and uses
  22 TOSCA to model policies. Please see the :ref:`TOSCA Policy Primer <tosca-label>` page for an introduction to TOSCA
  23 policy concepts.
  24
  25 .. image:: images/APIsInPolicyFramework.svg
  26
  27 TOSCA defines the concept of a *PolicyType*, the definition of a type of policy that can be applied to a service. It
  28 also defines the concept of a *Policy*, an instance of a *PolicyType*. In the Policy Framework, we handle and manage
  29 these TOSCA definitions and tie them to real implementations of policies that can run on PDPs.
  30
  31 The diagram above outlines how this is achieved. Each TOSCA *PolicyType* must have a corresponding *PolicyTypeImpl* in
  32 the Policy Framework. The TOSCA *PolicyType* definition can be used to create a TOSCA *Policy* definition, either
  33 directly by the Policy Framework, by CLAMP, or by some other system. Once the *Policy* artifact exists, it can be used
  34 together with the *PolicyTypeImpl* artifact to create a *PolicyImpl* artifact. A *PolicyImpl* artifact is an executable
  35 policy implementation that can run on a PDP.
  36
  37 The TOSCA *PolicyType* artifact defines the external characteristics of the policy; defining its properties, the types
  38 of entities it acts on, and its triggers.  A *PolicyTypeImpl* artifact is an XACML, Drools, or APEX implementation of
  39 that policy definition. *PolicyType* and *PolicyTypeImpl* artifacts may be preloaded, may be loaded manually, or may be
  40 created using the Lifecycle API. Alternatively, *PolicyType* definitions may be loaded over the Lifecycle API for
  41 preloaded *PolicyTypeImpl* artifacts. A TOSCA *PolicyType* artifact can be used by clients (such as CLAMP or CLI tools)
  42 to create, parse, serialize, and/or deserialize an actual Policy.
  43
  44 The TOSCA *Policy* artifact is used internally by the Policy Framework, or is input by CLAMP or other systems. This
  45 artifact specifies the values of the properties for the policy and specifies the specific entities the policy acts on.
  46 Policy Design uses the TOSCA *Policy* artifact and the *PolicyTypeImpl* artifact to create an executable *PolicyImpl*
  47 artifact.
  48
  49 2 ONAP Policy Types
  50 ===================
  51
  52 Policy Type Design manages TOSCA *PolicyType* artifacts and their *PolicyTypeImpl* implementations.
  53
  54 A TOSCA *PolicyType* may ultimately be defined by the modeling team but for now are defined by the Policy Framework
  55 project. Various editors and GUIs are available for creating *PolicyTypeImpl* implementations. However, systematic
  56 integration of *PolicyTypeImpl* implementation is outside the scope of the ONAP Dublin release.
  57
  58 The *PolicyType* definitions and implementations listed below are preloaded and are always available for use in the
  59 Policy Framework.
  60
  61 =======================================  ===============================================================================
  62 **Policy Type**                          **Description**
  63 =======================================  ===============================================================================
  64 onap.policies.Monitoring                 Overarching model that supports Policy driven DCAE microservice components used
  65                                          in Control Loops
  66 onap.policies.controlloop.Operational    Used to support legacy actor/action operational policies for control loops
  67 onap.policies.controlloop.Guard          Control Loop guard policies for policing control loops
  68 onap.policies.controlloop.Coordination   Control Loop Coordination policies to assist in coordinating multiple control
  69                                          loops at runtime
  70 onap.policies.controlloop.common.Drools  Used to support tosca compliant actor/action  operational policies for control
  71                                          loops
  72 onap.policies.native.drools.Controller   Used to support the definition of PDP-D controllers
  73 onap.policies.native.drools.Artifact     Used to associate application's software with a PDP-D controller
  74 =======================================  ===============================================================================
  75
  76 2.1 Policy Type: onap.policies.Monitoring
  77 -----------------------------------------
  78
  79 This is a base Policy Type that supports Policy driven DCAE microservice components used in a Control Loops. The
  80 implementation of this Policy Type is developed using the XACML PDP to support question/answer Policy Decisions during
  81 runtime for the DCAE Policy Handler.
  82
  83 .. code-block:: yaml
  84   :caption: Base Policy Type definition for onap.policies.Monitoring
  85   :linenos:
  86
  87   tosca_definitions_version: tosca_simple_yaml_1_0_0
  88   topology_template:
  89     policy_types:
  90       - onap.policies.Monitoring:
  91           derived_from: tosca.policies.Root
  92           version: 1.0.0
  93           description: a base policy type for all policies that govern monitoring provision
  94
  95 The *PolicyTypeImpl* implementation of the *onap.policies.Montoring* Policy Type is generic to support definition of
  96 TOSCA *PolicyType* artifacts in the Policy Framework using the Policy Type Design API. Therefore many TOSCA *PolicyType*
  97 artifacts will use the same *PolicyTypeImpl* implementation with different property types and towards different targets.
  98 This allows dynamically generated DCAE microservice component Policy Types to be created at Design Time.
  99
 100 DCAE microservice components can generate their own TOSCA *PolicyType* using TOSCA-Lab Control Loop guard policies in
 101 SDC (Stretch Goal) or can do so manually. See `How to generate artefacts for SDC catalog using Tosca Lab Tool
 102 <https://wiki.onap.org/display/DW/How+to+generate+artefacts+for+SDC+catalog+using+Tosca+Lab+Tool>`__
 103 for details on TOSCA-LAB in SDC. For Dublin, the DCAE team is defining the manual steps required to build policy models
 104 `Onboarding steps for DCAE MS through SDC/Policy/CLAMP (Dublin)
 105 <https://wiki.onap.org/pages/viewpage.action?pageId=60883710>`__.
 106
 107 .. note::
 108   For Dublin, microservice Policy Types will be preloaded into the SDC platform and be available as a Normative. The
 109   policy framework will preload support for those microservice Monitoring policy types.
 110
 111 .. code-block:: yaml
 112   :caption: Example PolicyType *onap.policies.monitoring.MyDCAEComponent* derived from *onap.policies.Monitoring*
 113   :linenos:
 114
 115   tosca_definitions_version: tosca_simple_yaml_1_0_0
 116   policy_types:
 117     - onap.policies.Monitoring:
 118         derived_from: tosca.policies.Root
 119         version: 1.0.0
 120         description: a base policy type for all policies that govern monitoring provision
 121     - onap.policies.monitoring.MyDCAEComponent:
 122         derived_from: onap.policies.Monitoring
 123         version: 1.0.0
 124         properties:
 125           mydcaecomponent_policy:
 126           type: map
 127           description: The Policy Body I need
 128           entry_schema:
 129           type: onap.datatypes.monitoring.mydatatype
 130
 131   data_types:
 132     - onap.datatypes.monitoring.MyDataType:
 133       derived_from: tosca.datatypes.Root
 134       properties:
 135         my_property_1:
 136         type: string
 137         description: A description of this property
 138         constraints:
 139           - valid_values:
 140             - value example 1
 141             - value example 2
 142
 143 For more examples of monitoring policy type definitions, please refer to the examples in the `ONAP policy-models gerrit
 144 repository <https://github.com/onap/policy-models/tree/master/models-examples/src/main/resources/policytypes>`__.
 145
 146 2.2 Policy Type: onap.policies.controlloop.Operational
 147 ------------------------------------------------------
 148
 149 This policy type is used to support actor/action operational policies for control loops. There are two types of
 150 implementations for this policy type
 151
 152 1. Drools implementations that supports runtime Control Loop actions taken on components such as SO/APPC/VFC/SDNC/SDNR
 153 2. Implementations using APEX to support Control Loops.
 154
 155 .. note::
 156   For Dublin, this policy type will ONLY be used for the Policy Framework to distinguish the policy type as operational.
 157
 158 .. code-block:: yaml
 159   :caption: Base Policy Type definition for onap.policies.controlloop.Operational
 160   :linenos:
 161
 162   tosca_definitions_version: tosca_simple_yaml_1_0_0
 163   policy_types:
 164     - onap.policies.controlloop.Operational:
 165         derived_from: tosca.policies.Root
 166         version: 1.0.0
 167         description: Operational Policy for Control Loops
 168
 169 Applications should use the following Content-Type when creating onap.policies.controlloop.Operational policies:
 170 .. code-block::
 171
 172   Content-Type: "application/yaml"
 173
 174 2.2.1 Operational Policy Type Schema for Drools
 175 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 176
 177 For Dublin Drools will still support the Casablanca YAML definition of an Operational Policy for Control Loops.
 178
 179 Please use the the `YAML Operational Policy format
 180 <https://github.com/onap/policy-models/blob/master/models-interactions/model-yaml/README-v2.0.0.md>`__.
 181
 182 2.2.2 Operational Policy Type Schema for APEX
 183 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 184
 185 The operational Policy Type schema for APEX extends the base operational Policy Type schema. This Policy Type allows
 186 parameters specific to the APEX PDP to be specified as a TOSCA policy. See `this sample APEX policy type definition
 187 <https://github.com/onap/integration-csit/blob/master/tests/policy/apex-pdp/data/onap.policies.controlloop.operational.Apex.json>`__.
 188
 189 2.3 Policy Type: onap.policies.controlloop.Guard
 190 ------------------------------------------------
 191
 192 This policy type is the the type definition for Control Loop guard policies for frequency limiting, blacklisting and
 193 min/max guards to help protect runtime Control Loop Actions from doing harm to the network. This policy type is
 194 developed using the XACML PDP to support question/answer Policy Decisions during runtime for the Drools and APEX
 195 onap.controlloop.Operational policy type implementations.
 196
 197 .. code-block:: yaml
 198   :caption: Base Policy Type definition for onap.policies.controlloop.Guard
 199   :linenos:
 200
 201   tosca_definitions_version: tosca_simple_yaml_1_0_0
 202   policy_types:
 203     - onap.policies.controlloop.Guard:
 204         derived_from: tosca.policies.Root
 205         version: 1.0.0
 206         description: Guard Policy for Control Loops Operational Policies
 207
 208 As with the *onap.policies.Monitoring* policy type, the *PolicyTypeImpl* implementation of the
 209 *onap.policies.controlloop.Guard* Policy Type is generic to support definition of TOSCA *PolicyType* artifacts in the
 210 Policy Framework using the Policy Type Design API.
 211
 212 .. note::
 213   For Dublin, only the following derived Policy Type definitions below are preloaded in the Policy Framework. However,
 214   the creation of policies will still support the payload from Casablanca.
 215
 216 Guard policy type definitions for *FrequencyLimiter*, *BlackList*, and  *MinMax* are available in the `ONAP
 217 policy-models gerrit repository
 218 <https://github.com/onap/policy-models/tree/master/models-examples/src/main/resources/policytypes>`__.
 219
 220 2.4 Policy Type: onap.policies.controlloop.common.Drools
 221 --------------------------------------------------------
 222
 223 This policy type supports composition of Tosca-compliant Operational Policies for the PDP-D.  The
 224 `onap.policies.controlloop.common.Drools policy type specification
 225 <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.operational.common.Drools.yaml>`__ is preferred for composition of operational
 226 policies over its `onap.policies.controlloop.Operational policy type specification
 227 <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.Operational.yaml>`__ precursor, which eventually will be deprecated.
 228 Both policy types are functionally equivalent.
 229
 230 2.5 Policy Type: onap.policies.native.drools.Controller
 231 -------------------------------------------------------
 232
 233 This policy type supports creation of native PDP-D controllers via policy.   A controller is an abstraction on
 234 the PDP-D that groups communication channels, message mapping rules, and
 235 any other arbitrary configuration data to realize an application.
 236
 237 Policies of this type are composed against the
 238 `onap.policies.native.drools.Controller policy type specification
 239 <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.native.Drools.yaml>`__ specification.
 240
 241 2.6 Policy Type: onap.policies.native.drools.Artifact
 242 -------------------------------------------------------
 243
 244 This policy type supports the dynamic association of a native PDP-D controller with rules and dependent
 245 java libraries.   This policy type is used in conjuction with the onap.policies.native.drools.Controller
 246 type to create or upgrade a drools application on a live PDP-D.
 247
 248 Policies of this type are composed against the
 249 `onap.policies.native.drools.Controller policy type specification
 250 <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.native.Drools.yaml>`__ specification.
 251
 252 3 PDP Deployment and Registration with PAP
 253 ==========================================
 254
 255 The unit of execution and scaling in the Policy Framework is a *PolicyImpl* entity. A *PolicyImpl* entity runs on a PDP.
 256 As is explained above, a *PolicyImpl* entity is a *PolicyTypeImpl* implementation parameterized with a TOSCA *Policy*.
 257
 258 .. image:: images/PolicyImplPDPSubGroup.svg
 259
 260 In order to achieve horizontal scalability, we group the PDPs running instances of a given *PolicyImpl* entity logically
 261 together into a *PDPSubGroup*. The number of PDPs in a *PDPSubGroup* can then be scaled up and down using Kubernetes. In
 262 other words, all PDPs in a subgroup run the same *PolicyImpl*, that is the same policy template implementation (in
 263 XACML, Drools, or APEX) with the same parameters.
 264
 265 The figure above shows the layout of *PDPGroup* and *PDPSubGroup* entities. The figure shows examples of PDP groups for
 266 Control Loop and Monitoring policies on the right.
 267
 268 The health of PDPs is monitored by the PAP in order to alert operations teams managing policy. The PAP manages the life
 269 cycle of policies running on PDPs.
 270
 271 The table below shows the deployment methods in which *PolicyImpl* entities can be deployed to PDP Subgroups.
 272
 273 ========== =========================================== ============================== ==================================
 274 **Method** **Description**                             **Advantages**                 **Disadvantages**
 275 ========== =========================================== ============================== ==================================
 276 Cold       The *PolicyImpl* (*PolicyTypeImpl* and      No run time configuration      Very restrictive, no run time
 277            TOSCA *Policy*) are predeployed on the PDP. required and run time          configuration of PDPs is possible.
 278            PDP is fully configured and ready to        administration is simple.
 279            execute when started.
 280
 281            PDPs register with the PAP when they
 282            start, providing the *PolicyImpl* they
 283            have been predeployed with.
 284
 285 Warm       The *PolicyTypeImpl* entity is predeployed  The configuration, parameters, Administration and management is
 286            on the PDP. A TOSCA *Policy* may be loaded  and PDP group of PDPs may be   required. The configuration and
 287            at startup. The PDP may be configured or    changed at run time by loading life cycle of the TOSCA policies
 288            reconfigured with a new or updated TOSCA    or updating a TOSCA *Policy*   can change at run time and must be
 289            *Policy* at run time.                       into the PDP.                  administered and managed.
 290
 291            PDPs register with the PAP when they start, Support TOSCA *Policy* entity
 292            providing the *PolicyImpl* they have been   life cycle managgement is
 293            predeployed with if any. The PAP may update supported, allowing features
 294            the TOSCA *Policy* on a PDP at any time     such as *PolicyImpl* Safe Mode
 295            after registration.                         and *PolicyImpl* retirement.
 296
 297 Hot        The *PolicyImpl* (*PolicyTypeImpl* and      The policy logic, rules,       Administration and management is
 298            TOSCA *Policy*) are deployed at run time.   configuration, parameters, and more complex. The *PolicyImpl*
 299            The *PolicyImpl* (*PolicyTypeImpl* and      PDP group of PDPs may be       itself and its configuration and
 300            TOSCA *Policy*) may be loaded at startup.   changed at run time by loading life cycle as well as the life
 301            The PDP may be configured or reconfigured   or updating a TOSCA *Policy*   cycle of the TOSCA policies can
 302            with a new or updated *PolicyTypeImpl*      and *PolicyTypeImpl* into the  change at run time and must be
 303            and/or TOSCA *Policy* at run time.          PDP.                           administered and managed.
 304
 305            PDPs register with the PAP when they        Lifecycle management of TOSCA
 306            start, providing the *PolicyImpl* they have *Policy* entities and
 307            been predeployed with if any. The PAP may   *PolicyTypeImpl* entites is
 308            update the TOSCA *Policy* and               supported, allowing features
 309            *PolicyTypeImpl* on a PDP at any time after such as *PolicyImpl* Safe Mode
 310            registration                                and *PolicyImpl* retirement.
 311 ========== =========================================== ============================== ==================================
 312
 313 4. Policy Framework Public APIs
 314 ===============================
 315
 316 The Policy Framework provides the public APIs outline in the subsections below. For a full description of the APIs, see
 317 their individual documentation linked in each subsection.
 318
 319 4.1 Policy Type Design API for TOSCA Policy Types
 320 -------------------------------------------------
 321
 322 The full documentation for this API is available on the :ref:`Policy Life Cycle API <api-label>` page.
 323
 324 The purpose of this API is to support CRUD of TOSCA *PolicyType* entities. This API is provided by the
 325 *PolicyDevelopment* component of the Policy Framework, see the :ref:`The ONAP Policy Framework Architecture
 326 <architecture-label>` page.
 327
 328 The API allows applications to create, update, delete, and query *PolicyType* entities so that they become available for
 329 use in ONAP by applications such as CLAMP. Some Policy Type entities are preloaded in the Policy Framework. The TOSCA
 330 fields below are valid on API calls:
 331
 332 ============ ======= ======== ========== ===============================================================================
 333 **Field**    **GET** **POST** **DELETE** **Comment**
 334 ============ ======= ======== ========== ===============================================================================
 335 (name)       M       M        M          The definition of the reference to the Policy Type, GET allows ranges to be
 336                                          specified
 337 version      O       M        C          GET allows ranges to be specified, must be specified if more than one version
 338                                          of the Policy Type exists
 339 description  R       O        N/A        Desciption of the Policy Type
 340 derived_from R       C        N/A        Must be specified when a Policy Type is derived from another Policy Type such
 341                                          as in the case of derived Monitoring Policy Types
 342 metadata     R       O        N/A        Metadata for the Policy Type
 343 properties   R       M        N/A        This field holds the specification of the specific Policy Type in ONAP
 344 targets      R       O        N/A        A list of node types and/or group types to which the Policy Type can be applied
 345 triggers     R       O        N/A        Specification of policy triggers, not currently supported in ONAP
 346 ============ ======= ======== ========== ===============================================================================
 347
 348 .. note::
 349   On this and subsequent tables, use the following legend:   M-Mandatory, O-Optional, R-Read-only, C-Conditional.
 350   Conditional means the field is mandatory when some other field is present.
 351
 352 .. note::
 353   Preloaded policy types may only be queried over this API, modification or deletion of preloaded policy type
 354   implementations is disabled.
 355
 356 .. note::
 357   Policy types that are in use (referenced by defined Policies) may not be deleted.
 358
 359 .. note::
 360   The group types of targets in TOSCA are groups of TOSCA nodes, not PDP groups; the *target* concept in TOSCA is
 361   equivalent to the Policy Enforcement Point (PEP) concept
 362
 363 4.2 Policy Design API
 364 ---------------------
 365
 366 The full documentation for this API is available on the :ref:`Policy Life Cycle API <api-label>` page.
 367
 368 The purpose of this API is to support CRUD of TOSCA *Policy* entities from TOSCA compliant *PolicyType* definitions.
 369 TOSCA *Policy* entities become the parameters for *PolicyTypeImpl* entities, producing *PolicyImpl* entities that can
 370 run on PDPs. This API is provided by the *PolicyDevelopment* component of the Policy Framework, see the :ref:`The ONAP
 371 Policy Framework Architecture <architecture-label>` page.
 372
 373 This API allows applications (such as CLAMP and Integration) to create, update, delete, and query *Policy* entities. The
 374 TOSCA fields below are valid on API calls:
 375
 376 =========== ======= ======== ========== ================================================================================
 377 **Field**   **GET** **POST** **DELETE** **Comment**
 378 =========== ======= ======== ========== ================================================================================
 379 (name)      M       M        M          The definition of the reference to the Policy, GET allows ranges to be specified
 380 type        O       M        O          The Policy Type of the policy, see section 3.1
 381 description R       O        O
 382 metadata    R       O        N/A
 383 properties  R       M        N/A        This field holds the specification of the specific Policy in ONAP
 384 targets     R       O        N/A        A list of nodes and/or groups to which the Policy can be applied
 385 =========== ======= ======== ========== ================================================================================
 386
 387 .. note::
 388   Policies that are deployed (used on deployed *PolicyImpl* entities) may not be deleted
 389
 390 .. note::
 391   This API is NOT used by DCAE for a decision on what policy the DCAE PolicyHandler should retrieve and enforce
 392
 393 .. note::
 394   The groups of targets in TOSCA are groups of TOSCA nodes, not PDP groups; the *target* concept in TOSCA is equivalent
 395   to the Policy Enforcement Point (PEP) concept
 396
 397 4.3 Policy Administration API
 398 -----------------------------
 399
 400 The full documentation for this API is available on the :ref:`Policy Administration Point (PAP) <pap-label>` page.
 401
 402 The purpose of this API is to support CRUD of PDP groups and subgroups and to support the deployment and life cycles of
 403 *PolicyImpl* entities (TOSCA *Policy* and *PolicyTypeImpl* entities) on PDP sub groups and PDPs. This API is provided by
 404 the *PolicyAdministration* component (PAP) of the Policy Framework, see the :ref:`The ONAP Policy Framework Architecture
 405 <architecture-label>` page.
 406
 407 PDP groups and subgroups may be prefedined in the system. Predefined groups and subgroups can be modified or deleted
 408 over this API. The policies running on predefined groups or subgroups as well as the desired instance counts and
 409 properties can also be modified.
 410
 411 A PDP may be preconfigured with its PDP group, PDP subgroup, and policies. The PDP sends this information to the PAP
 412 when it starts. If the PDP group, subgroup, or any policy is unknown to the PAP, the PAP locks the PDP in state PASSIVE.
 413
 414 The state of PDP groups is managed by the API. PDP groups can be in states PASSIVE, TEST, SAFE, or ACTIVE. For a full
 415 description of PDP group states, the :ref:`The ONAP Policy Framework Architecture <architecture-label>` page.
 416
 417 The API supports retrieval of statistics for PDP groups, PDP subgroups, and individual PDPs. It also allows a PDP group
 418 health check to be ordered on PDP groups and on individual PDPs.
 419
 420 The fields below are valid on API calls:
 421
 422 ============================ ======= ======== ========== ===============================================================
 423 **Field**                    **GET** **POST** **DELETE** **Comment**
 424 ============================ ======= ======== ========== ===============================================================
 425 name                         M       M        M          The name of the PDP group
 426 version                      O       M        C          The version of the PDP group
 427 state                        R       N/A      N/A        The administrative state of the PDP group: PASSIVE, SAFE, TEST,
 428                                                          or ACTIVE
 429 description                  R       O        N/A        The PDP group description
 430 properties                   R       O        N/A        Specific properties for a PDP group
 431 pdp_subgroups                R       M        N/A        A list of PDP subgroups for a PDP group
 432 ->pdp_type                   R       M        N/A        The PDP type of this PDP subgroup, currently xacml, drools, or
 433                                                          apex
 434 ->supported_policy_types     R       N/A      N/A        A list of the policy types supported by the PDPs in this PDP
 435                                                          subgroup.  A trailing “.*” can be used to specify multiple
 436                                                          policy types; for example, “onap.policies.monitoring.*”
 437                                                          would match any policy type beginning with
 438                                                          “onap.policies.monitoring.”
 439 ->policies                   R       M        N/A        The list of policies running on the PDPs in this PDP subgroup
 440 ->->(name)                   R       M        N/A        The name of a TOSCA policy running in this PDP subgroup
 441 ->->policy_type              R       N/A      N/A        The TOSCA policy type of the policy
 442 ->->policy_type_version      R       N/A      N/A        The version of the TOSCA policy type of the policy
 443 ->->policy_type_impl         R       C        N/A        The policy type implementation (XACML, Drools Rules, or APEX
 444                                                          Model) that implements the policy
 445 ->instance_count             R       N/A      N/A        The number of PDP instances running in a PDP subgroup
 446 ->min_instance_count         O       N/A      N/A        The minumum number of PDP instances to run in a PDP subgroup
 447 ->properties                 O       N/A      N/A        Deployment configuration or other properties for the PDP
 448                                                          subgroup
 449 ->deployment_info            R       N/A      N/A        Information on the deployment for a PDP subgroup
 450 ->instances                  R       N/A      N/A        A list of PDP instances running in a PDP subgroup
 451 ->->instance                 R       N/A      N/A        The instance ID of a PDP running in a Kuberenetes Pod
 452 ->->state                    R       N/A      N/A        The administrative state of the PDP: PASSIVE, SAFE, TEST, or
 453                                                          ACTIVE
 454 ->->healthy                  R       N/A      N/A        The result of the latest health check on the PDP:
 455                                                          HEALTHY/NOT_HEALTHY/TEST_IN_PROGRESS
 456 ->->message                  O       N/A      N/A        A status message for the PDP if any
 457 ->->deployment_instance_info R       N/A      N/A        Information on the node running the PDP
 458 ============================ ======= ======== ========== ===============================================================
 459
 460 Note: In the Dublin release, the *policy_type_impl* of all policy types in a PDP subgroup must be the same.
 461
 462 4.4 Policy Decision API - Getting Policy Decisions
 463 --------------------------------------------------
 464
 465 Policy decisions are required by ONAP components to support the policy-driven ONAP architecture. Policy Decisions are
 466 implemented using the XACML PDP. The calling application must provide attributes in order for the XACML PDP to return a
 467 correct decision.
 468
 469 Decision API queries are implemented with a POST operation with a JSON body that specifies the filter for the policies
 470 to be returned.
 471
 472 *https:{url}:{port}/decision/v1/ POST*
 473
 474 The table below describes the fields in the JSON payload for the decision API Call.
 475
 476 ============= ======= ======== ==========================================================================
 477 **Field**     **R/O** **Type** **Description**
 478 ============= ======= ======== ==========================================================================
 479 ONAPName      R       String   Name of the ONAP Project that is making the request.
 480 ONAPComponent O       String   Name of the ONAP Project component that is making the request.
 481 ONAPInstance  O       String   Optional instance identification for that ONAP component.
 482 action        R       String   The action that the ONAP component is performing on a resource.
 483                                "configure" → DCAE uS onap.Monitoring policy Decisions to configure uS
 484                                "naming"
 485                                "placement"
 486                                "guard"
 487 ============= ======= ======== ==========================================================================
 488
 489 These sub metadata structures are used to scope the resource the ONAP component is performing an action upon. At least
 490 one must be specified in order for Policy to return a decision. Multiple structures may be utilized to help define a
 491 precise scope for a decision.
 492
 493 4.4.1 Policy Decision API - DCAE configuration examples
 494 -------------------------------------------------------
 495
 496 These resource fields are examples on how DCAE implements its "configure" application to make Decision API calls.
 497
 498 ================= ======= ======== ==================================================================
 499 **Field**         **R/O** **Type** **Description**
 500 ================= ======= ======== ==================================================================
 501 policy-type-name  O       String   The policy type name. This may be a regular expression.
 502 policy-id         O       String   The policy id. This may be a regular expression or an exact value.
 503 ================= ======= ======== ==================================================================
 504
 505 This example below shows the JSON body of a query with a single policy ID.
 506
 507 .. code-block:: yaml
 508   :caption: Decision API Call - Single Policy ID query
 509   :linenos:
 510
 511   {
 512     "ONAPName": "DCAE",
 513     "ONAPComponent": "PolicyHandler",
 514     "ONAPInstance": "622431a4-9dea-4eae-b443-3b2164639c64",
 515     "action": "configure",
 516     "resource": {
 517       "policy-id": "onap.scaleout.tca"
 518     }
 519   }
 520
 521 .. code-block:: yaml
 522   :caption: Decision Response - Single Policy ID query
 523   :linenos:
 524
 525   {
 526     "policies": {
 527       "onap.scaleout.tca": {
 528         "type": "onap.policies.monitoring.cdap.tca.hi.lo.app",
 529         "version": "1.0.0",
 530         "metadata": {
 531           "policy-id": "onap.scaleout.tca",
 532           "policy-version": 1
 533         },
 534         "properties": {
 535           "tca_policy": {
 536             "domain": "measurementsForVfScaling",
 537             "metricsPerEventName": [{
 538               "eventName": "vLoadBalancer",
 539               "controlLoopSchemaType": "VNF",
 540               "policyScope": "type=configuration",
 541               "policyName": "onap.scaleout.tca",
 542               "policyVersion": "v0.0.1",
 543               "thresholds": [{
 544                   "closedLoopControlName": "ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3",
 545                   "closedLoopEventStatus": "ONSET",
 546                   "version": "1.0.2",
 547                   "fieldPath": "$.event.measurementsForVfScalingFields.vNicPerformanceArray[*]
 548                   .receivedBroadcastPacketsAccumulated",
 549                   "thresholdValue": 500,
 550                   "direction": "LESS_OR_EQUAL",
 551                   "severity": "MAJOR"
 552                 },
 553                 {
 554                   "closedLoopControlName": "ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3",
 555                   "closedLoopEventStatus": "ONSET",
 556                   "version": "1.0.2",
 557                   "fieldPath": "$.event.measurementsForVfScalingFields.vNicPerformanceArray[*]
 558                   .receivedBroadcastPacketsAccumulated",
 559                   "thresholdValue": 5000,
 560                   "direction": "GREATER_OR_EQUAL",
 561                   "severity": "CRITICAL"
 562               }]
 563             }]
 564           }
 565         }
 566       }
 567     }
 568   }
 569
 570 This example below shows the JSON body of a query with multiple policy IDs.
 571
 572 .. code-block:: yaml
 573   :caption: Decision API Call - Multiple Policy IDs query
 574   :linenos:
 575
 576   {
 577     "ONAPName": "DCAE",
 578     "ONAPComponent": "PolicyHandler",
 579     "ONAPInstance": "622431a4-9dea-4eae-b443-3b2164639c64",
 580     "action": "configure",
 581     "resource": {
 582       "policy-id": [
 583         "onap.scaleout.tca",
 584         "onap.restart.tca"
 585       ]
 586     }
 587   }
 588
 589 .. code-block:: yaml
 590   :caption: Decision Response - Multiple Policy IDs query
 591   :linenos:
 592
 593   {
 594     "policies": {
 595       "onap.scaleout.tca": {
 596         "type": "onap.policies.monitoring.cdap.tca.hi.lo.app",
 597         "version": "1.0.0",
 598         "metadata": {
 599           "policy-id": "onap.scaleout.tca"
 600         },
 601         "properties": {
 602           "tca_policy": {
 603             "domain": "measurementsForVfScaling",
 604             "metricsPerEventName": [
 605               {
 606                 "eventName": "vLoadBalancer",
 607                 "controlLoopSchemaType": "VNF",
 608                 "policyScope": "type=configuration",
 609                 "policyName": "onap.scaleout.tca",
 610                 "policyVersion": "v0.0.1",
 611                 "thresholds": [
 612                   {
 613                     "closedLoopControlName": "ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3",
 614                     "closedLoopEventStatus": "ONSET",
 615                     "version": "1.0.2",
 616                     "fieldPath": "$.event.measurementsForVfScalingFields.vNicPerformanceArray[*]
 617                     .receivedBroadcastPacketsAccumulated",
 618                     "thresholdValue": 500,
 619                     "direction": "LESS_OR_EQUAL",
 620                     "severity": "MAJOR"
 621                   },
 622                   {
 623                     "closedLoopControlName": "ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3",
 624                     "closedLoopEventStatus": "ONSET",
 625                     "version": "1.0.2",
 626                     "fieldPath": "$.event.measurementsForVfScalingFields.vNicPerformanceArray[*]
 627                     .receivedBroadcastPacketsAccumulated",
 628                     "thresholdValue": 5000,
 629                     "direction": "GREATER_OR_EQUAL",
 630                     "severity": "CRITICAL"
 631                   }
 632                 ]
 633               }
 634             ]
 635           }
 636         }
 637       },
 638       "onap.restart.tca": {
 639         "type": "onap.policies.monitoring.cdap.tca.hi.lo.app",
 640         "version": "1.0.0",
 641         "metadata": {
 642           "policy-id": "onap.restart.tca",
 643           "policy-version": 1
 644         },
 645         "properties": {
 646           "tca_policy": {
 647             "domain": "measurementsForVfScaling",
 648             "metricsPerEventName": [
 649               {
 650                 "eventName": "Measurement_vGMUX",
 651                 "controlLoopSchemaType": "VNF",
 652                 "policyScope": "DCAE",
 653                 "policyName": "DCAE.Config_tca-hi-lo",
 654                 "policyVersion": "v0.0.1",
 655                 "thresholds": [
 656                   {
 657                     "closedLoopControlName": "ControlLoop-vCPE-48f0c2c3-a172-4192-9ae3-052274181b6e",
 658                     "version": "1.0.2",
 659                     "fieldPath": "$.event.measurementsForVfScalingFields.additionalMeasurements[*]
 660                     .arrayOfFields[0].value",
 661                     "thresholdValue": 0,
 662                     "direction": "EQUAL",
 663                     "severity": "MAJOR",
 664                     "closedLoopEventStatus": "ABATED"
 665                   },
 666                   {
 667                     "closedLoopControlName": "ControlLoop-vCPE-48f0c2c3-a172-4192-9ae3-052274181b6e",
 668                     "version": "1.0.2",
 669                     "fieldPath": "$.event.measurementsForVfScalingFields.additionalMeasurements[*]
 670                     .arrayOfFields[0].value",
 671                     "thresholdValue": 0,
 672                     "direction": "GREATER",
 673                     "severity": "CRITICAL",
 674                     "closedLoopEventStatus": "ONSET"
 675                   }
 676                 ]
 677               }
 678             ]
 679           }
 680         }
 681       }
 682     }
 683   }
 684
 685 This example below shows the JSON body of a query to return all the deployed policies for a specific policy type.
 686
 687 .. code-block:: yaml
 688   :caption: Decision API Call - Policies for Policy Type query
 689   :linenos:
 690
 691   {
 692     "ONAPName": "DCAE",
 693     "ONAPComponent": "PolicyHandler",
 694     "ONAPInstance": "622431a4-9dea-4eae-b443-3b2164639c64",
 695     "action": "configure",
 696     "resource": {
 697       "policy-type": "onap.policies.monitoring.cdap.tca.hi.lo.app"
 698     }
 699   }
 700
 701 .. code-block:: yaml
 702   :caption: Decision Response - Policies for Policy Type query
 703   :linenos:
 704
 705   {
 706     "policies": {
 707       "onap.scaleout.tca": {
 708         "type": "onap.policies.monitoring.cdap.tca.hi.lo.app",
 709         "version": "1.0.0",
 710         "metadata": {
 711           "policy-id": "onap.scaleout.tca",
 712           "policy-version": 1,
 713         },
 714         "properties": {
 715           "tca_policy": {
 716             "domain": "measurementsForVfScaling",
 717             "metricsPerEventName": [
 718               {
 719                 "eventName": "vLoadBalancer",
 720                 "controlLoopSchemaType": "VNF",
 721                 "policyScope": "type=configuration",
 722                 "policyName": "onap.scaleout.tca",
 723                 "policyVersion": "v0.0.1",
 724                 "thresholds": [
 725                   {
 726                     "closedLoopControlName": "ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3",
 727                     "closedLoopEventStatus": "ONSET",
 728                     "version": "1.0.2",
 729                     "fieldPath": "$.event.measurementsForVfScalingFields.vNicPerformanceArray[*]
 730                     .receivedBroadcastPacketsAccumulated",
 731                     "thresholdValue": 500,
 732                     "direction": "LESS_OR_EQUAL",
 733                     "severity": "MAJOR"
 734                   },
 735                   {
 736                     "closedLoopControlName": "ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3",
 737                     "closedLoopEventStatus": "ONSET",
 738                     "version": "1.0.2",
 739                     "fieldPath": "$.event.measurementsForVfScalingFields.vNicPerformanceArray[*]
 740                     .receivedBroadcastPacketsAccumulated",
 741                     "thresholdValue": 5000,
 742                     "direction": "GREATER_OR_EQUAL",
 743                     "severity": "CRITICAL"
 744                   }
 745                 ]
 746               }
 747             ]
 748           }
 749         }
 750       },
 751       "onap.restart.tca": {
 752         "type": "onap.policies.monitoring.cdap.tca.hi.lo.app",
 753         "version": "1.0.0",
 754         "metadata": {
 755           "policy-id": "onap.restart.tca",
 756           "policy-version": 1
 757         },
 758         "properties": {
 759           "tca_policy": {
 760             "domain": "measurementsForVfScaling",
 761             "metricsPerEventName": [
 762               {
 763                 "eventName": "Measurement_vGMUX",
 764                 "controlLoopSchemaType": "VNF",
 765                 "policyScope": "DCAE",
 766                 "policyName": "DCAE.Config_tca-hi-lo",
 767                 "policyVersion": "v0.0.1",
 768                 "thresholds": [
 769                   {
 770                     "closedLoopControlName": "ControlLoop-vCPE-48f0c2c3-a172-4192-9ae3-052274181b6e",
 771                     "version": "1.0.2",
 772                     "fieldPath": "$.event.measurementsForVfScalingFields.additionalMeasurements[*].arrayOfFields[0]
 773                     .value",
 774                     "thresholdValue": 0,
 775                     "direction": "EQUAL",
 776                     "severity": "MAJOR",
 777                     "closedLoopEventStatus": "ABATED"
 778                   },
 779                   {
 780                     "closedLoopControlName": "ControlLoop-vCPE-48f0c2c3-a172-4192-9ae3-052274181b6e",
 781                     "version": "1.0.2",
 782                     "fieldPath": "$.event.measurementsForVfScalingFields.additionalMeasurements[*].arrayOfFields[0]
 783                     .value",
 784                     "thresholdValue": 0,
 785                     "direction": "GREATER",
 786                     "severity": "CRITICAL",
 787                     "closedLoopEventStatus": "ONSET"
 788                   }
 789                 ]
 790               }
 791             ]
 792           }
 793         }
 794       },
 795       "onap.vfirewall.tca": {
 796         "type": "onap.policy.monitoring.cdap.tca.hi.lo.app",
 797         "version": "1.0.0",
 798         "metadata": {
 799           "policy-id": "onap.vfirewall.tca",
 800           "policy-version": 1
 801         },
 802         "properties": {
 803           "tca_policy": {
 804             "domain": "measurementsForVfScaling",
 805             "metricsPerEventName": [
 806               {
 807                 "eventName": "vLoadBalancer",
 808                 "controlLoopSchemaType": "VNF",
 809                 "policyScope": "resource=vLoadBalancer;type=configuration",
 810                 "policyName": "onap.vfirewall.tca",
 811                 "policyVersion": "v0.0.1",
 812                 "thresholds": [
 813                   {
 814                     "closedLoopControlName": "ControlLoop-vFirewall-d0a1dfc6-94f5-4fd4-a5b5-4630b438850a",
 815                     "closedLoopEventStatus": "ONSET",
 816                     "version": "1.0.2",
 817                     "fieldPath": "$.event.measurementsForVfScalingFields.vNicPerformanceArray[*]
 818                     .receivedBroadcastPacketsAccumulated",
 819                     "thresholdValue": 500,
 820                     "direction": "LESS_OR_EQUAL",
 821                     "severity": "MAJOR"
 822                   },
 823                   {
 824                     "closedLoopControlName": "ControlLoop-vFirewall-d0a1dfc6-94f5-4fd4-a5b5-4630b438850a",
 825                     "closedLoopEventStatus": "ONSET",
 826                     "version": "1.0.2",
 827                     "fieldPath": "$.event.measurementsForVfScalingFields.vNicPerformanceArray[*]
 828                     .receivedBroadcastPacketsAccumulated",
 829                     "thresholdValue": 5000,
 830                     "direction": "GREATER_OR_EQUAL",
 831                     "severity": "CRITICAL"
 832                   }
 833                 ]
 834               }
 835             ]
 836           }
 837         }
 838       }
 839     }
 840   }
 841
 842 4.4.2 Policy Decision API - Guard Decision API examples
 843 -------------------------------------------------------
 844
 845 These resource fields are examples on how Drools-PDP implements its "guard" application to make Decision API calls. This
 846 structure is a transition from the legacy guard API calls. So each of these resources are contained under a "guard" object
 847 in the "resource" object of the JSON structure.
 848
 849 ================= ======= ======== ==================================================================
 850 **Field**         **R/O** **Type** **Description**
 851 ================= ======= ======== ==================================================================
 852 actor             O       String   The actor (eg APPC, SO) that is performing a recipe
 853 recipe            O       String   The recipe (eg Restart, Reboot) that the actor going to execute
 854 clname            O       String   The unique ID for the Control Loop
 855 target            O       String   The target VNF the actor is executing the recipe on
 856 vfCount           O       String   Specific to SO "VF Module Create" - the current count of VNFs
 857
 858 ================= ======= ======== ==================================================================
 859
 860 This example below shows the JSON body of a guard Decision API call.
 861
 862 .. code-block:: json
 863   :caption: Decision API Call - Guard
 864   :linenos:
 865
 866   {
 867     "ONAPName": "Policy",
 868     "ONAPComponent": "drools-pdp",
 869     "ONAPInstance": "usecase-template",
 870     "requestId": "unique-request-id-1",
 871     "action": "guard",
 872     "resource": {
 873         "guard": {
 874             "actor": "SO",
 875             "recipe": "VF Module Create",
 876             "clname": "ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3",
 877             "target": "vLoadBalancer-00",
 878             "vfCount": "1"
 879         }
 880     }
 881   }
 882
 883 .. code-block:: json
 884   :caption: Decision Response - Guard
 885   :linenos:
 886
 887   {"status":"Permit"}
 888
 889 4.4.3 Policy Decision API - Optimize Decision API examples
 890 ----------------------------------------------------------
 891
 892 These resource fields are examples on how OOF project will make Decision API calls. NOTE: The OOF project
 893 has not yet upgraded to the API. This work is scheduled for Frankfurt.
 894
 895 ================= ======= ============== ==================================================================
 896 **Field**         **R/O** **Type**       **Description**
 897 ================= ======= ============== ==================================================================
 898 scope             O       List of String   Optional scope for the policy.
 899 services          O       List of String   One or more services the policy applies to.
 900 resources         O       List of String   The unique ID for the Control Loop
 901 geography         O       List of String   The target VNF the actor is executing the recipe on
 902
 903 ================= ======= ============== ==================================================================
 904
 905 This example below shows the JSON body of an Optimize Decision API call.
 906
 907 .. code-block:: json
 908   :caption: Decision API Call - Optimize vCPE service in US
 909   :linenos:
 910
 911   {
 912     "ONAPName": "OOF",
 913     "ONAPComponent": "OOF-component",
 914     "ONAPInstance": "OOF-component-instance",
 915     "action": "optimize",
 916     "resource": {
 917         "scope": [],
 918         "services": ["vCPE"],
 919         "resources": [],
 920         "geography": ["US"]
 921     }
 922   }
 923
 924 .. code-block:: json
 925   :caption: Decision Response -
 926   :linenos:
 927
 928   {
 929     "policies:"  {
 930         ### Omitted for brevity
 931     }
 932   }
 933
 934 End of Document