From: elinuxhenrik Date: Mon, 28 Nov 2022 09:38:11 +0000 (+0100) Subject: Add documentation about rApp registration X-Git-Tag: 1.0.0~18 X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=commitdiff_plain;h=cf1b587eba848c3500c4ffa020d1665f3fc7021f;p=nonrtric%2Fplt%2Fsme.git Add documentation about rApp registration Issue-ID: NONRTRIC-814 Signed-off-by: elinuxhenrik Change-Id: If4d32daa597da6392c840ea352b553cb052212e7 --- diff --git a/README.md b/README.md new file mode 100644 index 0000000..47afecb --- /dev/null +++ b/README.md @@ -0,0 +1,26 @@ + + +# O-RAN-SC Non-RealTime RIC Service Management and Exposure + +See [CAPIF Core](capifcore/README.md) + diff --git a/capifcore/README.md b/capifcore/README.md index cba7ff1..9242007 100644 --- a/capifcore/README.md +++ b/capifcore/README.md @@ -20,9 +20,19 @@ --> -# O-RAN-SC Non-RealTime CAPIF implementation +# O-RAN-SC Non-RealTime RIC CAPIF Core implementation -This product is a Go implementation of the CAPIF Core function, based on the 3GPP CAPIF interfaces. +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. + +The data used within CAPIF Core is shown in the diagram below. + + + +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. + +***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". + + ## Generation of API code @@ -42,8 +52,8 @@ To fix the specifications there are three tools: When a dependency to a new specification is introduced in any of the CAPIF specifications, see example below, the following steps should be performed: -For the CAPIF specification "TS29222_CAPIF_Discover_Service_API" a new dependency like the following has been introduced. -websockNotifConfig: +For the CAPIF specification "TS29222_CAPIF_Discover_Service_API" a new dependency like the following has been introduced. +websockNotifConfig:     $ref: '**TS29122_CommonData.yaml#/components/schemas/WebsockNotifConfig**' 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. @@ -75,7 +85,8 @@ The application can also be built as a Docker image, by using the following comm ## Run -To run the Core Function from the command line, run the following commands from this folder. +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. - ./capifcore [-port ] + ./capifcore [-port ] [-chartMuseumUrl ] [-repoName ] [-loglevel ] +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`. diff --git a/capifcore/docs/diagrams/Information in rApp registration.svg b/capifcore/docs/diagrams/Information in rApp registration.svg new file mode 100644 index 0000000..46a0ccf --- /dev/null +++ b/capifcore/docs/diagrams/Information in rApp registration.svg @@ -0,0 +1,134 @@ +APIProviderEnrolmentDetailsstring apiProvDomIdstring apiProvDomInfo[]APIProviderFunctionDetails apiProvFuncsId provided by CAPIF CoreAPIProviderFunctionDetailsstring apiProvFuncIdstring apiProvFuncInfoApiProviderFuncRole apiProviderFuncRole (required)RegistrationInformation regInfo (required)Id provided by CAPIF Core- AEF: API provider function is API Exposing Function.- APF: API provider function is API Publishing Function.- AMF: API Provider function is API Management Function.RegistrationInformationstring apiProvCertatring apiProvPubKey (required)ServiceAPIDescriptionstring apiIdstring description[]AefProfile aefProfilesstring apiName (required)Id provided by CAPIF CoreAefProfileDataFormat dataFormatstring domainName[]InterfaceDescription interfaceDescriptionsProtocol protocol[]SecurityMethod securityMethodsstring aefId (required)[]Version versions (required)- JSON: JavaScript Object Notation- HTTP_1_1: HTTP version 1.1- HTTP_2: HTTP version 2- PSK: Security method 1 (Using TLS-PSK)- PKI: Security method 2 (Using PKI)- OAUTH: Security method 3 (TLS with OAuth token)From APIProviderFunctionDetailsInterfaceDescriptionstring ipv4Addressstring ipv6Address[]Operation operations[]SecurityMethod securityMethodsSecurity methods supported by the interface,it take precedence over the security methodsprovided in AefProfile, for this specific interface.Versionstring apiVersion[]Resource resources- REQUEST_RESPONSE- SUBSCRIBE_NOTIFYAPIInvokerEnrolmentDetailsstring apiInvokerIdstring apiInvokerInformationAPIList apiListOnboardingInformation onboardingInformationOnboardingInformationstring apiInvokerCertificatestring onboardingSecretstring ApiInvokerPublicKey (required)Secret provided by CAPIF CoreId provided by CAPIF CoreAPIList \ No newline at end of file diff --git a/capifcore/docs/diagrams/Register Provider.svg b/capifcore/docs/diagrams/Register Provider.svg new file mode 100644 index 0000000..f5ed6c7 --- /dev/null +++ b/capifcore/docs/diagrams/Register Provider.svg @@ -0,0 +1,43 @@ +CAPIF InternalrAppCataloguerAppCataloguerAppManagerrAppManagercapifcorecapifcoreprovidermanagerprovidermanagerhelmmanagerhelmmanagerpublishservicepublishserviceStart rApp, with rAppdescriptor specifying whichservices to expose and consumealt[Provider Enrolment]Register provider withAPIProviderEnrolmentDetailsStore providerProvider with apfId and aefIdsalt[Publish Service]Publish serviceswith ServiceAPIDescriptionCheck that AEFs areregistered for providerOkInstall and start chartOkStore published servicesServiceAPIDescription with apiIdalt[Register Invoker]Register invoker withAPIProviderFunctionDetailsGet available services for invokerServices available for the given invokerInvoker with invokerIdand avialable servicesOk \ No newline at end of file diff --git a/capifcore/docs/diagrams/classdiagram.plantuml b/capifcore/docs/diagrams/classdiagram.plantuml new file mode 100644 index 0000000..8700d97 --- /dev/null +++ b/capifcore/docs/diagrams/classdiagram.plantuml @@ -0,0 +1,106 @@ +@startuml Information in rApp registration +struct APIProviderEnrolmentDetails #palegreen { + string apiProvDomId + string apiProvDomInfo + []APIProviderFunctionDetails apiProvFuncs +} +note right of APIProviderEnrolmentDetails::apiProvDomId + Id provided by CAPIF Core +end note +struct APIProviderFunctionDetails #palegreen { + string apiProvFuncId + string apiProvFuncInfo + ApiProviderFuncRole apiProviderFuncRole (required) + RegistrationInformation regInfo (required) +} +note right of APIProviderFunctionDetails::apiProvFuncId + Id provided by CAPIF Core +end note +note right of APIProviderFunctionDetails::apiProviderFuncRole + - AEF: API provider function is API Exposing Function. + - APF: API provider function is API Publishing Function. + - AMF: API Provider function is API Management Function. +end note +struct RegistrationInformation #palegreen { + string apiProvCert + atring apiProvPubKey (required) +} +APIProviderEnrolmentDetails::apiProvFuncs o-- APIProviderFunctionDetails +APIProviderFunctionDetails::regInfo o-- RegistrationInformation + +struct ServiceAPIDescription #lightblue { + string apiId + string apiName (required) + string description + []AefProfile aefProfiles +} +note bottom of ServiceAPIDescription + Id provided by CAPIF Core +end note +struct AefProfile #lightblue { + string aefId (required) + DataFormat dataFormat + string domainName + []InterfaceDescription interfaceDescriptions + Protocol protocol + []SecurityMethod securityMethods + []Version versions (required) +} +note left of AefProfile::dataFormat + - JSON: JavaScript Object Notation +end note +note left of AefProfile::protocol + - HTTP_1_1: HTTP version 1.1 + - HTTP_2: HTTP version 2 +end note +note left of AefProfile::securityMethods + - PSK: Security method 1 (Using TLS-PSK) + - PKI: Security method 2 (Using PKI) + - OAUTH: Security method 3 (TLS with OAuth token) +end note +note "From APIProviderFunctionDetails" as aefIdRel +APIProviderFunctionDetails::apiProvFuncId .. aefIdRel +aefIdRel .. AefProfile::aefId +struct InterfaceDescription #lightblue { + string ipv4Address + string ipv6Address + []Operation operations + []SecurityMethod securityMethods +} +note right of InterfaceDescription + Security methods supported by the interface, + it take precedence over the security methods + provided in AefProfile, for this specific interface. +end note +struct Version #lightblue { + string apiVersion + []Resource resources +} +note right of Version::resources + - REQUEST_RESPONSE + - SUBSCRIBE_NOTIFY +end note +ServiceAPIDescription::aefProfiles o-- AefProfile +AefProfile::interfaceDescriptions o-- InterfaceDescription +AefProfile::versions o-- Version + +struct APIInvokerEnrolmentDetails #coral { + string apiInvokerId + string apiInvokerInformation + APIList apiList + OnboardingInformation onboardingInformation +} +struct OnboardingInformation #coral { + string apiInvokerCertificate + string ApiInvokerPublicKey (required) + string onboardingSecret +} +note right of OnboardingInformation::onboardingSecret + Secret provided by CAPIF Core +end note +note right of APIInvokerEnrolmentDetails::apiInvokerId + Id provided by CAPIF Core +end note +APIInvokerEnrolmentDetails::apiList o-- ServiceAPIDescription : APIList +APIInvokerEnrolmentDetails::onboardingInformation o-- OnboardingInformation +@enduml diff --git a/capifcore/docs/diagrams/registerpoviderandpublishservice.plantuml b/capifcore/docs/diagrams/registerpoviderandpublishservice.plantuml new file mode 100644 index 0000000..1f8e6ac --- /dev/null +++ b/capifcore/docs/diagrams/registerpoviderandpublishservice.plantuml @@ -0,0 +1,34 @@ +@startuml Register Provider +actor rAppCatalogue +participant rAppManager +box "CAPIF Internal" +participant capifcore +participant providermanager +participant helmmanager +participant publishservice +end box + +rAppCatalogue->rAppManager: Start rApp, with rApp\n descriptor specifying which\n services to expose and consume +alt#paleGreen #paleGreen Provider Enrolment + rAppManager->capifcore: Register provider with\n APIProviderEnrolmentDetails + capifcore->providermanager:Store provider + capifcore->rAppManager: Provider with apfId and aefIds +end +alt#LightBlue #LightBlue Publish Service + rAppManager->capifcore: Publish services\n with ServiceAPIDescription + capifcore->providermanager: Check that AEFs are\n registered for provider + providermanager->capifcore: Ok + capifcore->helmmanager: Install and start chart + helmmanager->capifcore: Ok + capifcore->publishservice: Store published services + capifcore->rAppManager: ServiceAPIDescription with apiId +end +alt#coral #coral Register Invoker + rAppManager->capifcore: Register invoker with\n APIProviderFunctionDetails + capifcore->publishservice:Get available services for invoker + publishservice->capifcore: Services available for the given invoker + capifcore->rAppManager: Invoker with invokerId\n and avialable services +end +rAppManager->rAppCatalogue: Ok + +@enduml \ No newline at end of file