solution/integration/README.md

   1 # Service Management and Orchestration (SMO)
   2
   3 ##### Table of Contents
   4 [Service Management and Orchestration (SMO)](#service-management-and-orchestration-smo)
   5 - [Introduction](#introduction)
   6 - [Overview](#overview)
   7 - [Prerequisites](#prerequisites)
   8 - [Usage](#usage)
   9   - [Bring Up Solution](#bring-up-solution)
  10   - [Log files and karaf console](#log-files-and-karaf-console)
  11   - [Customizing Solution](#customizing-solution)
  12   - [Verification Solution](#verification-solution)
  13     - [Access to SDN-R UX](#access-to-sdn-r-ux)
  14   - [Terminate solution](#terminate-solution)
  15   - [Cleanup](#cleanup)
  16   - [Troubleshooting](#troubleshooting)
  17
  18 ## Introduction
  19
  20 With respect to OAM the SMO implements the O1-interface consumers. According to the O-RAN OAM Architecture and the O-RAN OAM Interface Specification, the SMO implements a NetConf Client for configuration and a HTTP/REST/VES server for receiving all kind of events in a VES format.
  21
  22 The setup contains an OpenDaylight based NetConf client and a VES Collector.
  23
  24 ## Overview
  25
  26 This docker-compose file starts a pre-configured, self-contained SDN-R solution
  27 for developer test or demo purposes
  28
  29   * **Identity**
  30     ... representing an KeyCloak based identity service for centralized user
  31     management. Please note that the implementation does not support IPv6.
  32     Therefore, its own network is required called 'DMZ'.
  33
  34   * **SDN-R** single node instance
  35
  36     ... representing the NetConf consumer on the Service Management and
  37     Orchestration framework (SMO) for the O1 interface based on
  38     ODL-Silicon/ONAP-Istanbul
  39
  40   * **VES collector**
  41
  42     ... representing the VES (REST) provider at SMO for all kind of events.
  43
  44   * **DMaaP**
  45     ... representing SMO DMaaP component, includes message-router
  46
  47   * **ONAP-Policy**
  48     ... representing all the components of ONAP policy framework, in particular
  49     the policy-apex-pdp which executes the apex policies deployed in the framework
  50     when a certain event occurs.
  51
  52   * **Non-RT-RIC**
  53     ... representing all the components of Non-RT-RIC, includes Non-RT-RIC Control Panel, Non-RT-RIC (Spring Cloud) Service Gateway, A1 Policy Management Services,
  54     Enrichment Data Coordinator, Non-RT-RIC App Catalogue, "Helloworld" O-RU Fronthaul Recovery use-case, Near-RT RIC A1 Simulator etc.
  55
  56 ## Prerequisites
  57
  58 ```
  59 $ cat /etc/os-release | grep PRETTY_NAME
  60 PRETTY_NAME="Ubuntu 20.04.2 LTS"
  61
  62 $ docker --version
  63 Docker version 20.10.2, build 20.10.2-0ubuntu1~20.04.2
  64
  65 $ docker-compose version
  66 docker-compose version 1.29.1, build c34c88b2
  67 docker-py version: 5.0.0
  68 CPython version: 3.7.10
  69 OpenSSL version: OpenSSL 1.1.0l  10 Sep 2019
  70
  71 $ git --version
  72 git version 2.25.1
  73
  74 ```
  75 Please modify the /etc/hosts of your system.
  76
  77 * <your-system>: is the hostname of the system, where the browser is started
  78
  79 * <deployment-system-ipv4>: is the IP address of the system where the solution will be deployed
  80
  81 For development purposes <your-system> and <deployment-system> may reference the same system.
  82
  83 ```
  84 $ cat /etc/hosts
  85 127.0.0.1                     localhost
  86 127.0.1.1                     <your-system>
  87 <deployment-system-ipv4>   sdnc-web <your-system>
  88 <deployment-system-ipv4>   identity <your-system>
  89 ```
  90
  91 ## Expected Folder Structure
  92
  93 ```
  94 ├── network
  95 │   ├── .env
  96 │   ├── config.py
  97 │   ├── docker-compose.yml
  98 │   │
  99 │   ├── ntsim-ng-o-du
 100 │   └── ntsim-ng-o-ru
 101 └── smo
 102     ├── common
 103     │   ├── .env
 104     │   ├── docker-compose.yml
 105     │   │
 106     │   ├── dmaap
 107     │   ├── docker
 108     │   ├── identity
 109     │   ├── kafka
 110     │   └── zookeeper
 111     ├── non-rt-ric
 112     │   ├── docker-compose.yml
 113     │   │
 114     │   ├── test
 115     │   ├── data
 116     │   └── config
 117     ├── oam
 118     │   ├── docker-compose.yml
 119     │   │
 120     │   ├── sdnc-web
 121     │   ├── sdnr
 122     │   └── ves-collector
 123     └── onap-policy
 124         ├── docker-compose.yml
 125         │
 126         ├── config
 127         └── wait_for_port.sh
 128 ```
 129
 130 ## Usage
 131
 132 ### Bring Up Solution
 133
 134 #### Check (adjust if required) environment variables
 135
 136 ```
 137 nano smo/common/.env
 138 nano smo/non-rt-ric/.env
 139 nano smo/oam/.env
 140 nano network/.env
 141 ```
 142
 143 #### Startup solution
 144
 145 Please note that it is necessary to configure first the identity service,
 146 before starting further docker images.
 147
 148 The several docker-compose yml files must be started in the right order as listed below:
 149
 150 ```
 151 docker-compose -f smo/common/docker-compose.yml up -d
 152 python smo/common/identity/config.py
 153 ```
 154
 155 The python script configure the users within the identity service (keycloak).
 156 A system user (%USER) is also created with administration rights.
 157
 158 ```
 159 docker-compose -f smo/onap-policy/docker-compose.yml up -d
 160 docker-compose -f smo/oam/docker-compose.yml up -d
 161 docker-compose -f smo/non-rt-ric/docker-compose.yml up -d
 162 ```
 163
 164 In order to create/deploy the apex policy for O-RU closed loop recovery usecase,
 165 refer to the section named "Create/Deploy apex policy for O-RU & O-DU use case" in
 166 this page:
 167 https://wiki.o-ran-sc.org/pages/viewpage.action?pageId=35881325
 168
 169 Please note that the above instructions assume that the ToscaPolicy.json file
 170 with default config needs to be deployed. However, when there is a need to update
 171 the config (for example, to change the O-RU to O-DU mapping), a new ToscaPolicy.json
 172 file needs to be created. Refer to the section named "Workflow for updating the policy config"
 173 in this page:
 174 https://wiki.o-ran-sc.org/pages/viewpage.action?pageId=35881325
 175
 176 Please wait about 2min until all the service are up and running.
 177 If you see the login page (https://sdnc-web:8453) you are good to go and can start the (simulated) network.
 178
 179 ### populate data into Non-RT-RIC
 180
 181 Full instrucion on how to run Non-RT-RIC can be found in this page:
 182 <https://wiki.o-ran-sc.org/display/RICNR/Release+D>
 183
 184 When containers in Non-RT-RIC are all up, by default, there is no data running inside. Folder `non-rt-ric/data/` contains serveral scripts to populate data into Non-RT-RIC for test & demo purpose.
 185
 186 ```
 187 bash prepareDmaapMsg.sh
 188 ```
 189
 190 script `prepareDmaapMsg.sh` sends messages to dmaap message router, then Non-RT-RIC policy-agent service polls messages from dmaap, and creates policy instances accordingly.
 191
 192 ```
 193 bash preparePmsData.sh
 194 ```
 195
 196 script `preparePmsData.sh` sends http requests to policy-agent service, and creates policy instances accordingly.
 197
 198 ```
 199 bash prepareEcsData.sh
 200 ```
 201
 202 script `prepareEcsData.sh` sends http requests to ecs service, and creates data accordingly.
 203
 204 Afterwards, open webpage:
 205 <http://localhost:8182/>
 206 Now we should see some data in the page.
 207
 208 ```
 209 docker-compose -f network/docker-compose.yml up -d
 210 ```
 211
 212 Usually the first ves:event gets lost. Please restart the O-DU docker container(s) to send a second ves:pnfRegistration.
 213
 214 ```
 215 docker-compose -f network/docker-compose.yml restart ntsim-ng-o-du-1122
 216 python network/config.py
 217 ```
 218
 219 The python script configures the simulated O-DU and O-RU according to O-RAN hybrid architecture.
 220
 221 O-DU - NETCONF Call HOME and NETCONF notifications
 222 O-RU - ves:pnfRegistration and ves:fault, ves:heartbeat
 223
 224
 225 ![ves:pnfRegistration in ODLUX](docs/nstim-ng-connected-after-ves-pnf-registration-in-odlux.png "ves:pnfRegistration in ODLUX")
 226
 227 'True' indicated that the settings through SDN-R to the NETCONF server were
 228 successful.
 229
 230 SDN-R reads the fault events from DMaaP and processes them.
 231 Finally the fault events are visible in ODLUX.
 232
 233 ![ves:fault in ODLUX](docs/ves-fault-in-odlux.png "ves:fault in ODLUX")
 234
 235
 236 ### Log files and karaf console
 237
 238 #### ODL karaf.logs
 239
 240 ```
 241 docker exec -it sdnr tail -f /opt/opendaylight/data/log/karaf.log
 242 ```
 243
 244 #### karaf console access (karaf:karaf)
 245
 246 ```
 247 ssh karaf@localhost -p 8101
 248 ```
 249
 250 #### ves-collector logs
 251
 252 ```
 253 docker logs -f ves-collector
 254 ```
 255
 256 #### onap-policy apex logs
 257
 258 ```
 259 docker logs policy-apex-pdp
 260 ```
 261
 262 #### Non-RT-RIC logs
 263
 264 ```
 265 docker logs policy-agent
 266 docker logs oru-app
 267 docker logs ecs
 268 ```
 269
 270 ### Customizing Solution
 271
 272 '.env' file contains customizing parameters
 273
 274 ### Verification Solution
 275
 276 #### Access to SDN-R ODLUX
 277
 278 ##### Login into SDN-R
 279
 280     https://sdnc-web:8453
 281
 282     User: admin // see .env file
 283
 284     Password: Kp8bJ4SXszM0WXlhak3eHlcse2gAw84vaoGGmJvUy2U
 285
 286 In case of trouble, please update the commands with your customized '.env' file.
 287
 288 ### Terminate solution
 289
 290 To stop all container please respect the following order
 291
 292 ```
 293 docker-compose -f network/docker-compose.yml down
 294 docker-compose -f smo/oam/docker-compose.yml down
 295 docker-compose -f smo/onap-policy/docker-compose.yml down
 296 docker-compose -f smo/non-rt-ric/docker-compose.yml down
 297 docker-compose -f smo/common/docker-compose.yml down
 298 ```
 299
 300 ### Cleanup
 301
 302 !!! be careful if other stopped containers are on the same system
 303 ```
 304 docker system prune -a -f
 305 ```
 306 ### Troubleshooting
 307
 308 In most cases the .env setting do not fit to the environment and need to be
 309 adjusted.
 310
 311 Please make sure that the network settings to not overlap with other networks.
 312
 313 The commands ...
 314 ```
 315 docker ps -a
 316 docker-compose ps
 317
 318 ## Prerequisites
 319 # python3, tmux, libtmux
 320 tmux new-session -n workspace -s integration
 321
 322 # within tmux session
 323 python tmux-logging.py
 324 ```
 325 ... are your friends.
 326
 327 ![tmux logging](docs/tmux-logging.png "tmux logging")