"Optimization", "onap.policies.Optimization", "optimize", "Optimization policy types used by OOF"
"Naming", "onap.policies.Naming", "naming", "Naming policy types used by SDNC"
"Native", "onap.policies.native.Xacml", "native", "Native XACML Policies"
+ "Match", "onap.policies.Match", "native", "Matchable Policy Types for the ONAP community to use"
Each Policy Type is implemented as an application that extends the **XacmlApplicationServiceProvider**, and provides a **ToscaPolicyTranslator** that translates the TOSCA representation of the policy into a XACML OASIS 3.0 standard policy.
The Monitoring and Naming applications use this translator.
+.. _xacml-matchable-label:
+
StdMatchableTranslator Translator
---------------------------------
More robust translator that searches metadata of TOSCA properties for a **matchable** field set to **true**. The translator then uses those "matchable" properties to translate a policy into a XACML OASIS 3.0 policy which allows for fine-grained decision making such that ONAP applications can retrieve the appropriate policy(s) to be enforced during runtime.
.. csv-table::
:header: "Derived Policy Type", "Action", "Description"
- "onap.policies.monitoring.cdap.tca.hi.lo.app", "configure", "TCA DCAE microservice component"
+ "onap.policies.monitoring.tcagen2", "configure", "TCA DCAE microservice gen2 component"
"onap.policies.monitoring.dcaegen2.collectors.datafile.datafile-app-server", "configure", "REST Collector"
"onap.policies.monitoring.docker.sonhandler.app", "configure", "SON Handler microservice component"
+.. note::
+ DCAE project deprecated TCA DCAE microservice in lieu for their gen2 microservice. Thus, the policy type onap.policies.monitoring.cdap.tca.hi.lo.app was removed from Policy Framework.
+
This is an example Decision API payload made to retrieve a decision for a Monitoring Policy by id. Not recommended - as users may change id's of a policy. Available for backward compatibility.
.. literalinclude:: decision.monitoring.json
"onap.policies.controlloop.guard.common.FrequencyLimiter", "guard", "Limits frequency of actions over a specified time period"
"onap.policies.controlloop.guard.common.Blacklist", "guard", "Blacklists a regexp of VNF IDs"
"onap.policies.controlloop.guard.common.MinMax", "guard", "For scaling, enforces a min/max number of VNFS"
+ "onap.policies.controlloop.guard.common.Filter", "guard", "Used for filtering entities in A&AI from Control Loop actions"
"onap.policies.controlloop.guard.coordination.FirstBlocksSecond", "guard", "Gives priority to one control loop vs another"
This is an example Decision API payload made to retrieve a decision for a Guard Policy Type.
.. literalinclude:: decision.guard.json
:language: JSON
+The return decision simply has "permit" or "deny" in the response to tell the calling application whether they are allowed to perform the operation.
+
+.. literalinclude:: decision.guard.response.json
+ :language: JSON
+
+Guard Common Base Policy Type
+-----------------------------
+Each guard Policy Type derives from **onap.policies.controlloop.guard.Common** base policy type. Thus, they share a set of common
+properties.
+
+.. csv-table:: Common Properties for all Guards
+ :header: "Property", "Examples", "Required", "Type", "Description"
+
+ "actor", "APPC, SO", "Required", "String", "Identifies the actor involved in the Control Loop operation."
+ "operation", "Restart, VF Module Create", "Required", "String", "Identifies the Control Loop operation the actor must perform."
+ "timeRange", "start_time: T00:00:00Z end_time: T08:00:00Z", "Optional", "tosca.datatypes.TimeInterval", "A given time range the guard is in effect. Following the TOSCA specification the format should be ISO 8601 format "
+ "id", "control-loop-id", "Optional", "String", "A specific Control Loop id the guard is in effect."
+
+`Common Guard Policy Type <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.guard.Common.yaml>`__
+
+Frequency Limiter Guard Policy Type
+-----------------------------------
+The Frequency Limiter Guard is used to specify limits as to how many operations can occur over a given time period.
+
+.. csv-table:: Frequency Guard Properties
+ :header: "Property", "Examples", "Required", "Type", "Description"
+
+ "timeWindow", "10, 60", "Required", "integer", "The time window to count the actions against."
+ "timeUnits", "second minute, hour, day, week, month, year", "Required", "String", "The units of time the window is counting"
+ "limit", "5", "Required", "integer", "The limit value to be checked against."
+
+.. literalinclude:: example.guard.limiter.yaml
+ :language: YAML
+
+`Frequency Limiter Guard Policy Type <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.guard.common.FrequencyLimiter.yaml>`__
+
+Min/Max Guard Policy Type
+-------------------------
+The Min/Max Guard is used to specify a minimum or maximum number of instantiated entities in A&AI. Typically this is a VFModule for Scaling operations. One should specify either a min or a max value, or **both** a min and max value. At least one must be specified.
+
+.. csv-table:: Min/Max Guard Properties
+ :header: "Property", "Examples", "Required", "Type", "Description"
+
+ "target", "e6130d03-56f1-4b0a-9a1d-e1b2ebc30e0e", "Required", "String", "The target entity that has scaling restricted."
+ "min", "1", "Optional", "integer", "Minimum value. Optional only if max is not specified."
+ "max", "5", "Optional", "integer", "Maximum value. Optional only if min is not specified."
+
+.. literalinclude:: example.guard.minmax.yaml
+ :language: YAML
+
+`Min/Max Guard Policy Type <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.guard.common.MinMax.yaml>`__
+
+Blacklist Guard Policy Type
+---------------------------
+The Blacklist Guard is used to specify a list of A&AI entities that are blacklisted from having an operation performed on them. Recommendation is to use the vnf-id for the A&AI entity.
+
+.. csv-table:: Blacklist Guard Properties
+ :header: "Property", "Examples", "Required", "Type", "Description"
+
+ "blacklist", "e6130d03-56f1-4b0a-9a1d-e1b2ebc30e0e", "Required", "list of string", "List of target entity's that are blacklisted from an operation."
+
+.. literalinclude:: example.guard.blacklist.yaml
+ :language: YAML
+
+`Blacklist Guard Policy Type <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.guard.common.Blacklist.yaml>`__
+
+Filter Guard Policy Type
+------------------------
+The Filter Guard is a more robust guard for blacklisting and whitelisting A&AI entities when performing control loop operations. The intent for this guard is to filter in or out a block of entities, while allowing the ability to filter in or out specific entities. This allows a DevOps team to control the introduction of a Control Loop for a region or specific VNF's, as well as block specific VNF's that are being negatively affected when poor network conditions arise. Care and testing should be taken to understand the ramifications when combining multiple filters as well as their use in conjunction with other Guard Policy Types.
+
+.. csv-table:: Filter Guard Properties
+ :header: "Property", "Examples", "Required", "Type", "Description"
+
+ "algorithm", "blacklist-overrides", "Required", "What algorithm to be applied", "blacklist-overrides or whitelist-overrides are the valid values. Indicates whether blacklisting or whitelisting has precedence."
+ "filters", "see table below", "Required", "list of onap.datatypes.guard.filter", "List of datatypes that describe the filter."
+
+.. csv-table:: Filter Guard onap.datatypes.guard.filter Properties
+ :header: "Property", "Examples", "Required", "Type", "Description"
+
+ "field", "generic-vnf.vnf-name", "Required", "String", "Field used to perform filter on and must be a string value. See the Policy Type below for valid values."
+ "filter", "vnf-id-1", "Required", "String", "The filter being applied."
+ "function", "string-equal", "Required", "String", "The function that is applied to the filter. See the Policy Type below for valid values."
+ "blacklist", "true", "Required", "boolean", "Whether the result of the filter function applied to the filter is blacklisted or whitelisted (eg Deny or Permit)."
+
+.. literalinclude:: example.guard.filter.yaml
+ :language: YAML
+
+`Filter Guard Policy Type <https://github.com/onap/policy-models/blob/master/models-examples/src/main/resources/policytypes/onap.policies.controlloop.guard.common.Filter.yaml>`__
+
.. _xacml-optimization-label:
Optimization Policy Types
.. literalinclude:: decision.native.json
:language: JSON
+Match Policy Type
+=================
+
+This Policy type can be used to design your own Policy Type and utilize the :ref:`StdMatchableTranslator <xacml-matchable-label>`, and does not need to build your own custom application. You can design your Policy Type by inheriting from the Match policy type (eg. onap.policies.match.<YourPolicyType>) and adding a **matchable** metadata set to **true** for the properties that you would like to request a Decision on. All a user would need to do is then use the Policy Lifecycle API to add their Policy Type and then create policies from it. Then deploy those policies to the XACML PDP and they would be able to get Decisions without customizing their ONAP installation.
+
+Here is an example Policy Type:
+
+.. literalinclude:: match.policy-type.yaml
+ :language: YAML
+
+Here are example Policies:
+
+.. literalinclude:: match.policies.yaml
+ :language: YAML
+
+This is an example Decision API request that can be made:
+
+.. literalinclude:: decision.match.request.json
+ :language: JSON
+
+Which would render the following decision response:
+
+.. literalinclude:: decision.match.response.json
+ :language: JSON
+
Supporting Your Own Policy Types and Translators
************************************************
`Standard Tosca Policy Translator implementation <https://github.com/onap/policy-xacml-pdp/blob/master/applications/common/src/main/java/org/onap/policy/pdp/xacml/application/common/std/StdBaseTranslator.java>`.
-XACML Application Tutorial
-==========================
+XACML Application and Enforcement Tutorials
+===========================================
-The following tutorial can be helpful to get started:
+The following tutorials can be helpful to get started on building your own decision application as well as building enforcement into your application.
.. toctree::
:maxdepth: 1
xacml-tutorial
-
-Once your application is developed and the ONAP XACML PDP Engine can find your application via setting the classpath appropriately, then use the :ref:`PAP REST API <pap-label>` to ensure the ONAP XACML PDP is registering your custom Policy Type with the PAP. Once successful, then you should be able to start deploying the created policies to the XACML PDP Engine.
+ xacml-tutorial-enforcement
Code Review / policy / parent.git / blobdiff