docs/config-deploy.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. SPDX-License-Identifier: CC-BY-4.0
   3 .. Copyright (C) 2019 AT&T Intellectual Property
   4
   5 RIC Dashboard Configuration and Deployment
   6 ==========================================
   7
   8 This documents the configuration and deployment of the O-RAN SC RIC
   9 Dashboard web application, which is often deployed together with the
  10 ONAP Portal.
  11
  12 Configuration
  13 -------------
  14
  15 The application requires the following configuration files::
  16
  17     application.yaml
  18     key.properties
  19     portal.properties
  20
  21 In the usual Kubernetes deployment, all file contents are provided by
  22 a configuration map.
  23
  24 Application Properties
  25 ^^^^^^^^^^^^^^^^^^^^^^
  26
  27 The file ``application.yaml`` must be provided when the application
  28 is launched, either in the current working directory or in a ``config``
  29 subdirectory (latter is preferred). The Helm chart that deploys the
  30 application should mount this file appropriately.
  31
  32 Many properties have default values cached within the application, in
  33 file ``src/main/resources/application.yaml``.  Properties with default
  34 values do NOT need to be repeated in a deployment-specific configuration.
  35 Properties without default values MUST be specified in a
  36 deployment-specific configuration.
  37
  38 The properties are listed below in alphabetical order.
  39
  40 ``appmgr.url.prefix``
  41
  42 Application Manager URL prefix. No useful default. Usually a service
  43 name like ``http://ricplt-entry/appmgr``
  44
  45 ``appmgr.url.suffix``
  46
  47 Application Manager URL suffix. Default is ``/ric/v1``.
  48
  49 ``caasingress.aux.url.prefix``
  50
  51 CAAS-Ingress application URL prefix for the RIC Auxiliary cluster.  No useful default.
  52
  53 ``caasingress.aux.url.suffix``
  54
  55 CAAS-Ingress application URL suffix for the RIC Auxiliary cluster. Default is ``api``.
  56
  57 ``caasingress.insecure``
  58
  59 Flag whether to disable SSL/TLS certificate and hostname verification.
  60 If true, the dashboard can communicate with a CAAS-Ingress endpoint that
  61 uses self-signed certificates.
  62
  63 ``caasingress.plt.url.prefix``
  64
  65 CAAS-Ingress application URL prefix for the RIC Platform cluster.  No useful default.
  66
  67 ``caasingress.plt.url.suffix``
  68
  69 CAAS-Ingress application URL suffix for the RIC-PLT cluster. Default is ``api``.
  70
  71 ``e2mgr.url.prefix``
  72
  73 E2 Manager URL prefix. No useful default. Usually a service name like
  74 ``http://ricplt-entry/e2mgr``
  75
  76 ``e2mgr.url.suffix``
  77
  78 E2 Manager URL prefix. Default is ``/v1``.
  79
  80 ``mock.config.delay``
  81
  82 Sleep period for mock methods in milliseconds.  This mimics slow
  83 endpoints. Default is ``0``.
  84
  85 ``portalapi.appname``
  86
  87 Application name expected at ONAP portal. Default is ``RIC Dashboard``
  88
  89 ``portalapi.decryptor``
  90
  91 Java class that decrypts ciphertext from Portal. Default is
  92 ``org.oransc.ric.portal.dashboard.portalapi.PortalSdkDecryptorAes``.
  93
  94 ``portalapi.password``
  95
  96 REST password expected at ONAP portal. No default value.
  97
  98 ``portalapi.security``
  99
 100 Boolean flag whether the Dashboard limits access to users (browsers)
 101 that present security tokens set by the ONAP Portal.  If false, no
 102 access control is performed, which is only appropriate for isolated
 103 lab testing.
 104
 105 ``portalapi.usercookie``
 106
 107 Name of request cookie with user ID. Default is ``UserId``.
 108
 109 ``portalapi.username``
 110
 111 REST user name expected at ONAP portal. No default value.
 112
 113 ``ricinstances.regions``
 114
 115 List of RIC region entries.  Each region has a name and a list of RIC
 116 instances.  See the application.yaml file for an example.
 117
 118 ``server.port``
 119
 120 Port where the Tomcat server listens for requests. Default is ``8080``.
 121
 122 ``statsfile``
 123
 124 Path of file that stores application statistic details. Default is ``dashboard-stats.json``.
 125
 126 ``userfile``
 127
 128 Path of file that stores user details. Default is ``dashboard-users.json``.
 129
 130
 131 Key Properties
 132 ^^^^^^^^^^^^^^
 133
 134 The file ``key.properties`` must be provided on the Java classpath for
 135 the Spring-Boot application, as required by the EPSDK-FW library. The
 136 Helm chart for the application should mount this file appropriately.
 137 A sample file is in directory ``src/test/resources``.
 138
 139 The file must contain the following entries, listed here in
 140 alphabetical order.
 141
 142 ``cipher.enc.key``
 143
 144 Encryption key used by the EPSDK-FW library.  No default value.
 145
 146
 147 Portal Properties
 148 ^^^^^^^^^^^^^^^^^
 149
 150 The file ``portal.properties`` must be provided on the Java classpath
 151 for the application, as required by the EPSDK-FW library.  The Helm
 152 chart for the application should mount this file appropriately.  A
 153 sample file is in directory ``src/test/resources``.
 154
 155 The file must contain the following entries, listed here in
 156 alphabetical order.
 157
 158 ``ecomp_redirect_url``
 159
 160 Portal URL that is reachable by a user's browser.  This is a value
 161 like
 162 ``https://portal.api.simpledemo.onap.org:30225/ONAPPORTAL/login.htm``
 163
 164 ``ecomp_rest_url``
 165
 166 Portal REST URL that is reachable by the Dashboard back-end.
 167 This is a value like ``http://portal-app.onap:8989/ONAPPORTAL/auxapi``
 168
 169 ``portal.api.impl.class``
 170
 171 Java class name.  No default value.  Value must be
 172 ``org.oransc.ric.portal.dashboard.portalapi.PortalRestCentralServiceImpl``
 173
 174 ``role_access_centralized``
 175
 176 Selector for role access.  No default value.  Value must be ``remote``.
 177
 178 ``ueb_app_key``
 179
 180 Unique key assigned by ONAP Portal to the RIC Dashboard application.
 181 No default value.
 182
 183
 184 Deployment
 185 ----------
 186
 187 A production server requires the configuration files listed above.
 188 All files should be placed in a ``config`` directory.  That name is
 189 important; Spring automatically searches that directory for the
 190 ``application.yaml`` file. Further, that directory can easily be
 191 placed on the Java classpath so the additional files can be found at
 192 runtime.
 193
 194
 195 On-Board Dashboard to ONAP Portal
 196 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 197
 198 When on-boarding the Dashboard to the ONAP Portal the administrator
 199 must supply the following information about the deployed instance:
 200
 201 - Dashboard URL that is reachable by a user's browser. The domain of
 202   this host name must match the Portal URL that is similarly reachable
 203   by a user's browser for cookie-based authentication to function as
 204   expected.  This should be a value like
 205   ``http://dashboard.simpledemo.onap.org:8080``
 206 - Dashboard REST URL that is reachable by the Portal back-end server.
 207   This can be a host name or an IP address, because it does not use
 208   cookie-based authentication.  This must be a URL with suffix "/api/v3"
 209   for example ``http://192.168.1.1:8080/api/v3``.
 210
 211 The Dashboard server only listens on a single port, so the examples
 212 above both use the same port number.  Different port numbers might be
 213 required if an ingress controller or other proxy server is used.
 214
 215 After the on-boarding process is complete, the administrator must
 216 enter values from the Portal for the following properties explained
 217 above:
 218
 219 - ``portalapi.password``
 220 - ``portalapi.username``
 221 - ``ueb_app_key``
 222
 223 Launch Server
 224 ^^^^^^^^^^^^^
 225
 226 After creating, populating and mounting Kubernetes config maps
 227 appropriately, launch the server with this command-line invocation to
 228 include the ``config`` directory on the Java classpath::
 229
 230     java -cp config:target/ric-dash-be-2.0.1-SNAPSHOT.jar \
 231         -Dloader.main=org.oransc.ric.portal.dashboard.DashboardApplication \
 232         org.springframework.boot.loader.PropertiesLauncher