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 ``/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 ``/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
 163 Key Properties
 164 ^^^^^^^^^^^^^^
 165
 166 The file ``key.properties`` must be provided on the Java classpath for
 167 the Spring-Boot application, as required by the EPSDK-FW library. The
 168 Helm chart for the application should mount this file appropriately.
 169 A sample file is in directory ``src/test/resources``.
 170
 171 The file must contain the following entries, listed here in
 172 alphabetical order.
 173
 174 ``cipher.enc.key``
 175
 176 Encryption key used by the EPSDK-FW library.  No default value.
 177
 178
 179 Portal Properties
 180 ^^^^^^^^^^^^^^^^^
 181
 182 The file ``portal.properties`` must be provided on the Java classpath
 183 for the application, as required by the EPSDK-FW library.  The Helm
 184 chart for the application should mount this file appropriately.  A
 185 sample file is in directory ``src/test/resources``.
 186
 187 The file must contain the following entries, listed here in
 188 alphabetical order.
 189
 190 ``ecomp_redirect_url``
 191
 192 Portal URL that is reachable by a user's browser.  This is a value
 193 like
 194 ``https://portal.api.simpledemo.onap.org:30225/ONAPPORTAL/login.htm``
 195
 196 ``ecomp_rest_url``
 197
 198 Portal REST URL that is reachable by the Dashboard back-end.
 199 This is a value like ``http://portal-app.onap:8989/ONAPPORTAL/auxapi``
 200
 201 ``portal.api.impl.class``
 202
 203 Java class name.  No default value.  Value must be
 204 ``org.oransc.ric.portal.dashboard.portalapi.PortalRestCentralServiceImpl``
 205
 206 ``role_access_centralized``
 207
 208 Selector for role access.  No default value.  Value must be ``remote``.
 209
 210 ``ueb_app_key``
 211
 212 Unique key assigned by ONAP Portal to the RIC Dashboard application.
 213 No default value.
 214
 215
 216 Deployment
 217 ----------
 218
 219 A production server requires the configuration files listed above.
 220 All files should be placed in a ``config`` directory.  That name is
 221 important; Spring automatically searches that directory for the
 222 ``application.yaml`` file. Further, that directory can easily be
 223 placed on the Java classpath so the additional files can be found at
 224 runtime.
 225
 226
 227 On-Board Dashboard to ONAP Portal
 228 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 229
 230 When on-boarding the Dashboard to the ONAP Portal the administrator
 231 must supply the following information about the deployed instance:
 232
 233 - Dashboard URL that is reachable by a user's browser. The domain of
 234   this host name must match the Portal URL that is similarly reachable
 235   by a user's browser for cookie-based authentication to function as
 236   expected.  This should be a value like
 237   ``http://dashboard.simpledemo.onap.org:8080``
 238 - Dashboard REST URL that is reachable by the Portal back-end server.
 239   This can be a host name or an IP address, because it does not use
 240   cookie-based authentication.  This must be a URL with suffix "/api/v3"
 241   for example ``http://192.168.1.1:8080/api/v3``.
 242
 243 The Dashboard server only listens on a single port, so the examples
 244 above both use the same port number.  Different port numbers might be
 245 required if an ingress controller or other proxy server is used.
 246
 247 After the on-boarding process is complete, the administrator must
 248 enter values from the Portal for the following properties explained
 249 above:
 250
 251 - ``portalapi.password``
 252 - ``portalapi.username``
 253 - ``ueb_app_key``
 254
 255 Launch Server
 256 ^^^^^^^^^^^^^
 257
 258 After creating, populating and mounting Kubernetes config maps
 259 appropriately, launch the server with this command-line invocation to
 260 include the ``config`` directory on the Java classpath::
 261
 262     java -cp config:target/ric-dash-be-2.0.1-SNAPSHOT.jar \
 263         -Dloader.main=org.oransc.ric.portal.dashboard.DashboardApplication \
 264         org.springframework.boot.loader.PropertiesLauncher