capifcore/README.md

   1 <!--
   2 -
   3 ========================LICENSE_START=================================
   4 O-RAN-SC
   5 %%
   6 Copyright (C) 2022: Nordix Foundation. All rights reserved.
   7 Copyright (C) 2023 OpenInfra Foundation Europe. All rights reserved.
   8 %%
   9 Licensed under the Apache License, Version 2.0 (the "License");
  10 you may not use this file except in compliance with the License.
  11 You may obtain a copy of the License at
  12
  13         http://www.apache.org/licenses/LICENSE-2.0
  14
  15 Unless required by applicable law or agreed to in writing, software
  16 distributed under the License is distributed on an "AS IS" BASIS,
  17 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  18 See the License for the specific language governing permissions and
  19 limitations under the License.
  20 ========================LICENSE_END===================================
  21
  22 -->
  23
  24 # O-RAN-SC Non-RealTime RIC CAPIF Core implementation
  25
  26 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.
  27
  28 The nearly complete data model for CAPIF is shown in the diagram below.
  29
  30 <img src="docs/diagrams/Information model for CAPIF.svg">
  31
  32 The data used within CAPIF Core for registering rApps that provide and consume services is shown in the diagram below.
  33
  34 <img src="docs/diagrams/Information in rApp registration.svg">
  35
  36 Some examples of interactions between components using the CAPIF interface are shown in the sequence diagram below.
  37
  38 ***NOTE!*** It has not been decided that CAPIF Core will actually handle the Helm chart installation. The prototype includes this as an example of what CAPIF Core could potentially do.
  39
  40 <img src="docs/diagrams/Register Provider.svg">
  41
  42 If Helm is used, before publishing a service, the chart belonging to the service must be registered in ChartMuseum. When publishing the service the following information should be provided in the `ServiceAPIDescription::description` attribute; "namespace", "repoName", "chartName", "releaseName". An example of the information: "Description of rApp helloWorld,namespace,repoName,chartName,releaseName".
  43
  44 ## Generation of API code
  45
  46 The CAPIF APIs are generated from the OpenAPI specifications provided by 3GPP. The `generate.sh` script downloads the
  47 specifications from 3GPP, fixes them and then generates the APIs. It also generates the mocks needed for unit testing.
  48 The specifications are downloaded from the following site; https://www.3gpp.org/ftp/Specs/archive/29_series. To see
  49 the APIs in swagger format, see the following link; https://github.com/jdegre/5GC_APIs/tree/Rel-16#common-api-framework-capif.
  50 **NOTE!** The documentation in this link is for release 16 of CAPIF, the downloaded specifications are for release 17.
  51
  52 To fix the specifications there are three tools:
  53 - `commoncollector`, collects type definitions from peripheral specifications to keep down the number of dependencies to
  54   other specifications. The types to collect are listed in the `definitions.txt`file. Some fixes are hard coded.
  55 - `enumfixer`, fixes enumeration definitions so they can be properly generated.
  56 - `specificationfixer`, fixes flaws in the specifications so they can be properly generated. All fixes are hard coded.
  57
  58 ### Steps to add a new dependency to the commoncollector
  59
  60 When a dependency to a new specification is introduced in any of the CAPIF specifications, see example below, the following steps should be performed:
  61
  62 For the CAPIF specification "TS29222_CAPIF_Discover_Service_API" a new dependency like the following has been introduced.
  63
  64     websockNotifConfig:
  65         $ref: ✅TS29122_CommonData.yaml#/components/schemas/WebsockNotifConfig✅'
  66
  67 1. Copy the part between the checkboxes 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.
  68 2. Look in the `generate.sh` script, between the "<replacements_start>" and "<new_replacement>" tags, to see if "TS29122_CommonData"
  69    has already been replaced in "TS29222_CAPIF_Discover_Service_API".
  70 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.
  71
  72 ### Security in CAPIF
  73
  74 The security requirements applicable to all CAPIF entities include providing an authorization mechanism for service APIs from third-party API providers and supporting a common security mechanism for all API implementations to ensure confidentiality and integrity protection.
  75
  76 In the current implementation Keycloak is being used as identity and access management (IAM) solution that provides authentication, authorization, and user management for applications and services. Keycloak provides robust authentication mechanisms, including username/password, two-factor authentication, and client certificate authentication that complies with CAPIF security requirements.
  77
  78 A docker-compose file is included to start up keycloak.
  79
  80 ## Build and test
  81
  82 To generate mocks manually, run the following command:
  83
  84     go generate ./...
  85
  86 **NOTE!** The `helmmanagement` package contains two mocks from the `helm.sh/helm/v3` product. If they need to be
  87 regenerated, their interfaces must be copied into the `helm.go` file and a generation annotation added before running
  88 the generation script.
  89
  90 To build the application, run the following command:
  91
  92     go build
  93
  94 To run the unit tests for the application, run the following command:
  95
  96     go test ./...
  97
  98 The application can also be built as a Docker image, by using the following command:
  99
 100     docker build . -t capifcore
 101
 102 ## Run
 103
 104 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.
 105
 106     ./capifcore [-port <port (default 8090)>] [-secPort <Secure port (default 4433)>] [-chartMuseumUrl <URL to ChartMuseum>] [-repoName <Helm repo name (default capifcore)>] [-loglevel <log level (default Info)>] [-certPath <Path to certificate>] [-keyPath <Path to private key>]
 107
 108 Use docker compose file to start CAPIF core together with Keycloak:
 109
 110     docker-compose up
 111
 112 **NOTE!** There is a configuration file in configs/keycloak.yaml with information related to keycloak host, when running locally the host value must be set to localhost (Eg. host: "localhost") and when using docker-compose set value of host to keycloak (Eg. host:"keycloak")
 113
 114 Before using CAPIF API invoker management, an invoker realm must be created in keycloak. Make sure it is created before running CAPIF core. After creating the realm in keycloak, set the name in the keycloak.yaml configuration file.
 115
 116 To run CAPIF Core as a K8s pod together with ChartMuseum, start and stop scripts are provided. The pod configurations are provided in the `configs` folder. CAPIF Core is then available on port `31570`.
 117
 118 ## Postman
 119
 120 A Postman collection has been included in this repo at sme/postman/CAPIF.postman_collection.json.