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