PatrikBuhr | a2bc79c | 2019-10-29 13:39:00 +0100 | [diff] [blame] | 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 |