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 the O1 interface based on
  28     ODL.
  29
  30   * **VES collector**
  31
  32     ... representing the VES (REST) provider at SMO for all kind of events.
  33
  34   * **Messages**
  35     ... representing SMO MessageRouter component, includes message-router
  36
  37 ## Prerequisites
  38
  39 ```
  40 $ cat /etc/os-release | grep PRETTY_NAME
  41 PRETTY_NAME="Ubuntu 22.04.1 LTS"
  42
  43 $ docker --version
  44 Docker version 20.10.12, build 20.10.12-0ubuntu4
  45
  46 $ docker-compose version
  47 docker-compose version 1.29.2, build unknown
  48 docker-py version: <module 'docker.version' from '/usr/local/lib/python3.10/dist-packages/docker/version.py'>
  49 CPython version: 3.10.6
  50 OpenSSL version: OpenSSL 3.0.2 15 Mar 2022
  51
  52
  53 $ git --version
  54 git version 2.34.1
  55
  56 ```
  57 Please modify the /etc/hosts of your system.
  58
  59 * \<your-system>: is the hostname of the system, where the browser is started
  60
  61 * \<deployment-system-ipv4>: is the IP address of the system where the solution will be deployed
  62
  63 For development purposes <your-system> and <deployment-system> may reference the same system.
  64
  65 ```
  66 $ cat /etc/hosts
  67 127.0.0.1                      localhost
  68 127.0.1.1                      <your-system>
  69
  70 # SMO OAM development system
  71 <deployment-system-ipv4>                   smo.o-ran-sc.org
  72 <deployment-system-ipv4>           gateway.smo.o-ran-sc.org
  73 <deployment-system-ipv4>          identity.smo.o-ran-sc.org
  74 <deployment-system-ipv4>          messages.smo.o-ran-sc.org
  75 <deployment-system-ipv4> ves-collector.oam.smo.o-ran-sc.org
  76 <deployment-system-ipv4>         odlux.oam.smo.o-ran-sc.org
  77 <deployment-system-ipv4>    controller.oam.smo.o-ran-sc.org
  78
  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 Please ensure that you download and copy the required 3GPP OpenAPIs for VES-stndDefined
  90 message validation into the folder './solution/operation-and-maintenance/smo/oam/ves-collector/externalRepo'.
  91
  92 Please follow the instructions in ./solution/operation-and-maintenance/smo/oam/ves-collector/externalRepo/3gpp/rep/sa5/MnS/blob/Rel16/OpenAPI/README.md.
  93
  94 The following tree shows the successfully tested folder structure. It combines different versions of the schemas ('Rel16' and 'SA88-Rel16') using 3GPP branch names.
  95
  96 ```
  97 $ tree solution/operation-and-maintenance/smo/oam/ves-collector/externalRepo/
  98 solution/operation-and-maintenance/smo/oam/ves-collector/externalRepo/
  99 ├── 3gpp
 100 │   └── rep
 101 │       └── sa5
 102 │           └── MnS
 103 │               └── blob
 104 │                   ├── Rel16
 105 │                   │   └── OpenAPI
 106 │                   │       ├── README.md
 107 │                   │       ├── TS28532_FaultMnS.yaml
 108 │                   │       ├── TS28532_FileDataReportingMnS.yaml
 109 │                   │       ├── TS28532_HeartbeatNtf.yaml
 110 │                   │       ├── TS28532_PerfMnS.yaml
 111 │                   │       ├── TS28532_ProvMnS.yaml
 112 │                   │       ├── TS28532_StreamingDataMnS.yaml
 113 │                   │       ├── TS28536_CoslaNrm.yaml
 114 │                   │       ├── TS28541_5GcNrm.yaml
 115 │                   │       ├── TS28541_NrNrm.yaml
 116 │                   │       ├── TS28541_SliceNrm.yaml
 117 │                   │       ├── TS28550_PerfMeasJobCtrlMnS.yaml
 118 │                   │       ├── TS28623_ComDefs.yaml
 119 │                   │       ├── TS28623_GenericNrm.yaml
 120 │                   │       ├── TS29512_Npcf_SMPolicyControl.yaml
 121 │                   │       ├── TS29514_Npcf_PolicyAuthorization.yaml
 122 │                   │       └── TS29571_CommonData.yaml
 123 │                   └── SA88-Rel16
 124 │                       └── OpenAPI
 125 │                           ├── 5gcNrm.yaml
 126 │                           ├── PerDataFileReportMnS.yaml
 127 │                           ├── PerMeasJobCtlMnS.yaml
 128 │                           ├── PerThresMonMnS.yaml
 129 │                           ├── PerfDataStreamingMnS.yaml
 130 │                           ├── README.md
 131 │                           ├── comDefs.yaml
 132 │                           ├── coslaNrm.yaml
 133 │                           ├── faultMnS.yaml
 134 │                           ├── genericNrm.yaml
 135 │                           ├── heartbeatNtf.yaml
 136 │                           ├── nrNrm.yaml
 137 │                           ├── provMnS.yaml
 138 │                           ├── sliceNrm.yaml
 139 │                           └── streamingDataMnS.yaml
 140 ```
 141
 142 ## Expected Folder Structure
 143
 144 The following figure show the expected folder structure for the different
 145 docker-compose file and its configurations.
 146
 147 ```
 148 ├── network
 149 │   ├── .env
 150 │   ├── config.py
 151 │   ├── docker-compose.yml
 152 │   │
 153 │   ├── ntsim-ng-o-du
 154 │   └── ntsim-ng-o-ru
 155 └── smo
 156     ├── common
 157     │   ├── .env
 158     │   ├── docker-compose.yml
 159     │   │
 160     │   ├── messages
 161     │   ├── docker
 162     │   ├── identity
 163     │   ├── kafka
 164     │   └── zookeeper
 165     └── oam
 166         ├── .env
 167         ├── docker-compose.yml
 168         │
 169         ├── odlux
 170         ├── controller
 171         └── ves-collector
 172 ```
 173
 174 ## Usage
 175
 176 ### Bring Up Solution
 177
 178 #### Short story
 179
 180 The following commands should be invoked. More detailed can be found in the
 181 next chapters.
 182
 183 ```
 184 docker-compose -f smo/common/docker-compose.yml up -d
 185 # wait until the cpu load is low again
 186 python smo/common/identity/config.py
 187
 188 docker-compose -f smo/oam/docker-compose.yml up -d
 189 docker-compose -f smo/apps/docker-compose.yml up -d
 190
 191 # wait until the cpu load is low again
 192
 193 docker-compose -f network/docker-compose.yml up -d
 194 # wait about 2min
 195 docker restart ntsim-ng-o-du-1122
 196 python network/config.py
 197 ```
 198
 199 #### Check (adjust if required) environment variables
 200
 201 ```
 202 nano smo/common/.env
 203 nano smo/oam/.env
 204 nano network/.env
 205 ```
 206
 207 #### Startup solution
 208
 209 Please note that it is necessary to configure first the identity service,
 210 before starting further docker images.
 211
 212 The several docker-compose yml files must be started in the right order as listed below:
 213
 214 ```
 215 docker-compose -f smo/common/docker-compose.yml up -d
 216 python smo/common/identity/config.py
 217 ```
 218
 219 The python script configure the users within the identity service (keycloak).
 220 A system user (%USER) is also created with administration rights.
 221
 222
 223 ```
 224 docker-compose -f smo/oam/docker-compose.yml up -d
 225 ```
 226
 227 Looking into the ONAP SDN-R logs will give you the startup procedure.
 228
 229 ```
 230 docker logs -f controller
 231 ```
 232
 233 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.
 234
 235 ```
 236 docker-compose -f network/docker-compose.yml up -d
 237 ```
 238
 239 Usually the first ves:event gets lost. Please restart the O-DU docker container(s) to send a second ves:pnfRegistration.
 240
 241 ```
 242 docker-compose -f network/docker-compose.yml restart ntsim-ng-o-du-1122
 243 python network/config.py
 244 ```
 245
 246 The python script configures the simulated O-DU and O-RU according to O-RAN hybrid architecture.
 247
 248 O-DU - NETCONF Call HOME and NETCONF notifications
 249 O-RU - ves:pnfRegistration and ves:fault, ves:heartbeat
 250
 251 ![ves:pnfRegistration in ODLUX](docs/nstim-ng-connected-after-ves-pnf-registration-in-odlux.png "ves:pnfRegistration in ODLUX")
 252
 253 'True' indicated that the settings through SDN-R to the NETCONF server were
 254 successful.
 255
 256 SDN-R reads the fault events from DMaaP and processes them.
 257 Finally the fault events are visible in ODLUX.
 258
 259 ![ves:fault in ODLUX](docs/ves-fault-in-odlux.png "ves:fault in ODLUX")
 260
 261
 262 ### Log files and karaf console
 263
 264 #### ODL karaf.logs
 265
 266 ```
 267 docker exec -it controller tail -f /opt/opendaylight/data/log/karaf.log
 268 ```
 269
 270 #### ves-collector logs
 271
 272 ```
 273 docker logs -f ves-collector
 274 ```
 275
 276 ### Customizing Solution
 277
 278 '.env' file contains customizing parameters
 279
 280 ### Verification Solution
 281
 282 #### Access to SDN-R ODLUX
 283
 284 ##### Login into SDN-R
 285
 286     https://odlux.oam.smo.o-ran-sc.org
 287
 288     User: admin // see .env file
 289
 290     Password: Kp8bJ4SXszM0WXlhak3eHlcse2gAw84vaoGGmJvUy2U
 291
 292 In case of trouble, please update the commands with your customized '.env' file.
 293
 294 ### Terminate solution
 295
 296 To stop all container please respect the following order
 297
 298 ```
 299 docker-compose -f network/docker-compose.yml down
 300 docker-compose -f smo/apps/docker-compose.yml down
 301 docker-compose -f smo/oam/docker-compose.yml down
 302 docker-compose -f smo/common/docker-compose.yml down
 303 ```
 304
 305 ### Cleanup
 306
 307 !!! be careful if other stopped containers are on the same system
 308 ```
 309 docker system prune -a -f
 310 ```
 311 ### Troubleshooting
 312
 313 In most cases the .env setting do not fit to the environment and need to be
 314 adjusted.
 315
 316 Please make sure that the network settings to not overlap with other networks.
 317
 318 The commands ...
 319 ```
 320 docker ps -a
 321 docker-compose ps
 322 docker rm -f $(docker ps -aq)