From: liamfallon Date: Tue, 14 Apr 2020 12:42:34 +0000 (+0100) Subject: Architecture Sections 2.1 and 2.2 X-Git-Tag: 3.1.3~10 X-Git-Url: https://gerrit.onap.org/r/gitweb?p=policy%2Fparent.git;a=commitdiff_plain;h=1c7c520a656c05949e726bdb40db78e7ca657966 Architecture Sections 2.1 and 2.2 Issue-ID: POLICY-2399 Change-Id: I36b87c94cb7149c3c5e510f3fead88c41d09cec6 Signed-off-by: liamfallon --- diff --git a/docs/architecture/architecture.rst b/docs/architecture/architecture.rst index b31c371c..5bd061eb 100644 --- a/docs/architecture/architecture.rst +++ b/docs/architecture/architecture.rst @@ -116,7 +116,7 @@ The Policy Type Implementation is developed that can configure the maximum downt can receive a trigger from the analytics system when the maximum downtime is breached, and that can either request more resources, report an issue to a trouble ticketing system, and can log a breach. -VPN Policies are created by specifying values for the properties, triggers, and targets specifed in VPN Policy Type. +VPN Policies are created by specifying values for the properties, triggers, and targets specified in VPN Policy Type. In the case of the bank network, the *maximumDowntime* threshold is specified as 5 minutes downtime per year and the *mitigationStrategy* is defined as *allocateMoreResources*, and the target is specified as being the bank's VPN service @@ -234,37 +234,34 @@ The UML class diagram above shows thePolicy Framework Object Model. 2.2 Policy Design Architecture ------------------------------ -This section describes the architecture of the model driven system used to develop policy types and to create concrete +This section describes the architecture of the model driven system used to develop policy types and to create policies using policy types. The output of Policy Design is deployment-ready artifacts and Policy metadata in the Policy Framework database. -Policies that are expressed via natural language or a model require some development work ahead of time for them to be -translated into concrete runtime policies. Some Policy Domains will be set up and available in the platform during +Policy types that are expressed via natural language or a model require an implementation that allows them to be +translated into runtime policies. Some Policy Type implementations are set up and available in the platform during startup such as Control Loop Operational Policy Models, OOF placement Models, DCAE microservice models. Policy type -implementation logic development is done by an experienced developer. +implementations can also be loaded and deployed at run time. 2.2.1 Policy Type Design ^^^^^^^^^^^^^^^^^^^^^^^^ Policy Type Design is the task of creating policy types that capture the generic and vendor independent aspects of a -policy for a particular domain use case. The policy type implementation specifies the model information, rules, and -tasks that a policy type requires to generate concrete policies. +policy for a particular domain use case. -All policy types are specified in a TOSCA service template. Once policy types are defined and created in the system, +All policy types are specified in TOSCA service templates. Once policy types are defined and created in the system, *PolicyDevelopment* manages them and uses them to allow policies to be created from these policy types in a uniform way regardless of the domain that the policy type is addressing or the PDP technology that will execute the policy. A *PolicyTypeImpl* is developed for a policy type for a certain type of PDP (for example XACML oriented for decision policies, Drools rules or Apex state machines oriented for ECA policies). While a policy type is implementation independent, a policy type implementation for a policy type is specific for the technology of the PDP on which -policies that use that policy type implementation will execute. Further, the design environment and tool chain for -a policy type implementation is specific to the technology of the PDP on which policies that use that policy type -implementation will use. - -The *PolicyTypeImpl* implementation (or raw policy) is the specification of the specific rules or tasks, the flow of -the policy, its internal states and data structures and other relevant information. *A PolicyTypeImpl* can be specific -to a particular policy type, it can be more general, providing the implementation of a class of policy types, or -the same policy type may have many implementations. +policies that use that policy type implementation will execute. A Policy Type may have many implementations. A +*PolicyTypeImpl* is the specification of the specific rules or tasks, the flow of the policy, its internal states +and data structures and other relevant information. A *PolicyTypeImpl* can be specific to a particular policy type +or it can be more general, providing the implementation of a class of policy types. Further, the design environment +and tool chain for implementing implementations of policy types is specific to the technology of the PDP on which +the implementation will run. *PolicyDevelopment* provides the RESTful :ref:`Policy Design API `, which allows other components to query policy types, Those components can then create policies that specify values for the properties, triggers, and targets @@ -284,17 +281,12 @@ It is possible to generate policy types using MDD (Model Driven Development) tec using a DSL (Domain Specific Language) or a policy specification environment for a particular application domain. For example, policy types for specifying SLAs could be expressed in a SLA DSL and policy types for managing SON features could be generated from a visual SON management tool. The ONAP Policy framework provides an API that allows tool chains -to create policy types. SDC uses this approach for generating Policy Types in the Policy Framework, see the -:ref:`Policy Design and Development ` page. - -The SDC GUI supports several types of policies that can be captured at design time. DCAE micro service configuration -policies can be onboarded via the DCAE-DS (DCAE Design Studio). - +to create policy types, see the :ref:`Policy Design and Development ` page. .. image:: images/PolicyTypeDesign.svg -The GUI implementation in another ONAP component such as SDC DCAE-DS uses the *API_User* API to create and edit ONAP -policy types. +A GUI implementation in another ONAP component (a *PolicyTypeDesignClient*) may use the *API_User* API to create and +edit ONAP policy types. 2.2.1.2 Programming Policy Type Implementations """"""""""""""""""""""""""""""""""""""""""""""" @@ -321,16 +313,22 @@ file and posted over the policy design API described on the :ref:`Policy Design A number of mechanisms for policy creation are supported in ONAP. The process in *PolicyDevelopment* for creating a policy is the same for all mechanisms. The most general mechanism for creating a policy is using the RESTful *Policy Design API*, which provides a full interface to the policy creation support of *PolicyDevelopment*. This API may -be exercised directly using utilities such as *curl*. *PolicyDevelopment* provides a command line tool that is a loose -wrapper around the API. It also provides a general purpose Policy GUI in the ONAP Portal for policy creation, which -again is a general purpose wrapper around the policy creation API. The Policy GUI can interpret any TOSCA Model that has -been loaded into it and flexibly presents a GUI for a user to create policies from. The development of these mechanisms -will be phased over a number of ONAP releases. +be exercised directly using utilities such as *curl*. + +In future releases, the Policy Framework may provide a command line tool that will be a loose wrapper around the API. It +may also provide a general purpose Policy GUI in the ONAP Portal for policy creation, which again would be a general +purpose wrapper around the policy creation API. The Policy GUI would interpret any TOSCA Model that has been loaded into +it and flexibly presents a GUI for a user to create policies from. The development of these mechanisms will be phased +over a number of ONAP releases. A number of ONAP components use policy in manners which are specific to their particular needs. The manner in which the policy creation process is triggered and the way in which information required to create a policy is specified and accessed is specialized for these ONAP components. +For example, *CLAMP* provides a GUI for creation of Control Loop policies, which reads the Policy Type associated +with a control loop, presents the properties as fields in its GUI, and creates a policy using the property values entered +by the user. + The following subsections outline the mechanisms for policy creation and modification supported by the ONAP Policy Framework. @@ -348,7 +346,7 @@ An *API_User* first gets a reference to and the metadata for the Policy type for *API_User* then asks for a reference and the metadata for the policy. *PolicyDevelopment* looks up the policy in the database. If the policy already exists, *PolicyDevelopment* reads the artifact and returns the reference of the existing policy to the *API_User* with the metadata for the existing policy. If the policy does not exist, *PolicyDevelopment* -creates and new reference and metadata and returns that to the *API_User*. +informs the *API_User*. The *API_User* may now proceed with a policy specification session, where the parameters are set for the policy using the policy type specification. Once the *API_User* is happy that the policy is completely and correctly specified, it @@ -394,10 +392,10 @@ using TOSCA Policy Types. .. image:: images/ScriptedPolicyDesign.svg -One straightforward way of generating policies from Policy types is to use directives specified in a script file. The -command line utility is an *API_User*. The script reads directives from a file. For each directive, it reads the policy -type using the Policy Type API, and uses the parameters of the directive to prepare a TOSCA Policy. It then uses the -Policy API to create the policy. +One straightforward way of generating policies from Policy types is to use commands specified in a script file. A +command line utility such as *curl* is an *API_User*. Commands read policy types using the Policy Type API, parse the +policy type and uses the properties of the policy type to prepare a TOSCA Policy. It then issues further commands to use +the Policy API to create policies. 2.2.3 Policy Design Process ^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/architecture/images/PolicyDesign.svg b/docs/architecture/images/PolicyDesign.svg index 79ae900e..f414ca7f 100644 --- a/docs/architecture/images/PolicyDesign.svg +++ b/docs/architecture/images/PolicyDesign.svg @@ -1,5 +1,6 @@ -Policy DesignPolicyDesignAPI_UserAPI_UserPolicyDesignPolicyDesignPolicyDBPolicyDB1Get Policy Type Reference2Get Policy Type Artifact and Metadata3Return Policy Type Reference and Metadata4Get Policy Reference and Metadata5Get Policy Metadataalt[Policy Artifact exists]6Return Policy Reference and Metadata[Policy Artifact does not exist]7Return New Policy Reference and Empty Metadata8Policy Editing and Generation Sessionto get Policy Parameters from userloop9Use Policy Type specification10Create Policy PolicyDesign --> PolicyDesign : Create Policy11Save Policy Artifact and Metadata12Policy Creation Result \ No newline at end of file diff --git a/docs/architecture/images/PolicyTypeDesign.svg b/docs/architecture/images/PolicyTypeDesign.svg index fda281c1..be2daf73 100644 --- a/docs/architecture/images/PolicyTypeDesign.svg +++ b/docs/architecture/images/PolicyTypeDesign.svg @@ -1,14 +1,15 @@ -Policy Type DesignPolicyDesign«API_User»DCAE_DS«API_User»DCAE_DSPolicyTypeDesignPolicyTypeDesignPolicyDBPolicyDB1Get Policy Type Reference and Metadata2Get Policy Type Metadataand Artifactalt[Policy Type Artifact exists]3Return Policy Type Reference and Metadata[Policy Artifact does not exist]4Return New Policy Type Reference and Empty Metadata5Policy Type Editing and Generation Session6Create Policy Type and Metadata7Policy Generation Result \ No newline at end of file diff --git a/docs/architecture/images/ScriptedPolicyDesign.svg b/docs/architecture/images/ScriptedPolicyDesign.svg index e94a4dbb..f0dd6931 100644 --- a/docs/architecture/images/ScriptedPolicyDesign.svg +++ b/docs/architecture/images/ScriptedPolicyDesign.svg @@ -1,9 +1,9 @@ -Scripted Policy DesignPolicyDesign«API_User»Script«API_User»ScriptDirectiveFileDirectiveFilePolicyTypeDesignPolicyTypeDesignPolicyDesignPolicyDesignloop1Read next directive from script file2Read Policy Type for directive3Prepare TOSCA Policy for coreation4Read parameters from script file directive5Set Parameters in TOSCA Policy being prepared6Create Policy7Policy creation result \ No newline at end of file diff --git a/docs/architecture/plantuml/PolicyDesign.puml b/docs/architecture/plantuml/PolicyDesign.puml index f844809e..6b4b8020 100644 --- a/docs/architecture/plantuml/PolicyDesign.puml +++ b/docs/architecture/plantuml/PolicyDesign.puml @@ -19,7 +19,7 @@ PolicyDesign --> PolicyDB : Get Policy Metadata alt Policy Artifact exists PolicyDesign --> API_User : Return Policy Reference and Metadata else Policy Artifact does not exist - PolicyDesign --> API_User : Return New Policy Reference and Empty Metadata + PolicyDesign --> API_User : Return Policy Not Found end API_User --> API_User : Policy Editing and Generation Session\nto get Policy Parameters from user diff --git a/docs/architecture/plantuml/PolicyTypeDesign.puml b/docs/architecture/plantuml/PolicyTypeDesign.puml index 92d3c0ca..9125ee87 100644 --- a/docs/architecture/plantuml/PolicyTypeDesign.puml +++ b/docs/architecture/plantuml/PolicyTypeDesign.puml @@ -2,13 +2,13 @@ title Policy Type Design -participant DCAE_DS <> +participant PolicyTypeDesignClient <> box "PolicyDesign" #LightBlue participant PolicyTypeDesign end box autonumber -DCAE_DS --> PolicyTypeDesign : Get Policy Type Reference and Metadata +PolicyTypeDesignClient --> PolicyTypeDesign : Get Policy Type Reference and Metadata PolicyTypeDesign --> PolicyDB : Get Policy Type Metadata\nand Artifact alt Policy Type Artifact exists @@ -17,12 +17,12 @@ else Policy Artifact does not exist PolicyTypeDesign --> DCAE_DS : Return New Policy Type Reference and Empty Metadata end -DCAE_DS --> DCAE_DS : Policy Type Editing and Generation Session +PolicyTypeDesignClient --> PolicyTypeDesignClient : Policy Type Editing and Generation Session -activate DCAE_DS -deactivate DCAE_DS +activate PolicyTypeDesignClient +deactivate PolicyTypeDesignClient -DCAE_DS --> PolicyTypeDesign : Create Policy Type and Metadata -PolicyTypeDesign --> DCAE_DS : Policy Generation Result +PolicyTypeDesignClient --> PolicyTypeDesign : Create Policy Type and Metadata +PolicyTypeDesign --> PolicyTypeDesignClient : Policy Generation Result @enduml \ No newline at end of file diff --git a/docs/architecture/plantuml/ScriptedPolicyDesign.puml b/docs/architecture/plantuml/ScriptedPolicyDesign.puml index e9702174..2092a4df 100644 --- a/docs/architecture/plantuml/ScriptedPolicyDesign.puml +++ b/docs/architecture/plantuml/ScriptedPolicyDesign.puml @@ -3,7 +3,6 @@ title Scripted Policy Design participant Script <> -collections DirectiveFile box "PolicyDesign" #LightBlue participant PolicyTypeDesign @@ -15,12 +14,11 @@ autonumber activate Script loop - Script --> DirectiveFile : Read next directive from script file - Script --> PolicyTypeDesign : Read Policy Type for directive - Script --> Script : Prepare TOSCA Policy for coreation - Script --> Script : Read parameters from script file directive + Script --> PolicyTypeDesign : Read Policy Type using command + Script --> Script : Prepare TOSCA Policy for creation + Script --> Script : Parse parameters from retrieved policy type Script --> Script : Set Parameters in TOSCA Policy being prepared - Script --> PolicyDesign : Create Policy + Script --> PolicyDesign : Create Policy using command PolicyDesign --> Script : Policy creation result end