Updated Architecture Chapter 1

Updated TOSCA policy primer to include image.

Updated Architecture doc to fix links.
Updated chapter 1 of architecture doc.
Fixed hierarchy problem with chapter levels in architecture doc.

Issue-ID: POLICY-1676
Change-Id: I25868082465508d214b4bf1559e5aa8ce84fb069
Signed-off-by: liamfallon <liam.fallon@est.tech>

1 files changed, 79 insertions, 0 deletions

diff --git a/docs/architecture/tosca-policy-primer.rst b/docs/architecture/tosca-policy-primer.rst
new file mode 100644
index 00000000..686d3564
--- /dev/null
+++ b/docs/architecture/tosca-policy-primer.rst
@@ -0,0 +1,79 @@
+.. This work is licensed under a
+.. Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+.. _tosca-label:
+
+TOSCA Policy Primer
+-------------------
+
+.. contents::
+    :depth: 2
+
+This page gives a short overview of how Policy is modelled in the
+`TOSCA Simple Profile in YAML <http://docs.oasis-open.org/tosca/TOSCA-Simple-Profile-YAML/v1.1/TOSCA-Simple-Profile-YAML-v1.1.pdf>`__.
+
+TOSCA defines three concepts for Policy: Policy Type, Policy, and Trigger.
+
+.. image:: images/ToscaPolicyStructure.png
+   :width: 800
+
+Policy Type
+~~~~~~~~~~~
+
+A Policy Type is used to specify the types of policies that may be used in a service. The parameter definitions
+for a policy of this type, the entity types to which it applies, and what triggers policies of this type may be
+specified.
+
+
+The types of policies that are used in a service are defined in the policy_types section of the TOSCA service template
+as a Policy Type. More formally, TOSCA  defines a Policy Type as an artifact that "defines a type of requirement that
+affects or governs an application or service’s topology at  some stage of its life cycle, but is not explicitly part of
+the topology itself". In the definition of a Policy Type in TOSCA, you specify:
+
+* its properties, which define the type of configuration parameters that the policy takes
+* its targets, which define the node types and/or groups to which the policy type applies
+* its triggers, which specify the conditions in which policies of this type are fired
+
+Policy
+~~~~~~
+
+A Policy is used to specify the actual instances of policies that are used in a service. The parameter values of the
+policy and the actual entities to which it applies may be specified.
+
+The policies that are used in a service are defined in the policies section of the TOSCA topology template as a Policy.
+More formally, TOSCA  defines a Policy as an artifact that "defines a policy that can be associated with a TOSCA
+topology or top-level entity definition". In the definition of a Policy in TOSCA, you specify:
+
+* its properties, which define the values of the configuration parameters that the policy takes
+* its targets, which define the node types and/or group types to which the policy type applies
+
+Note that policy triggers are specified on the Policy Type definition and are not specified on the Policy itself.
+
+Trigger
+~~~~~~~
+
+A Trigger defines an event, condition, and action that is used to initiate execution of a policy associated with it.
+The definition of the Trigger allows specification of the type of events to trigger on, the filters on those events,
+conditions and constraints for trigger firing, the action to perform on triggering, and various other parameters.
+
+The triggers that are used in a service are defined as reusable modules in the TOSCA service template as a Trigger.
+More formally, TOSCA  defines a Trigger as an artifact that "defines the event, condition and action that is used to
+“trigger” a policy it is associated with". In the definition of a Trigger in TOSCA, you specify:
+
+* its event_type, which defines the name of the event that fires the policy
+* its schedule, which defines the time interval in which the trigger is active
+* its target_filter, which defines specific filters for firing such as specific characteristics of the nodes or
+relations for which the trigger should or should not fire
+* its condition, which defines extra conditions on the incoming event for firing the trigger
+* its constraint, which defines extra conditions on the incoming event for not firing the trigger
+* its period, which defines the period to use for evaluating conditions and constraints
+* its evaluations, which defines the number of evaluations that must be performed over the period to assert the
+condition or constraint exists
+* its method, the method to use for evaluation of conditions and constraints
+* its action, the workflow or operation to invoke when the trigger fires
+
+Note that how a Trigger actually works with a Policy is not clear from the specification.
+
+End of Document
+