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