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 Kubernetes deployment, all file contents are provided by a
  22 configuration map. Construction of Helm charts, config maps and other
  23 Kubernetes deployment resources is beyond the scope of this document.
  24
  25 Application Properties
  26 ^^^^^^^^^^^^^^^^^^^^^^
  27
  28 The file ``application.yaml`` must be provided when the application is
  29 launched, either in the current working directory or in a ``config``
  30 subdirectory (latter is preferred). For example, a Helm chart that
  31 deploys the application should mount this file appropriately.
  32
  33 Many properties have default values cached within the application, in
  34 file ``src/main/resources/application.yaml``.  Properties with default
  35 values do NOT need to be repeated in a deployment-specific configuration.
  36 Properties without default values MUST be specified in a
  37 deployment-specific configuration.
  38
  39 The properties are listed below in alphabetical order with their fully
  40 qualified dot-separated names, for example "server.port".  Please note
  41 that in the YAML file, every component of the name is on a separate
  42 line, for example::
  43
  44     server:
  45         port: 8080
  46
  47 The application uses the following properties.
  48
  49 ``appmgr.url.suffix``
  50
  51 Application Manager URL suffix. Default is ``/appmgr/ric/v1``.
  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.suffix``
  64
  65 CAAS-Ingress application URL suffix for the RIC-PLT cluster. Default is ``api``.
  66
  67 ``e2mgr.url.suffix``
  68
  69 E2 Manager URL suffix. Default is ``/e2mgr/v1``.
  70
  71 ``portalapi.appname``
  72
  73 Application name expected at ONAP portal. Default is ``RIC Dashboard``
  74
  75 ``portalapi.decryptor``
  76
  77 Java class that decrypts ciphertext from Portal. Default is
  78 ``org.oransc.ric.portal.dashboard.portalapi.PortalSdkDecryptorAes``.
  79
  80 ``portalapi.password``
  81
  82 REST password expected at ONAP portal. No default value.
  83
  84 ``portalapi.security``
  85
  86 Boolean flag whether the Dashboard limits access to users (browsers)
  87 that present security tokens set by the ONAP Portal.  If false, no
  88 access control is performed, which is only appropriate for isolated
  89 lab testing.
  90
  91 ``portalapi.usercookie``
  92
  93 Name of request cookie with user ID. Default is ``UserId``.
  94
  95 ``portalapi.username``
  96
  97 REST user name expected at ONAP portal. No default value.
  98
  99 ``ricinstances.regions``
 100
 101 List of RIC region entries.  Each region has a name and a list of RIC
 102 instances.  A region has entries as shown below, where the "[0]"
 103 notation refers to the first instance in a list.  A partial example
 104 appears next::
 105
 106   ricinstances:
 107     regions:
 108         -
 109           name: Region AAA
 110           instances:
 111               -
 112                 key: i1
 113                 name: Primary RIC Instance
 114                 appUrlPrefix: App prefix 1
 115                 caasUrlPrefix: Caas prefix 1
 116                 pltUrlPrefix: Plt prefix 1
 117
 118
 119 ``ricinstances.regions[0].name``
 120
 121 User-friendly name of the region.
 122
 123 ``ricinstances.regions[0].instances[0].key``
 124
 125 Unique key for the instance, across all instances.
 126
 127 ``ricinstances.regions[0].instances[0].name``
 128
 129 User-friendly name for the instance.
 130
 131 ``ricinstances.regions[0].instances[0].appUrlPrefix``
 132
 133 xApplication URL prefix. In a Kubernetes deployment, this should be
 134 the URL where an ingress service listens.  Usually a service
 135 name like ``http://ricplt-entry/xapp``
 136
 137 ``ricinstances.regions[0].instances[0].caasUrlPrefix``
 138
 139 CAAS-Ingress application URL prefix for the RIC Auxiliary cluster.
 140
 141 ``ricinstances.regions[0].instances[0].pltUrlPrefix``
 142
 143 RIC Platform URL prefix. In a Kubernetes deployment, this should be
 144 the URL where an ingress service listens.  Usually a service name like
 145 ``http://ricplt-entry/xapp``
 146
 147 ``server.port``
 148
 149 Port where the Tomcat server listens for requests. Default is
 150 ``8080``.
 151
 152 ``statsfile``
 153
 154 Path of file that stores application statistic details. Default is
 155 ``dashboard-stats.json``.
 156
 157 ``userfile``
 158
 159 Path of file that stores user details. Default is
 160 ``dashboard-users.json``.
 161
 162 ``xappobrd.url.suffix``
 163
 164 Xapp Onboarder URL suffix. Default is ``/xapporbd/api/v1``.
 165
 166 Key Properties
 167 ^^^^^^^^^^^^^^
 168
 169 The file ``key.properties`` must be provided on the Java classpath for
 170 the Spring-Boot application, as required by the EPSDK-FW library. The
 171 Helm chart for the application should mount this file appropriately.
 172 A sample file is in directory ``src/test/resources``.
 173
 174 The file must contain the following entries, listed here in
 175 alphabetical order.
 176
 177 ``cipher.enc.key``
 178
 179 Encryption key used by the EPSDK-FW library.  No default value.
 180
 181
 182 Portal Properties
 183 ^^^^^^^^^^^^^^^^^
 184
 185 The file ``portal.properties`` must be provided on the Java classpath
 186 for the application, as required by the EPSDK-FW library.  The Helm
 187 chart for the application should mount this file appropriately.  A
 188 sample file is in directory ``src/test/resources``.
 189
 190 The file must contain the following entries, listed here in
 191 alphabetical order.
 192
 193 ``ecomp_redirect_url``
 194
 195 Portal URL that is reachable by a user's browser.  This is a value
 196 like
 197 ``https://portal.api.simpledemo.onap.org:30225/ONAPPORTAL/login.htm``
 198
 199 ``ecomp_rest_url``
 200
 201 Portal REST URL that is reachable by the Dashboard back-end.
 202 This is a value like ``http://portal-app.onap:8989/ONAPPORTAL/auxapi``
 203
 204 ``portal.api.impl.class``
 205
 206 Java class name.  No default value.  Value must be
 207 ``org.oransc.ric.portal.dashboard.portalapi.PortalRestCentralServiceImpl``
 208
 209 ``role_access_centralized``
 210
 211 Selector for role access.  No default value.  Value must be ``remote``.
 212
 213 ``ueb_app_key``
 214
 215 Unique key assigned by ONAP Portal to the RIC Dashboard application.
 216 No default value.
 217
 218
 219 Deployment
 220 ----------
 221
 222 A production server requires the configuration files listed above.
 223 All files should be placed in a ``config`` directory.  That name is
 224 important; Spring automatically searches that directory for the
 225 ``application.yaml`` file. Further, that directory can easily be
 226 placed on the Java classpath so the additional files can be found at
 227 runtime.
 228
 229
 230 On-Board Dashboard to ONAP Portal
 231 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 232
 233 When on-boarding the Dashboard to the ONAP Portal the administrator
 234 must supply the following information about the deployed instance:
 235
 236 - Dashboard URL that is reachable by a user's browser. The domain of
 237   this host name must match the Portal URL that is similarly reachable
 238   by a user's browser for cookie-based authentication to function as
 239   expected.  This should be a value like
 240   ``http://dashboard.simpledemo.onap.org:8080``
 241 - Dashboard REST URL that is reachable by the Portal back-end server.
 242   This can be a host name or an IP address, because it does not use
 243   cookie-based authentication.  This must be a URL with suffix "/api/v3"
 244   for example ``http://192.168.1.1:8080/api/v3``.
 245
 246 The Dashboard server only listens on a single port, so the examples
 247 above both use the same port number.  Different port numbers might be
 248 required if an ingress controller or other proxy server is used.
 249
 250 After the on-boarding process is complete, the administrator must
 251 enter values from the Portal for the following properties explained
 252 above:
 253
 254 - ``portalapi.password``
 255 - ``portalapi.username``
 256 - ``ueb_app_key``
 257
 258 Launch Server
 259 ^^^^^^^^^^^^^
 260
 261 After creating, populating and mounting Kubernetes config maps
 262 appropriately, launch the server with this command-line invocation to
 263 include the ``config`` directory on the Java classpath::
 264
 265     java -cp config:target/ric-dash-be-2.0.1-SNAPSHOT.jar \
 266         -Dloader.main=org.oransc.ric.portal.dashboard.DashboardApplication \
 267         org.springframework.boot.loader.PropertiesLauncher