X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=blobdiff_plain;f=docs%2Fconfig-deploy.rst;h=ddf164f9ba3c9bd4e5c895980c118296e4dd2ef9;hb=refs%2Fchanges%2F11%2F2511%2F1;hp=e11c1e407fb38accadfe959dfdccb1056394eea3;hpb=6b79976523018d41b3643b15deeb6706ad4daa6e;p=portal%2Fric-dashboard.git diff --git a/docs/config-deploy.rst b/docs/config-deploy.rst index e11c1e40..ddf164f9 100644 --- a/docs/config-deploy.rst +++ b/docs/config-deploy.rst @@ -1,51 +1,41 @@ -.. ===============LICENSE_START======================================================= -.. O-RAN SC CC-BY-4.0 -.. %% -.. Copyright (C) 2019 AT&T Intellectual Property and Nokia -.. %% -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. ===============LICENSE_END========================================================= +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. Copyright (C) 2019 AT&T Intellectual Property RIC Dashboard Configuration and Deployment ========================================== This documents the configuration and deployment of the O-RAN SC RIC -Dashboard web application. +Dashboard web application, which is often deployed together with the +ONAP Portal. Configuration ------------- -The application requires the following configuration files. In the -usual Kubernetes deployment, all files are provided by a configuration -map:: +The application requires the following configuration files:: - application.properties + application.yaml key.properties portal.properties +In the usual Kubernetes deployment, all file contents are provided by +a configuration map. Application Properties ^^^^^^^^^^^^^^^^^^^^^^ -This Spring-Boot application reads key-value pairs from the file -``application.properties`` in the current working directory when -launched, or from the same file in a ``config`` subdirectory. Many -properties have default values cached within the application, in file -``src/main/resources/application.properties``. Properties with -default values do NOT need to be repeated in a deployment-specific -configuration. Properties without default values MUST be specified in -a deployment-specific configuration. The properties are listed below -in alphabetical order. +The file ``application.yaml`` must be provided when the application +is launched, either in the current working directory or in a ``config`` +subdirectory (latter is preferred). The Helm chart that deploys the +application should mount this file appropriately. + +Many properties have default values cached within the application, in +file ``src/main/resources/application.yaml``. Properties with default +values do NOT need to be repeated in a deployment-specific configuration. +Properties without default values MUST be specified in a +deployment-specific configuration. + +The properties are listed below in alphabetical order. ``a1med.url.prefix`` @@ -56,15 +46,6 @@ like ``http://ricplt-entry/a1mediator`` A1 Mediator URL suffix. Default is the empty string. -``anrxapp.url.prefix`` - -ANR Application URL prefix. No useful default. Usually a service name -like ``http://ricxapp-entry/anr`` - -``anrxapp.url.suffix`` - -ANR Application URL suffix. Default is the empty string. - ``appmgr.url.prefix`` Application Manager URL prefix. No useful default. Usually a service @@ -72,7 +53,29 @@ name like ``http://ricplt-entry/appmgr`` ``appmgr.url.suffix`` -Application Manager URL suffix. Default is ``/ric/v1`` +Application Manager URL suffix. Default is ``/ric/v1``. + +``caasingress.aux.url.prefix`` + +CAAS-Ingress application URL prefix for the RIC Auxiliary cluster. No useful default. + +``caasingress.aux.url.suffix`` + +CAAS-Ingress application URL suffix for the RIC Auxiliary cluster. Default is ``api``. + +``caasingress.insecure`` + +Flag whether to disable SSL/TLS certificate and hostname verification. +If true, the dashboard can communicate with a CAAS-Ingress endpoint that +uses self-signed certificates. + +``caasingress.plt.url.prefix`` + +CAAS-Ingress application URL prefix for the RIC Platform cluster. No useful default. + +``caasingress.plt.url.suffix`` + +CAAS-Ingress application URL suffix for the RIC-PLT cluster. Default is ``api``. ``e2mgr.url.prefix`` @@ -81,12 +84,12 @@ E2 Manager URL prefix. No useful default. Usually a service name like ``e2mgr.url.suffix`` -E2 Manager URL prefix. Default is ``/v1`` +E2 Manager URL prefix. Default is ``/v1``. ``mock.config.delay`` Sleep period for mock methods in milliseconds. This mimics slow -endpoints. Default is ``0`` +endpoints. Default is ``0``. ``portalapi.appname`` @@ -95,23 +98,30 @@ Application name expected at ONAP portal. Default is ``RIC Dashboard`` ``portalapi.decryptor`` Java class that decrypts ciphertext from Portal. Default is -``org.oransc.ric.portal.dashboard.portalapi.PortalSdkDecryptorAes`` +``org.oransc.ric.portal.dashboard.portalapi.PortalSdkDecryptorAes``. ``portalapi.password`` -Application password expected at ONAP portal. No default value. +REST password expected at ONAP portal. No default value. + +``portalapi.security`` + +Boolean flag whether the Dashboard limits access to users (browsers) +that present security tokens set by the ONAP Portal. If false, no +access control is performed, which is only appropriate for isolated +lab testing. ``portalapi.usercookie`` -Name of request cookie with user ID. Default is ``UserId`` +Name of request cookie with user ID. Default is ``UserId``. ``portalapi.username`` -Application user name expected at ONAP portal. No default value. +REST user name expected at ONAP portal. No default value. ``server.port`` -Port where the Tomcat server listens for requests. Default is ``8080`` +Port where the Tomcat server listens for requests. Default is ``8080``. ``metrics.url.ac`` @@ -119,16 +129,19 @@ Url to the kibana source which visualizes AC App metrics. No default value and n ``userfile`` -Path of file that stores user details. Default is ``users.json`` +Path of file that stores user details. Default is ``users.json``. Key Properties ^^^^^^^^^^^^^^ The file ``key.properties`` must be provided on the Java classpath for -the EPSDK-FW library. A sample file is in directory -``src/test/resources``. The file must contain the following entries, -listed here in alphabetical order. +the Spring-Boot application, as required by the EPSDK-FW library. The +Helm chart for the application should mount this file appropriately. +A sample file is in directory ``src/test/resources``. + +The file must contain the following entries, listed here in +alphabetical order. ``cipher.enc.key`` @@ -139,19 +152,23 @@ Portal Properties ^^^^^^^^^^^^^^^^^ The file ``portal.properties`` must be provided on the Java classpath -for the EPSDK-FW library. A sample file is in directory -``src/test/resources``. The file must contain the following entries, -listed here in alphabetical order. +for the application, as required by the EPSDK-FW library. The Helm +chart for the application should mount this file appropriately. A +sample file is in directory ``src/test/resources``. + +The file must contain the following entries, listed here in +alphabetical order. ``ecomp_redirect_url`` -URL of ONAP Portal. No default value. Usually a value like +Portal URL that is reachable by a user's browser. This is a value +like ``https://portal.api.simpledemo.onap.org:30225/ONAPPORTAL/login.htm`` ``ecomp_rest_url`` -URL of ONAP Portal REST endpoint. No default value. Usually a value -like ``http://portal-app.onap:8989/ONAPPORTAL/auxapi`` +Portal REST URL that is reachable by the Dashboard back-end. +This is a value like ``http://portal-app.onap:8989/ONAPPORTAL/auxapi`` ``portal.api.impl.class`` @@ -160,7 +177,7 @@ Java class name. No default value. Value must be ``role_access_centralized`` -Selector for role access. No default value. Value must be ``remote`` +Selector for role access. No default value. Value must be ``remote``. ``ueb_app_key`` @@ -172,23 +189,48 @@ Deployment ---------- A production server requires the configuration files listed above. -All files should be placed in a ``config`` directory. That name is important; -Spring automatically searches that directory for the ``application.properties`` -file. Further, that directory can easily be placed on the Java classpath so -the additional files can be found at runtime. +All files should be placed in a ``config`` directory. That name is +important; Spring automatically searches that directory for the +``application.yaml`` file. Further, that directory can easily be +placed on the Java classpath so the additional files can be found at +runtime. -After creating and mounting Kubernetes config maps appropriately, launch -the server with this command-line invocation to include the ``config`` directory -on the Java classpath:: - java -cp config:target/ric-dash-be-1.2.0-SNAPSHOT.jar \ - -Dloader.main=org.oransc.ric.portal.dashboard.DashboardApplication \ - org.springframework.boot.loader.PropertiesLauncher +On-Board Dashboard to ONAP Portal +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When on-boarding the Dashboard to the ONAP Portal the administrator +must supply the following information about the deployed instance: + +- Dashboard URL that is reachable by a user's browser. The domain of + this host name must match the Portal URL that is similarly reachable + by a user's browser for cookie-based authentication to function as + expected. This should be a value like + ``http://dashboard.simpledemo.onap.org:8080`` +- Dashboard REST URL that is reachable by the Portal back-end server. + This can be a host name or an IP address, because it does not use + cookie-based authentication. This must be a URL with suffix "/api/v3" + for example ``http://192.168.1.1:8080/api/v3``. + +The Dashboard server only listens on a single port, so the examples +above both use the same port number. Different port numbers might be +required if an ingress controller or other proxy server is used. + +After the on-boarding process is complete, the administrator must +enter values from the Portal for the following properties explained +above: + +- ``portalapi.password`` +- ``portalapi.username`` +- ``ueb_app_key`` + +Launch Server +^^^^^^^^^^^^^ -Alternately, to use the configuration in the "application-abc.properties" file, -modify the command to have "spring.config.name=name" like this:: +After creating, populating and mounting Kubernetes config maps +appropriately, launch the server with this command-line invocation to +include the ``config`` directory on the Java classpath:: java -cp config:target/ric-dash-be-1.2.0-SNAPSHOT.jar \ - -Dspring.config.name=application-abc \ -Dloader.main=org.oransc.ric.portal.dashboard.DashboardApplication \ org.springframework.boot.loader.PropertiesLauncher