README.md

   1 # O-RAN-SC Hello World Xapp in Golang
   2
   3 This repository contains open-source code for a prototype golang xAPP for near real-time
   4 RAN Intelligent Controller which makes use of golang Xapp Framework.
   5
   6 This xAPP aims to provide basic implementation of :
   7
   8 1. A1 interfaces interactions
   9
  10 2. Read-write operations into a persistent storage.
  11
  12 3. xAPP Configuration management
  13
  14 4. RMR Health Check
  15
  16 5. xAPP SDL Check
  17
  18 6. Raising alarms
  19
  20 7. Generating metrics
  21
  22 8. E2 Interface intereactions
  23
  24
  25 ## Introduction
  26
  27 This document provides guidelines on how to install and configure the HW Golang xAPP in various environments/operating modes.
  28 The audience of this document is assumed to have good knowledge in RIC Platform.
  29
  30
  31 ## Preface
  32 This xAPP can be run directly as a Linux binary, as a docker image, or in a pod in a Kubernetes environment.  The first
  33 two can be used for dev testing. The last option is how an xAPP is deployed in the RAN Intelligent Controller environment.
  34 This covers all three methods.
  35
  36 1. Docker
  37
  38 2. Linux Binary
  39
  40 3. Kubernetes
  41
  42
  43
  44 ## Software Installation and Deployment
  45
  46 ### Onboarding of hw-go using dms_cli tool
  47
  48 `dms_cli` offers rich set of command line utility to onboard `hw-go` xapp
  49 to `chartmuseme`.
  50
  51 First checkout the [hw-go](https://gerrit.o-ran-sc.org/r/admin/repos/ric-app/hw-go) repository from gerrit.
  52
  53 ```
  54 git clone "https://gerrit.o-ran-sc.org/r/ric-app/hw-go"
  55 ```
  56
  57 `hw-go` has following folder structure
  58 ```
  59 ├── Dockerfile
  60 ├── INFO.yaml
  61 ├── LICENSES.txt
  62 ├── README.md
  63 ├── config
  64 │   ├── config-file.json           // descriptor for hw-go
  65 │   ├── schema.json                // schema for controls section of descriptor
  66 │   └── uta_rtg.rt                 // local route file
  67 ├── docs
  68 ├── go.mod
  69 ├── go.sum
  70 └── hwApp.go
  71
  72 ```
  73
  74 For onboarding `hw-go` make sure that `dms_cli` and helm3 is installed. One can follow [documentation](https://docs.o-ran-sc.org/projects/o-ran-sc-it-dep/en/latest/installation-guides.html#ric-applications) to
  75 configure `dms_cli`.
  76
  77 Once `dms_cli` is availabe we can proceed to onboarding proceure.
  78
  79 configure the `export CHART_REPO_URL` to point `chartmuseme`.
  80 ```
  81 $export CHART_REPO_URL=http://<service-ricplt-xapp-onboarder-http.ricplt>:8080
  82 ```
  83
  84 check if `dms_cli` working fine.
  85 ```
  86 $ dms_cli health
  87 True
  88 ```
  89
  90 Now move to `config` folder to initiate onboarding.
  91
  92 ```
  93 $ cd config
  94 $ dms_cli onboard --config_file_path=config-file.json --shcema_file_path=schema.json
  95 httpGet:
  96   path: '{{ index .Values "readinessProbe" "httpGet" "path" | toJson }}'
  97   port: '{{ index .Values "readinessProbe" "httpGet" "port" | toJson }}'
  98 initialDelaySeconds: '{{ index .Values "readinessProbe" "initialDelaySeconds" | toJson }}'
  99 periodSeconds: '{{ index .Values "readinessProbe" "periodSeconds" | toJson }}'
 100
 101 httpGet:
 102   path: '{{ index .Values "livenessProbe" "httpGet" "path" | toJson }}'
 103   port: '{{ index .Values "livenessProbe" "httpGet" "port" | toJson }}'
 104 initialDelaySeconds: '{{ index .Values "livenessProbe" "initialDelaySeconds" | toJson }}'
 105 periodSeconds: '{{ index .Values "livenessProbe" "periodSeconds" | toJson }}'
 106
 107 {
 108     "status": "Created"
 109 }
 110 ```
 111
 112 Check if `hw-go` is onborded
 113
 114 ```
 115 $ curl --location --request GET "http://<appmgr>:32080/onboard/api/v1/charts"  --header 'Content-Type: application/json'
 116
 117 {
 118     "hw-go": [
 119         {
 120             "name": "hw-go",
 121             "version": "1.0.0",
 122             "description": "Standard xApp Helm Chart",
 123             "apiVersion": "v1",
 124             "appVersion": "1.0",
 125             "urls": [
 126                 "charts/hw-go-1.0.0.tgz"
 127             ],
 128             "created": "2021-06-24T18:57:41.98056196Z",
 129             "digest": "14a484d9a394ed34eab66e5241ec33e73be8fa70a2107579d19d037f2adf57a0"
 130         }
 131     ]
 132 }
 133
 134 ```
 135
 136 If we would wish to download the charts then we can perform following curl operation :
 137
 138 ```
 139 curl --location --request GET "http://<appmgr>:32080/onboard/api/v1/charts/xapp/hw-go/ver/1.0.0"  --header 'Content-Type: application/json' --output hw-go.tgz
 140 ```
 141
 142 Now the onboarding is done.
 143
 144 ### Deployment of hw-go
 145
 146 Once charts are available we can deploy the the `hw-go` using following curl command :
 147
 148 ```
 149 $ curl --location --request POST "http://<appmgr>:32080/appmgr/ric/v1/xapps"  --header 'Content-Type: application/json'  --data-raw '{"xappName": "hw-go", "helmVersion": "1.0.0"}'
 150 {"instances":null,"name":"hw-go","status":"deployed","version":"1.0"}
 151 ```
 152
 153 Deployment will be done in `ricxapp` ns :
 154
 155 ```
 156 # kubectl get po -n ricxapp
 157 NAME                             READY   STATUS    RESTARTS   AGE
 158 ricxapp-hw-go-55ff7549df-kpj6k   1/1     Running   0          2m
 159
 160 # kubectl get svc -n ricxapp
 161 NAME                         TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)             AGE
 162 aux-entry                    ClusterIP   IP1             <none>        80/TCP,443/TCP      73d
 163 service-ricxapp-hw-go-http   ClusterIP   IP2             <none>        8080/TCP            103m
 164 service-ricxapp-hw-go-rmr    ClusterIP   IP3             <none>        4560/TCP,4561/TCP   103m
 165
 166 ```
 167
 168 Now we can query to appmgr to get list of all the deployed xapps :
 169
 170 ```
 171 # curl http://service-ricplt-appmgr-http.ricplt:8080/ric/v1/xapps | jq .
 172   % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
 173                                  Dload  Upload   Total   Spent    Left  Speed
 174 100   347  100   347    0     0    578      0 --:--:-- --:--:-- --:--:--   579
 175 [
 176   {
 177     "instances": [
 178       {
 179         "ip": "service-ricxapp-hw-go-rmr.ricxapp",
 180         "name": "hw-go-55ff7549df-kpj6k",
 181         "policies": [
 182           1
 183         ],
 184         "port": 4560,
 185         "rxMessages": [
 186           "RIC_SUB_RESP",
 187           "A1_POLICY_REQ",
 188           "RIC_HEALTH_CHECK_REQ"
 189         ],
 190         "status": "running",
 191         "txMessages": [
 192           "RIC_SUB_REQ",
 193           "A1_POLICY_RESP",
 194           "A1_POLICY_QUERY",
 195           "RIC_HEALTH_CHECK_RESP"
 196         ]
 197       }
 198     ],
 199     "name": "hw-go",
 200     "status": "deployed",
 201     "version": "1.0"
 202   }
 203 ]
 204
 205 ```
 206
 207 Logs from `hw-go` :
 208
 209 ```
 210 # kubectl  logs ricxapp-hw-go-55ff7549df-kpj6k -n ricxapp
 211 {"ts":1624562552123,"crit":"INFO","id":"hw-app","mdc":{"time":"2021-06-24T19:22:32"},"msg":"Using config file: config/config-file.json"}
 212 {"ts":1624562552124,"crit":"INFO","id":"hw-app","mdc":{"CONTAINER_NAME":"","HOST_NAME":"","PID":"6","POD_NAME":"","SERVICE_NAME":"","SYSTEM_NAME":"","time":"2021-06-24T19:22:32"},"msg":"Serving metrics on: url=/ric/v1/metrics namespace=ricxapp"}
 213 {"ts":1624562552133,"crit":"INFO","id":"hw-app","mdc":{"CONTAINER_NAME":"","HOST_NAME":"","PID":"6","POD_NAME":"","SERVICE_NAME":"","SYSTEM_NAME":"","time":"2021-06-24T19:22:32"},"msg":"Register new counter with opts: {ricxapp SDL Stored The total number of stored SDL transactions map[]}"}
 214 {"ts":1624562552133,"crit":"INFO","id":"hw-app","mdc":{"CONTAINER_NAME":"","HOST_NAME":"","PID":"6","POD_NAME":"","SERVICE_NAME":"","SYSTEM_NAME":"","time":"2021-06-24T19:22:32"},"msg":"Register new counter with opts: {ricxapp SDL StoreError The total number of SDL store errors map[]}"}
 215 1624562552 6/RMR [INFO] ric message routing library on SI95 p=0 mv=3 flg=00 (fd4477a 4.5.2 built: Jan 21 2021)
 216 {"ts":1624562552140,"crit":"INFO","id":"hw-app","mdc":{"CONTAINER_NAME":"","HOST_NAME":"","HWApp":"0.0.1","PID":"6","POD_NAME":"","SERVICE_NAME":"","SYSTEM_NAME":"","time":"2021-06-24T19:22:32"},"msg":"new rmrClient with parameters: ProtPort=0 MaxSize=0 ThreadType=0 StatDesc=RMR LowLatency=false FastAck=false Policies=[]"}
 217 {"ts":1624562552140,"crit":"INFO","id":"hw-app","mdc":{"CONTAINER_NAME":"","HOST_NAME":"","HWApp":"0.0.1","PID":"6","POD_NAME":"","SERVICE_NAME":"","SYSTEM_NAME":"","time":"2021-06-24T19:22:32"},"msg":"Register new counter with opts: {ricxapp RMR Transmitted The total number of transmited RMR messages map[]}"}
 218 {"ts":1624562552140,"crit":"INFO","id":"hw-app","mdc":{"CONTAINER_NAME":"","HOST_NAME":"","HWApp":"0.0.1","PID":"6","POD_NAME":"","SERVICE_NAME":"","SYSTEM_NAME":"","time":"2021-06-24T19:22:32"},"msg":"Register new counter with opts: {ricxapp RMR Received The total number of received RMR messages map[]}"}
 219 {"ts":1624562552140,"crit":"INFO","id":"hw-app","mdc":{"CONTAINER_NAME":"","HOST_NAME":"","HWApp":"0.0.1","PID":"6","POD_NAME":"","SERVICE_NAME":"","SYSTEM_NAME":"","time":"2021-06-24T19:22:32"},"msg":"Register new counter with opts: {ricxapp RMR TransmitError The total number of RMR transmission errors map[]}"}
 220 {"ts":1624562552140,"crit":"INFO","id":"hw-app","mdc":{"CONTAINER_NAME":"","HOST_NAME":"","HWApp":"0.0.1","PID":"6","POD_NAME":"","SERVICE_NAME":"","SYSTEM_NAME":"","time":"2021-06-24T19:22:32"},"msg":"Register new counter with opts: {ricxapp RMR ReceiveError The total number of RMR receive errors map[]}"}
 221 {"ts":1624562552140,"crit":"INFO","id":"hw-app","mdc":{"CONTAINER_NAME":"","HOST_NAME":"","HWApp":"0.0.1","PID":"6","POD_NAME":"","SERVICE_NAME":"","SYSTEM_NAME":"","time":"2021-06-24T19:22:32"},"msg":"Xapp started, listening on: :8080"}
 222 {"ts":1624562552140,"crit":"INFO","id":"hw-app","mdc":{"CONTAINER_NAME":"","HOST_NAME":"","HWApp":"0.0.1","PID":"6","POD_NAME":"","SERVICE_NAME":"","SYSTEM_NAME":"","time":"2021-06-24T19:22:32"},"msg":"rmrClient: Waiting for RMR to be ready ..."}
 223 {"ts":1624562553140,"crit":"INFO","id":"hw-app","mdc":{"CONTAINER_NAME":"","HOST_NAME":"","HWApp":"0.0.1","PID":"6","POD_NAME":"","SERVICE_NAME":"","SYSTEM_NAME":"","time":"2021-06-24T19:22:33"},"msg":"rmrClient: RMR is ready after 1 seconds waiting..."}
 224 {"ts":1624562553141,"crit":"INFO","id":"hw-app","mdc":{"CONTAINER_NAME":"","HOST_NAME":"","HWApp":"0.0.1","PID":"6","POD_NAME":"","SERVICE_NAME":"","SYSTEM_NAME":"","time":"2021-06-24T19:22:33"},"msg":"xApp ready call back received"}
 225 1624562553 6/RMR [INFO] sends: ts=1624562553 src=service-ricxapp-hw-go-rmr.ricxapp:0 target=localhost:4591 open=0 succ=0 fail=0 (hard=0 soft=0)
 226 1624562553 6/RMR [INFO] sends: ts=1624562553 src=service-ricxapp-hw-go-rmr.ricxapp:0 target=localhost:4560 open=0 succ=0 fail=0 (hard=0 soft=0)
 227 1624562553 6/RMR [INFO] sends: ts=1624562553 src=service-ricxapp-hw-go-rmr.ricxapp:0 target=service-ricplt-a1mediator-rmr.ricplt:4562 open=0 succ=0 fail=0 (hard=0 soft=0)
 228 RMR is ready now ...
 229 {"ts":1624562557140,"crit":"INFO","id":"hw-app","mdc":{"CONTAINER_NAME":"","HOST_NAME":"","HWApp":"0.0.1","PID":"6","POD_NAME":"","SERVICE_NAME":"","SYSTEM_NAME":"","time":"2021-06-24T19:22:37"},"msg":"Application='hw-go' is not ready yet, waiting ..."}
 230 {"ts":1624562562141,"crit":"INFO","id":"hw-app","mdc":{"CONTAINER_NAME":"","HOST_NAME":"","HWApp":"0.0.1","PID":"6","POD_NAME":"","SERVICE_NAME":"","SYSTEM_NAME":"","time":"2021-06-24T19:22:42"},"msg":"Application='hw-go' is not ready yet, waiting ..."}
 231 {"ts":1624562567141,"crit":"INFO","id":"hw-app","mdc":{"CONTAINER_NAME":"","HOST_NAME":"","HWApp":"0.0.1","PID":"6","POD_NAME":"","SERVICE_NAME":"","SYSTEM_NAME":"","time":"2021-06-24T19:22:47"},"msg":"Application='hw-go' is not ready yet, waiting ..."}
 232 {"ts":1624562567370,"crit":"INFO","id":"hw-app","mdc":{"CONTAINER_NAME":"","HOST_NAME":"","HWApp":"0.0.1","PID":"6","POD_NAME":"","SERVICE_NAME":"","SYSTEM_NAME":"","time":"2021-06-24T19:22:47"},"msg":"restapi: method=GET url=/ric/v1/health/ready"}
 233 {"ts":1624562569766,"crit":"INFO","id":"hw-app","mdc":{"CONTAINER_NAME":"","HOST_NAME":"","HWApp":"0.0.1","PID":"6","POD_NAME":"","SERVICE_NAME":"","SYSTEM_NAME":"","time":"2021-06-24T19:22:49"},"msg":"restapi: method=GET url=/ric/v1/health/alive"}
 234 ```
 235
 236 Here we are done with the onboaring and deployment of `hw-go`.
 237
 238 ## License
 239
 240 ```
 241
 242    Copyright (c) 2021 Samsung Electronics Co., Ltd. All Rights Reserved.
 243
 244    Licensed under the Apache License, Version 2.0 (the "License");
 245    you may not use this file except in compliance with the License.
 246    You may obtain a copy of the License at
 247
 248        http://www.apache.org/licenses/LICENSE-2.0
 249
 250    Unless required by applicable law or agreed to in writing, software
 251    distributed under the License is distributed on an "AS IS" BASIS,
 252    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 253    See the License for the specific language governing permissions and
 254    limitations under the License.
 255
 256 ```