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 ## Prerequisites
  48
  49 ```
  50 $ cat /etc/os-release | grep PRETTY_NAME
  51 PRETTY_NAME="Ubuntu 20.04.2 LTS"
  52
  53 $ docker --version
  54 Docker version 20.10.2, build 20.10.2-0ubuntu1~20.04.2
  55
  56 $ docker-compose version
  57 docker-compose version 1.29.1, build c34c88b2
  58 docker-py version: 5.0.0
  59 CPython version: 3.7.10
  60 OpenSSL version: OpenSSL 1.1.0l  10 Sep 2019
  61
  62 $ git --version
  63 git version 2.25.1
  64
  65 ```
  66 Please modify the /etc/hosts of your system.
  67
  68 * <your-system>: is the hostname of the system, where the browser is started
  69
  70 * <deployment-system-ipv4>: is the IP address of the system where the solution will be deployed
  71
  72 For development purposes <your-system> and <deployment-system> may reference the same system.
  73
  74 ```
  75 $ cat /etc/hosts
  76 127.0.0.1                     localhost
  77 127.0.1.1                     <your-system>
  78 <deployment-system-ipv4>   sdnc-web <your-system>
  79 <deployment-system-ipv4>   identity <your-system>
  80 ```
  81
  82 ## Expected Folder Structure
  83
  84 ```
  85 ├── network
  86 │   ├── .env
  87 │   ├── config.py
  88 │   ├── docker-compose.yml
  89 │   │
  90 │   ├── ntsim-ng-o-du
  91 │   └── ntsim-ng-o-ru
  92 └── smo
  93     ├── common
  94     │   ├── .env
  95     │   ├── docker-compose.yml
  96     │   │
  97     │   ├── dmaap
  98     │   ├── docker
  99     │   ├── identity
 100     │   ├── kafka
 101     │   └── zookeeper
 102     ├── non-rt-ric
 103     │   ├── .env
 104     │   ├── docker-compose.yml
 105     │   │
 106     │   └── <config-folders>
 107     └── oam
 108         ├── docker-compose.yml
 109         │
 110         ├── sdnc-web
 111         ├── sdnr
 112         └── ves-collector
 113 ```
 114
 115 ## Usage
 116
 117 ### Bring Up Solution
 118
 119 #### Check (adjust if required) environment variables
 120
 121 ```
 122 nano smo/common/.env
 123 nano smo/non-rt-ric/.env
 124 nano smo/oam/.env
 125 nano network/.env
 126 ```
 127
 128 #### Startup solution
 129
 130 Please note that it is necessary to configure first the identity service,
 131 before starting further docker images.
 132
 133 The several docker-compose yml files must be started in the right order as listed below:
 134
 135 ```
 136 docker-compose -f smo/common/docker-compose.yml up -d
 137 python smo/common/identity/config.py
 138 ```
 139
 140 The python script configure the users within the identity service (keycloak).
 141 A system user (%USER) is also created with administration rights.
 142
 143 ```
 144 docker-compose -f smo/non-rt-ric/docker-compose.yml up -d
 145 docker-compose -f smo/oam/docker-compose.yml up -d
 146 ```
 147
 148 Please wait about 2min until all the service are up and running.
 149 If you see the login page (https://sdnc-web:8453) you are good to go and can start the (simulated) network.
 150
 151 ```
 152 docker-compose -f network/docker-compose.yml up -d
 153 ```
 154
 155 Usually the first ves:event gets lost. Please restart the O-DU docker container(s) to send a second ves:pnfRegistration.
 156
 157 ```
 158 docker-compose -f network/docker-compose.yml restart ntsim-ng-o-du-1122
 159 python network/config.py
 160 ```
 161
 162 The python script configures the simulated O-DU and O-RU according to O-RAN hybrid architecture.
 163
 164 O-DU - NETCONF Call HOME and NETCONF notifications
 165 O-RU - ves:pnfRegistration and ves:fault, ves:heartbeat
 166
 167
 168 ![ves:pnfRegistration in ODLUX](docs/nstim-ng-connected-after-ves-pnf-registration-in-odlux.png "ves:pnfRegistration in ODLUX")
 169
 170 'True' indicated that the settings through SDN-R to the NETCONF server were
 171 successful.
 172
 173 SDN-R reads the fault events from DMaaP and processes them.
 174 Finally the fault events are visible in ODLUX.
 175
 176 ![ves:fault in ODLUX](docs/ves-fault-in-odlux.png "ves:fault in ODLUX")
 177
 178
 179 ### Log files and karaf console
 180
 181 #### ODL karaf.logs
 182
 183 ```
 184 docker exec -it sdnr tail -f /opt/opendaylight/data/log/karaf.log
 185 ```
 186
 187 #### karaf console access (karaf:karaf)
 188
 189 ```
 190 ssh karaf@localhost -p 8101
 191 ```
 192
 193 #### ves-collector logs
 194
 195 ```
 196 docker logs -f ves-collector
 197 ```
 198
 199 ### Customizing Solution
 200
 201 '.env' file contains customizing parameters
 202
 203 ### Verification Solution
 204
 205 #### Access to SDN-R ODLUX
 206
 207 ##### Login into SDN-R
 208
 209     https://sdnc-web:8453
 210
 211     User: admin // see .env file
 212
 213     Password: Kp8bJ4SXszM0WXlhak3eHlcse2gAw84vaoGGmJvUy2U
 214
 215 In case of trouble, please update the commands with your customized '.env' file.
 216
 217 ### Terminate solution
 218
 219 To stop all container please respect the following order
 220
 221 ```
 222 docker-compose -f network/docker-compose.yml down
 223 docker-compose -f smo/oam/docker-compose.yml down
 224 docker-compose -f smo/non-rt-ric/docker-compose.yml down
 225 docker-compose -f smo/common/docker-compose.yml down
 226 ```
 227
 228 ### Cleanup
 229
 230 !!! be careful if other stopped containers are on the same system
 231 ```
 232 docker system prune -a -f
 233 ```
 234 ### Troubleshooting
 235
 236 In most cases the .env setting do not fit to the environment and need to be
 237 adjusted.
 238
 239 Please make sure that the network settings to not overlap with other networks.
 240
 241 The commands ...
 242 ```
 243 docker ps -a
 244 docker-compose ps
 245
 246 ## Prerequisites
 247 # python3, tmux, libtmux
 248 tmux new-session -n workspace -s integration
 249
 250 # within tmux session
 251 python tmux-logging.py
 252 ```
 253 ... are your friends.
 254
 255 ![tmux logging](docs/tmux-logging.png "tmux logging")