From 40b1ff8d94aa8a936e51ba3b14f83d40bab431fc Mon Sep 17 00:00:00 2001 From: Pamela Dragosh Date: Tue, 25 Aug 2020 10:18:40 -0400 Subject: [PATCH] Add Match documentation Adding documentation for new Match Policy Type. Issue-ID: POLICY-2596 Change-Id: I97b033b345ae40e4684d5572d47132c304c735b9 Signed-off-by: Pamela Dragosh --- docs/xacml/decision.match.request.json | 10 ++++++++++ docs/xacml/decision.match.response.json | 18 ++++++++++++++++++ docs/xacml/match.policies.yaml | 19 +++++++++++++++++++ docs/xacml/match.policy-type.yaml | 16 ++++++++++++++++ docs/xacml/xacml.rst | 28 ++++++++++++++++++++++++++++ 5 files changed, 91 insertions(+) create mode 100644 docs/xacml/decision.match.request.json create mode 100644 docs/xacml/decision.match.response.json create mode 100644 docs/xacml/match.policies.yaml create mode 100644 docs/xacml/match.policy-type.yaml diff --git a/docs/xacml/decision.match.request.json b/docs/xacml/decision.match.request.json new file mode 100644 index 00000000..72ddc317 --- /dev/null +++ b/docs/xacml/decision.match.request.json @@ -0,0 +1,10 @@ +{ + "ONAPName": "my-ONAP", + "ONAPComponent": "my-component", + "ONAPInstance": "my-instance", + "requestId": "unique-request-1", + "action": "match", + "resource": { + "matchable": "foo" + } +} \ No newline at end of file diff --git a/docs/xacml/decision.match.response.json b/docs/xacml/decision.match.response.json new file mode 100644 index 00000000..0f9e465a --- /dev/null +++ b/docs/xacml/decision.match.response.json @@ -0,0 +1,18 @@ +{ + "policies": { + "test_match_1": { + "type": "onap.policies.match.Test", + "type_version": "1.0.0", + "properties": { + "matchable": "foo", + "nonmatchable": "value1" + }, + "name": "test_match_1", + "version": "1.0.0", + "metadata": { + "policy-id": "test_match_1", + "policy-version": "1.0.0" + } + } + } +} \ No newline at end of file diff --git a/docs/xacml/match.policies.yaml b/docs/xacml/match.policies.yaml new file mode 100644 index 00000000..d0e214ca --- /dev/null +++ b/docs/xacml/match.policies.yaml @@ -0,0 +1,19 @@ +tosca_definitions_version: tosca_simple_yaml_1_1_0 +topology_template: + policies: + - test_match_1: + type: onap.policies.match.Test + version: 1.0.0 + type_version: 1.0.0 + name: test_match_1 + properties: + matchable: foo + nonmatchable: value1 + - test_match_2: + type: onap.policies.match.Test + version: 1.0.0 + type_version: 1.0.0 + name: test_match_2 + properties: + matchable: bar + nonmatchable: value2 \ No newline at end of file diff --git a/docs/xacml/match.policy-type.yaml b/docs/xacml/match.policy-type.yaml new file mode 100644 index 00000000..a131b844 --- /dev/null +++ b/docs/xacml/match.policy-type.yaml @@ -0,0 +1,16 @@ +tosca_definitions_version: tosca_simple_yaml_1_1_0 +policy_types: + onap.policies.match.Test: + derived_from: onap.policies.Match + version: 1.0.0 + name: onap.policies.match.Test + description: Test Matching Policy Type to test matchable policies + properties: + matchable: + type: string + metadata: + matchable: true + required: true + nonmatchable: + type: string + required: true diff --git a/docs/xacml/xacml.rst b/docs/xacml/xacml.rst index 1010f8ed..32949f4a 100644 --- a/docs/xacml/xacml.rst +++ b/docs/xacml/xacml.rst @@ -23,6 +23,7 @@ The following Policy Types are supported by the XACML PDP Engine (PDP-X): "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. @@ -45,6 +46,8 @@ A simple translator that wraps the TOSCA policy into a XACML policy and performs 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. @@ -257,6 +260,31 @@ This is an example Native Decision API payload made to retrieve a decision for w .. 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 `, 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.) 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 ************************************************ -- 2.16.6