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