solution/README.md

   1 # Service Management and Orchestration (SMO)
   2
   3 This project focus on a docker-compose deployment solution for SMO/OAM Components.
   4
   5 ## Introduction
   6
   7 With respect to OAM the SMO implements the O1-interface consumers.
   8 According to the O-RAN OAM Architecture and the O-RAN OAM Interface Specification,
   9 the SMO implements a NETCONF Client for configuration and a HTTP/REST/VES server
  10 for receiving all kind of events in VES format.
  11
  12 The setup contains an OpenDaylight based NETCONF client and an ONAP VES Collector.
  13
  14 ## SMO OAM Components
  15
  16 This docker-compose file starts a pre-configured, self-contained SDN-R solution
  17 with the following components.
  18
  19   * **Identity**
  20     ... representing an KeyCloak based identity service for centralized user
  21     management. Please note that the implementation does not support IPv6.
  22     Therefore, its own network is required called 'DMZ'.
  23
  24   * **Controller** single node instance
  25
  26     ... representing the NETCONF consumer on the Service Management and
  27     Orchestration framework (SMO) for O-RAN O1 interface and/or O-RAN OpenFronthaul Management Plane and/or other NETCONF/YANG schemas implemented by the OpenDaylight project.
  28
  29   * **VES collector**
  30
  31     ... representing the VES (REST) provider at SMO for all kind of events.
  32
  33   * **Messages**
  34     ... representing SMO MessageRouter component, includes message-router
  35
  36 ## Prerequisites
  37
  38 ### Operating (HOST) System
  39
  40 ```
  41 $ cat /etc/os-release | grep PRETTY_NAME
  42 PRETTY_NAME="Ubuntu 22.04.2 LTS"
  43 ```
  44
  45 ### Docker
  46
  47 ```
  48 $ docker --version
  49 Docker version 23.0.1, build a5ee5b1
  50 ```
  51 Please follow the required docker daemon configuration as documented in the following README.md:
  52 - [./smo/common/docker/README.md](./smo/common/docker/README.md)
  53
  54 ### Docker Compose
  55
  56 ```
  57 $ docker compose version
  58 Docker Compose version v2.17.2
  59 ```
  60
  61 ### GIT
  62
  63 ```
  64 $ git --version
  65 git version 2.34.1
  66 ```
  67
  68 ### Python
  69
  70 ```
  71 $ python3 --version
  72 Python 3.10.6
  73 ```
  74
  75 A python parser package is required.
  76 ```
  77 sudo apt install python3-pip
  78 pip install jproperties
  79 ```
  80
  81 It is beneficial (but not mandatory) adding the following line add the
  82 end of your ~/.bashrc file. I will suppress warnings when python script
  83 do not verify self signed certificates for HTTPS communication.
  84
  85 ```
  86 export PYTHONWARNINGS="ignore:Unverified HTTPS request"
  87 ```
  88
  89 ### ETC Host (DNS function)
  90
  91 Please modify the /etc/hosts of your system.
  92
  93 * \<your-system>: is the hostname of the system, where the browser is started
  94
  95 * \<deployment-system-ipv4>: is the IP address of the system where the solution will be deployed
  96
  97 For development purposes <your-system> and <deployment-system> may reference the same system.
  98
  99 ```
 100 $ cat /etc/hosts
 101 127.0.0.1                      localhost
 102 127.0.1.1                      <your-system>
 103
 104 # SMO OAM development system
 105 <deployment-system-ipv4>                   smo.o-ran-sc.org
 106 <deployment-system-ipv4>           gateway.smo.o-ran-sc.org
 107 <deployment-system-ipv4>          identity.smo.o-ran-sc.org
 108 <deployment-system-ipv4>          messages.smo.o-ran-sc.org
 109 <deployment-system-ipv4> ves-collector.oam.smo.o-ran-sc.org
 110 <deployment-system-ipv4>         odlux.oam.smo.o-ran-sc.org
 111 <deployment-system-ipv4>    controller.oam.smo.o-ran-sc.org
 112
 113 ```
 114
 115 ## Expected Folder Structure
 116
 117 The following figure show the expected folder structure for the different
 118 docker-compose file and its configurations.
 119
 120 ```
 121 ├── network
 122 │   ├── .env
 123 │   ├── config.py
 124 │   ├── docker-compose.yml
 125 │   │
 126 │   ├── ntsim-ng-o-du
 127 │   └── ntsim-ng-o-ru
 128 └── smo
 129     ├── apps
 130     │   ├── .env
 131     │   ├── docker-compose.yml
 132     │   └── flows
 133     ├── common
 134     │   ├── .env
 135     │   ├── docker-compose.yml
 136     │   │
 137     │   ├── docker
 138     │   ├── gateway
 139     │   ├── identity
 140     │   ├── messages
 141     │   ├── kafka
 142     │   └── zookeeper
 143     └── oam
 144         ├── .env
 145         ├── docker-compose.yml
 146         │
 147         ├── odlux
 148         ├── controller
 149         └── ves-collector
 150 ```
 151
 152 ## Usage
 153
 154 ### Bring Up Solution
 155
 156 #### Short story
 157
 158 The following commands should be invoked. More detailed can be found in the
 159 next chapters.
 160
 161 ```
 162 docker compose -f smo/common/docker-compose.yml up -d
 163 # wait until the cpu load is low again
 164 python smo/common/identity/config.py
 165
 166 docker compose -f smo/oam/docker-compose.yml up -d
 167 docker compose -f smo/apps/docker-compose.yml up -d
 168
 169 # wait until the cpu load is low again
 170
 171 docker compose -f network/docker-compose.yml up -d
 172 # wait about 2min
 173 docker restart ntsim-ng-o-du-1122
 174 python network/config.py
 175 ```
 176
 177 #### Check (adjust if required) environment variables
 178
 179 ```
 180 nano smo/common/.env
 181 nano smo/oam/.env
 182 nano network/.env
 183 ```
 184
 185 #### Startup solution
 186
 187 Please note that it is necessary to configure first the identity service,
 188 before starting further docker images.
 189
 190 The several docker-compose yml files must be started in the right order as listed below:
 191
 192 ```
 193 docker compose -f smo/common/docker-compose.yml up -d
 194 python smo/common/identity/config.py
 195 ```
 196
 197 The python script configure the users within the identity service (keycloak).
 198 A system user (%USER) is also created with administration rights.
 199
 200
 201 ```
 202 docker compose -f smo/oam/docker-compose.yml up -d
 203 ```
 204
 205 Looking into the ONAP SDN-R logs will give you the startup procedure.
 206
 207 ```
 208 docker logs -f controller
 209 ```
 210
 211 If you see the login page (https://odlux.oam.smo.o-ran-sc.org) you are good to go and can start the (simulated) network.
 212
 213 ```
 214 docker compose -f network/docker-compose.yml up -d
 215 ```
 216
 217 Usually the first ves:event gets lost. Please restart the O-DU docker container(s) to send a second ves:pnfRegistration.
 218
 219 ```
 220 docker compose -f network/docker-compose.yml restart ntsim-ng-o-du-1122
 221 python network/config.py
 222 ```
 223
 224 The python script configures the simulated O-DU and O-RU according to O-RAN hybrid architecture.
 225
 226 O-DU - NETCONF Call HOME and NETCONF notifications
 227 O-RU - ves:pnfRegistration and ves:fault, ves:heartbeat
 228
 229 ![ves:pnfRegistration in ODLUX](docs/nstim-ng-connected-after-ves-pnf-registration-in-odlux.png "ves:pnfRegistration in ODLUX")
 230
 231 'True' indicated that the settings through SDN-R to the NETCONF server were
 232 successful.
 233
 234 SDN-R reads the fault events from DMaaP and processes them.
 235 Finally the fault events are visible in ODLUX.
 236
 237 ![ves:fault in ODLUX](docs/ves-fault-in-odlux.png "ves:fault in ODLUX")
 238
 239
 240 ### Log files and karaf console
 241
 242 #### ODL karaf.logs
 243
 244 ```
 245 docker exec -it controller tail -f /opt/opendaylight/data/log/karaf.log
 246 ```
 247
 248 #### ves-collector logs
 249
 250 ```
 251 docker logs -f ves-collector
 252 ```
 253
 254 ### Customizing Solution
 255
 256 '.env' file contains customizing parameters
 257
 258 ### Verification Solution
 259
 260 #### Access to SDN-R ODLUX
 261
 262 ##### Login into SDN-R
 263
 264     https://odlux.oam.smo.o-ran-sc.org
 265
 266     User: admin // see .env file
 267
 268     Password: Kp8bJ4SXszM0WXlhak3eHlcse2gAw84vaoGGmJvUy2U
 269
 270 In case of trouble, please update the commands with your customized '.env' file.
 271
 272 ### Terminate solution
 273
 274 To stop all container please respect the following order
 275
 276 ```
 277 docker compose -f network/docker-compose.yml down
 278 docker compose -f smo/apps/docker-compose.yml down
 279 docker compose -f smo/oam/docker-compose.yml down
 280 docker compose -f smo/common/docker-compose.yml down
 281 ```
 282
 283 ### Cleanup
 284
 285 !!! be careful if other stopped containers are on the same system
 286 ```
 287 docker system prune -a -f
 288 ```
 289 ### Troubleshooting
 290
 291 In most cases the .env setting do not fit to the environment and need to be
 292 adjusted.
 293
 294 Please make sure that the network settings to not overlap with other networks.
 295
 296 The commands ...
 297 ```
 298 docker ps -a
 299 docker-compose ps
 300 docker rm -f $(docker ps -aq)