solution/README.md

   1 # Service Management and Orchestration (SMO) for OAM
   2
   3 This project focus on a docker-compose deployment solution for SMO/OAM Components.
   4
   5 ## Introduction
   6
   7 With respect to Operation and Maintenance (OAM) the SMO implements the O1-interface and OpenFronthaul Management-Plane consumers.
   8 According to the O-RAN OAM Architecture and the O-RAN OAM Interface Specification, the SMO implements a NETCONF Client for configuration
   9 and a HTTP/REST/VES server for receiving all kind of events in VES format.
  10
  11 The O-RAN-SC OAM deployment contains an OpenDaylight based NETCONF client and an ONAP VES Collector. Kafka is used as massage router for communication between the components. The Keycloak implementation offers and Identity service, while traefik acts as reverse proxy to terminate all incoming https traffic. For storing data in a persistence way the implementation of the mariaDB project is used.
  12
  13 Before you start please think about a nice full qualified domain name of your environment. Your DNS or /etc/hosts settings needs to be updated.
  14 Here an inspiration: smo.dev.o-ran-sc.<your-organization>.com
  15
  16 ## SMO OAM Components
  17
  18 This docker-compose file starts a pre-configured, self-contained SDN-R solution
  19 with the following components.
  20
  21   * **Identity**
  22     ... representing an KeyCloak based identity service for centralized user
  23     management. Please note that the implementation does not support IPv6.
  24     Therefore, its own network is required called 'DMZ'.
  25
  26   * **Controller** single node instance
  27
  28     ... representing the NETCONF consumer on the Service Management and
  29     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.
  30
  31   * **VES collector**
  32
  33     ... representing the VES (REST) provider at SMO for all kind of events.
  34
  35   * **Messages**
  36     ... representing SMO MessageRouter component, includes message-router
  37
  38   * **Gateway**
  39     ... representing a revers proxy terminating TLS traffic (https, NETCONF)
  40
  41 ## Prerequisites
  42
  43 ### Resources
  44
  45 The solution was tested on a VM with
  46
  47 - 4x Core
  48 - 16 GBit RAM
  49 - 50 Gbit Storage
  50
  51 ### Operating (HOST) System
  52
  53 ```
  54 $ cat /etc/os-release | grep PRETTY_NAME
  55 PRETTY_NAME="Ubuntu 24.04.1 LTS"
  56 ```
  57
  58 ### Docker
  59
  60 ```
  61 $ docker --version
  62 Docker version 27.5.1, build 9f9e405
  63 ```
  64 Please follow the required docker daemon configuration as documented in the following README.md:
  65 - [./smo/common/docker/README.md](./smo/common/docker/README.md)
  66
  67 ### Docker Compose
  68
  69 ```
  70 $ docker compose version
  71 Docker Compose version v2.32.4
  72 ```
  73
  74 In case your environment acts behind a proxy, please see related docker documentations:
  75
  76 https://docs.docker.com/engine/daemon/proxy/
  77
  78
  79 ### GIT
  80
  81 ```
  82 $ git --version
  83 git version 2.43.0
  84 ```
  85
  86 ### GCC
  87
  88 ```
  89 $ sudo apt install gcc
  90 ```
  91
  92 ### Python
  93
  94 ```
  95 $ python3 --version
  96 Python 3.12.3
  97 ```
  98
  99 ### Python3-dev
 100
 101 ```
 102 $ sudo apt install python3-dev
 103 ```
 104
 105 A python parser package is required.
 106 ```
 107 python3 -m venv .oam
 108 source .oam/bin/activate
 109 pip3 install -r requirements.txt
 110 ```
 111
 112 ### ETC Host (DNS function)
 113
 114 Your local IP and your used interface is required. Please use the following
 115 script to modify all .env and other configuration files accordingly.
 116 The script will find automatically the interface and its ip-address
 117 to the internet.
 118 You can check its usage with option "-h":
 119
 120 ```
 121 python3 ./adopt_to_environment.py -h
 122 ```
 123
 124 Please run the script with your preferred fully qualified domain name,
 125 you like to use in your browser address bar.
 126
 127 ```
 128 python3 ./adopt_to_environment.py -d <your-smo-fqdn>
 129 ```
 130
 131 you can revert the settings in the modified .env and configuration files
 132 using the option "-r".
 133
 134 ```
 135 python3 ./adopt_to_environment.py -d <your-smo-fqdn> -r
 136 ```
 137
 138
 139 It is beneficial (but not mandatory) adding the following line add the
 140 end of your ~/.bashrc file. I will suppress warnings when python script
 141 do not verify self signed certificates for HTTPS communication.
 142
 143 ```
 144 export PYTHONWARNINGS="ignore:Unverified HTTPS request"
 145 ```
 146
 147 Please modify the /etc/hosts of your system or modify the DNS of your
 148 environment.
 149
 150 * \<your-system>: is the hostname of the system, where the browser is started
 151
 152 * \<deployment-system-ipv4>: is the IP address of the system where the solution will be deployed
 153
 154
 155 ```
 156 $ cat /etc/hosts
 157 127.0.0.1                      localhost
 158 127.0.1.1                      <your-system>
 159
 160 # SMO OAM development system
 161 <deployment-system-ipv4>                   smo.o-ran-sc.org
 162 <deployment-system-ipv4>           gateway.smo.o-ran-sc.org
 163 <deployment-system-ipv4>          identity.smo.o-ran-sc.org
 164 <deployment-system-ipv4>          messages.smo.o-ran-sc.org
 165 <deployment-system-ipv4>      kafka-bridge.smo.o-ran-sc.org
 166 <deployment-system-ipv4>          kafka-ui.smo.o-ran-sc.org
 167 <deployment-system-ipv4>         odlux.oam.smo.o-ran-sc.org
 168 <deployment-system-ipv4>         flows.oam.smo.o-ran-sc.org
 169 <deployment-system-ipv4>         tests.oam.smo.o-ran-sc.org
 170 <deployment-system-ipv4>    controller.dcn.smo.o-ran-sc.org
 171 <deployment-system-ipv4> ves-collector.dcn.smo.o-ran-sc.org
 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 ```bash
 184 source .oam/bin/activate
 185 ./setup.sh
 186 ```
 187
 188 #### Simulated network
 189 Before starting the simulated network, you need to locally build the docker images.
 190 This is because of copyright issues with the 3GPP YANG models.
 191
 192 The build should be pretty straightforward. The repository containing the PyNTS code needs to be cloned and then a command needs to be ran for building the images. Run this from another terminal, in another folder, not in this repo.
 193
 194 ```bash
 195 git clone "https://gerrit.o-ran-sc.org/r/sim/o1-ofhmp-interfaces"
 196 cd o1-ofhmp-interfaces
 197 make build-all
 198 ```
 199 After everything is built successfully, you can return to your solution folder here and start the network.
 200 ```bash
 201 docker compose -f network/docker-compose.yaml up -d
 202 docker compose -f network/docker-compose.yaml restart pynts-o-du-o1
 203 ```
 204
 205 #### Check (adjust if required) environment variables
 206
 207 ```
 208 nano smo/common/.env
 209 nano smo/oam/.env
 210 nano network/.env
 211 ```
 212
 213 #### Startup solution
 214
 215 Please note that it is necessary to configure first the identity service,
 216 before starting further docker images.
 217
 218 The several docker-compose yaml files must be started in the right order as listed below:
 219
 220 ```
 221 docker compose -f infra/docker-compose.yaml up -d
 222 docker compose -f smo/common/docker-compose.yaml up -d
 223 python smo/common/identity/config.py
 224 ```
 225
 226 The python script configure the users within the identity service (keycloak).
 227 A system user (%USER) is also created with administration rights.
 228
 229 ```
 230 docker compose -f smo/oam/docker-compose.yaml up -d
 231 ```
 232
 233 Looking into the ONAP SDN-R logs will give you the startup procedure.
 234
 235 ```
 236 docker logs -f controller
 237 ```
 238
 239 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.
 240
 241 ```
 242 docker compose -f network/docker-compose.yaml up -d
 243 ```
 244
 245 Usually the first ves:event gets lost. Please restart the O-DU docker container(s) to send a second ves:pnfRegistration.
 246
 247 ```
 248 docker compose -f network/docker-compose.yaml restart pynts-o-du-o1
 249 ```
 250
 251 The simulated O-DU and O-RUs are pre-configured according to O-RAN hybrid architecture.
 252
 253 O-RU - NETCONF Call HOME and NETCONF notifications
 254 O-DU - ves:pnfRegistration and ves:fault, ves:heartbeat
 255
 256 ![ves:pnfRegistration in ODLUX](docs/nstim-ng-connected-after-ves-pnf-registration-in-odlux.png "ves:pnfRegistration in ODLUX")
 257
 258 SDN-R reads the fault events from DMaaP and processes them.
 259 Finally the fault events are visible in ODLUX.
 260
 261 ![ves:fault in ODLUX](docs/ves-fault-in-odlux.png "ves:fault in ODLUX")
 262
 263
 264 ### Log files and karaf console
 265
 266 #### ODL karaf.logs
 267
 268 ```
 269 docker exec -it controller tail -f /opt/opendaylight/data/log/karaf.log
 270 ```
 271
 272 #### ves-collector logs
 273
 274 ```
 275 docker logs -f ves-collector
 276 ```
 277
 278 ### Customizing Solution
 279
 280 '.env' file contains customizing parameters
 281
 282 ### Verification Solution
 283
 284 #### Access to SDN-R ODLUX
 285
 286     https://odlux.oam.smo.o-ran-sc.org
 287
 288     User: admin
 289
 290     Password: // see .env file
 291
 292 In case of trouble, please update the commands with your customized '.env' file.
 293
 294 #### Access to Node Red Flows
 295
 296     https://flows.oam.smo.o-ran-sc.org
 297
 298     User: admin
 299
 300     Password: // see .env file
 301
 302 In case of trouble, please update the commands with your customized '.env' file.
 303
 304 ### Terminate solution
 305
 306 To stop all container please respect the following order
 307
 308 ```
 309 docker compose -f network/docker-compose.yaml down
 310 docker compose -f smo/apps/docker-compose.yaml down
 311 docker compose -f smo/oam/docker-compose.yaml down
 312 docker compose -f smo/common/docker-compose.yaml down
 313 docker compose -f infra/docker-compose.yaml down
 314 ```
 315
 316 alternative:
 317 ```
 318 ./teardown.sh
 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)
 339
 340 ### Certificates
 341
 342 By default solution comes up with self signed certificates. These certificates are created automatically
 343
 344 ```
 345 ./setup.sh
 346 ```
 347 In case of external certifictes both key-file and certificate should be provided in PEM-format.
 348 `setup.sh`copies the files in the right directory and starts the solution
 349 ```
 350 ls *.pem
 351 #cert.pem  key.pem
 352 ./setup.sh --cert ./cert.pem --key ./key.pem
 353 ```
 354