docs/config-deploy.rst

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