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