capifcore/README.md

   1 <!--
   2  -
   3    ========================LICENSE_START=================================
   4    O-RAN-SC
   5    %%
   6    Copyright (C) 2022: Nordix Foundation
   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 CAPIF Core implementation
  24
  25 This product is a Go implementation of the CAPIF Core function, 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.
  26
  27 The data used within CAPIF Core is shown in the diagram below.
  28
  29 <img src="docs/diagrams/Information in rApp registration.svg">
  30
  31 An example of how an rApp that both exposes and consumes services can be registered in CAPIF Core is shown in the sequence diagram below.
  32
  33 ***NOTE!*** It has not been decided that CAPIF Core will actually do the Helm chart installation and starting. This is just provided in the prototype as an example of what CAPIF Core could do. Before publisihing a service, the chart that belongs to the service must be registered in ChartMusem. When publishing the service the following information should be provided in the `ServiceAPIDescription::description` attribute; "namespace", "repoName", "chartName", "releaseName". An exaple of the information: "Description of rApp helloWorld,namespace,repoName,chartName,releaseName".
  34
  35 <img src="docs/diagrams/Register Provider.svg">
  36
  37 ## Generation of API code
  38
  39 The CAPIF APIs are generated from the OpenAPI specifications provided by 3GPP. The `generate.sh` script downloads the
  40 specifications from 3GPP, fixes them and then generates the APIs. It also generates the mocks needed for unit testing.
  41 The specifications are downloaded from the following site; https://www.3gpp.org/ftp/Specs/archive/29_series. To see
  42 the APIs in swagger format, see the following link; https://github.com/jdegre/5GC_APIs/tree/Rel-16#common-api-framework-capif.
  43 **NOTE!** The documentation in this link is for release 16 of CAPIF, the downloaded specifications are for release 17.
  44
  45 To fix the specifications there are three tools:
  46 - `commoncollector`, collects type definitions from peripheral specifications to keep down the number of dependencies to
  47   other specifications. The types to collect are listed in the `definitions.txt`file. Some fixes are hard coded.
  48 - `enumfixer`, fixes enumeration definitions so they can be properly generated.
  49 - `specificationfixer`, fixes flaws in the specifications so they can be properly generated. All fixes are hard coded.
  50
  51 ### Steps to add a new dependency to the commoncollector
  52
  53 When a dependency to a new specification is introduced in any of the CAPIF specifications, see example below, the following steps should be performed:
  54
  55 For the CAPIF specification "TS29222_CAPIF_Discover_Service_API" a new dependency like the following has been introduced.
  56 websockNotifConfig:
  57 &nbsp;&nbsp;&nbsp;&nbsp;$ref: '**TS29122_CommonData.yaml#/components/schemas/WebsockNotifConfig**'
  58
  59 1. Copy the bold part of the reference and add it to the `definitions.txt` file. This step is not needed if the type is already defined in the file.
  60 2. Look in the `generate.sh` script, between the "<replacements_start>" and "<new_replacement>" tags, to see if "TS29122_CommonData"
  61    has already been replaced in "TS29222_CAPIF_Discover_Service_API".
  62 3. If it has not been replaced, add a replacement above the "<new_replacement>" tag by copying and adapting the two rows above the tag.
  63
  64 ## Build and test
  65
  66 To generate mocks manually, run the following command:
  67
  68     go generate ./...
  69
  70 **NOTE!** The `helmmanagement` package contains two mocks from the `helm.sh/helm/v3` product. If they need to be
  71 regenerated, their interfaces must be copied into the `helm.go` file and a generation annotation added before running
  72 the generation script.
  73
  74 To build the application, run the following command:
  75
  76     go build
  77
  78 To run the unit tests for the application, run the following command:
  79
  80     go test ./...
  81
  82 The application can also be built as a Docker image, by using the following command:
  83
  84     docker build . -t capifcore
  85
  86 ## Run
  87
  88 To run the Core Function from the command line, run the following commands from this folder. For the parameter `chartMuseumUrl`, if it is not provided CAPIF Core will not do any Helm integration, i.e. try to start any Halm chart when publishing a service.
  89
  90     ./capifcore [-port <port (default 8090)>] [-chartMuseumUrl <URL to ChartMuseum>] [-repoName <Helm repo name (default capifcore)>] [-loglevel <log level (default Info)>]
  91
  92 To run CAPIF Core as a K8s pod together with ChartMuseum, start and stop scipts are provided. The pod configurations are provided in the `configs` folder. CAPIF Core is then available att port `31570`.