From b71482aae05f1a68cde23c72aa67e2b0c97a3d40 Mon Sep 17 00:00:00 2001 From: liamfallon Date: Wed, 9 Nov 2022 17:41:41 +0000 Subject: Document Policy GUI and gui-server Issue-ID: POLICY-4138 Change-Id: If7eccc6057ce54609ab6ad07dd3a9bd129caa93a Signed-off-by: liamfallon --- docs/apex/APEX-Policy-Examples.rst | 6 +- docs/development/devtools/drools-smoke.rst | 2 +- docs/development/devtools/strimzi-policy.rst | 2 +- docs/development/devtools/xacml-smoke.rst | 2 +- docs/index.rst | 1 + docs/ui/designtime-ui/apex-policy-editor.rst | 16 +++ docs/ui/designtime-ui/designtime-ui.rst | 17 ++++ docs/ui/images/ApexPolicyEditorUI.png | Bin 0 -> 166223 bytes docs/ui/images/DesigntimeUI.png | Bin 0 -> 20833 bytes docs/ui/images/MainUI.png | Bin 0 -> 20297 bytes docs/ui/images/RuntimeUI.png | Bin 0 -> 19798 bytes docs/ui/images/UIArchitecture.drawio | 1 + docs/ui/images/UIArchitecture.png | Bin 0 -> 83343 bytes docs/ui/runtime-ui/gui-server.rst | 143 +++++++++++++++++++++++++++ docs/ui/runtime-ui/runtime-ui.rst | 17 ++++ docs/ui/ui.rst | 43 ++++++++ 16 files changed, 245 insertions(+), 5 deletions(-) create mode 100644 docs/ui/designtime-ui/apex-policy-editor.rst create mode 100644 docs/ui/designtime-ui/designtime-ui.rst create mode 100644 docs/ui/images/ApexPolicyEditorUI.png create mode 100644 docs/ui/images/DesigntimeUI.png create mode 100644 docs/ui/images/MainUI.png create mode 100644 docs/ui/images/RuntimeUI.png create mode 100644 docs/ui/images/UIArchitecture.drawio create mode 100644 docs/ui/images/UIArchitecture.png create mode 100644 docs/ui/runtime-ui/gui-server.rst create mode 100644 docs/ui/runtime-ui/runtime-ui.rst create mode 100644 docs/ui/ui.rst diff --git a/docs/apex/APEX-Policy-Examples.rst b/docs/apex/APEX-Policy-Examples.rst index 982f3e0f..8a9a7203 100644 --- a/docs/apex/APEX-Policy-Examples.rst +++ b/docs/apex/APEX-Policy-Examples.rst @@ -1,6 +1,8 @@ .. This work is licensed under a Creative Commons Attribution 4.0 International License. .. http://creativecommons.org/licenses/by/4.0 +.. _apex-policy-examples-label: + Policy Examples *************** @@ -15,7 +17,7 @@ Policy Examples :depth: 3 Sample APEX Policy in TOSCA format -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. container:: paragraph @@ -40,7 +42,7 @@ My First Policy .. container:: ulist - - :ref:`My-First-Policy on the APEX site ` + - :ref:`My-First-Policy Example ` VPN SLA ^^^^^^^ diff --git a/docs/development/devtools/drools-smoke.rst b/docs/development/devtools/drools-smoke.rst index 07c812c4..dacefdd4 100644 --- a/docs/development/devtools/drools-smoke.rst +++ b/docs/development/devtools/drools-smoke.rst @@ -21,7 +21,7 @@ ONAP OOM kubernetes For installation instructions, please refer to the following documentation: -`OOM Quick Start Guide `_ +`OOM Documentation `_ At a minimum policy needs the following components installed: diff --git a/docs/development/devtools/strimzi-policy.rst b/docs/development/devtools/strimzi-policy.rst index 772281e8..a3fce3f8 100644 --- a/docs/development/devtools/strimzi-policy.rst +++ b/docs/development/devtools/strimzi-policy.rst @@ -194,7 +194,7 @@ Download OOM repo The Policy kubernetes chart is located in the `OOM repository `_. This chart includes different policy components referred as . -Please refer to the `OOM documentation `_ on how to install and deploy ONAP. +Please refer to the `OOM documentation `_ on how to install and deploy ONAP. .. code-block:: bash cd diff --git a/docs/development/devtools/xacml-smoke.rst b/docs/development/devtools/xacml-smoke.rst index 5b7eb8ea..91818c66 100644 --- a/docs/development/devtools/xacml-smoke.rst +++ b/docs/development/devtools/xacml-smoke.rst @@ -21,7 +21,7 @@ ONAP OOM kubernetes For installation instructions, please refer to the following documentation: -`OOM Quick Start Guide `_ +`OOM Documentation `_ At a minimum policy needs the following components installed: diff --git a/docs/index.rst b/docs/index.rst index 7922c08e..8dcfef33 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -22,5 +22,6 @@ Policy Framework Architecture apex/apex distribution/distribution clamp/clamp + ui/ui system-attributes/system-attributes release-notes diff --git a/docs/ui/designtime-ui/apex-policy-editor.rst b/docs/ui/designtime-ui/apex-policy-editor.rst new file mode 100644 index 00000000..6a5ecb95 --- /dev/null +++ b/docs/ui/designtime-ui/apex-policy-editor.rst @@ -0,0 +1,16 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +.. _apex-policy-editor-label: + +The Policy Framework Apex Policy Editor +####################################### + +.. contents:: + :depth: 4 + +The Apex Policy Editor allows a user to create and edit an Apex policy. It's UI is shown in the image below. + +.. image:: ../images/ApexPolicyEditorUI.png + +See the :ref:`My-First-Policy Example ` for an example of using the Apex policy editor. + diff --git a/docs/ui/designtime-ui/designtime-ui.rst b/docs/ui/designtime-ui/designtime-ui.rst new file mode 100644 index 00000000..da9e6d98 --- /dev/null +++ b/docs/ui/designtime-ui/designtime-ui.rst @@ -0,0 +1,17 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +.. _designtime-ui-label: + +The Policy Framework Designtime User Interface +############################################## + +The Policy Framework Designtime UI is shown in the image below. It is, at present, a plain HTML page. + +.. image:: ../images/DesigntimeUI.png + +The pages below describe the elements of the Policy Framework Designtime UI. + +.. toctree:: + :maxdepth: 2 + + apex-policy-editor diff --git a/docs/ui/images/ApexPolicyEditorUI.png b/docs/ui/images/ApexPolicyEditorUI.png new file mode 100644 index 00000000..54c3b86f Binary files /dev/null and b/docs/ui/images/ApexPolicyEditorUI.png differ diff --git a/docs/ui/images/DesigntimeUI.png b/docs/ui/images/DesigntimeUI.png new file mode 100644 index 00000000..16cacf10 Binary files /dev/null and b/docs/ui/images/DesigntimeUI.png differ diff --git a/docs/ui/images/MainUI.png b/docs/ui/images/MainUI.png new file mode 100644 index 00000000..b9337834 Binary files /dev/null and b/docs/ui/images/MainUI.png differ diff --git a/docs/ui/images/RuntimeUI.png b/docs/ui/images/RuntimeUI.png new file mode 100644 index 00000000..53396651 Binary files /dev/null and b/docs/ui/images/RuntimeUI.png differ diff --git a/docs/ui/images/UIArchitecture.drawio b/docs/ui/images/UIArchitecture.drawio new file mode 100644 index 00000000..b715fb72 --- /dev/null +++ b/docs/ui/images/UIArchitecture.drawio @@ -0,0 +1 @@ +7Vtbb+I4FP41PLbyJddHetsZ7a3azmg7fVmZxIDVJEbGFJhfvw4xkNih0EISWk2lqvFx7MTf99nn+MTt4et08Zsgk/GfPKZJD4F40cM3PYSgEyL1J7cstQUBp7CMBIu1bWt4YD+pNgJtnbGYTis3Ss4TySZVY8SzjEayYiNC8Hn1tiFPqk+dkBG1DA8RSWzrvyyW48KKMPa2FV8oG43Xj/ZcPcCUrO/WQ5mOScznJRO+7eFrwbksrtLFNU1y+NbAFO3udtRu3kzQTB7S4K9Ykqeb78nkP9oPBk8/+0/s6wXSb/tCkpke8j1PWLRUtjtBUjrn4lldf/+a95TlqKrfqxxYKvS45HKNluCzLKb580APX83HTNKHCYny2rkSiLKNZZqoElSXQ55JTTgMVfmFCskU8v2EjTJllDxvMGRJcs0TLlZPwMPhEEWRsk+l4M+0VBN7A8/1VI0ekOqNLnZCBTcEKO1SnlIp8iHrBjjQnGnZbuQ432rAxbrbcYl+5GtdEK270abvLTPqQpPzFqKwRdTvswEVGZVqfjRKxIBLyVObCwpjl/p1XISej8mJuIAAVsmAoU0GdoFNBsagITKgxcUNneZgIfCNpfQ4OnbDX+LJs+mICQ2GtVPDiwI6GJ5oaoTg0q1ODtfmA7k1kwPCpvhAFh//zDL5yZnwAdzLw2auVBYp0NQiZa9Ra2fiJerhVwPlMrxRfnUbM8nFCReuOhpcGsROHQ0BGmDvROuTAwxf4SGbBlhDg9vUbHAtFvozpVsiGc9sJq55OuFTVl/ZBk3DIfV2uHQ/HABwGppc9E6a/KZo8iya7pjCF4GH5VTS1MJcxY+T/DJaJkyBL/B+5AcFTX8MNgYSPY9W5P09k6obqu1TTY9bQ9d5hQMuNP3Phtkyk0HduoeaotK3qNzNHhHx26eM5geBrlY516lOH9ezQa/zNRA0hXnQIeYtLVmugbnfNebh59e5Z2AedI352id9ZqH7Bug1O7yWQbd3eLsi2VKWxKzqK8c5JJG046ePPkuM/IgHOifM3gJaoNMs7ucpwRz3hEynLKrCXA1qTdDpgsnHvO7S1aUful1+fbPQzVaFpS4Ur0BjK8doAK1ek89ERF8bYHGfJGJE5b6o0iaunLh6ZS8iaKK2CS/V160jSz/hnjM1kI0uQqe6JfU9Y6dZDFO3QqVcpdlRaHQEjY4KHKyOVtrZDPsIOdk72cbk5IGgJCjwqqCUbMTysVz4sZVkXtw2W5WWpU7uqWAKFypOL07vQHGiLsXpGPkSx0yDHCpOx/EvQVj6qXYbgEvsWLVtCdfO509WjuuCTJgl4a1E4QfJtkCEjX08Ruv9YHn/h2p05DXmfOyMiwZ9okD8hKDjcwDdzp+QKL0QexO/x6PeTlRsoe6cA+p2qmM0YxdTKl5e/R54Aqm3klSH4BylfkCuozYamSpvI48JUo4INx5L0XHRCq0D5+aDZf/AgKRwl52Fy8a+1/f8tdbeGpNAYOS3fWj11XTocUB26AOo9AxF6nYpUgiNlBh2369SZKSRkY9aVul6mnxwlfpnKNNOUw8QGospPmIxRUbmHQWty9ROQL4m04znn/KuYjIdb8KtkjJz+z2Rau+frSwI4E0gtT7WhvYq+HBR7U8EdJoJgNDIXzrmR96DlWL2pFa0tpWCLKV8+fbt3s5Gc2Hb8jsfLGGp8FlWBVSNubXaygG6NhH9jThSisgTTdbH45TFcf6Y2s3AIfI7LrqH5sSGddG9VyO9xs6SITt58BEdUmv+CB3qjvxfUdPpFhk72fKp3FGnWgkNqTjhO72R2ZF14KVpldjJoV+uaIcrCs08NujaD9lJpl2fvPtxyjKmiNBHCg3OPt4ZTt/4bnn44UCnKTbsZMq7D3G2SFc7mXGTLlx38vlEdKni9l90ioVy+69O+PZ/ \ No newline at end of file diff --git a/docs/ui/images/UIArchitecture.png b/docs/ui/images/UIArchitecture.png new file mode 100644 index 00000000..e60dd5a6 Binary files /dev/null and b/docs/ui/images/UIArchitecture.png differ diff --git a/docs/ui/runtime-ui/gui-server.rst b/docs/ui/runtime-ui/gui-server.rst new file mode 100644 index 00000000..ffb0f9f9 --- /dev/null +++ b/docs/ui/runtime-ui/gui-server.rst @@ -0,0 +1,143 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +.. _gui-server-label: + +The Policy Framework GUI Server +############################### + +The **gui-server** microservice serves the GUI code to the browser for Policy Framework UI. In addition, it acts as +a single point of reference for the REST interfaces provided by **policy-api**, **policy-pap**, and **acm-runtime**. +It can also be used as a HTTPS gatewy for REST references into a Policy Framework deployment in a Kubernetes cluster. + +.. contents:: + :depth: 2 + +The **gui-server** is a regular microservice, and it is packaged, delivered and configured as a docker image. It is +a Spring application and therefore uses a normal Spring-style *applciation.yaml* approach to configuration. + +Definitive example configurations are available in the codebase: + +- `application_http.yaml `_ + showing how to configure gui-server for HTTP access +- `application_https.yaml `_ + showing how to configure gui-server for HTTPS access + +The configuration parameters are explained in the sections below + +Server Configuration +-------------------- + +Configuration for HTTP access to gui-server:: + + server: + port: 2443 + ssl: + enabled: false + +Start gui-server on port 2443 and disable SSL. + +Configuration for HTTPS access to gui-server:: + + server: + port: 2443 + ssl: + enabled: true + enabled-protocols: TLSv1.2 + client-auth: want + key-store: file:./src/test/resources/helloworld-keystore.jks + key-store-password: changeit + trust-store: file:./src/test/resources/helloworld-truststore.jks + trust-store-password: changeit + +Start gui-server on port 2443 and enable SSL with the parameters specified above + +Note that other standard Spring **server** configuraiton parameters as +documented +`on the Spring website `_ +are supported. + +Runtime Adaptation Configuration +-------------------------------- + +You can configure the adaptation for **policy-api**, **policy-pap**, and **runtime-acm**. In other words, you can map +the URL that the GUI produced or that you want to use in a REST tool such as *postman* or *curl* in the **runtime-ui** +part of the aaplication.yaml file:: + + runtime-ui: + policy-api: + mapping-path: "/runtime-ui/policy-api/restservices/" + url: http://localhost:30440 + disable-ssl-validation: true + disable-ssl-hostname-check: true + policy-pap: + mapping-path: "/runtime-ui/policy-pap/restservices/" + url: http://localhost:30442 + disable-ssl-validation: true + disable-ssl-hostname-check: true + acm: + mapping-path: "/runtime-ui/acm/restservices/" + url: http://localhost:30258 + disable-ssl-validation: true + disable-ssl-hostname-check: true + +The parameters under the **policy-api**, **policy-pap**, and **acm** sections are identical. + +mapping-path and url +++++++++++++++++++++ + +The **mapping-path** is the root part of the path that will be replaced by the **url**, the **url** replaces the +**mapping-path**. + +Therefore, using the configuration above for policy-api, the following mapping occurs:: + + http://localhost:2443/runtime-ui/policy-api/restservices/policy/api/v1/healthcheck + + maps to + + http://localhost:30440/policy/api/v1/healthcheck + +and:: + + https://localhost:2443/runtime-ui/acm/restservices/onap/policy/clamp/acm/v2/commission + + maps to + + http://localhost:30258/onap/policy/clamp/acm/v2/commission + +disable-ssl-validation and disable-ssl-hostname-check ++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +The **disable-ssl-validation** **disable-ssl-hostname-check** are boolean values. If the target server (policy-api, +policy-pap, or runtime-acm) is using http, these values should be set to **false**. If the target server is using +HTTPS, set the values as **true** so that the **gui-server** transfers and forwards certificates to target servers. + +Spring Boot Acuator Monitoring +------------------------------ + +The **gui-server** supports regular +`Spring Boot Actuator monitoring `_ +and monitoring over `prometheus `_. + +The following section of the *application.yaml** file is an example of how to enable monitoring:: + + management: + endpoints: + web: + base-path: / + exposure: + include: health,metrics,prometheus + path-mapping.metrics: plain-metrics + path-mapping.prometheus: metrics + +The configuration above enables the following URLs:: + + # Health Check + http://localhost:2443/health + + # Plain Metrics + http://localhost:2443/plain-metrics + + # Prometheus Metrics + http://localhost:2443/metrics + + diff --git a/docs/ui/runtime-ui/runtime-ui.rst b/docs/ui/runtime-ui/runtime-ui.rst new file mode 100644 index 00000000..b77607dc --- /dev/null +++ b/docs/ui/runtime-ui/runtime-ui.rst @@ -0,0 +1,17 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +.. _runtime-ui-label: + +The Policy Framework Runtime User Interface +########################################### + +The Policy Framework Runtime UI is shown in the image below. It is, at present, a plain HTML page. + +.. image:: ../images/RuntimeUI.png + +The pages below describe the elements of the Policy Framework Runtime UI. + +.. toctree:: + :maxdepth: 2 + + gui-server diff --git a/docs/ui/ui.rst b/docs/ui/ui.rst new file mode 100644 index 00000000..b4b2d33f --- /dev/null +++ b/docs/ui/ui.rst @@ -0,0 +1,43 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +.. _ui-label: + +The Policy Framework User Interfaces +#################################### + +The Policy Framework has a demonstration user interface that supports design time and runtime activities for the Policy +Framework. + +Design time activities are offline activities such as policy editing and ACM composition preparation. The design time UI +works with offline files, producing artifacts that can be consumed by the runtime Policy Framework APIs. + +Runtime operations include creating and updating policy types and policies, deploying policies as well as working with +Automation Compositions. The runtime UI works towards the REST APIs published by the Policy Framework. + +.. image:: images/UIArchitecture.png + +.. note:: + The policy framework UI is developed for use in demonstrations. It is a work in progress. As such, it does not cover + all the features and functions that are avaiable on the Policy Framework REST APIs. + +A Policy Framework installation in Kubernetes is shown in the figure above. The **policy-api**, **policy-pap** and +**acm-runtime** microservices publish REST interfaces. In a Service Mesh installation, these interfaces are exposed +over HTTP and are available inside the Service Mesh. Alternatively, the interfaces may be exposed publicly over HTTPS. + +The **gui-server** microservice serves the GUI code to the browser for Policy Framework UI. In addition, it acts as +a single point of reference for the REST interfaces provided by **policy-api**, **policy-pap**, and **acm-runtime**. +It can also be used as a HTTPS gatewy for REST references into a Policy Framework deployment in a Kubernetes cluster. + +The Policy Framework UI runs in a browser as a Web application. It has a **designtime** and a **runtime** part. + +.. image:: images/MainUI.png + +The Policy Framework main UI is shown in the image above. It is, at present, a plain HTML page. + +The pages below describe the elements of the Policy Framework UI. + +.. toctree:: + :maxdepth: 4 + + designtime-ui/designtime-ui + runtime-ui/runtime-ui -- cgit 1.2.3-korg