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.16.0
  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 ### VES Schemas
 116
 117 Please ensure that you download and copy the required 3GPP OpenAPIs for VES-stndDefined
 118 message validation into the folder [./smo/oam/ves-collector/externalRepo](./smo/oam/ves-collector/externalRepo).
 119
 120 Please follow the instructions in [./smo/oam/ves-collector/externalRepo/3gpp/rep/sa5/MnS/raw/Rel-18/OpenAPI/README.md](./smo/oam/ves-collector/externalRepo/3gpp/rep/sa5/MnS/raw/Rel-18/OpenAPI/README.md).
 121
 122 The following tree shows the successfully tested folder structure. It combines different versions of the schemas ('Rel16' ) using 3GPP branch names.
 123
 124 ```
 125 $ tree solution/operation-and-maintenance/smo/oam/ves-collector/externalRepo/
 126 solution/operation-and-maintenance/smo/oam/ves-collector/externalRepo/
 127 ├── 3gpp
 128 │   └── rep
 129 │       └── sa5
 130 │           └── MnS
 131 │               └── raw
 132 │                   └── Rel-16
 133 │                       └── OpenAPI
 134 │                           ├── README.md
 135 │                           ├── TS28532_FaultMnS.yaml
 136 │                           ├── TS28532_FileDataReportingMnS.yaml
 137 │                           ├── TS28532_HeartbeatNtf.yaml
 138 │                           ├── TS28532_PerfMnS.yaml
 139 │                           ├── TS28532_ProvMnS.yaml
 140 │                           ├── TS28532_StreamingDataMnS.yaml
 141 │                           ├── TS28536_CoslaNrm.yaml
 142 │                           ├── TS28541_5GcNrm.yaml
 143 │                           ├── TS28541_NrNrm.yaml
 144 │                           ├── TS28541_SliceNrm.yaml
 145 │                           ├── TS28550_PerfMeasJobCtrlMnS.yaml
 146 │                           ├── TS28623_ComDefs.yaml
 147 │                           ├── TS28623_GenericNrm.yaml
 148 │                           ├── TS29512_Npcf_SMPolicyControl.yaml
 149 │                           ├── TS29514_Npcf_PolicyAuthorization.yaml
 150 │                           └── TS29571_CommonData.yaml
 151 ```
 152
 153 ## Expected Folder Structure
 154
 155 The following figure show the expected folder structure for the different
 156 docker-compose file and its configurations.
 157
 158 ```
 159 ├── network
 160 │   ├── .env
 161 │   ├── config.py
 162 │   ├── docker-compose.yml
 163 │   │
 164 │   ├── ntsim-ng-o-du
 165 │   └── ntsim-ng-o-ru
 166 └── smo
 167     ├── apps
 168     │   ├── .env
 169     │   ├── docker-compose.yml
 170     │   └── flows
 171     ├── common
 172     │   ├── .env
 173     │   ├── docker-compose.yml
 174     │   │
 175     │   ├── docker
 176     │   ├── gateway
 177     │   ├── identity
 178     │   ├── messages
 179     │   ├── kafka
 180     │   └── zookeeper
 181     └── oam
 182         ├── .env
 183         ├── docker-compose.yml
 184         │
 185         ├── odlux
 186         ├── controller
 187         └── ves-collector
 188 ```
 189
 190 ## Usage
 191
 192 ### Bring Up Solution
 193
 194 #### Short story
 195
 196 The following commands should be invoked. More detailed can be found in the
 197 next chapters.
 198
 199 ```
 200 docker-compose -f smo/common/docker-compose.yml up -d
 201 # wait until the cpu load is low again
 202 python smo/common/identity/config.py
 203
 204 docker-compose -f smo/oam/docker-compose.yml up -d
 205 docker-compose -f smo/apps/docker-compose.yml up -d
 206
 207 # wait until the cpu load is low again
 208
 209 docker-compose -f network/docker-compose.yml up -d
 210 # wait about 2min
 211 docker restart ntsim-ng-o-du-1122
 212 python network/config.py
 213 ```
 214
 215 #### Check (adjust if required) environment variables
 216
 217 ```
 218 nano smo/common/.env
 219 nano smo/oam/.env
 220 nano network/.env
 221 ```
 222
 223 #### Startup solution
 224
 225 Please note that it is necessary to configure first the identity service,
 226 before starting further docker images.
 227
 228 The several docker-compose yml files must be started in the right order as listed below:
 229
 230 ```
 231 docker-compose -f smo/common/docker-compose.yml up -d
 232 python smo/common/identity/config.py
 233 ```
 234
 235 The python script configure the users within the identity service (keycloak).
 236 A system user (%USER) is also created with administration rights.
 237
 238
 239 ```
 240 docker-compose -f smo/oam/docker-compose.yml up -d
 241 ```
 242
 243 Looking into the ONAP SDN-R logs will give you the startup procedure.
 244
 245 ```
 246 docker logs -f controller
 247 ```
 248
 249 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.
 250
 251 ```
 252 docker-compose -f network/docker-compose.yml up -d
 253 ```
 254
 255 Usually the first ves:event gets lost. Please restart the O-DU docker container(s) to send a second ves:pnfRegistration.
 256
 257 ```
 258 docker-compose -f network/docker-compose.yml restart ntsim-ng-o-du-1122
 259 python network/config.py
 260 ```
 261
 262 The python script configures the simulated O-DU and O-RU according to O-RAN hybrid architecture.
 263
 264 O-DU - NETCONF Call HOME and NETCONF notifications
 265 O-RU - ves:pnfRegistration and ves:fault, ves:heartbeat
 266
 267 ![ves:pnfRegistration in ODLUX](docs/nstim-ng-connected-after-ves-pnf-registration-in-odlux.png "ves:pnfRegistration in ODLUX")
 268
 269 'True' indicated that the settings through SDN-R to the NETCONF server were
 270 successful.
 271
 272 SDN-R reads the fault events from DMaaP and processes them.
 273 Finally the fault events are visible in ODLUX.
 274
 275 ![ves:fault in ODLUX](docs/ves-fault-in-odlux.png "ves:fault in ODLUX")
 276
 277
 278 ### Log files and karaf console
 279
 280 #### ODL karaf.logs
 281
 282 ```
 283 docker exec -it controller tail -f /opt/opendaylight/data/log/karaf.log
 284 ```
 285
 286 #### ves-collector logs
 287
 288 ```
 289 docker logs -f ves-collector
 290 ```
 291
 292 ### Customizing Solution
 293
 294 '.env' file contains customizing parameters
 295
 296 ### Verification Solution
 297
 298 #### Access to SDN-R ODLUX
 299
 300 ##### Login into SDN-R
 301
 302     https://odlux.oam.smo.o-ran-sc.org
 303
 304     User: admin // see .env file
 305
 306     Password: Kp8bJ4SXszM0WXlhak3eHlcse2gAw84vaoGGmJvUy2U
 307
 308 In case of trouble, please update the commands with your customized '.env' file.
 309
 310 ### Terminate solution
 311
 312 To stop all container please respect the following order
 313
 314 ```
 315 docker-compose -f network/docker-compose.yml down
 316 docker-compose -f smo/apps/docker-compose.yml down
 317 docker-compose -f smo/oam/docker-compose.yml down
 318 docker-compose -f smo/common/docker-compose.yml down
 319 ```
 320
 321 ### Cleanup
 322
 323 !!! be careful if other stopped containers are on the same system
 324 ```
 325 docker system prune -a -f
 326 ```
 327 ### Troubleshooting
 328
 329 In most cases the .env setting do not fit to the environment and need to be
 330 adjusted.
 331
 332 Please make sure that the network settings to not overlap with other networks.
 333
 334 The commands ...
 335 ```
 336 docker ps -a
 337 docker-compose ps
 338 docker rm -f $(docker ps -aq)