servicemanager/README.md

   1 <!--
   2 -
   3 ========================LICENSE_START=================================
   4 O-RAN-SC
   5 %%
   6 Copyright (C) 2024 OpenInfra Foundation Europe. All rights reserved.
   7 %%
   8 Licensed under the Apache License, Version 2.0 (the "License");
   9 you may not use this file except in compliance with the License.
  10 You may obtain a copy of the License at
  11
  12      http://www.apache.org/licenses/LICENSE-2.0
  13
  14 Unless required by applicable law or agreed to in writing, software
  15 distributed under the License is distributed on an "AS IS" BASIS,
  16 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  17 See the License for the specific language governing permissions and
  18 limitations under the License.
  19 ========================LICENSE_END===================================
  20
  21 -->
  22
  23 # O-RAN-SC Non-RealTime RIC Service Management and Exposure
  24
  25 This product is a Go implementation of a service that calls the CAPIF Core function. When publishing a service we create a Kong route and Kong service, https://konghq.com/. The InterfaceDescription that we return is updated to point to the Kong Data Plane. Therefore, the API interface that we return from Service Discovery has the Kong host and port, and not the original service's host and port. This allows the rApp's API call to be re-directed through Kong.
  26
  27 ## O-RAN-SC Non-RealTime RIC CAPIF Core Implementation
  28
  29 This product is a Go implementation of the CAPIF Core function, which is based on the 3GPP "29.222 Common API Framework for 3GPP Northbound APIs (CAPIF)" interfaces, see https://portal.3gpp.org/desktopmodules/Specifications/SpecificationDetails.aspx?specificationId=3450.
  30
  31 See [CAPIF Core](../capifcore/README.md)
  32
  33 ## Generation of API Code
  34
  35 The CAPIF APIs are generated from the OpenAPI specifications provided by 3GPP. The `generate.sh` script downloads the
  36 specifications from 3GPP, fixes them and then generates the APIs. While these files are checked into the repo, they can be re-generated using `generate.sh`.
  37
  38 ```sh
  39 ./generate.sh
  40 ```
  41
  42 The specifications are downloaded from the following site; https://www.3gpp.org/ftp/Specs/archive/29_series. To see
  43 the APIs in swagger format, see the following link; https://github.com/jdegre/5GC_APIs/tree/Rel-16#common-api-framework-capif.
  44 **NOTE!** The documentation in this link is for release 16 of CAPIF, the downloaded specifications are for release 17.
  45
  46 To fix the specifications there are three tools.
  47 - `commoncollector`, collects type definitions from peripheral specifications to keep down the number of dependencies to
  48   other specifications. The types to collect are listed in the `definitions.txt`file. Some fixes are hard coded.
  49 - `enumfixer`, fixes enumeration definitions so they can be properly generated.
  50 - `specificationfixer`, fixes flaws in the specifications so they can be properly generated. All fixes are hard coded.
  51
  52 ## Set Up
  53
  54 First, we need to run `generate.sh` as described above to generate our API code from the 3GPP spec.
  55
  56 Before we can test or run R1-SME-Manager, we need to configure a .env file with the required parameters. Please see the template .env.example in the servicemanager directory.
  57
  58 You can set the environmental variable SERVICE_MANAGER_ENV to specify the .env file. For example, the following command specifies to use the config file
  59 .env.development. If this flag is not set, first we try .env.development and then .env.
  60
  61 ```sh
  62 export SERVICE_MANAGER_ENV=development
  63 ```
  64
  65 ### Capifcore and Kong
  66
  67 We also need Kong and Capifcore to be running. Please see the examples in the `configs` folder.
  68
  69 ## Build
  70
  71 After generating the API code, we can build the application with the following command.
  72
  73 ```sh
  74 go build
  75 ```
  76
  77 ## Unit Tests
  78
  79 To run the unit tests for the application, first ensure that the .env file is configured. In the following example, we specify `.env.test`. For now, we need to disable parallelism in the unit tests with -p=1.
  80
  81 ```sh
  82 export SERVICE_MANAGER_ENV=test
  83 go test -p=1 -count=1 ./...
  84 ```
  85
  86 ## Run Locally
  87
  88 To run as a local app, first ensure that the .env file is configured. In the following example, we specify `.env.development`.
  89
  90 ```sh
  91 export SERVICE_MANAGER_ENV=development
  92 ./servicemanager
  93 ```
  94
  95 R1-SME-Manager is then available on the port configured in .env.
  96
  97 ## Building the Docker Image
  98
  99 The application can also be built as a Docker image, by using the following command. We build the image without a .env file. This is supplied by volume mounting at container run-time. Because we need to include Capifcore in the Docker build context, we build from the git repo's root directory, sme.
 100
 101 ```sh
 102 docker build -t servicemanager -f servicemanager/Dockerfile .
 103 ```
 104
 105 ## Kongclearup
 106
 107 Please note that a special executable has been provided for deleting Kong routes and services that have been created ServiceManager in Kong. This executable is called `kongclearup` and is found in the working directory of the ServiceManger Docker image, at `/app/kongclearup`. When we create a Kong route or service, we add Kong tags with information as follows.
 108   * apfId
 109   * aefId
 110   * apiId
 111   * apiVersion
 112   * resourceName
 113
 114 When we delete Kong routes and services using `kongclearup`, we check for the existance of these tags, specifically, apfId, apiId and aefId. Only if these tags exist and have values do we proceed to delete the Kong service or route.
 115
 116 The executable `kongclearup` uses the volume-mounted .env file to load the configuration giving the location of Kong.
 117
 118 Please refer to `sme/servicemanager/internal/kongclearup.go`.
 119
 120 ## Stand-alone Deployment on Kubernetes
 121
 122 For a stand-alone deployment, please see the `deploy` folder for configurations to deploy to R1-SME-Manager to Kubernetes. We need the following steps.
 123  - Deploy a PV for Kong's Postgres database (depends on your Kubernetes cluster)
 124  - Deploy a PVC for Kong's Postgres database
 125  - Deploy Kong with Postgres
 126  - Deploy Capifcore
 127  - Deploy R1-SME-Manager
 128
 129 We consolidate the above steps into the script `deploy-to-k8s.sh`. To delete the full deployment, you can use `delete-from-k8s.sh`. The deploy folder has the following structure.
 130
 131 - sme/
 132   - servicemanager/
 133     - deploy/
 134       - src/
 135       - manifests/
 136
 137 We store the Kubernetes manifests files in the manifests in the subfolder. We store the shell scripts in the src folder.
 138
 139 In `deploy-to-k8s.sh`, we copy .env.example and use sed to replace the template values with values for testing/production. You will need to update this part of the script with your own values. There is an example sed replacement in function `substitute_manifest()` in `deploy-to-k8s.sh`. Here, you can substitute your own Docker images for Capifcore and Service Manager for local development.
 140
 141 In addition there are 2 switches that are added for developer convenience.
 142  * --repo # allow you to specify your own docker repo
 143  * --env  # allow you to specify an additional env file, and set SERVICE_MANAGER_ENV to point to this file.
 144
 145 `./deploy-to-k8s.sh --repo your-docker-repo-id --env ../../.env.minikube`