diff --git a/doc/OpenSlice_deployment_examples.md b/doc/OpenSlice_deployment_examples.md new file mode 100644 index 0000000000000000000000000000000000000000..1c21271e0479574aad0e62ffabf9510d9342e594 --- /dev/null +++ b/doc/OpenSlice_deployment_examples.md @@ -0,0 +1,74 @@ +# OpenSlice deployment examples + +Here are some examples from past and current efforts that use OpenSlice in various cases. + +## 5GinFIRE EU project (2018) + +* MultiVIM approach +* 9 Testbeds +* Automotive, Smart City, eHeath, PPDR, Media, SDR, Cloud +* 22 Experiment proposals from Verticals +* 100+ Users +* VxF catalog: + * 150+ ONBOARDED VxFs + * OSM TWO, FOUR, FIVE + * 50+ are public to be reused +* NSD catalog: + * 90+ ONBOARDED NSDs + * 30+ are public to be reused + * 500+ Deployment requests (orchestrations) performed + + +![OpenSlice usage](./images/deployment_example/Slide1.PNG) + +## 5G-VINNI EU project (2020) + +* Multi-vendor challenge – Commercial and opensource +* 5G services on multiple sites +* Introduction of TMFORUM models and APIs + +![OpenSlice usage](./images/deployment_example/Slide2.PNG) + +## 5GASP EU project (2021-2024) + +* Support a multi-site CI/CD testing automated DevOps cycle for network Applications +* Multiple NFVOs +* Introducing Service Test models +* Introducing the Product models for a network application marketplace + +![OpenSlice usage](./images/deployment_example/Slide3.PNG) + +## FIDAL EU project (2023-) + +* Support multi-site automated testing +* Multiple testbeds/ different APIs + +![OpenSlice usage](./images/deployment_example/Slide4.PNG) + +## ACROSS EU project (2023-) + +* Used as a cross-domain orchestrator +* Support the multi-domain orchestrator +* Support Zero-touch provisioning concepts + + +![OpenSlice usage](./images/deployment_example/Slide5.PNG) + +## INCODE EU project (2023-) + +* Support the provisioning of end-to-end domain services + +![OpenSlice usage](./images/deployment_example/Slide6.PNG) + + +## IMAGINEB5G EU project (2023-) + +* Support the provisioning of end-to-end domain services + +## ETSI ZSM PoC #2 + +* Automated Network Slice Scaling in Multi-Site Environments +* [See more](https://zsmwiki.etsi.org/index.php?title=PoC_2_Automated_Network_Slice_Scaling_in_Multi-Site_Environments) + + +![OpenSlice usage](./images/deployment_example/Slide7.PNG) diff --git a/doc/architecture/CRIDGE/CRIDGEforDevelopers.md b/doc/architecture/CRIDGE/CRIDGEforDevelopers.md new file mode 100644 index 0000000000000000000000000000000000000000..10cd9ac45c80ad5606af1fa18d611b753ad261fd --- /dev/null +++ b/doc/architecture/CRIDGE/CRIDGEforDevelopers.md @@ -0,0 +1,226 @@ + +# CRIDGE: A Service to manage Custom Resources in a Kubernetes Cluster + +## Intended Audience: OSL developers + + > Kubernetes is an orchestration system for automating software deployment, scaling, and management. One can interact though the Kubernetes API and it has a set of objects ready for use out of the box. Custom Resource Definitions (CRDs) is a way that allows to manage things other than Kubernetes itself and allows to create our own objects The use of CRDs makes the possibilities of Kubernetes management almost limitless. You can extend the base Kubernetes API with any object you like using CRDs. + + +CRIDGE is a service designed to create and manage Custom Resources (CRs) based on Custom Resource Definitions (CRDs) installed on a Kubernetes cluster. By leveraging the OpenSlice (OSL), CRIDGE enables seamless integration and orchestration within Kubernetes environments, utilizing Kubernetes APIs via the TMF APIs and models. Thus, more or less, OSL exposes Kubernetes APIs as TMF APIs and models. + + >By allowing the design and lifecycle management of services/resources that expose CRDs/CRs in a Kubernetes cluster via the TMF APIs, OSL can be used in many complex scenarios now involing resources from multiple domains. + + + +1. CRIDGE service allows OSL to: + - Create and manage Custom Resources (CRs) using installed CRDs on a target Kubernetes cluster. + - Facilitate complex orchestration scenarios by wrapping Kubernetes APIs as TMF APIs and models. + - Handles connectivity to a Kubernetes cluster and manages the lifecycle of CRDs + - Wraps the Kubernetes API, Receives and provides resources towards other OSL services via the service bus + +2. Enabling Loose Coupling and Orchestration + - Language Flexibility: Developers can write CRDs in any language and expose them via the Kubernetes APIs. OSL will reuse these CRDs, enhancing flexibility and integration capabilities. + - Familiar Deployment: Developers can create and deploy applications using familiar tools such as Helm charts, simplifying the process and reducing the learning curve. + +3. Ecosystem Reusability + - CRIDGE capitalizes on the extensive Kubernetes ecosystem, particularly focusing on operators (CRDs). + - Key repositories and hubs such as artifacthub.io and Operatorhub.io can be utilized for finding and deploying operators. + +4. Service Catalog Exposure and Deployment + + OSL can expose CRs in service catalogs, facilitating their deployment in complex scenarios. + These scenarios may include service bundles that involve multiple systems, such as RAN controllers or other Kubernetes clusters, providing a robust and versatile deployment framework. + + + + > Why the CRIDGE name? we wanted to build a service that maps TMF models to CRDs; a kind of a **CR**D to TMF br**idge**. Therefore CRIDGE was born + +# Approach + + > OSL in general is responible for exposing service specifications which are ready to be ordered and orchestrated, through tmforum Open APIs as defined in the OSL Service Spec Catalog. Usually for a service specification a corresponding (one or more) resource specification (resourceSpecificationReference) is registered in the OSL Resource Spec Catalog. + +The following image illustrates the approach. + +[![img01.png](img01.png)]() + +1. A CRD in a cluster will be mapped in TMF model as a Resource specification and therefore can be exposed as a service specification in a catalog +2. Service Orders can be created for this service specification. The OSL Orchestrator (OSOM) will manage the lifecycle of the Service Order. +3. OSOM creates a Resource in OSL Resource inventory and requests (via CRIDGE) a new Custom Resource (CR) in the target cluster + - The resource is created in a specific namespace (for example the UUID of the Service Order) + - A CR in a cluster will be mapped in TMF model as a Resource in the resource Inventory + - Other related resources created by the CRD Controller within the namespace are automatically created in OSL Resource Inventory under the same Service Order + + + +[![img02.png](img02.png)]() + + + +The provided image illustrates the architecture and workflow of the CRIDGE service, showing how it interacts with other components within a Kubernetes (K8s) cluster. Here is an explanation of the key components and flow in the diagram: + + - Other OSL Services: This box represents various OSL services such as Service Spec Catalogue, Resource Spec Catalogue, Service Inventory, Resource Inventory, and OSOM (OpenSlice Service Orchestration and Management). + - Service Bus: This is the communication layer that facilitates interaction between the CRIDGE service and other OSL services. + - CRIDGE: CRIDGE acts as a bridge that converts CRDs (Custom Resource Definitions) to TMF (TM Forum) APIs and models. It enables the creation and management of Custom Resources (CRs) in the Kubernetes cluster. + - K8s API: The Kubernetes API server, which is the central control point for managing the Kubernetes cluster. CRIDGE interacts with the K8s API to manage CRDs and CRs. + + > CRD (Custom Resource Definition): A CRD is a way to define custom resources in Kubernetes cluster-wise. It allows the extension of Kubernetes API to create and manage user-defined resources. Example : +``` + apiVersion: apiextensions.k8s.io/v1 + kind: CustomResourceDefinition + metadata: + name: myresource.example.com +``` + + - Namespaces: Kubernetes namespaces provide a way to partition resources within a cluster. The diagram shows that multiple namespaces (nsxx, nsyy, nsz) can be managed by CRIDGE. + + > CR (Custom Resource): A CR is an instance of a CRD. It represents the actual custom resource that is managed within the Kubernetes cluster. Example shown in different namespaces: +``` + apiVersion: example.com/v1 + kind: Myresource + metadata: + name: example_resource_1 +``` + +In a nutchell: + + - Various OSL services use the Service Bus to communicate with CRIDGE. + - CRIDGE converts requests towards Kubernetes API and vice-versa, facilitating the integration of custom resources with other OSL services. + - CRDs are defined and managed through the K8s API. The example CRD is named myresource.example.com. + - Deploying CRs in Namespaces: Custom resources defined by the CRD are created and managed within different namespaces in the Kubernetes cluster. Each namespace can have its own instances of the custom resources. + + > The example CRD myresource.example.com allows the creation of custom resources of type Myresource. + > Instances of Myresource are created in various namespaces, each with unique names like example_resource_1. + + +# Handling more than one clusters + +A CRIDGE service is usually responsible for managing one cluster. In the following diagram we show how it can be used for managing multiple clusters: + + +[![img03.png](img03.png)]() + +We assume that there is an OSL Management cluster that OSL is installed. CRIDGE is also installed there if we would like to manage resources in the same management cluster. + - Each CRIDGE service has for example its own configuration to connect to target cluster + - Each CRIDGE can be installed either in the managed cluster or at the remote clusters. Connectivity is handled via the service bus + - Important: Each CRIDGE has a different context and API endpoints. This is used to request CRDs on a different cluster + + + > A CRD has a globally unique name for example mycrd.example.com. So we need to somehow identify also the different cluster + + +# Awareness for CRDs and CRs in cluster + +> CRDs and CRs can appear (disappear) or change status at any time in a cluster. OSL Resource Inventory need to be aware of these events. + +The sync process is found in the code and explained by the following picture: + + + +[![img04.png](img04.png)]() + + WatcherService is executed when the cridge service application starts (see onApplicationEvent). First things: + +- KubernetesClientResource is a class that wraps fabric8’s KubernetesClient + - This fabric8 KubernetesClient is initialized from the kubeconf and default context of the machine that runs CRIDGE +- On CRIDGE Start up we try to register this cluster and context to OSL catalogs. + - See registerKubernetesClientInOSLResource method which registers the KubernetesContextDefinition in Resource Inventory as a LogicalResource via createOrUpdateResourceByNameCategoryVersion method +- After the creation(or update) of this cluster as a Resource in OSL we proceed to create SharedIndexInformers for CustomResourceDefinition objects +- In this way CRIDGE is always aware of all CRDs and their CRs in the cluster, even if a CRD or CR is added/updated/deleted in the K8S cluster outside of OSL(CRIDGE) +- The SharedIndexInformer events notify CRIDGE, which is always aware of all CRDs and their CRs in the cluster, even if a CRD or CR is added/updated/deleted in the K8S cluster outside of OSL(CRIDGE) + - NOTE: The ADD event is raised every time also we run CRIDGE. Therefore, on ADD we do the method to createORupdate resource specifications and resources +- On ADD event: + - The CRD is transformed to OSL Kubernetes domain model: method kubernetesClientResource.KubernetesCRD2OpensliceCRD + - Then the OSL Kubernetes domain model is: + - transformed to Resource Specification and is stored to catalog (see createOrUpdateResourceSpecByNameCategoryVersion) + - Transformed to Resource and is stored to catalog (see createOrUpdateResourceByNameCategoryVersion) + - Conceptually while a CRD is a new resource located in the Kubernetes cluster resource, it is transformed also as a Resource Specification (a high-level entity) which is ready to be reused as an entity to other scenarios. The same concept as in Kubernetes where a CRD is a definition ready to be used for instantiating resources of this CRD + - Then for this CRD a Watcher is added for all Resources of this Kind (fabric8’s GenericKubernetesResource entity) + - When we have a newly added/updated/deleted resource of a certain CRD the method updateGenericKubernetesResourceInOSLCatalog is called for this object (fabric8’s GenericKubernetesResource entity) + - We examine if the resource has label org.etsi.osl.resourceId + - This label is added by OSOM during service orders to correlate K8S requested resources with resources in inventory + - If the label exists, we update the resource by ID updateResourceById + - Else a resource is created in catalog + + +# Deployment of a new CR based on a CRD + + +[![img05.png](img05.png)]() + +- A message arrives to deploy a CR + - The call examines if this CRIDGE service can handle the request (based on context and masterURL) +- There are headers received and a crspec in json +- The crspec is unmarshaled as GenericKubernetesResource +- Headers are in format org.etsi.osl.* +- These headers are injected as labels + - (see later in orchestration) +- A namespace is created for this resource +- Watchers are created for this namespace for e.g. new secrets, config maps etc , so that they can be available back as resources to the Inventory of OSL (Note only Secrets for now are watched) + + +# Expose CRDs as Service Specifications in OpenSlice catalogs + +See [ExposingKubernetesResources](ExposingKubernetesResources.md) + + + + +# Service Orchestration and CRDs/CRs + +OSOM checks the presence of attribute _CR_SPEC at the RFS to make a request for a CR deployment + +- _CR_SPEC is a JSON or YAML string that is used for the request + - It is similar to what one will do with e.g. a kubectl apply + - There are tools to translate a yaml file to a json + +> LCM rules can be used to change attributes of this yaml/json file, before sending this for orchestration + +However, the following issue needs to be solved: ** How to map the CR lifecycle that is defined in the CRD with the TMF resource Lifecycle? ** + - For this We introduced the following characteristics: _CR_CHECK_FIELD, _CR_CHECKVAL_STANDBY, _CR_CHECKVAL_ALARM, _CR_CHECKVAL_AVAILABLE, _CR_CHECKVAL_RESERVED, _CR_CHECKVAL_UNKNOWN, _CR_CHECKVAL_SUSPENDED + +OSOM sends to CRIDGE a message with the following information: + +- currentContextCluster: current context of cluster +- clusterMasterURL: current master url of the cluster +- org.etsi.osl.serviceId: This is the related service id that the created resource has a reference +- org.etsi.osl.resourceId: This is the related resource id that the created CR will wrap and reference. +- org.etsi.osl.prefixName: we need to add a short prefix (default is cr) to various places. For example in K8s cannot start with a number +- org.etsi.osl.serviceOrderId: the related service order id of this deployment request +- org.etsi.osl.namespace: requested namespace name +- org.etsi.osl.statusCheckFieldName: The name of the field that is needed to be monitored in order to monitor the status of the service and translate it to TMF resource statys (RESERVED AVAILABLE, etc) +- org.etsi.osl.statusCheckValueStandby: The CR specific value (of the CheckFieldName) that needs to me mapped to the TMF resource state STANDBY (see org.etsi.osl.tmf.ri639.model.ResourceStatusType) +- org.etsi.osl.statusCheckValueAlarm: The CR specific value (of the CheckFieldName) that needs to me mapped to the TMF resource state ALARMS (see org.etsi.osl.tmf.ri639.model.ResourceStatusType) +- org.etsi.osl.statusCheckValueAvailable: The CR specific value (of the CheckFieldName) that needs to me mapped to the TMF resource state AVAILABLE (see org.etsi.osl.tmf.ri639.model.ResourceStatusType) +- org.etsi.osl.statusCheckValueReserved: The CR specific value (of the CheckFieldName) that needs to me mapped to the TMF resource state RESERVED (see org.etsi.osl.tmf.ri639.model.ResourceStatusType) +- org.etsi.osl.statusCheckValueUnknown: The CR specific value (of the CheckFieldName) that needs to me mapped to the TMF resource state UNKNOWN (see org.etsi.osl.tmf.ri639.model.ResourceStatusType) +- org.etsi.osl.statusCheckValueSuspended: The CR specific value (of the CheckFieldName) that needs to me mapped to the TMF resource state SUSPENDED (see org.etsi.osl.tmf.ri639.model.ResourceStatusType) + +- Parameters: + - aService reference to the service that the resource and the CR belongs to + - resourceCR reference the equivalent resource in TMF repo of the target CR. One to one mapping + - orderId related service order ID + - startDate start date of the deployment (not used currently) + - endDate end date of the deployment (not used currently) + - _CR_SPEC the spec that is sent to cridge (in json) +- Returns: + - a string response from cridge. It might return "OK" if everything is ok. "SEE OTHER" if there are multiple CRIDGEs then some other cridge will handle the request for the equivalent cluster. Any other response is handled as error + + +- CRIDGE receives the message and creates according to the labels the necessary CR +- It monitors the created resource(s) in namespace (see the Sequence Diagram in previous images) +- It monitors and tries to figure out and map the Status of the CR to the TMF Status according to the provided org.etsi.osl.statusCheck* labels +- It sends to the message bus the current resource for creation or update to the TMF service inventory + + +--- + +## Probe further + + - See examples of exposing operators via OpenSlice: + - [Exposing Kubernetes Operators as a Service : Offering "Calculator as a Service" through OpenSlice](../../service_design/examples/ExposingCRDs_aaS_Example_Calculator/ExposingCRDs_aaS_Example_Calculator.md) + + + + + + diff --git a/doc/architecture/CRIDGE/img01.png b/doc/architecture/CRIDGE/img01.png new file mode 100644 index 0000000000000000000000000000000000000000..d9f6f73dd21ff94572fd411c68e31a2915426f70 Binary files /dev/null and b/doc/architecture/CRIDGE/img01.png differ diff --git a/doc/architecture/CRIDGE/img02.png b/doc/architecture/CRIDGE/img02.png new file mode 100644 index 0000000000000000000000000000000000000000..fb546ad61cce1ce5c9cc593507f816ef64c7bcc5 Binary files /dev/null and b/doc/architecture/CRIDGE/img02.png differ diff --git a/doc/architecture/CRIDGE/img03.png b/doc/architecture/CRIDGE/img03.png new file mode 100644 index 0000000000000000000000000000000000000000..79d0d2a208ca3c63489264a87d4a155d44d12cc4 Binary files /dev/null and b/doc/architecture/CRIDGE/img03.png differ diff --git a/doc/architecture/CRIDGE/img04.png b/doc/architecture/CRIDGE/img04.png new file mode 100644 index 0000000000000000000000000000000000000000..233831d1bb986c92432fdaff602db44fc2c0df48 Binary files /dev/null and b/doc/architecture/CRIDGE/img04.png differ diff --git a/doc/architecture/CRIDGE/img05.png b/doc/architecture/CRIDGE/img05.png new file mode 100644 index 0000000000000000000000000000000000000000..3b05561502893694d3d72d12cbbfc154786da853 Binary files /dev/null and b/doc/architecture/CRIDGE/img05.png differ diff --git a/doc/architecture/nfvweb.md b/doc/architecture/nfvweb.md deleted file mode 100644 index b96dee34a9662e14f4c5eb3f41f507817686b094..0000000000000000000000000000000000000000 --- a/doc/architecture/nfvweb.md +++ /dev/null @@ -1,11 +0,0 @@ -# Openslice NFV Web Portal - -The [NFV Web Portal](http://portal.openslice.io/nfvportal) offers a domain-specific UI to manage NFV Services. - -Indicatively, the portal can be used to: -- Register new a new MANO provider (e.g. OSM) -- Synchronize the onboarded VNF/NS packages, and the VIMs of the registered MANO provider -- Onboard/Delete VNF/NS packages on specific MANO provider -- Deploy a NS to a target MANO provider - -More information can be found at [NFV Services](../nfvcatalogs.md). \ No newline at end of file diff --git a/doc/config_intro.md b/doc/config_intro.md new file mode 100644 index 0000000000000000000000000000000000000000..c3549c1554349b33b949f361341d15cbb7bbd500 --- /dev/null +++ b/doc/config_intro.md @@ -0,0 +1,9 @@ +# Configuring and managing OpenSlice + +## Intended Audience: OpenSlice administrators + +This section provides information on how to configure and manage different aspect of OpenSlice while in operation. For example: + +* Manage user roles and access in Keycloak +* Configure/Manage NFVOs +* Advanced configuration scenarios \ No newline at end of file diff --git a/doc/deployment.md b/doc/deployment.md index 48aa4950f66ab2832035d882083496724d291e2e..e2a495a67146ca9f1e31d7009bb2024f0cd98734 100644 --- a/doc/deployment.md +++ b/doc/deployment.md @@ -1,619 +1,11 @@ -## Requirements +# OpenSlice Deployment -### Hardware requirements: +This section is meant to guide the user through the installation of OpenSlice. +## Intended Audience: OpenSlice administrators -| **Minimum Hardware Requirements** | **Recomended Hardware Requirements** | -| --------------------------------- | ------------------------------------ | -| 4 CPU cores | 8 CPU cores | -| 8 GB RAM | 16 GB RAM | -| 20 GB storage | 40 GB storage | +Following, you may thorough guides depending on the installation type of your choice: -### Software Requirements: +- [Installing via Docker Compose guide](./deploymentCompose.md) +- [Installing via Kubernetes guide](./deploymentK8s.md) -* Docker (Docker Compose installation) -* Kubernetes (Kubernetes installation - experimental) - - -## Preparing the environment - -> See the [Kubernetes section](#Kubernetes-installation), if you would like to deploy OpenSlice in a Kubernetes cluster. - - -### 1. Backup your previous database if necessary: -```bash -sudo docker exec amysql /usr/bin/mysqldump -u root --password=letmein ostmfdb > backup_ostmfdb.sql -``` -### 2. Install docker - -> Since July 2023 Docker Compose V1 stopped receiving updates. OpenSlice fully reverted to Compose V2, which is integrated in the Docker installation. - -### 3. Configure containers to properly resolve the DNS of your domain (optional) - -``` -sudo nano /etc/docker/daemon.json -``` - -and add: - -``` -{ - "dns": ["8.8.8.8", "8.8.4.4"] -} -``` -After editing daemon.json restart docker daemon for the changes to take place - -```bash -sudo systemctl restart docker -``` - -## Downloading the project - -### 1. Create a new folder to download the project - -```bash -mkdir openslice -``` -```bash -cd openslice -``` - -### 2. Download the deployment script - -Download the deployment / environment preparation script - -```bash -wget https://labs.etsi.org/rep/osl/code/org.etsi.osl.main/-/raw/main/compose/deploy.sh -``` -Make it executable -```bash -sudo chmod +x deploy.sh -``` - -### 3. Run the deployment script - -OpenSlice is a multi repo project. This script selects the same branch for all repositories of the project to pull from. - -After that it builds the respective jar files locally and installs all the npm packages needed for the UI. - -If you run the script without selecting a branch the the main branch is going to be selected. - -We recommend: - -* main branch for the most stable experience and -* develop branch for an experience with the latest features (for develop branch installation, it is strongly advisable that you may as well follow the [develop documentation](https://osl.etsi.org/documentation/develop/deployment/)) - -```bash -sudo ./deploy.sh main #[or replace main with other branch name] -``` - -> **We recommend running the deploy.sh script with root permissions! In other case, some directories may not be accessible by the project building tools and hinder the smooth installation.** - - -## Configure docker-compose services - -### 1. Create configuration specific Docker Compose file from the template - -```bash -cd org.etsi.osl.main/compose/ -``` -```bash -sudo cp docker-compose.yaml.configure docker-compose.yaml -``` -### 2. Configure mysql-portal container *(optional)* - -1. In folder `org.etsi.osl.main/compose/mysql-init` edit the file `01-databases.sql`. -2. In the `org.etsi.osl.main/compose/docker-compose.yaml` edit the credentials of the users that services use to connect to the databases, if you wish. - * portaluser (default is 12345) and - * keycloak (default is password) - - -### 3. Configure keycloak container *(optional)* - -1. If you made changes to keycloak's mysql credentials: - - In folder `org.etsi.osl.main/compose/` edit the file `docker-compose.yaml`. - -``` -DB_DATABASE: keycloak -DB_USER: keycloak -DB_PASSWORD: password -``` - -2. If you want to change the keycloak admin password: - - In folder `org.etsi.osl.main/compose/` edit the file `docker-compose.yaml` - -``` -KEYCLOAK_PASSWORD: Pa55w0rd -``` - -### 4. Configure bugzilla container *(optional)* - -If you want to utilise the Bugzilla connector: - -In folder `org.etsi.osl.main/compose/` edit the file `docker-compose.yaml` - -``` -SPRING_APPLICATION_JSON: '{ - "spring.activemq.brokerUrl": "tcp://anartemis:61616?jms.watchTopicAdvisories=false", - "spring.activemq.user": "artemis", - "spring.activemq.password": "artemis", - "bugzillaurl":"", - "bugzillakey":"", - "main_operations_product":"" -}' -``` - -And add the provided Bugzilla installation information: - -``` -"bugzillaurl":"bugzillaurl.xx:443/bugzilla/", -"bugzillakey":"exampleKeyeqNNwxBlgxZgMEIne0Oeq0Bz", -"main_operations_product":"Main Site Operations" // this is the default product to issue tickets -``` - -Bugzilla should have the following components under the specified product: - -* NSD Deployment Request: Component used to schedule deployment req -* Onboarding: Issues related to VNF/NSD Onboarding -* Operations Support: Default component for operations support -* Validation: Use to track validation processes of VNFs and NSDs -* VPN Credentials/Access: Used for requesting VPN Credentials/Access - -Also in the 'Main Site Operations' product, a version named 'unspecified' must be created. - -### 5. Configure osportalapi container (NFV services) *(conditional)* - -Change the respective fields: - -- If you made changes to mysql and keycloak credentials. -- If you want to change logging level (TRACE / DEBUG / INFO / WARN / ERROR). - -> ***If you are using a non-local domain, replace everywhere the http://keycloak:8080 with the respective {{protocol://domain.name}}, as well as "spring.portal.main.domain" property.*** - -In folder `org.etsi.osl.main/compose/` edit the file `docker-compose.yaml` - -``` -SPRING_APPLICATION_JSON: '{ - "spring.datasource.username":"root", - "spring.datasource.password":"letmein", - "spring-addons.issuers[0].uri": "http://keycloak:8080/auth/realms/openslice", - "spring.security.oauth2.resourceserver.jwt.issuer-uri": "http://keycloak:8080/auth/realms/openslice", - "springdoc.oAuthFlow.authorizationUrl": "http://keycloak:8080/auth/realms/openslice/protocol/openid-connect/auth", - "springdoc.oAuthFlow.tokenUrl": "http://keycloak:8080/auth/realms/openslice/protocol/openid-connect/token", - "spring.portal.main.domain": "http://localhost", - "logging.level.org.springframework" : "INFO" -}' -``` - -### 6. osscapi container (TMF API service) *(conditional)* - -Change the respective fields: - -- If you made changes to mysql and keycloak credentials. -- If you want to change logging level (TRACE / DEBUG / INFO / WARN / ERROR). - -> **If you are using a non-local domain, replace everywhere the http://keycloak:8080 with the respective {{protocol://domain.name}}.** - -In folder `org.etsi.osl.main/compose/` edit the file `docker-compose.yaml` - -``` -SPRING_APPLICATION_JSON: '{ - "spring.datasource.username":"root", - "spring.datasource.password":"letmein", - "spring-addons.issuers[0].uri": "http://keycloak:8080/auth/realms/openslice", - "spring.security.oauth2.resourceserver.jwt.issuer-uri": "http://keycloak:8080/auth/realms/openslice", - "springdoc.oAuthFlow.authorizationUrl": "http://keycloak:8080/auth/realms/openslice/protocol/openid-connect/auth", - "springdoc.oAuthFlow.tokenUrl": "http://keycloak:8080/auth/realms/openslice/protocol/openid-connect/token", - "logging.level.org.springframework" : "INFO" -}' -``` - -## Configure nginx - -In folder `org.etsi.osl.main/compose/nginx` create a configuration specific `nginx.conf` file. - - -```bash -cd org.etsi.osl.main/compose/nginx/ -``` - -```bash -sudo cp nginx.conf.default nginx.conf -``` - -If needed, in the nginx.conf file, edit the server_name for an non-local deployment. - - - -## Configure Web UI - -In folder `org.etsi.osl.portal.web/src/js/` create a configuration specific `config.js` file. - -```bash -cd org.etsi.osl.portal.web/src/js -``` - -```bash -sudo cp config.js.default config.js -``` - -Edit the `config.js` file with the information of your domain - - -``` -{ - TITLE: "OpenSlice by ETSI", - WIKI: "https://openslice.readthedocs.io/en/stable/", - BUGZILLA: "ROOTURL/bugzilla/", - STATUS: "ROOTURL/status/", - APIURL: "http://localost:13000", - WEBURL: "ROOTURL/nfvportal", - APIOAUTHURL: "ROOTURL/auth/realms/openslice", - APITMFURL: "ROOTURL/tmf-api/serviceCatalogManagement/v4" -} -``` - -## Configure TMF Web UI - -In the folder `org.etsi.osl.tmf.web/src/assets/config` there are 3 files available for configuration: - -* config.prod.json (Basic information + API configuration) -* theming.scss (CSS color palette theming) -* config.theming.json (HTML configuration - Logo, Favicon, Footer) - - -The first 2 files above (i.e. config.prod.json, theming.scss) are essential for the successful deployment of OpenSlice, thus created automatically during the initial deployment at `org.etsi.osl.tmf.web/src/assets/config` directory as a copy of the default ones from the remote repository. - -Ensure that you check the `config.prod.json` file and readjust to your deployment if needed. - -```bash -# Starting from the root project directory -cd org.etsi.osl.tmf.web/src/assets/config -``` -```bash -sudo cp config.theming.default.json config.theming.json -``` - -E.g. Edit "TITLE" or "WIKI" property with your domain title -``` -{ - TITLE: "OpenSlice by ETSI", - WIKI: "https://osl.etsi.org/documentation/latest/deployment/", -} -``` - -> The {BASEURL} placeholder in the file automatically detects the Origin (Protocol://Domain:Port) of the deployment and applies it to every respective property. E.g. If you are attempting a local deployment of Openslice, then {BASEURL} is automatically translated to "http://localhost". Similarly, you may use {BASEURL} to translate to a public deployment configuration, e.g. "https://portal.openslice.io". - -If further customization, apart from the default provided, is needed for branding (Logo, Footer) then config.theming.json needs to be created in io.openslice.tmf.web/src/assets/config directory, as follows: - -```bash -# Starting from the root project directory -cd org.etsi.osl.tmf.web/src/assets/config -``` - -```bash -sudo cp config.theming.default.json config.theming.json -``` - -> ***IMPORTANT NOTE:*** -If you want to apply changes to the JSON configuration files without the need to rebuild the application, you have to apply the changes at the `org.etsi.osl.tmf.web/dist/io-openslice-portal-web/assets/config` directory. Although, it is mandatory to also apply these changes to the `org.etsi.osl.tmf.web/src/assets/config` for persistancy, as after any future rebuild of OpenSlice the `/dist` directory is being overwritten along with its contents. The OpenSlice team strongly recommends to always apply your changes to the TMF web UI configuration files at `org.etsi.osl.tmf.web/src/assets/config` and rebuild the application. - -## Deploy OpenSlice via Docker Compose - -After configuring the services, and editing the docker compose file accordingly, the docker compose instantiation command can be performed. - -```bash -# Starting from the root project directory -cd org.etsi.osl.main/compose/ -``` - -```bash -sudo docker compose --profile prod down;sudo docker compose --profile prod up -d --build -``` - -> Depending on your machine, this process might take time. if for any reason the deployment fails during first time, please rerun the above before any further measures. - - -## Validating deployments and container monitoring - -You can monitor containers' status with portainer at port 9000 (http://your-ip:9000). - -Initially, you may monitor the local machine at portainer. - -Please check that all containers are in running state. - - -## Post installation steps - -After the successful deployment of OpenSlice, to ensure the E2E user experience, **this section is mandatory**. It contains crucial configuration in regard of authentication and user creation. - -### Configure Keycloak server - -The Keycloack server is managing authentication and running on a container at port 8080. It is also proxied to your host via nginx under http://localhost/auth. - -- Navigate to http://domain.com/auth/ or https://domain.com/auth/, (http://ipaddress:8080/auth/ or https://ipaddress:8443/auth/ which are directly accessible without proxy) - -- Navigate to Administration Console - -- Login with the credentials from section [Configure keycloak container](#3-configure-keycloak-container-optional). Default values are: - - user: admin and - - password: KEYCLOAK_PASSWORD - -> if you are running in HTTP you will get a message: HTTPS required. - -To resolve this issue when running in HTTP: - -- Select the master realm from top left corner -- Go to login Tab and select "Require SSL": None -- Repeat for realm Openslice - - -> If you are running in HTTPS, then "Require SSL" can be left unchanged to external requests. - -#### 1. Configure redirects - -Navigate to realm Openslice > client > osapiWebClientId and change the Root URL to your domain. - -Also, insert your domain, e.g. http://example.org/*, at: -* Valid Redirect URIs -* Web Origins - -#### 2. Configure email - -Keycloak allows new users to register. Subsequently, this will also allow new users to register to the OpenSlice portal. - -On Tab Login > check User registration, Verify email, Forgot password etc. - -Also, enter the details on Realm > Email > Enable Authentication. - -#### 3. Add an OpenSlice admin user - -This step is mandatory so as to access the OpenSlice Web UI. To add an OpenSlice admin user you must: -- Navigate to manage/users and add an OpenSlice admin user, e.g. username=admin. -- Set a password -- Navigate to Role Mappings and add ADMIN and MENTOR to Assigned Roles. - -> That user is different from the Keycloak admin user. It is required to login and browse the OpenSlice Web UI. The Roles ADMIN and MENTOR guarantee full access through the Openslice UI, thus such a user is always required. - -### Keycloak at localhost - -> **This is an important step if you run Keycloak on localhost!** - -1 - Edit your Hosts File, adding the line below - -```127.0.0.1 keycloak``` - -Hosts File Location: - - - In Linux/Unix, the file's location is at /etc/hosts - - - In Windows, its location is at c:\Windows\System32\Drivers\etc\hosts - -2 - Replace http://localhost/auth/ with http://keycloak:8080/auth/ in your Keycloak config for AngularJS and Angular (see examples below). - - -> Explanation - -Nginx uses the http://keycloak:8080 URL, which is accessible via the internal docker system's network. -The Front-end (TS/Angular) shall also use the http://keycloak:8080. -This way, you will not get the invalid token error, as the API is acquiring the token from http://keycloak:8080 (internally) and the Front-end is getting verified by an issuer at the same URL, as well. - - - -2.1 - For the Angular configuration (TMF portal UI), navigate to org.etsi.osl.tmf.web/src/assets/config and edit config.prod.json - -```bash -# Starting from the root project directory -cd org.etsi.osl.tmf.web/src/assets/config -``` - -```bash -nano config.prod.json -``` - -After editing it should look like the example bellow: - -```yaml -{ - "TITLE": "OpenSlice by ETSI", - "PORTALVERSION":"2023-Q3 1.2.0-SNAPSHOT", - "WIKI": "https://openslice.readthedocs.io/en/stable/", - "BUGZILLA": "{BASEURL}/bugzilla/", - "STATUS": "http://status.localhost/", - "WEBURL": "{BASEURL}", - "PORTAL_REPO_APIURL": "{BASEURL}/osapi", - "ASSURANCE_SERVICE_MGMT_APIURL": "{BASEURL}/oas-api", - "APITMFURL": "{BASEURL}/tmf-api", - "OAUTH_CONFIG" : { - "issuer": "http://keycloak:8080/auth/realms/openslice", - "loginUrl": "http://keycloak:8080/auth/realms/openslice/protocol/openid-connect/auth", - "tokenEndpoint": "http://keycloak:8080/auth/realms/openslice/protocol/openid-connect/token", - "userinfoEndpoint": "http://keycloak:8080/auth/realms/openslice/protocol/openid-connect/userinfo", - "redirectUri": "{BASEURL}/redirect", - "logoutUrl": "http://keycloak:8080/auth/realms/openslice/protocol/openid-connect/logout", - "postLogoutRedirectUri": "{BASEURL}", - - "responseType": "code", - "oidc": false, - "clientId": "osapiWebClientId", - "dummyClientSecret": "secret", - - "requireHttps": false, - "useHttpBasicAuth": true, - clearHashAfterLogin": false, - - "showDebugInformation": true - } -} -``` - -> Note the difference in changing {BASEURL} -> http://keycloak:8080 - -> If you want the changes to take place immediately without rebuilding the project, then repeat the process for org.etsi.osl.tmf.web/dist/org.etsi.osl.tmf.web/assets/config/config.prod.json - -2.2 - For the AngularJS configuration (NVF portal UI), navigate to org.etsi.osl.portal.web/src/js and edit config.js - -```bash -# Starting from the root project directory -cd org.etsi.osl.portal.web/src/js -``` - -```bash -nano config.js -``` - -after editing it should look like the example bellow: - -``` -var appConfig = angular.module('portalwebapp.config',[]); - - -appConfig.factory('APIEndPointService', function() { - return { - TITLE: "OpenSlice by ETSI", - WIKI: "https://openslice.readthedocs.io/en/stable/", - BUGZILLA: "ROOTURL/bugzilla/", - STATUS: "ROOTURL/status/", - APIURL: "http://localost:13000", - WEBURL: "ROOTURL/nfvportal", - APIOAUTHURL: "ROOTURL/auth/realms/openslice", - APITMFURL: "ROOTURL/tmf-api/serviceCatalogManagement/v4" - }; -}); -``` - -> Note the difference in "APIOAUTHURL" property - - -### NFV Orchestrator Configuration - -After successfully deploying and configuring OpenSlice, you may configure its environment (e.g. the NFVO) that will facilitate the deployment of NFV artifacts. - -See [NFV Orchestrator Configuration](./nfvoconfig.md). - - -
- -## Kubernetes installation - -Openslice can be installed in a Kubernetes cluster. - -**This is a work in progress, and should be used for stable deployments!**. - -Please reference "develop" tagged documentation for any latest progress. - -The related scripts are inside the kubernetes folder. Follow these steps along the lines. You need to configure the ingress properly depending on how you want to expose Openslice. - -1 - Create an openslice namespace - -```bash -kubectl create namespace openslice -``` - -2 - Apply or create an ingress. Ingress exposes HTTP and HTTPS routes from outside the cluster to services within the cluster. Traffic routing is controlled by rules defined on the Ingress resource. -An Ingress may be configured to give Services externally-reachable URLs, load balance traffic, terminate SSL / TLS, and offer name-based virtual hosting. An Ingress controller is responsible for fulfilling the Ingress, usually with a load balancer, though it may also configure your edge router or additional frontends to help handle the traffic. You must have an Ingress controller to satisfy an Ingress. -You may need to deploy an Ingress controller such as ingress-nginx. - -You can also adapt it to connect to public cloud load balancers depending on your needs. - -The following will expose an ingress resource from one of your a k8s nodes on port 80. - -```bash - kubectl apply -f openslice-ingress.yaml -``` - - -Finding the ingress IP: - - -```bash - -kubectl describe -f openslice-ingress.yaml - - -Name: openslice-ingress -Namespace: openslice -Address: 10.10.10.35 -Default backend: default-http-backend:80 () -Rules: - Host Path Backends - ---- ---- -------- - * - /services tmfweb:80 () - /tmf-api osscapi:13082 () - /auth keycloak:8080 () - /osapi osportalapi:13000 () - / portalweb:80 () -Annotations: kubernetes.io/ingress.class: nginx -Events: - Type Reason Age From Message - ---- ------ ---- ---- ------- - Normal Sync 9m29s (x2 over 9m58s) nginx-ingress-controller Scheduled for sync - -``` - -From the above example, our exposed ingress is at Address: 10.10.10.35 - -3 - We need to configure the expose address and deploy openslice (IP or URL e.g. http://myopenslice.xxx) - -```bash -./k8sdeploy.sh 10.10.10.35 -``` - - -4 - Check the status of Openslice in the cluster. Should be similar to the following: - -```bash - -kubectl get pods --namespace=openslice -o wide - -NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES -activemq-59d4bfdb4b-bvjqr 1/1 Running 0 109s 192.168.43.97 kc-2 -bugzilla-client-7dd7cb47cb-8qb8m 1/1 Running 0 100s 192.168.12.114 kc-3 -centrallog-95bbf7867-k8fpt 1/1 Running 0 100s 192.168.12.107 kc-3 -consul-b5dd76b76-64dzk 1/1 Running 0 107s 192.168.43.90 kc-2 -keycloak-7c5b6bbc95-k2qfl 1/1 Running 0 105s 192.168.12.106 kc-3 -manoclient-95f68f4c9-c9t6r 1/1 Running 0 104s 192.168.12.113 kc-3 -mysql-portal-0 1/1 Running 0 107s 192.168.43.99 kc-2 -osom-6d548cf555-q8ptj 1/1 Running 0 104s 192.168.43.93 kc-2 -osportalapi-5fff744db8-5g4zs 1/1 Running 0 103s 192.168.43.98 kc-2 -osscapi-6d68b54d97-jn8tz 0/1 Running 0 102s 192.168.12.104 kc-3 -portalweb-8469d57df4-94tfj 1/1 Running 0 101s 192.168.48.44 kc-nfs -tmfweb-868f7bb9c5-x4lfh 1/1 Running 0 102s 192.168.48.43 kc-nfs -``` -```bash -kubectl get deployments --namespace=openslice -o wide - -NAME READY UP-TO-DATE AVAILABLE AGE CONTAINERS IMAGES SELECTOR -activemq 1/1 1 1 2m15s anactivemq webcenter/activemq:5.14.3 org.etsi.osl.service=activemq -bugzilla-client 1/1 1 1 2m6s bugzilla-client openslice/org.etsi.osl.bugzilla:latest org.etsi.osl.service=bugzilla-client -centrallog 1/1 1 1 2m6s centrallog openslice/org.etsi.osl.centrallog.service org.etsi.osl.service=centrallog -consul 1/1 1 1 2m13s aconsul consul org.etsi.osl.service=consul -keycloak 1/1 1 1 2m11s keycloak quay.io/keycloak/keycloak:11.0.3 org.etsi.osl.service=keycloak -manoclient 1/1 1 1 2m10s manoclient openslice/org.etsi.osl.mano:latest org.etsi.osl.service=manoclient -osom 1/1 1 1 2m10s openslice-osom openslice/org.etsi.osl.osom:latest org.etsi.osl.service=osom -osportalapi 1/1 1 1 2m9s openslice-portalapi openslice/org.etsi.osl.portal.api:latest org.etsi.osl.service=osportalapi -osscapi 1/1 1 1 2m8s openslice-scapi openslice/org.etsi.osl.tmf.api:latest org.etsi.osl.service=osscapi -portalweb 1/1 1 1 2m7s openslice-portalweb openslice/org.etsi.osl.portal.web:latest org.etsi.osl.service=portalweb -tmfweb 1/1 1 1 2m8s openslice-tmfweb openslice/org.etsi.osl.tmf.web:latest org.etsi.osl.service=tmfweb -``` -```bash -kubectl get services --namespace=openslice -o wide - -NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE SELECTOR -activemq ClusterIP 10.111.160.120 8161/TCP,61616/TCP 2m22s org.etsi.osl.service=activemq -bugzilla-client ClusterIP 10.101.43.28 13010/TCP 2m14s org.etsi.osl.service=bugzilla-client -centrallog ClusterIP 10.109.15.151 13013/TCP 2m14s org.etsi.osl.service=centrallog -consul ClusterIP 10.101.103.240 8500/TCP,8600/TCP 2m21s org.etsi.osl.service=consul -keycloak ClusterIP 10.110.216.62 8080/TCP,8443/TCP 2m19s org.etsi.osl.service=keycloak -manoclient ClusterIP 10.108.112.84 13011/TCP 2m18s org.etsi.osl.service=manoclient -mysql-portal ClusterIP None 3306/TCP 2m19s org.etsi.osl.service=mysql-portal -osom ClusterIP 10.105.173.85 13100/TCP 2m18s org.etsi.osl.service=osom -osportalapi ClusterIP 10.104.121.164 13000/TCP 2m17s org.etsi.osl.service=osportalapi -osscapi ClusterIP 10.108.6.161 13082/TCP 2m16s org.etsi.osl.service=osscapi -portalweb ClusterIP 10.97.126.98 80/TCP 2m15s org.etsi.osl.service=portalweb -tmfweb ClusterIP 10.98.56.82 80/TCP 2m15s org.etsi.osl.service=tmfweb - -``` \ No newline at end of file diff --git a/doc/deploymentCompose.md b/doc/deploymentCompose.md new file mode 100644 index 0000000000000000000000000000000000000000..09d9dc3b0f3f960c6a8f2c71a8387428ce9dd6c3 --- /dev/null +++ b/doc/deploymentCompose.md @@ -0,0 +1,497 @@ +# OpenSlice Deployment Guide with Docker Compose + +## Intended Audience: OpenSlice administrators + +## Requirements + +### Hardware requirements: + + +| **Minimum Hardware Requirements** | **Recomended Hardware Requirements** | +| --------------------------------- | ------------------------------------ | +| 4 CPU cores | 8 CPU cores | +| 8 GB RAM | 16 GB RAM | +| 30 GB storage | 50 GB storage | + +### Software Requirements: + +* **Docker:** A running environment for Docker Compose services + +## Preparing the environment + +### 1. Backup your previous database if necessary: +```bash +sudo docker exec amysql /usr/bin/mysqldump -u root --password=letmein ostmfdb > backup_ostmfdb.sql +``` +### 2. Install docker + +> Since July 2023 Docker Compose V1 stopped receiving updates. OpenSlice fully reverted to Compose V2, which is integrated in the Docker installation. + +### 3. Configure containers to properly resolve the DNS of your domain (optional) + +``` +sudo nano /etc/docker/daemon.json +``` + +and add: + +``` +{ + "dns": ["8.8.8.8", "8.8.4.4"] +} +``` +After editing daemon.json restart docker daemon for the changes to take place + +```bash +sudo systemctl restart docker +``` + +## Downloading the project + +### 1. Create a new folder to download the project + +```bash +mkdir openslice +``` +```bash +cd openslice +``` + +### 2. Download the deployment script + +Download the deployment / environment preparation script + +```bash +wget https://labs.etsi.org/rep/osl/code/org.etsi.osl.main/-/raw/develop/compose/deploy.sh +``` +Make it executable +```bash +sudo chmod +x deploy.sh +``` + +### 3. Run the deployment script + +OpenSlice is a multi repo project. This script selects the same branch for all repositories of the project to pull from. + +After that it builds the respective jar files locally and installs all the npm packages needed for the UI. + +If you run the script without selecting a branch the the main branch is going to be selected. + +We recommend: + +* main branch for the most stable experience and +* develop branch for an experience with the latest features (for develop branch installation, it is strongly advisable that you may as well follow the [develop documentation](https://osl.etsi.org/documentation/develop/deployment/)) + +```bash +sudo ./deploy.sh develop #[or replace main with other branch name] +``` + +> **We recommend running the deploy.sh script with root permissions! In other case, some directories may not be accessible by the project building tools and hinder the smooth installation.** + + +## Configure Docker Compose services + +### 1. Create configuration specific Docker Compose file from the template + +```bash +cd org.etsi.osl.main/compose/ +``` +```bash +sudo cp docker-compose.yaml.configure docker-compose.yaml +``` +### 2. Configure mysql-portal container *(optional)* + +1. In folder `org.etsi.osl.main/compose/mysql-init` edit the file `01-databases.sql`. +2. In the `org.etsi.osl.main/compose/docker-compose.yaml` edit the credentials of the users that services use to connect to the databases, if you wish. + * portaluser (default is 12345) and + * keycloak (default is password) + + +### 3. Configure keycloak container *(optional)* + +1. If you made changes to keycloak's mysql credentials: + + In folder `org.etsi.osl.main/compose/` edit the file `docker-compose.yaml`. + +``` +DB_DATABASE: keycloak +DB_USER: keycloak +DB_PASSWORD: password +``` + +2. If you want to change the keycloak admin password: + + In folder `org.etsi.osl.main/compose/` edit the file `docker-compose.yaml` + +``` +KEYCLOAK_PASSWORD: Pa55w0rd +``` + +### 4. Configure bugzilla container *(optional)* + +If you want to utilise the Bugzilla connector: + +In folder `org.etsi.osl.main/compose/` edit the file `docker-compose.yaml` + +``` +SPRING_APPLICATION_JSON: '{ + "spring.activemq.brokerUrl": "tcp://anartemis:61616?jms.watchTopicAdvisories=false", + "spring.activemq.user": "artemis", + "spring.activemq.password": "artemis", + "bugzillaurl":"", + "bugzillakey":"", + "main_operations_product":"" +}' +``` + +And add the provided Bugzilla installation information: + +``` +"bugzillaurl":"bugzillaurl.xx:443/bugzilla/", +"bugzillakey":"exampleKeyeqNNwxBlgxZgMEIne0Oeq0Bz", +"main_operations_product":"Main Site Operations" // this is the default product to issue tickets +``` + +Bugzilla should have the following components under the specified product: + +* NSD Deployment Request: Component used to schedule deployment req +* Onboarding: Issues related to VNF/NSD Onboarding +* Operations Support: Default component for operations support +* Validation: Use to track validation processes of VNFs and NSDs +* VPN Credentials/Access: Used for requesting VPN Credentials/Access + +Also in the 'Main Site Operations' product, a version named 'unspecified' must be created. + +### 5. Configure osportalapi container (NFV services) *(conditional)* + +Change the respective fields: + +- If you made changes to mysql and keycloak credentials. +- If you want to change logging level (TRACE / DEBUG / INFO / WARN / ERROR). + +> ***If you are using a non-local domain, replace everywhere the http://keycloak:8080 with the respective {{protocol://domain.name}}, as well as "spring.portal.main.domain" property.*** + +In folder `org.etsi.osl.main/compose/` edit the file `docker-compose.yaml` + +``` +SPRING_APPLICATION_JSON: '{ + "spring.datasource.username":"root", + "spring.datasource.password":"letmein", + "spring-addons.issuers[0].uri": "http://keycloak:8080/auth/realms/openslice", + "spring.security.oauth2.resourceserver.jwt.issuer-uri": "http://keycloak:8080/auth/realms/openslice", + "springdoc.oAuthFlow.authorizationUrl": "http://keycloak:8080/auth/realms/openslice/protocol/openid-connect/auth", + "springdoc.oAuthFlow.tokenUrl": "http://keycloak:8080/auth/realms/openslice/protocol/openid-connect/token", + "spring.portal.main.domain": "http://localhost", + "logging.level.org.springframework" : "INFO" +}' +``` + +### 6. osscapi container (TMF API service) *(conditional)* + +Change the respective fields: + +- If you made changes to mysql and keycloak credentials. +- If you want to change logging level (TRACE / DEBUG / INFO / WARN / ERROR). + +> **If you are using a non-local domain, replace everywhere the http://keycloak:8080 with the respective {{protocol://domain.name}}.** + +In folder `org.etsi.osl.main/compose/` edit the file `docker-compose.yaml` + +``` +SPRING_APPLICATION_JSON: '{ + "spring.datasource.username":"root", + "spring.datasource.password":"letmein", + "spring-addons.issuers[0].uri": "http://keycloak:8080/auth/realms/openslice", + "spring.security.oauth2.resourceserver.jwt.issuer-uri": "http://keycloak:8080/auth/realms/openslice", + "springdoc.oAuthFlow.authorizationUrl": "http://keycloak:8080/auth/realms/openslice/protocol/openid-connect/auth", + "springdoc.oAuthFlow.tokenUrl": "http://keycloak:8080/auth/realms/openslice/protocol/openid-connect/token", + "logging.level.org.springframework" : "INFO" +}' +``` + +## Configure nginx + +In folder `org.etsi.osl.main/compose/nginx` create a configuration specific `nginx.conf` file. + + +```bash +cd org.etsi.osl.main/compose/nginx/ +``` + +```bash +sudo cp nginx.conf.default nginx.conf +``` + +If needed, in the nginx.conf file, edit the server_name for an non-local deployment. + + + +## Configure Web UI + +In folder `org.etsi.osl.portal.web/src/js/` create a configuration specific `config.js` file. + +```bash +cd org.etsi.osl.portal.web/src/js +``` + +```bash +sudo cp config.js.default config.js +``` + +Edit the `config.js` file with the information of your domain. `ROOTURL` will automatically extract the the Origin (Protocol://Domain:Port) of the deployment, but you must change `APIURL` property, if you are not aiming for a localhost installation, e.g. "https://portal.openslice.io". + +Example file: + +``` +{ + BUGZILLA: "ROOTURL/bugzilla/", + STATUS: "ROOTURL/status/", + APIURL: "http://localhost", + WEBURL: "ROOTURL/nfvportal", + APIOAUTHURL: "ROOTURL/auth/realms/openslice", + APITMFURL: "ROOTURL/tmf-api/serviceCatalogManagement/v4" +} +``` + +## Configure TMF Web UI + +In the folder `org.etsi.osl.tmf.web/src/assets/config` there are 3 files available for configuration: + +* config.prod.json (Basic information + API configuration) +* theming.scss (CSS color palette theming) +* config.theming.json (HTML configuration - Logo, Favicon, Footer) + + +The first 2 files above (i.e. config.prod.json, theming.scss) are essential for the successful deployment of OpenSlice, thus created automatically during the initial deployment at `org.etsi.osl.tmf.web/src/assets/config` directory as a copy of the default ones from the remote repository. + +Ensure that you check the `config.prod.json` and `theming.scss` files and readjust to your deployment if needed. + +```bash +# Starting from the root project directory +cd org.etsi.osl.tmf.web/src/assets/config +``` + +E.g. You may edit "TITLE", "WIKI", etc properties with your domain title. Also configure TMF's API and Keycloak's location for the web application, if needed. + +Example file: + +``` +{ + "TITLE": "OpenSlice by ETSI", + "PORTALVERSION":"2024Q2", + "WIKI": "https://osl.etsi.org/documentation", + "BUGZILLA": "{BASEURL}/bugzilla/", + "STATUS": "{BASEURL}/status/", + "WEBURL": "{BASEURL}", + "PORTAL_REPO_APIURL": "{BASEURL}/osapi", + "ASSURANCE_SERVICE_MGMT_APIURL": "{BASEURL}/oas-api", + "APITMFURL": "{BASEURL}/tmf-api", + "OAUTH_CONFIG" : { + "issuer": "{BASEURL}/auth/realms/openslice", + "loginUrl": "{BASEURL}/auth/realms/openslice/protocol/openid-connect/auth", + "tokenEndpoint": "{BASEURL}/auth/realms/openslice/protocol/openid-connect/token", + "userinfoEndpoint": "{BASEURL}/auth/realms/openslice/protocol/openid-connect/userinfo", + "redirectUri": "{BASEURL}/redirect", + "logoutUrl": "{BASEURL}/auth/realms/openslice/protocol/openid-connect/logout", + "postLogoutRedirectUri": "{BASEURL}", + + "responseType": "code", + "oidc": false, + "clientId": "osapiWebClientId", + "dummyClientSecret": "secret", + + "requireHttps": false, + "useHttpBasicAuth": true, + "clearHashAfterLogin": false, + + "showDebugInformation": true + } +} +``` + +> The {BASEURL} placeholder in the file automatically detects the Origin (Protocol://Domain:Port) of the deployment and applies it to every respective property. E.g. If you are attempting a local deployment of OpenSlice, then {BASEURL} is automatically translated to "http://localhost". Similarly, you may use {BASEURL} to translate to a public deployment configuration, e.g. "https://portal.openslice.io". + +If further customization, apart from the default provided, is needed for branding (Logo, Footer) then `config.theming.json` needs to be created in io.openslice.tmf.web/src/assets/config directory, as follows: + +```bash +# Starting from the root project directory +cd org.etsi.osl.tmf.web/src/assets/config +``` + +```bash +sudo cp config.theming.default.json config.theming.json +``` + +> ***IMPORTANT NOTE:*** +If you want to apply changes to the JSON configuration files without the need to rebuild the application, you have to apply the changes at the `org.etsi.osl.tmf.web/dist/io-openslice-portal-web/assets/config` directory. Although, it is mandatory to also apply these changes to the `org.etsi.osl.tmf.web/src/assets/config` for persistancy, as after any future rebuild of OpenSlice the `/dist` directory is being overwritten along with its contents. The OpenSlice team strongly recommends to always apply your changes to the TMF web UI configuration files at `org.etsi.osl.tmf.web/src/assets/config` and rebuild the application. + +## Deploy OpenSlice via Docker Compose + +After configuring the services, and editing the docker compose file accordingly, the docker compose instantiation command can be performed. + +```bash +# Starting from the root project directory +cd org.etsi.osl.main/compose/ +``` + +```bash +sudo docker compose --profile prod down;sudo docker compose --profile prod up -d --build +``` + +> Depending on your machine, this process might take time. if for any reason the deployment fails during first time, please rerun the above before any further measures. + + +## Validating deployments and container monitoring + +You can monitor containers' status with portainer at port 9000 (http://your-ip:9000). + +Initially, you may monitor the local machine at portainer. + +Please check that all containers are in running state. + + +## Post installation steps + +After the successful deployment of OpenSlice, to ensure the E2E user experience, **this section is mandatory**. It contains crucial configuration in regard of authentication and user creation. + +### Configure Keycloak server + +The Keycloack server is managing authentication and running on a container at port 8080. It is also proxied to your host via nginx under http://localhost/auth. + +- Navigate to http://domain.com/auth/ or https://domain.com/auth/, (http://ipaddress:8080/auth/ or https://ipaddress:8443/auth/ which are directly accessible without proxy) + +- Navigate to Administration Console + +- Login with the credentials from section [Configure keycloak container](#3-configure-keycloak-container-optional). Default values are: + - user: admin and + - password: Pa55w0rd + +> if you are running in HTTP you will get a message: HTTPS required. + +To resolve this issue when running in HTTP: + +- Select the master realm from top left corner +- Go to login Tab and select "Require SSL": None +- Repeat for realm Openslice + + +> If you are running in HTTPS, then "Require SSL" can be left unchanged to external requests. + +#### 1. Configure redirects + +Navigate to realm Openslice > Clients > osapiWebClientId and change the Root URL to your domain. + +Also, insert your domain, e.g. http://example.org/*, at: + +- Valid Redirect URIs +- Web Origins + +#### 2. Configure email + +Keycloak allows new users to register. Subsequently, this will also allow new users to register to the OpenSlice portal. + +Navigate to realm Openslice > Realm Settings > Login Tab > check User registration, Verify email, Forgot password etc. + +Finally, enter the details of the mail server at the Email Tab. + +> Email configuration is optional for test runs, but if not provided the above functionalities (e.g. external user registration) will not be possible. + + +#### 3. Add an OpenSlice admin user + +This step is mandatory so as to access the OpenSlice Web UI. To add an OpenSlice admin user you must: + +- Navigate to realm Openslice > Users > Add user +- Set a password +- Upon creation, navigate to Role Mappings and add ADMIN to Assigned Roles list + +> That user is different from the Keycloak admin user. It is required to login and browse the OpenSlice Web UI. The Role ADMIN guarantee full access through the OpenSlice UI, thus such a user is always required. + +### Keycloak at localhost + +> **This is an important step if you run Keycloak on localhost!** + +1 - Edit your Hosts File, adding the line below + +```127.0.0.1 keycloak``` + +Hosts File Location: + + - In Linux/Unix, the file's location is at /etc/hosts + + - In Windows, its location is at c:\Windows\System32\Drivers\etc\hosts + +2 - Replace http://localhost/auth/ with http://keycloak:8080/auth/ in your Keycloak config for AngularJS and Angular (see examples below). + + +> Explanation + +Nginx uses the http://keycloak:8080 URL, which is accessible via the internal docker system's network. +The Front-end (TS/Angular) shall also use the http://keycloak:8080. +This way, you will not get the invalid token error, as the API is acquiring the token from http://keycloak:8080 (internally) and the Front-end is getting verified by an issuer at the same URL, as well. + + + +2.1 - For the Angular configuration (TMF portal UI), navigate to org.etsi.osl.tmf.web/src/assets/config and edit config.prod.json + +```bash +# Starting from the root project directory +cd org.etsi.osl.tmf.web/src/assets/config +``` + +```bash +nano config.prod.json +``` + +After editing, the displayed properties should look like the example below: + +```yaml +{ + "OAUTH_CONFIG" : { + "issuer": "http://keycloak:8080/auth/realms/openslice", + "loginUrl": "http://keycloak:8080/auth/realms/openslice/protocol/openid-connect/auth", + "tokenEndpoint": "http://keycloak:8080/auth/realms/openslice/protocol/openid-connect/token", + "userinfoEndpoint": "http://keycloak:8080/auth/realms/openslice/protocol/openid-connect/userinfo", + "redirectUri": "{BASEURL}/redirect", + "logoutUrl": "http://keycloak:8080/auth/realms/openslice/protocol/openid-connect/logout", + "postLogoutRedirectUri": "{BASEURL}", + } +} +``` + +> Note the difference in changing {BASEURL} -> http://keycloak:8080 + +> **If you want the changes to take place immediately without rebuilding the project, then repeat the process for org.etsi.osl.tmf.web/dist/org.etsi.osl.tmf.web/assets/config/config.prod.json** + +2.2 - For the AngularJS configuration (NVF portal UI), navigate to org.etsi.osl.portal.web/src/js and edit config.js + +```bash +# Starting from the root project directory +cd org.etsi.osl.portal.web/src/js +``` + +```bash +nano config.js +``` + +After editing, the displayed properties should look like the example below: + +``` +var appConfig = angular.module('portalwebapp.config',[]); + + +appConfig.factory('APIEndPointService', function() { + return { + APIOAUTHURL: "http://keycloak:8080/auth/realms/openslice", + }; +}); +``` + +> Note the difference in "APIOAUTHURL" property, changing ROOTURL -> http://keycloak:8080 + + +### NFV Orchestrator Configuration + +After successfully deploying and configuring OpenSlice, you may configure its environment (e.g. the NFVO) that will facilitate the deployment of NFV artifacts. + +See [NFV Orchestrator Configuration](./nfvoconfig.md). diff --git a/doc/deploymentK8s.md b/doc/deploymentK8s.md new file mode 100644 index 0000000000000000000000000000000000000000..bf0a32edddcc0e67207c173fb8edc0e412d78bf5 --- /dev/null +++ b/doc/deploymentK8s.md @@ -0,0 +1,388 @@ +# OpenSlice Deployment Guide with Kubernetes + +## Intended Audience: OpenSlice administrators + +## Requirements + +### Hardware requirements: + +| **Minimum Hardware Requirements** | **Recommended Hardware Requirements** | +| --------------------------------- | ------------------------------------ | +| 4 CPU cores | 8 CPU cores | +| 8 GB RAM | 16 GB RAM | +| 30 GB storage | 50 GB storage | + +### Software Requirements: + +* **git:** For cloning the project repository. +* **Kubernetes:** A running cluster where OpenSlice will be deployed. + * **Disclaimer:** The current manual setup of Persistent Volumes using `hostPath` is designed to operate with **only a single worker node**. This setup will not support data persistence if a pod is rescheduled to another node. +* **Helm:** For managing the deployment of OpenSlice. +* **Ingress Controller:** Ingress exposes HTTP and HTTPS routes from outside the cluster to services within the cluster. Traffic routing is controlled by rules defined on the Ingress resource. An Ingress may be configured to give Services externally-reachable URLs, load balance traffic, terminate SSL / TLS, and offer name-based virtual hosting. An Ingress controller is responsible for fulfilling the Ingress, usually with a load balancer, though it may also configure your edge router or additional frontends to help handle the traffic. You must have an Ingress controller to satisfy an Ingress. + * An Nginx ingress controller is required, which can be installed using [this guide](https://docs.nginx.com/nginx-ingress-controller/installation/installing-nic/installation-with-helm/). + * If you use another type of ingress controller, you'll need to modify `[repo-root]/kubernetes/helm/openslice/templates/openslice-ingress.yaml` to conform to your ingress controller's requirements. +* **Network Load Balancer:** Required for exposing the service (e.g., GCP, AWS, Azure, MetalLB). +* **Domain/IP Address:** Necessary for accessing the application. This should be configured in `[repo-root]/kubernetes/helm/openslice/values.yaml` under `rooturl`. + +### Additional Configuration + +* **Storage Class:** In a production environment, specify your `storageClass` in `[repo-root]/kubernetes/helm/openslice/values.yaml` under `storageClass`. If not defined, PVs will be created and managed manually. + * **Disclaimer:** Before deploying, confirm that your storage system supports claims of one 10G and two 1G volumes. + +## Preparing the environment + +### 1. Setting Up A Kubernetes Cluster +Refer to the official Kubernetes documentation for setting up a cluster. Ensure your cluster meets the hardware requirements specified above. + +### 2. Installing Helm +Helm must be installed on your machine to deploy OpenSlice via Helm charts. Follow the [official Helm installation guide](https://helm.sh/docs/intro/install/). + +## Downloading the project + +### 1. Create a new folder to download the project + +```bash +mkdir openslice +cd openslice +``` + +### 2. Download the project code +Clone the project code from the GitLab repository. +**Note:** This process will be simplified once the charts are published in the GitLab registry, requiring only the chart to be pulled. + +```bash +git clone https://labs.etsi.org/rep/osl/code/org.etsi.osl.main.git +cd org.etsi.osl.main/kubernetes/helm/openslice/ +``` + +### 3. Prerequisites before deployment + +Before deploying the Helm chart, ensure you have configured the necessary components as detailed in the following section, i.e. [Configure Helm Chart Services](#configure-helm-chart-services). By default, the `main` branch is selected for deployment. + +We recommend: + +* main branch for the most stable experience and +* develop branch for an experience with the latest features (for develop branch installation, it is strongly advisable that you may as well follow the [develop documentation](https://osl.etsi.org/documentation/develop/deployment/)) + + +## Configure Helm Chart Services + +When deploying OpenSlice with Helm, service configurations are handled through the `values.yaml` file. This file allows you to define all necessary configurations for your deployment, including database credentials, service URLs, and logging levels. Below are examples of how to configure your services in Helm based on your provided values. + +### Configuring Services + +#### 1. Database Configuration + +To configure MySQL and other related services, you can directly set the values in your `values.yaml` file under the `oscreds` and `mysql` sections. For example: + +```yaml +oscreds: + mysql: + username: "root" + password: "letmein" + openslicedb: "osdb" + keycloak: + database: "keycloak" + username: "keycloak" + password: "password" + adminpassword: "Pa55w0rd" + portal: + database: "osdb" + username: "portaluser" + password: "12345" +``` + +#### 2. External Services Configuration + +For configuring external services like Bugzilla and CentralLog, specify their URLs and credentials in the `values.yaml` file: + +```yaml +bugzillaurl: "example.com:443/bugzilla" +bugzillakey: "VH2Vw0iI5aYgALFFzVDWqhACwt6Hu3bXla9kSC1Z" +main_operations_product: "Main Site Operations" // this is the default product to issue tickets +centrallogurl: "http://elk_ip:elk_port/index_name/_doc" +``` + +Bugzilla should have the following components under the specified product: + +* NSD Deployment Request: Component used to schedule deployment req +* Onboarding: Issues related to VNF/NSD Onboarding +* Operations Support: Default component for operations support +* Validation: Use to track validation processes of VNFs and NSDs +* VPN Credentials/Access: Used for requesting VPN Credentials/Access + +Also in the 'Main Site Operations' product, a version named 'unspecified' must be created. + +#### 3. Keycloak Configuration + +Keycloak settings, including the database and admin password, are part of the `oscreds.mysql.keycloak` section. If you need to adjust Keycloak-specific settings like realms or client configurations, you'll likely need to customize your Helm chart further or manage these settings directly within Keycloak after deployment. The Keycloak realm configuration that is imported by default can be found under `kubernetes/helm/openslice/files/keycloak-init/realm-export.json`. + +```yaml +oscreds: + mysql: + keycloak: + database: "keycloak" + username: "keycloak" + password: "password" + adminpassword: "Pa55w0rd" +``` + +#### 4. Application and Logging Configuration + +Application-specific configurations, such as OAuth client secrets, can be set in the `spring` section: + +```yaml +spring: + oauthClientSecret: "secret" +``` + +#### 5. Ingress and Root URL + +To configure the ingress controller and root URL for OpenSlice, update the rooturl field with your ingress load balancer IP or domain. This setting is crucial for external access to your application: + +```yaml +rooturl: "http://openslice.com" # Example domain +# or +rooturl: "http://3.15.198.35:8080" # Example IP with port +``` + +#### 6. Persistent Volume for MySQL + +For persistent storage, especially for MySQL, define the storage size under the `mysql` section. This ensures that your database retains data across pod restarts and deployments. + +```yaml +mysql: + storage: "10Gi" +``` + +## Configure Web UI + +In folder `kubernetes/helm/openslice/files/org.etsi.osl.portal.web/src/js` you must make a copy of `config.js.default` file and rename it to `config.js`. + +This is **mandatory** for the configuration file to be discoverable. + +Edit the `config.js` configuration file with your static configuration, if needed. + +``` +{ + TITLE: "OpenSlice by ETSI", + WIKI: "https://osl.etsi.org/documentation/", + BUGZILLA: "{{ .Values.rooturl }}/bugzilla", + STATUS: "{{ .Values.rooturl }}/status", + APIURL: "{{ .Values.rooturl }}", + WEBURL: "{{ .Values.rooturl }}/nfvportal", + APIOAUTHURL: "{{ .Values.rooturl }}/auth/realms/openslice", + APITMFURL: "{{ .Values.rooturl }}/tmf-api/serviceCatalogManagement/v4" +} +``` + + + +## Configure TMF Web UI + +In the folder `kubernetes/helm/openslice/files/org.etsi.osl.tmf.web/src/assets/config` there are 3 files available for configuration: + +* config.prod.default.json (Basic information + API configuration) +* theming.default.scss (CSS color palette theming) +* config.theming.default.json (HTML configuration - Logo, Favicon, Footer) + +You must make a copy of files: + +* `config.prod.default.json` and rename it to `config.prod.json` +* `theming.default.scss` and rename it to `theming.scss` + +The 2 files above (i.e. config.prod.json, theming.scss) are essential for the successful deployment of OpenSlice, and executing the above steps is **mandatory** for the configuration files to be discoverable. + +Ensure that you check the `config.prod.json` and `theming.scss` files and readjust to your deployment if needed. + +```bash +# Starting from the root project directory +cd kubernetes/helm/openslice/files/org.etsi.osl.tmf.web/src/assets/config +``` + +E.g. You may edit "TITLE", "WIKI", etc properties with your domain title. Also configure TMF's API and Keycloak's location for the web application, if needed. + +``` +{ + "TITLE": "OpenSlice by ETSI", + "PORTALVERSION":"2024Q2", + "WIKI": "https://osl.etsi.org/documentation", + "BUGZILLA": "{BASEURL}/bugzilla/", + "STATUS": "{BASEURL}/status/", + "WEBURL": "{BASEURL}", + "PORTAL_REPO_APIURL": "{BASEURL}/osapi", + "ASSURANCE_SERVICE_MGMT_APIURL": "{BASEURL}/oas-api", + "APITMFURL": "{BASEURL}/tmf-api", + "OAUTH_CONFIG" : { + "issuer": "{BASEURL}/auth/realms/openslice", + "loginUrl": "{BASEURL}/auth/realms/openslice/protocol/openid-connect/auth", + "tokenEndpoint": "{BASEURL}/auth/realms/openslice/protocol/openid-connect/token", + "userinfoEndpoint": "{BASEURL}/auth/realms/openslice/protocol/openid-connect/userinfo", + "redirectUri": "{BASEURL}/redirect", + "logoutUrl": "{BASEURL}/auth/realms/openslice/protocol/openid-connect/logout", + "postLogoutRedirectUri": "{BASEURL}", + + "responseType": "code", + "oidc": false, + "clientId": "osapiWebClientId", + "dummyClientSecret": "secret", + + "requireHttps": false, + "useHttpBasicAuth": true, + "clearHashAfterLogin": false, + + "showDebugInformation": true + } +} +``` + +> The {BASEURL} placeholder in the file automatically detects the Origin (Protocol://Domain:Port) of the deployment and applies it to every respective property. E.g. If you are attempting a local deployment of OpenSlice, then {BASEURL} is automatically translated to "http://localhost". Similarly, you may use {BASEURL} to translate to a public deployment configuration, e.g. "https://portal.openslice.io". + +If further customization, apart from the default provided, is needed for branding (Logo, Footer) then `config.theming.json` needs to be created in kubernetes/helm/openslice/files/org.etsi.osl.tmf.web/src/assets/config directory, as follows: + +```bash +# Starting from the root project directory +cd kubernetes/helm/openslice/files/org.etsi.osl.tmf.web/src/assets/config +``` + +```bash +sudo cp config.theming.default.json config.theming.json +``` + + +### 3. Deploy the Helm Chart + +After configuring the services, and editing the `values.yaml` file accordingly, the helm install command can be performed. + +```bash +cd kubernetes/helm/openslice/ +helm install myopenslice . --namespace openslice --create-namespace +``` + +## Validating deployments and container monitoring + +In a Kubernetes environment, you can monitor the status of your deployments and containers using `kubectl`, the Kubernetes command-line tool, which provides powerful capabilities for inspecting the state of resources in your cluster. + +### Checking the Status of your application's deployment + +To check the status of your deployment, use the following commands. The output should be similar: + +```bash + +kubectl get pods -n openslice + +NAME READY UP-TO-DATE AVAILABLE AGE +myopenslice-artemis 1/1 1 1 6m28s +myopenslice-blockdiag 1/1 1 1 6m28s +myopenslice-bugzilla 1/1 1 1 6m28s +myopenslice-centrallog 1/1 1 1 6m28s +myopenslice-cridge 1/1 1 1 6m28s +myopenslice-keycloak 1/1 1 1 6m28s +myopenslice-kroki 1/1 1 1 6m28s +myopenslice-manoclient 1/1 1 1 6m28s +myopenslice-oasapi 1/1 1 1 6m28s +myopenslice-osom 1/1 1 1 6m28s +myopenslice-osportalapi 1/1 1 1 6m28s +myopenslice-osscapi 1/1 1 1 6m28s +myopenslice-portalweb 1/1 1 1 6m28s +myopenslice-tmfweb 1/1 1 1 6m28s +``` +```bash +kubectl get deployments -n openslice + +NAME READY UP-TO-DATE AVAILABLE AGE +myopenslice-artemis 1/1 1 1 7m17s +myopenslice-blockdiag 1/1 1 1 7m17s +myopenslice-bugzilla 1/1 1 1 7m17s +myopenslice-centrallog 1/1 1 1 7m17s +myopenslice-cridge 1/1 1 1 7m17s +myopenslice-keycloak 1/1 1 1 7m17s +myopenslice-kroki 1/1 1 1 7m17s +myopenslice-manoclient 1/1 1 1 7m17s +myopenslice-oasapi 1/1 1 1 7m17s +myopenslice-osom 1/1 1 1 7m17s +myopenslice-osportalapi 1/1 1 1 7m17s +myopenslice-osscapi 1/1 1 1 7m17s +myopenslice-portalweb 1/1 1 1 7m17s +myopenslice-tmfweb 1/1 1 1 7m17s +``` +```bash +kubectl get services -n openslice + +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +myopenslice-artemis ClusterIP 10.101.128.223 8161/TCP,61616/TCP,61613/TCP 7m43s +myopenslice-blockdiag ClusterIP 10.109.196.90 8001/TCP 7m43s +myopenslice-bugzilla ClusterIP 10.107.10.101 13010/TCP 7m43s +myopenslice-centrallog ClusterIP 10.109.84.33 13013/TCP 7m43s +myopenslice-keycloak ClusterIP 10.104.172.73 8080/TCP,8443/TCP 7m43s +myopenslice-kroki ClusterIP 10.106.92.111 8000/TCP 7m43s +myopenslice-manoclient ClusterIP 10.100.143.154 13011/TCP 7m43s +myopenslice-mysql ClusterIP 10.108.206.75 3306/TCP 7m43s +myopenslice-oasapi ClusterIP 10.100.107.66 13101/TCP 7m43s +myopenslice-osom ClusterIP 10.97.88.133 13100/TCP 7m43s +myopenslice-osportalapi ClusterIP 10.111.212.76 13000/TCP 7m43s +myopenslice-osscapi ClusterIP 10.101.84.220 13082/TCP 7m43s +myopenslice-portalweb ClusterIP 10.101.16.112 80/TCP 7m43s +myopenslice-tmfweb ClusterIP 10.101.157.185 80/TCP 7m43s +``` + +### Accessing Logs for Troubleshooting + +If a pod is not in the expected state, you can access its logs for troubleshooting: + +```bash +kubectl logs -n openslice +``` + +## Post installation steps + +After the successful deployment of OpenSlice, to ensure the E2E user experience, **this section is mandatory**. It contains crucial configuration in regard of authentication and user creation. + +### Configure Keycloak server + +The Keycloack server is managing authentication and running on a container at port 8080. It is also proxied to your host via the ingress resource under http://your-domain/auth. + +- Navigate to http://your-domain/auth/ or https://your-domain/auth/, (http://ipaddress:8080/auth/ or https://ipaddress:8443/auth/ which are directly accessible without proxy) + +- Navigate to Administration Console + +- Login with the credentials from section [Keycloak Configuration](#3-keycloak-configuration). Default values are: + - user: admin + - password: Pa55w0rd + +> This applies only if you are running in HTTP and get a message: HTTPS required. + +To resolve this issue when running in HTTP: + +- Select the master realm from top left corner +- Go to login Tab and select "Require SSL": None +- Repeat for realm Openslice + + +> If you are running in HTTPS, then "Require SSL" can be left unchanged to external requests. + +#### 1. Configure email + +Keycloak allows new users to register. Subsequently, this will also allow new users to register to the OpenSlice portal. + +Navigate to realm Openslice > Realm Settings > Login Tab > check User registration, Verify email, Forgot password etc. + +Finally, enter the details of the mail server at the Email Tab. + +> Email configuration is optional for test runs, but if not provided the above functionalities (e.g. external user registration) will not be possible. + + +#### 2. Add an OpenSlice admin user + +This step is mandatory so as to access the OpenSlice Web UI. To add an OpenSlice admin user you must: +- Navigate to realm Openslice > Users > Add user +- Set a password +- Upon creation, navigate to Role Mappings and add ADMIN to Assigned Roles list + +> That user is different from the Keycloak admin user. It is required to login and browse the OpenSlice Web UI. The Role ADMIN guarantee full access through the OpenSlice UI, thus such a user is always required. + +### NFV Orchestrator Configuration + +After successfully deploying and configuring OpenSlice, you may configure its environment (e.g. the NFVO) that will facilitate the deployment of NFV artifacts. + +See [NFV Orchestrator Configuration](./nfvoconfig.md). \ No newline at end of file diff --git a/doc/etsi_osl.md b/doc/etsi_osl.md new file mode 100644 index 0000000000000000000000000000000000000000..08f6df2aec3b4030475851106e731a06dfb54657 --- /dev/null +++ b/doc/etsi_osl.md @@ -0,0 +1,3 @@ +# The ETSI SDG OSL + +OpenSlice is developed by the OSL ETSI Software Development Group [see more info](https://osl.etsi.org/). \ No newline at end of file diff --git a/doc/history.md b/doc/history.md new file mode 100644 index 0000000000000000000000000000000000000000..5608a95fe296b702489f96b385b43394226699fe --- /dev/null +++ b/doc/history.md @@ -0,0 +1,22 @@ +# History + +* The NFV portal part of OpenSlice was initially developed in H2020 European Research project [5GinFIRE](https://5ginfire.eu) by University of Patras, Greece +* OpenSlice core services, APIs was further developed and maintained in H2020 European project [5G-VINNI](https://5g-vinni.eu/) by University of Patras, Greece +* OpenSlice has been a part of OSM's OSS/BSS ecosystem +* OpenSlice is now an ETSI SDG Group since 2023 + + +## Citation + +Please cite our [![paper]](https://arxiv.org/abs/2102.03290) if you use OpenSlice in your research + +``` +@misc{tranoris2021openslice, + title={Openslice: An opensource OSS for Delivering Network Slice as a Service}, + author={Christos Tranoris}, + year={2021}, + eprint={2102.03290}, + archivePrefix={arXiv}, + primaryClass={cs.NI} +} +``` \ No newline at end of file diff --git a/doc/images/deployment_example/Slide1.PNG b/doc/images/deployment_example/Slide1.PNG new file mode 100644 index 0000000000000000000000000000000000000000..31a3bf1f97198b9dc9341bf8d7a1013a3f93be53 Binary files /dev/null and b/doc/images/deployment_example/Slide1.PNG differ diff --git a/doc/images/deployment_example/Slide2.PNG b/doc/images/deployment_example/Slide2.PNG new file mode 100644 index 0000000000000000000000000000000000000000..bd00aec2c740323dd0b60f87f9bbd02e830f68ea Binary files /dev/null and b/doc/images/deployment_example/Slide2.PNG differ diff --git a/doc/images/deployment_example/Slide3.PNG b/doc/images/deployment_example/Slide3.PNG new file mode 100644 index 0000000000000000000000000000000000000000..8e5042688e1ee7d7a390af9359c5152e130ddd42 Binary files /dev/null and b/doc/images/deployment_example/Slide3.PNG differ diff --git a/doc/images/deployment_example/Slide4.PNG b/doc/images/deployment_example/Slide4.PNG new file mode 100644 index 0000000000000000000000000000000000000000..736ef4a3f30909dc3b10225a8890d59c43829056 Binary files /dev/null and b/doc/images/deployment_example/Slide4.PNG differ diff --git a/doc/images/deployment_example/Slide5.PNG b/doc/images/deployment_example/Slide5.PNG new file mode 100644 index 0000000000000000000000000000000000000000..a62ef15699ecf935e7f0544b812ccf1614dda095 Binary files /dev/null and b/doc/images/deployment_example/Slide5.PNG differ diff --git a/doc/images/deployment_example/Slide6.PNG b/doc/images/deployment_example/Slide6.PNG new file mode 100644 index 0000000000000000000000000000000000000000..a3adfee0c6c6f2170f00d4ef30a80fe046cf9194 Binary files /dev/null and b/doc/images/deployment_example/Slide6.PNG differ diff --git a/doc/images/deployment_example/Slide7.PNG b/doc/images/deployment_example/Slide7.PNG new file mode 100644 index 0000000000000000000000000000000000000000..b3d3eaf63235881e95dc724735e7957db25d11e5 Binary files /dev/null and b/doc/images/deployment_example/Slide7.PNG differ diff --git a/doc/images/global_approach.png b/doc/images/global_approach.png new file mode 100644 index 0000000000000000000000000000000000000000..8a929073b685fe03684bcea77fda51c760b98016 Binary files /dev/null and b/doc/images/global_approach.png differ diff --git a/doc/index.md b/doc/index.md index e8c0cbc224a790cb4d22acc2ef3d2a0fdf3b1de3..b28ee108a47368caccf9afdd3a99c0799477db82 100644 --- a/doc/index.md +++ b/doc/index.md @@ -1,134 +1,87 @@ drawing -version: 2023Q4 - Release 0 +version: 2024Q2 - SNAPSHOT -The ETSI Software Development Group for OpenSlice (SDG OSL) is developing an open source service based Operations Support System (OSS) to deliver Network Slice as a Service (NSaaS) following specifications from major SDOs including ETSI, TM Forum and GSMA. See more details [here](https://osl.etsi.org/about/). +The ETSI Software Development Group for OpenSlice (SDG OSL) is developing an open-source service-based Operations Support System (OSS) to deliver Network as a Service (NaaS) following specifications from major SDOs including ETSI, TM Forum and GSMA. ## Usage -OpenSlice allows Vertical Customers to browse the available offered service specifications and also allows NFV developers to onboard and manage VNF and Network Service artifacts. It also supports TMFORUM OpenAPIs regarding Service Catalog Management, Ordering, Resource, etc. -The following figure displays the usage of OpenSlice. +OpenSlice can be used in managing 5G network services from the user device to the core network and cloud as well as for Orchestrating cloud resources across private and public clouds for enterprise applications. OpenSlice is capable of supporting most of the features of an end-to-end (E2E) service orchestration framework while many of them will be more mature in future releases. The following figure displays the general usage of OpenSlice. -[![OpenSlice usage](./images/index_intro_architecture.png)](./images/index_intro_architecture.png) +[![OpenSlice usage](./images/global_approach.png)](./images/global_approach.png) +The image illustrates how OpenSlice supports the idea of an E2E network service orchestration framework by integrating multiple network components and layers, from user devices at the edge to radio, transport networks, core and public cloud services, ensuring seamless, secure, and efficient delivery of network services. Assuming that there are domain controllers for all the above domains OpenSlice can create the end-to-end service via the domain controllers by following the process of creating and deploying the end-to-end service by implementing transformations, and consuming APIs from various network entities. +OpenSlice, in a nutchell, offers user interfaces where users can interact with the framework to order, expose, and manage service catalogs, services and resources that can be ordered, following business logic and policies and exposed through the APIs. -There are two portals offering UI friendly access to users: +### An end-to-end (E2E) service orchestration framework -* The Services portal allows users to access services and service providers to design services. -* The NFV portal allows users to self-manage NFV artifacts and onboard them to a target MANO/NFV Orchestrator. - -3rd party applications can use OpenSlice through TMForum Open APIs. - -Service Specifications reside into Service Catalogs, grouped in Categories. OpenSlice offers a Service Orchestrator called [OSOM](./architecture/osom.md). OSOM instantiates Service Specifications by requesting Network Services from target MANOs/NFVOs. NFV artifacts reside into a VNF/NSD catalog and are onboarded to a target MANO/NFV Orchestrator. Service Specifications reference NSD from the VNF/NSD catalog. - -Customers make Service Orders and OpenSlice instantiates the requested Service Specifications of the Service Order. Running Services instantiated by OpenSlice, reside in OpenSlice Service Inventory. The following picture displays how Service Specifications are related to Running Services and how Running Services relate with instantiated running Network Services. (See also [Service Inventory](./service_inventory.md)) - -[![OpenSlice Service Specification instantiation](./images/service_specification_instantiation.png)](./images/service_specification_instantiation.png) - -## Service Lifecycle Rules - -OpenSlice constains support for defining rules of services, affecting their behavior. See [LCM Rules](./lcm.md). - -## Multidomain scenarios and federation - -OpenSlice can be used to exchange service specifications/catalogs and make service orders between Organizations as the following figure displays. - -[![OpenSlice Service Specification instantiation](./images/multi-domain-organizations.png)](./images/multi-domain-organizations.png) - -An Identity federation is also possible since our authentication service is based on Keycloak (see [OAuth](./architecture/oauth.md)). - -See more on [Consuming Services From External Partner Organizations](./architecture/consumingServicesFromExternalPartners.md). - - -## Live Demo - -* OpenSlice demo: -* OpenSlice Service Catalogs and ordering: -* OpenSlice NFV Services onboarding: -> username=admin, password=openslice
or
username=admin, password=changeme +An end-to-end (E2E) service orchestration framework is designed to manage and automate the entire lifecycle of services across multiple domains and technologies. For delivering, especially, Network as a Service (NaaS) a comprehensive system is needed that automates and manages the entire lifecycle of network services, from provisioning to monitoring and decommissioning, while ensuring seamless integration, operation, and delivery of services from the initial request to the final delivery, spanning all involved components and layers. Such E2E frameworks enable users to consume network services on-demand, similar to how cloud computing services are consumed. Some key components and features of such frameworks are: +- Service Catalogs including predefined Network Services based on service templates for common network services like 5G core functions, 5G slices, VPNs, SD-WAN, firewalls, load balancers, etc. as well as custom Network services with Options for users to define their own network configurations. +- User Interface (UI) and APIs exposure, offering both a Self-Service Portal that allows users to request, configure, and manage network services as well as APIs for enabling programmatic access to network services for integration with other systems and automation scripts. +- Service Design and Creation tharough service templates based on predefined models for creating services. +- Automation and Workflow Management via Orchestration Engines, supporting Process Automation for automating repetitive tasks and processes, workflow management and orchestration for automating the provisioning, configuration, and management of network services while coordinating multiple workflows to ensure services are delivered efficiently, ensuring that services comply with predefined policies and standards. +- Standardized API exposure for seamless integration with different systems and services and APIs transformation support for converting data formats and protocols to ensure compatibility and information exhange between systems during workflows orchestration +- Service and Resource management and Orchestration while including the capability of multi-domain coordination in managing services/resources across different domains like cloud, 5G core, radios, transport network, and edge including dynamic allocation with adjusting resources based on demand and service requirements. To accomplish the above advanced technologies need to be exploited like, Containerized workloads, Network Function Virtualization (NFV) which uses virtualized network functions to provide services like routing, switching, and security and Software-Defined Networking (SDN) which Controls the network programmatically to dynamically manage traffic and resources. +- Monitoring and Analytics including Service Monitoring while continuously tracking the performance and health of services with capabilities to analyse data to optimize service delivery and predict issues. Real-Time Monitoring is also needed for tracking the performance and health of network services enabling analytics that provide insights for optimization and troubleshooting. +- Security and Access Control for ensuring only authorized users and systems can access network services. while implementing rules and policies to comply with regulatory requirements. -## Video demo +### An E2E service orchestration workflow -* +In general an E2E service orchestration workflow includes the following phases: ---- +- Service Request: Users or systems request a network service through the self-service portal or API. The request can specify details such as bandwidth, security features, geographic coverage, and duration. +- Service Orchestration: The orchestration engine evaluates the request, determines the necessary resources, and initiates the automated workflows.It interacts with the underlying components (e.g. 5G Core, Radios, Containerized controllers, NFV, SDN controllers ) to provision and configure the required network functions and connectivity. +- Provisioning and Configuration: Services, network resources and network functions (VNFs) are instantiated and configured according to the service request during Service Orchestration through the orchestration engine. Other controllers manage their own domains, for example SDN controllers, manage the flow of data through the network to ensure optimal performance and adherence to policies, RAN controllers manage the RAN resoruces, Containerized controllers manage their workload, etc +- Service Delivery: The E2E network service is activated and made available to the user. Continuous monitoring ensures the service operates as expected, with automatic adjustments made as necessary. +- Lifecycle Management: The orchestration framework handles updates, scaling, and any necessary modifications throughout the service lifecycle. +- At the end of the service period, resources are decommissioned and reclaimed. -## Installing -See [Deployment/Installation](./deployment.md). +### OpenSlice for Service Providers ---- +OpenSlice is used by Service Providers to design Network Services, expose them in Service Catalogues and make them available for Service Orders. OpenSlice then can perform the E2E service orchestration workflow. -## Hardware requirements +There are various portals offering UI friendly access to users acting as Service Providers: -The complete environment consists of microservices deployed as docker containers. Portainer is also installed to monitor them at port 9000. +* The Services portal allows Service Providers to design and expose services. +* The Resource portal allows users to access resource specifications and running resources in resource inventory. +* The NFV portal allows users to manage NFV artifacts and onboard them to a target MANO/NFV Orchestrator. +* The Testing portal allows Service Providers to manage test artifacts +* The Products portal allows Service Providers to expose services as products -If you would like to operate all APIs, OSOM, the Mysql Server, nginx, etc then you need at least: +### OpenSlice for Service Consumers -| **Minimum Hardware Requirements** | **Recomended Hardware Requirements** | -| --------------------------------- | ------------------------------------ | -| 4 CPU cores | 8 CPU cores | -| 8 GB RAM | 16 GB RAM | -| 20 GB storage | 40 GB storage | +OpenSlice allows Service Consumers to browse the available offered service specifications in a self-service manner. It also supports TMFORUM Northbound APIs regarding Service Catalog Management, Ordering, Resource, etc. +There are various portals offering UI friendly access to users acting as Service Consumers: +* The Services portal allows Service Consumers to select and order predefined services. +* The Resource portal allows users to access running resources in resource inventory. +* The NFV portal allows users to self-manage NFV artifacts and onboard them to a target MANO/NFV Orchestrator. +* The Testing portal allows Service Consumers to manage test artifacts +* The Products portal allows Service Consumers to expose services as products -(NOTE: Bugzilla or ELK are not included and we assume they run elsewhere) - -However, you may try the front facing services of OpenSlice with a minimum installation on a VM on a laptop with: - -- 2 cores -- 4GB of RAM - - - -## Supported APIs - -Quick overview of the supported APIs through our Swagger links: - -* [TMF APIs](http://portal.openslice.io/tmf-api/swagger-ui/index.html) -* [API for VNF/NSD management](http://portal.openslice.io/osapi/swagger-ui/index.html) - -## Source code - -OpenSlice source code is available at [OSL GitLab repository](https://labs.etsi.org/rep/osl/code). - -## Contributing - -You may contribute following the guidelines at [Contributing page](./contributing/developing.md). - -## Social Media - -* [Twitter](https://twitter.com/OpensliceOSS) -* [Slack](https://openslice.slack.com) - -## History - -* The NFV portal part of OpenSlice was initially developed in H2020 European Research project [5GinFIRE](https://5ginfire.eu) by University of Patras, Greece -* OpenSlice core services, APIs was further developed and maintained in H2020 European project [5G-VINNI](https://5g-vinni.eu/) by University of Patras, Greece -* OpenSlice has been a part off OSM's OSS/BSS ecosystem +3rd party applications can use OpenSlice through TMForum Open APIs. -[![Part of OSM Ecosystem](./images/osm_ecosystem_ossbss.png)](https://osm.etsi.org/wikipub/index.php/OSS_BSS) -## Ecosystem +## Live Demo -Discover the current OpenSlice ecosystem [here](https://osl.etsi.org/ecosystem/). +Check a live demo of OpenSlice in the following pages: -## Citation +* OpenSlice demo: +* OpenSlice Service Catalogs and ordering: +* OpenSlice NFV Services onboarding: -Please cite our [![paper]](https://arxiv.org/abs/2102.03290) if you use Openslice +Login credentials: -``` +* username=admin, password=openslice +* username=admin, password=changeme -@misc{tranoris2021openslice, - title={Openslice: An opensource OSS for Delivering Network Slice as a Service}, - author={Christos Tranoris}, - year={2021}, - eprint={2102.03290}, - archivePrefix={arXiv}, - primaryClass={cs.NI} -} +# Probe further -``` \ No newline at end of file +* Installing OpenSlice. See the [Deployment](deployment.md) of OpenSlice +* Learn more on [how OpenSlice supports Network as a Service(NaaS)](./naas/introduction) +* Who is implementing OpenSlice? See [OSL ETSI SDG](https://osl.etsi.org/) +* How OpenSlice works? See the [Architecture](./architecture/architecture.md) of OpenSlice diff --git a/doc/lcm.md b/doc/lcm.md deleted file mode 100644 index b668b908c58da2c6972e11a0b6ca50450fd02176..0000000000000000000000000000000000000000 --- a/doc/lcm.md +++ /dev/null @@ -1,158 +0,0 @@ -# Lifecycle Management (LCM) Rules - -* NOTE: This is a prototype/experimental feature. So issues might raise during operation - -LCM Rules are used for defining complex conditions and actions during the lifecycle of a service. In Openslice there are four types of rules defined: - -* PRE_PROVISION -* CREATION -* AFTER_ACTIVATION -* SUPERVISION -* AFTER_DEACTIVATION - - -The following figure displays the different phases that the rules are performed, during the lifecycle of a Network Slice Instance. - -[![Rules in NSI](../images/lcm/lcmfig1.png)](../images/lcm/lcmfig1.png) - -* PRE_PROVISION rules: Run only once just before creating a service with a given priority. -* CREATION rules: Run while the referenced service dependencies of a service are created -* AFTER_ACTIVATION rules: Run only once just after a service get the ACTIVE state -* SUPERVISION rules: Run when a characteristic of a service is changed and the service is in the ACTIVE state -* AFTER_DEACTIVATION rules: Run only once just after a service get the INACTIVE/TERMINATED state - -In general the rules allow to perform many actions during service LCM. Thes are some examples: - -* Modify service specification parameters before the instantiation of a service (or during operation) based on other dependencies. These parameters might be part of other services already included in Service order -* Translate GST/NEST parameter values to other values passed later to NFVO for instantiation or control -* Define complex OSM Configs based on other dependencies and passing variables -* Define any dependencies when creating the referenced services -* Dynamically include new service dependencies -* Create new service orders so include dynamically other services -* Call external (RESTful) services (via http(s), define payload, examine response) - - - - -## Examine if the rules are executed successfully - -Rules are transformed automatically to executable code (currently is Java). If a rule is performed successfully or has any issues (e.g. unexpected syntax errors or exceptions) appear in OSOM logfiles and also tey are attached as Notes to the running Service. - -## LCM Rules and OSOM Service Orchestration - -OSOM is the responsible service for executing the rules on a specific phase. The following image explains the design in the BPMN phases: - - -[![Rules](../images/lcm/lcmfig1_osom.png)](../images/lcm/lcmfig1_osom.png) - - - -## Define rules - -Rules are defined when designing a Service Spec. Here is an example of a list of rules: - - -[![lcmrules](../images/lcm/lcmfig2.png)](../images/lcm/lcmfig2.png) - -Execution order of rules on a specific phase is random - -* NOTE: There is a priority field. The lower the number the highest the priority of rule execution. For example Rule with priority 0 will run before rule with priority 1. - - -### Definition language - -* The visual language that Openslice used is based on Google's Blockly (see https://developers.google.com/blockly) -* The blockly graph is automatically translated to Java internally and then dynamically executed during orchestration phases. - -The following figure is an example of such a rule design. The rule for example will run in PRE_PROVISION phase: - -[![lcmrules](../images/lcm/lcmfig3.png)](../images/lcm/lcmfig3.png) - -* The goal of the above rule is to properly define a variable AreaCodes given the chosen AreaOfService from a Service Order. -* On the right side the user can define some rule properties or observe the underlying generated java code. - - -## The blocks library - -The following images describe some blocks found in the library. - -Blockly has syntax rules. It helps with colours to define them. - -So for example a parameter that is a Number cannot be "glued" with a String. Will need some conversion first - -[![lcmrules](../images/lcm/lcmfig4.png)](../images/lcm/lcmfig4.png) -[![lcmrules](../images/lcm/lcmfig5.png)](../images/lcm/lcmfig5.png) -[![lcmrules](../images/lcm/lcmfig6.png)](../images/lcm/lcmfig6.png) -[![lcmrules](../images/lcm/lcmfig7.png)](../images/lcm/lcmfig7.png) -[![lcmrules](../images/lcm/lcmfig8.png)](../images/lcm/lcmfig8.png) - -## Examples of Rules - - -The following images provide some examples of rules. - -### define variables according to cases - -In the following example we : - -* define a String variable. -* Then according to the Area of Service selected from the Service Order of the Service Specification we need to define it properly. -* We output the value to the OSOM Log -* Define dynamically the value of another parameter (This is fictional) and then do some other condition check - -The strAreaCodes could be passed then e.g. to NFVO for instantiation of services to these cells. - - -[![lcmrules](../images/lcm/lcmfig9.png)](../images/lcm/lcmfig9.png) - - - -### Define complex OSM configs for DAY 0 - -The following displays some complex examples for defining the parameters to pass to the NFV. In this case is OSM. - -* NOTE: The OSM_CONFIG characteristic of a service is the one that it is used in orchestration to instantiate NS from OSM - -* check the variable strTargetsParam. It is passed to the variable strOsmConfig3 which is executed if the Number of Cameras is more than 100. -* if the Video quality requested is 3, then the Maximum Namber of camers will be 8. Check the OSM detailed configuration block and its syntax. -* if the Video quality requested is 2, we use a simpler OSM Config block to configure the parameter OSM_CONFIG. We just injected a json text ( watch the Escape of the string for the Quotes!) -* if the Video quality requested is 1, again we use a simpler OSM Config block to configure the parameter OSM_CONFIG. We use as injected json text a variable constructed later - - -[![lcmrules](../images/lcm/lcmfig10.png)](../images/lcm/lcmfig10.png) - - -### Define and instantiate different services according to Service Order request - -In the following example we would like to offer a service either as Platinum, Gold or Silver. Depending on the selection we need to instantiate different services. - -There are different ways to accomplish this: - -* create dynamically New Service Orders of RFSs with equivalent quality of Services -* change for example the VIMs that you deploy the NS -* change the NSD (that is use different VNFs) - -The following image displays for example the latter case. - -[![lcmrules](../images/lcm/lcmfig11.png)](../images/lcm/lcmfig11.png) - - -### Call an external RESTful service - -This is useful in cases for example of alarms , external logging, calling other services e.g. email or even a complex algorithm written in other language e.g. call an external service and get a result. (service e.g. a Python service) - - -[![lcmrules](../images/lcm/lcmfig12.png)](../images/lcm/lcmfig12.png) - -[![lcmrules](../images/lcm/lcmfig13.png)](../images/lcm/lcmfig13.png) - -### Create New Service Orders - -The following example calls to Order a New Service Specification with specific Parameter Values - -[![lcmrules](../images/lcm/lcmfig14.png)](../images/lcm/lcmfig14.png) - - - - - diff --git a/doc/naas/exposed_apis.md b/doc/naas/exposed_apis.md new file mode 100644 index 0000000000000000000000000000000000000000..b6efad8f34d635c9e258a8a2aeded50fb74ab227 --- /dev/null +++ b/doc/naas/exposed_apis.md @@ -0,0 +1,23 @@ +|Endpoint |Title |Description |Version +|:------:|:------:|:------:|:------:| +|/tmf-api/serviceCatalogManagement/v4 |633 Service Catalog Management |Provides a catalog of services. |4.0.0 +|/tmf-api/productCatalogManagement/v4/ |620 Product Catalog Management |Provides a catalog of products. |4.0.0 +|/tmf-api/productOrderingManagement/v4/ v622 Product Ordering |Provides a standardized mechanism for placing a product order. |4.0.0 +|/tmf-api/resourceCatalogManagement/v4 |634 Resource Catalog Management |This is Swagger UI environment generated for the TMF Resource Catalog Management specification. |4.0.0 +|/tmf-api/serviceInventory/v4 |638 Service Inventory Management |Provides a consistent/standardized mechanism to query and manipulate the Service inventory. |4.0.0 +|/tmf-api/serviceOrdering/v4 |641 API ServiceOrdering |Provides a standardized mechanism for managing Service Order. |4.0.0 +|/tmf-api/serviceQualityManagement/v2 |657 Service Quality Management |This is Swagger UI environment generated for the TMF Service Quality Management specification. |2.0.0 +|/tmf-api/partyRoleManagement/v4/ |669 Party Role Management |This is Swagger UI environment generated for the TMF Party Role Management specification. |4.0.0 +|/tmf-api/party/v4/organization |632 API Party |Provides standardized mechanism for party management such as creation, update, retrieval, deletion and notification of events. |4.0.0 +|/tmf-api/agreementManagement/v2/ |651 Agreement Management T|his is Swagger UI environment generated for the TMF Agreement Management specification. |2.0.0 +|/tmf-api/resourceOrderingManagement/v4 |652 Resource Order Management-v4.0.0 |This is Swagger UI environment generated for the TMF 652-Resource Order Management-v4.0.0 specification. |4.0.0 +|/tmf-api/accountManagement/v4 |666 Account Management |This is Swagger UI environment generated for the TMF Account Management specification.| 4.0.0 +|/tmf-api/customerManagement/v4 |629 Customer Management |TMF Customer Management |4.0.0 +|/tmf-api/userinfo |691 Federated ID |TMF Federated ID |1.0.0 +|/tmf-api/ServiceActivationAndConfiguration/v3/ |640 API Service Activation and Configuration| Provides the ability to activate and configure Services. |3.0.0 +|/tmf-api/alarmManagement/v4/ |642 API Alarm| |4.0.0 +|/tmf-api/serviceTestManagement/v4 |653 Service Test Management |Provides the ability to manage tests of provisioned Services. |4.0.0 +|/tmf-api/resourceInventoryManagement/v4 |639 API Resource Inventory Management |Provides the ability to manage Resources. |4.0.0 +|/tmf-api/lcmrulesmanagement/v1/ |LCM Rules Custom API environment for LCM Rules| |1.0.0 +|/tmf-api/resourcePoolManagement/v1 |685 Resource Pool Management |Resources that can be reserved are only in one pool. |1.0.0 +|/tmf-api/geographicSiteManagement/v5 |674 Geographic Site Management |Covers the operations to manage sites that can be associated with entities |5.0.0 \ No newline at end of file diff --git a/doc/naas/gst_to_gsma/img01.png b/doc/naas/gst_to_gsma/img01.png new file mode 100644 index 0000000000000000000000000000000000000000..f72c1855e08903dfcca60a213b88a106775b8130 Binary files /dev/null and b/doc/naas/gst_to_gsma/img01.png differ diff --git a/doc/naas/gst_to_tmf.md b/doc/naas/gst_to_tmf.md new file mode 100644 index 0000000000000000000000000000000000000000..8de472024ac206982ef938b28e86ffdf51584fe2 --- /dev/null +++ b/doc/naas/gst_to_tmf.md @@ -0,0 +1,31 @@ +# Generic Slice Template as a Service Specification + +## Intended Audience: Service Designers + +GSMA Generic Slice Template (GST) Defines customer-oriented service requirements, E.g. Availability, Area of service, delay tolerance, etc. and attempts to narrow down the gap between (network) service customers and vendors + +Moreove it Proposes standardized Network Slice Templates (NESTs) to target specific use cases + + +In OpenSlice we made an effort and translated the GST to a Service Specification model. So Service Designers can use it as a template to design a new Service. + +The image illustrates the relationship between the GSMA Generic Slice Template (GST), TM Forum Service Specification, and how they are utilized within OpenSlice to offer network services. + +[![gst_to_gsma](./gst_to_gsma/img01.png)](./gst_to_gsma/img01.png) + +The GST to TM Forum via OpenSlice: + + * GST Attributes List: A comprehensive list of service attributes, such as availability, delay tolerance, downlink throughput, energy efficiency, isolation level, mission-critical support, and many others. + * TMF Service Specification: Demonstrates the transformation of GST attributes into a TM Forum service specification, showing JSON code snippets that define service parameters. + * Offered Service based on GST: Represents the final offered service, an example of a GST-based service shown as an entry in a catalog, ready to be consumed by customers. + +What was our flow: + + * Started with defining service requirements and attributes using GST. + * Translated these GST attributes into a formal TM Forum service specification. + * Service Offering in OpenSlice: The service specification is then used to create and offer a specific network service within OpenSlice, available for customer selection and deployment. + + +## Probe further + +See v9 of the GST model in GSMA [here](https://www.gsma.com/newsroom/wp-content/uploads//NG.116-v9.0-1.pdf) \ No newline at end of file diff --git a/doc/naas/introduction.md b/doc/naas/introduction.md new file mode 100644 index 0000000000000000000000000000000000000000..e986a8c77dae83bf7753a93e1179bce8afa3b32b --- /dev/null +++ b/doc/naas/introduction.md @@ -0,0 +1,26 @@ +# Network as a Service (NaaS) + +This section describes some core concepts for Delivering Network as a Service in OpenSlice. There are many articles and reports on the subject like: + + +* TMF909 API Suite Specification for NaaS +* TMF926A Connectivity as a Service +* TMF931-Open Gateway Onboarding and Ordering Component Suite +* GSMA Open Gatewy initiative + +In general Network as a Service (NaaS) is a service model that allows users to consume network infrastructure and services , similar to how they would consume other cloud services like Software as a Service (SaaS) or Infrastructure as a Service (IaaS). NaaS abstracts the complexity of managing physical network infrastructure, providing users with virtualized network resources that can be dynamically allocated and managed through software. + + +## OpenSlice and NaaS + +OpenSlice makes extensive use of TMFORUM's models and APIs. Therefore if one is familiar with TMF APIs the terminology and ideas are the same. + +To deliver NaaS we need to incorporate various APIs (see TMF909 API Suite Specification for NaaS). OpenSlice implements various TMF APIs to deliver NaaS and support the lifecycle functions required to manage the network capabilities exposed as Network as a Service and managed by operational domains. + + + +## Probe further + +* Check the [TMFORUM - API assets - Onboarding and Ordering Component Suite (TMF931)](https://www.tmforum.org/oda/open-apis/partners/camara) +* For a complete list of supported APIs, see [Supported APIs](exposed_apis.md) +* Check the defined user roles of OpenSlice in our [Terminology](../terminology.md) \ No newline at end of file diff --git a/doc/naas/lcm/img01.png b/doc/naas/lcm/img01.png new file mode 100644 index 0000000000000000000000000000000000000000..145c8976ccf2b3f60304a74d59138f00eb88b3ce Binary files /dev/null and b/doc/naas/lcm/img01.png differ diff --git a/doc/naas/lcm/img02.png b/doc/naas/lcm/img02.png new file mode 100644 index 0000000000000000000000000000000000000000..a98bcfb28dc42a3182730671fc6ec095c4c66a6d Binary files /dev/null and b/doc/naas/lcm/img02.png differ diff --git a/doc/naas/lcm/img03.png b/doc/naas/lcm/img03.png new file mode 100644 index 0000000000000000000000000000000000000000..bd0afe6e125b54d1956c84075d5a9f54312537aa Binary files /dev/null and b/doc/naas/lcm/img03.png differ diff --git a/doc/naas/lcm_intro.md b/doc/naas/lcm_intro.md new file mode 100644 index 0000000000000000000000000000000000000000..5670c58f2197bba6e08f015996b137f3f307842e --- /dev/null +++ b/doc/naas/lcm_intro.md @@ -0,0 +1,108 @@ +# Lifecycle Management - LCM + + +Lifecycle Management: The orchestration framework handles the activation, termination and any necessary modifications throughout the service lifecycle. + + +## Intended Audience: Service Designers + + +In OpenSlice the Lifecycle of a service follows in general the concept of Network Slice lifecycle as defined by 3GPP. + + +[![lcm](./lcm/img01.png)](./lcm/img01.png) + +## Introduction in OpenSlice LCM + +OpenSlice adopted the LCM model by 3GPP and mapped to the TMF model service state. Next we discuss briefly the process and the relationships. + +The lifecycle of a service, particularly in the context of Network Service lifecycle encompasses several stages that ensure the service is effectively planned, deployed, managed, and eventually decommissioned. + +Here is an overview of these stages and relationships with OpenSlice: + +### 0. Preparation Phase + +This phase is performed by Service Designers + +#### Service Design: +- **Requirements Gathering:** Collect service requirements from stakeholders, including performance metrics, quality of service (QoS), security needs, and geographical coverage. +- **Service Specification:** Define the service in terms of functionalities, attributes, and dependencies. This can be formalized using standardized templates such as the GSMA Generic Slice Template (GST). +- **Resource Planning:** Identify and plan the required resources, including network functions, computing power, storage, and connectivity, inclluding network function configurations. +- **Expose to Service Catalog**: Expose to service catalog for user ordering. + + + +**Next phases are handled by the Service Orchestrator after a service is scheduled for instantiation** + +**If it is a bundle of services, each services follows its own Lifecycle!** + + +### 1. Instantiation Phase + +#### Service Instantiation: + +- **Configuration:** Configure the network service according to the specifications including the user requirements from the service order, ensuring that all components are correctly set up to provide the desired service. +- **Resource Allocation - Feasibility check:** Allocate the necessary physical and virtual resources based on the service specification. This includes any containerized resources, virtual network functions (VNFs) and software-defined networking (SDN) components. (This step is not performed in OpenSlice) +- OpenSlice Service Orchestrator creates the services at "RESERVED" state +- **User Notification:** There could be an email notification from the system (if Bugzilla is configured) + +#### Service Deployment: + +- **Activation:** OpenSlice Service Orchestrator activates the network service and makes the service available to the end-users. This may involve: + - Create any related services that the service depends on + - Contacting all related controllers during provisioning, e.g. Kubernetes controllers, Kubernetes operators, MANO Orchestrators, RAN controllers, SDN Controlles, or other external services (e.g. via REST calls) + - Scheduling instantiation, Resolving dependencies and passing paramemters between controllers, + - setting up user accounts, provisioning access credentials -this is performed either offline or via other services. +- OpenSlice Service Orchestrator if everything is succesful puts the service at "ACTIVE" state +- **User Notification:** There could be an email notification from the system (if Bugzilla is configured) + +### 2. Operation Phase + +#### Service Operation: + +- **Lifecycle Management:** Manage the network slice throughout its lifecycle, including scaling, reconfiguration, and adaptation to changing requirements. +- In OpenSlice this is performed with Lifecycle management Rules (see next) + +In this phase the Service Designer can define several aspects. **Be aware that these are NOT performed automatically by OpenSlice - further examples and future enhancements will address these**. This could include: + +- **Monitoring:** Continuously monitor the service for performance, availability, and compliance with SLAs. Utilize tools for real-time tracking and alerts for any anomalies or performance degradation. +- **Maintenance:** Conduct regular maintenance activities, including software updates, patching, and optimization to ensure the service runs smoothly. +- **Scaling:** Dynamically scale the resources up or down based on the demand and performance requirements. +- **Fault Management:** Detect and resolve faults in the network slice to minimize downtime and maintain service quality. + +### 3. Decommissioning Phase + +- **Service Termination:** Service Orchestrator terminates the network service. This may involve: + - Terminate any related services that the service depends on + - Contacting all related controllers during termination to release resources, e.g. Kubernetes controllers, Kubernetes operators, MANO Orchestrators, RAN controllers, SDN Controlles, or other external services (e.g. via REST calls) + - Scheduling termination, Resolving dependencies and passing paramemters between controllers +- OpenSlice Service Orchestrator, if everything is succesful, puts the service at "TERMINATED" state +- **User Notification:** There could be an email notification from the system (if Bugzilla is configured) + +### High level example: Enhanced Mobile Broadband (eMBB) Service Lifecycle + +1. **Preparation:** + + - Define eMBB service requirements for high bandwidth and low latency. + - Create an eMBB service specification template specifying related services and resources to Kubernetes Operators, VNFs for content delivery and traffic management. + - Expose to catalog + +2. **Instantiation:** + + - Instantiate other services and allocate resources such as edge computing nodes and high-capacity links. + - Configure the service to prioritize video streaming traffic. + +3. **Operation:** + + - Monitor the service to ensure it meets high-bandwidth requirements. + - Scale up resources during peak usage periods, such as live sports events. + +4. **Decommissioning:** + + - Notify users about service termination. + - Decommission the network service, reclaiming resources for other services. + + +## Probe further + +* See 3GPP [Lifecycle](https://portal.3gpp.org/desktopmodules/Specifications/SpecificationDetails.aspx?specificationId=3091) \ No newline at end of file diff --git a/doc/naas/lcm_rules_intro.md b/doc/naas/lcm_rules_intro.md new file mode 100644 index 0000000000000000000000000000000000000000..f7d70588e8a9b783d071a147571db4d57183fe95 --- /dev/null +++ b/doc/naas/lcm_rules_intro.md @@ -0,0 +1,60 @@ +# Lifecycle Management Rules - LCM Rules + + +Lifecycle Management Rules: Defining complex conditions and actions during the lifecycle of a service and any necessary modifications throughout the service lifecycle. + + +## Intended Audience: Service Designers + + OpenSlice end-to-end (E2E) service orchestrator follows some predefined workflows to manage a service lifecycle (They are described in BPMN language and included in our orchestration engine) + + So in the system there are already predefined recipes, which in each process-step of the workflow some piece of code is executed. + + How is it possible to intervene in the workflow process and inject some user defined actions? The next image illustrates the idea + +[![lcm](./lcm/img02.png)](./lcm/img02.png) + +## How is it possible to intervene in the workflow process and affect it? + +LCM Rules are used for defining complex conditions and actions during the lifecycle of a service. In Openslice there are the following types of rules defined: + +* PRE_PROVISION +* CREATION +* AFTER_ACTIVATION +* SUPERVISION +* AFTER_DEACTIVATION + +The following figure displays the different phases that the rules are performed, during the lifecycle of a Network Service Instance. + + +[![lcm](./lcm/img03.png)](./lcm/img03.png) + + +* PRE_PROVISION rules: Run only once just before creating a service with a given priority. +* CREATION rules: Run while the referenced service dependencies of a service are created +* AFTER_ACTIVATION rules: Run only once just after a service get the ACTIVE state +* SUPERVISION rules: Run when a characteristic of a service is changed and the service is in the ACTIVE state +* AFTER_DEACTIVATION rules: Run only once just after a service get the INACTIVE/TERMINATED state + +In general the rules allow to perform many actions during service LCM. These are some examples: + +* Modify service specification parameters before the instantiation of a service (or during operation) based on other dependencies. These parameters might be part of other services already included in Service order +* Translate GST/NEST parameter values to other values passed later to NFVO for instantiation or control +* Define complex OSM Configs based on other dependencies and passing variables +* Define any dependencies when creating the referenced services +* Dynamically include new service dependencies +* Create new service orders so include dynamically other services +* Call external (RESTful) services (via http(s), define payload, examine response) + + + + +## Examine if the rules are executed successfully + +Rules are transformed automatically to executable code (currently is Java). If a rule is performed successfully or has any issues (e.g. unexpected syntax errors or exceptions) appear in OSOM logfiles and also tey are attached as Notes to the running Service. + + +## Probe further + +* In the [Service Design](../service_design/intro.md) section we present in details the Lifecycle rules and how one can design them +* Many of them are used in our provided Service Design [examples](../service_design/examples/intro.md) \ No newline at end of file diff --git a/doc/naas/nfv/intro.md b/doc/naas/nfv/intro.md new file mode 100644 index 0000000000000000000000000000000000000000..a376782caed3846b81cc0dcb45f3e5903d068a7f --- /dev/null +++ b/doc/naas/nfv/intro.md @@ -0,0 +1 @@ +_This section is WIP._ \ No newline at end of file diff --git a/doc/naas/nfv/nfvcatalogs.md b/doc/naas/nfv/nfvcatalogs.md new file mode 100644 index 0000000000000000000000000000000000000000..a376782caed3846b81cc0dcb45f3e5903d068a7f --- /dev/null +++ b/doc/naas/nfv/nfvcatalogs.md @@ -0,0 +1 @@ +_This section is WIP._ \ No newline at end of file diff --git a/doc/nfvcatalogs.md b/doc/naas/nfv/nfvservices.md similarity index 65% rename from doc/nfvcatalogs.md rename to doc/naas/nfv/nfvservices.md index ad055840d65abfe337af4a5b60a3e7e10097ec42..ffa454d73d891e3ede7e9f2287878f929fc8f333 100644 --- a/doc/nfvcatalogs.md +++ b/doc/naas/nfv/nfvservices.md @@ -1,16 +1,16 @@ # NFV Services -NFV Services are managed through a dedicate UI the NFV portal (eg http://portal.openslice.io/nfvportal) +NFV Services are managed through a dedicated UI, i.e. the NFV portal (eg., [http://portal.openslice.io/nfvportal](http://portal.openslice.io/nfvportal)). -Users are able through this portal to manage their NFV artifacts towards the NFVO, ( for example onboard VNFs and NSDs to a target OSM) +Users are able through this portal to manage their NFV artifacts towards the NFVO (for example onboard VNFs and NSDs to a target OSM). -Openslice NFV Services target to accommodate the following envisaged user roles. All users are assumed to be Authenticated: +OpenSlice NFV Services target to accommodate the following envisaged user roles. All users are assumed to be Authenticated: -* NFV developer: This role is responsible to upload VNF and NSD Descriptors in the Openslice services towards NFVO like OSM -* Services administrator: This role represents the user that are responsible for maintenance of the Openslice services +* NFV developer: This role is responsible to upload VNF and NSD Descriptors in the OpenSlice services towards NFVO, like OSM +* Services administrator: This role represents the user that are responsible for maintenance of the OpenSlice services -(obsolete: ) +(obsolete:) * Testbed provider: This role represents users that are responsible for testbed administration, configuration, integration, adaptation, support, etc * Experimenter: This role represents the user that will utilize our services and tools to deploy an experiment. That is the experiment description in terms of e.g.: NSD (Network Service Descriptor) or TOSCA Specification (in future versions) @@ -21,12 +21,12 @@ Finally an anonymous user role exists who has some really simple usage scenarios During the onboarding process the following occurs: -• A NFV developer submits a NFV archive (VNF or NSD) (he can later manage if needed some metadata) -• The administrator can manage the NFV artifact (e.g. edit it) -• The administrator On-Boards the NFV artifact to the target MANO -• The administrator can optionally mark the NFV: -o As public in order to be publicly visible by all portal users -o As Certified which means this is certified by a certain entity +- A NFV developer submits a NFV archive (VNF or NSD) (he can later manage if needed some metadata) +- The administrator can manage the NFV artifact (e.g. edit it) +- The administrator On-Boards the NFV artifact to the target MANO +- The administrator can optionally mark the NFV: +- As public in order to be publicly visible by all portal users +- As Certified which means this is certified by a certain entity ## Request a new NSD deployment (this is different in comparison to Services) diff --git a/doc/naas/resource_catalog.md b/doc/naas/resource_catalog.md new file mode 100644 index 0000000000000000000000000000000000000000..145f67956aa8956dcdb5a91cb2cfe3604aca69ca --- /dev/null +++ b/doc/naas/resource_catalog.md @@ -0,0 +1,8 @@ + + +#OpenSlice Resource Catalog: + + * Resource Specifications: Defines the underlying resources required to deliver services, such as network components, servers, and software. + * Resource Availability: Tracks the availability and status of resources to ensure efficient service delivery. + +_This section is WIP._ \ No newline at end of file diff --git a/doc/naas/resource_inventory.md b/doc/naas/resource_inventory.md new file mode 100644 index 0000000000000000000000000000000000000000..a376782caed3846b81cc0dcb45f3e5903d068a7f --- /dev/null +++ b/doc/naas/resource_inventory.md @@ -0,0 +1 @@ +_This section is WIP._ \ No newline at end of file diff --git a/doc/naas/resource_spec.md b/doc/naas/resource_spec.md new file mode 100644 index 0000000000000000000000000000000000000000..a376782caed3846b81cc0dcb45f3e5903d068a7f --- /dev/null +++ b/doc/naas/resource_spec.md @@ -0,0 +1 @@ +_This section is WIP._ \ No newline at end of file diff --git a/doc/naas/service_catalog.md b/doc/naas/service_catalog.md new file mode 100644 index 0000000000000000000000000000000000000000..a11afbbd2e925e09815aa3e21b932a2ce01e51d3 --- /dev/null +++ b/doc/naas/service_catalog.md @@ -0,0 +1,51 @@ +# OpenSlice Service Catalogs + +OpenSlice offers complete management of Service Catalogs. + +## Intended Audience: Service Designers, OpenSlice administrators, Users + + +OpenSlice offers complete management of Service Catalogs which offer to end users: + +* Service categories: Lists the available services, including their specifications and performance metrics. +* Service Bundles: Combines multiple services into a single offering to provide added value to customers. + +Service Catalogs contain Service Specifications (organized in Service Categories) exposed to users for Service Orders. + + +## UI management + +In the UI this looks like the following. Service catalogs and categories exposed in Service marketplace. + +In the menu the administrator can manage the Service Catalogs and Categories. + +[![img01](./service_catalog/img01.png)](./service_catalog/img01.png) + + +## API exposed + +When installing OpenSlice the API endpoints can be browsed at: +``` +[YOURDOMAIN]/tmf-api/swagger-ui/index.html?urls.primaryName=tmf-api-633-ServiceCatalogManagement-v4.0.0 + +endpoint examples: + +/serviceCatalogManagement/v4/serviceCatalog List or find ServiceCatalog objects +/serviceCatalogManagement/v4/serviceCategory List or find ServiceCategory objects + +``` + +## Example Use Case + +Scenario: A service provider wants to offer a new managed XXXX service to enterprise customers. + + * Service Definition: Service Template thus create a template for the XXXX service, including specifications for bandwidth, network features, and performance metrics. + * Service Catalog Integration: Add to Service Catalog the XXXX service with all relevant details. + * Service Delivery/Order: Provision Service by Using the orchestration system to provision and configure the XXXX service based on customer orders. + + +## Probe further + +* Read the model of Service Catalogs in TMF [TMF633 Service Catalog API User Guide v4.0.0](https://www.tmforum.org/resources/specification/tmf633-service-catalog-api-user-guide-v4-0-0/) +* Check a demo of the API [here](http://portal.openslice.io/tmf-api/swagger-ui/index.html?urls.primaryName=tmf-api-633-ServiceCatalogManagement-v4.0.0) +* Check a demo of the Catalog and Categories [here](http://portal.openslice.io) \ No newline at end of file diff --git a/doc/naas/service_catalog/img01.png b/doc/naas/service_catalog/img01.png new file mode 100644 index 0000000000000000000000000000000000000000..84e3830dd98c49ff6177f914e84ea82b027e5410 Binary files /dev/null and b/doc/naas/service_catalog/img01.png differ diff --git a/doc/naas/service_inventory.md b/doc/naas/service_inventory.md new file mode 100644 index 0000000000000000000000000000000000000000..f162b499292af5137873ac24baa81fcc2ac3b870 --- /dev/null +++ b/doc/naas/service_inventory.md @@ -0,0 +1,35 @@ +# Service Inventory + +Service Inventory contains references to running services that realize a Service Order. + +## Intended Audience: Service Designers, OpenSlice administrators, Users + + +The Service Inventory is a repository that maintains detailed records of all active services and the underlying resources that support them. It acts as a central repository, tracking the lifecycle of each service from provisioning to decommissioning, and includes references to the specific virtual and physical resources that realize the service, such as servers, network components, storage, and software instances. + +This inventory enables real-time visibility into the status, configuration, and dependencies of each service, facilitating effective management, troubleshooting, and optimization. + +By providing a view of the active services, the Service Inventory includes services/resource allocation, and ensures that services are delivered in alignment with the initial request. + + +## UI management + +Through the menu and dedicated forms the administrator can manage the Service Inventory and any active Services (reconfigure or terminate).Various examples in this document will guide you to the usage and the management of the Services in Service Inventory. + +## API exposed + +When installing OpenSlice the API endpoints can be browsed at: +``` +[YOURDOMAIN]/tmf-api/swagger-ui/index.html?urls.primaryName=tmf-api-638-ServiceInventoryManagement-v4.0.0 +``` + +endpoint examples: + +/serviceInventory/v4/service List or find Service objects + + +## Probe further + +* See [Ordering Services from catalogs](../service_ordering/ordering_services.md) +* See [Service Design](../service_design/intro.md) + diff --git a/doc/naas/service_ordering.md b/doc/naas/service_ordering.md new file mode 100644 index 0000000000000000000000000000000000000000..29584172298d6851fed7ad1e988880e77650bd8f --- /dev/null +++ b/doc/naas/service_ordering.md @@ -0,0 +1,43 @@ +# Service Ordering + +Customer Facing Service Specifications - or also CFSSpec (organized in Service Categories) are exposed to users for Service Orders. + +## Intended Audience: Service Designers, OpenSlice administrators + + +The Service Order process is a structured sequence of steps initiated by a customer's Service Order request for a specific service, aimed at delivering and activating the desired service or services (if it is a service bundle), as well as its related services. It begins with the customer submitting a service request through OpenSlice Services portal or the Service Order API, specifying the necessary details such as service specification, configurations, and any specific requirements. + +The request is then validated and verified for completeness and eligibility by an administrator which marks the Service Order as ACKNOWLEDGED otherwise it rejects it. + +Once ACKNOWLEDGED, the service order is processed by OpenSlice orchestration system (OSOM), which schedules/automates the provisioning of the required resources and configurations, coordinating across various components such as MANO controlers for virtual network functions (VNFs), or Containerized controllers or any 3rd party controllers or services or even physical infrastructure. The OpenSlice orchestration system ensures that all dependencies are managed and that the service is correctly configured. + +After provisioning, the service is activated and handed over to the customer, . This end-to-end process ensures a seamless, efficient, and automated delivery of services, enhancing customer satisfaction and operational efficiency. + +Ongoing monitoring and other actions can be performed by the Life Cycle management rules + + +***Future developments***: +In future releases it might be possible the ongoing monitoring and support provided to ensure continuous performance and reliability. The service could undergo a series of tests to ensure it meets the specified performance metrics and SLAs before delivering + +## UI management + +Through the menu and dedicated forms the administrator can manage the Service Orders. Various examples in this document will guide you to the usage and the management of the Service Orders. + +## API exposed + +When installing OpenSlice the API endpoints can be browsed at: +``` +[YOURDOMAIN]/tmf-api/swagger-ui/index.html?urls.primaryName=tmf-api-641-ServiceOrdering-v4.0.0 +``` + +endpoint examples: + +/serviceOrdering/v4/serviceOrder List or find ServiceOrder objects + + + + +## Probe further + +* See [Ordering Services from catalogs](../service_ordering/ordering_services.md) +* See [Service Design](../service_design/intro.md) \ No newline at end of file diff --git a/doc/naas/service_spec.md b/doc/naas/service_spec.md new file mode 100644 index 0000000000000000000000000000000000000000..5a3289f205299a3f21197ac7e44e16254ab01099 --- /dev/null +++ b/doc/naas/service_spec.md @@ -0,0 +1,71 @@ +# OpenSlice Service Specification + +OpenSlice offers complete management of Service Specifications. + +## Intended Audience: Service Designers + +Service Specification is an entity that describes a service offering. There are two types of Service Specifications: + +* Resource Facing Service Specification +* Customer Facing Service Specification + +## Resource Facing Service Specification + +Is a Service that It exposes a resource Specification as a Service. (For example expose a Network Service Descriptor as a Service) + +## Customer Facing Service Specification + +Customer Facing Service Specifications - or also CFSSpec (organized in Service Categories) are exposed to users for Service Orders. Usually it exposes other CFSSpec(as a Service Bundle) or other RFSSpecs + +## Definition + +Usually a Service Specification has the following aspects: + +* Name, Description, Version +* Marked as a Service Bundle: Combines multiple services into a single offering to provide added value to customers. +* if is is a Bundle then you must add Related Service Specifications +* If it is a Resource Facing Service Specification has multiple related Resource Facing Service Specifications +* Characteristics: a list of service characteristics and their type (TEXT, INTEGER, etc) + * Also they can be exposed as "Configurable" so to allow to end-users during the Service Order to select or type values +* A logo, displayed if needed in the Service Marketplace +* Any attachments that further help the user +* Life Cycle Rules that determine the behavior of the Service and instrument the Service Orchestrator. More on Life Cycle Rules [here](./lcm_rules_intro.md) + +Service Designers can create a Service Specification from scratch or use some templates: + + * Create a Service based from a Network Service Descriptor (NSD) + * Create a Service based on a Kubernetes Operator + * Create a Service based on the GSMA GST - Generic Slice Template + +## UI management + +In the UI this looks like the following. + +Through the menu and dedicated forms the administrator can manage the Service Specifications. Various examples in this document will guide you to the usage and the design of the services. + +## API exposed + +When installing OpenSlice the API endpoints can be browsed at: +``` +[YOURDOMAIN]/tmf-api/swagger-ui/index.html?urls.primaryName=tmf-api-633-ServiceCatalogManagement-v4.0.0 +``` + +endpoint examples: + +/serviceCatalogManagement/v4/serviceSpecification List or find ServiceSpecification objects + + + +## Example Use Case + +Scenario: A service provider wants to offer a new managed XXXX service to enterprise customers. + + * Service Definition: Create a service specification template for the XXXX service, including specifications for bandwidth, network features, and performance metrics. + + +## Probe further + +* Read the model of Service Catalogs in TMF [TMF633 Service Catalog API User Guide v4.0.0](https://www.tmforum.org/resources/specification/tmf633-service-catalog-api-user-guide-v4-0-0/) +* Check a demo of the API [here](http://portal.openslice.io/tmf-api/swagger-ui/index.html?urls.primaryName=tmf-api-633-ServiceCatalogManagement-v4.0.0) +* Check a demo of the Service Specifications in Catalog and Categories [here](http://portal.openslice.io) (You need to login - see main guide page) +* Check the GSMA GST \ No newline at end of file diff --git a/doc/naas/so/img01.png b/doc/naas/so/img01.png new file mode 100644 index 0000000000000000000000000000000000000000..a43930df2be8db5257b4d8e43ff419c9b9837314 Binary files /dev/null and b/doc/naas/so/img01.png differ diff --git a/doc/naas/so/service_specification_instantiation.png b/doc/naas/so/service_specification_instantiation.png new file mode 100644 index 0000000000000000000000000000000000000000..4bdaea9b5ac8702a2dfd801d7c85669c8cba8a97 Binary files /dev/null and b/doc/naas/so/service_specification_instantiation.png differ diff --git a/doc/so_ServiceCreationProcess.pu b/doc/naas/so/so_ServiceCreationProcess.pu similarity index 100% rename from doc/so_ServiceCreationProcess.pu rename to doc/naas/so/so_ServiceCreationProcess.pu diff --git a/doc/so_activity_main.pu b/doc/naas/so/so_activity_main.pu similarity index 100% rename from doc/so_activity_main.pu rename to doc/naas/so/so_activity_main.pu diff --git a/doc/naas/so_intro.md b/doc/naas/so_intro.md new file mode 100644 index 0000000000000000000000000000000000000000..7e454bc6a411afdcb4af8c49b2462961cb661637 --- /dev/null +++ b/doc/naas/so_intro.md @@ -0,0 +1,18 @@ +# Service Orchestration + +Definition: The orchestration engine evaluates the request, determines the necessary resources, and initiates the automated workflows.It interacts with underlying controller components (e.g. 5G Core, Radios, Containerized controllers, NFV, SDN controllers) to provision and configure the required network functions and connectivity. + +## Intended Audience: Service Designers + +OpenSlice end-to-end (E2E) service orchestration framework is designed to manage and automate the entire lifecycle of services across multiple domains and technologies. For delivering, Network as a Service (NaaS) OpenSlice automates and manages the entire lifecycle of network services, from provisioning to monitoring and decommissioning, while ensuring seamless integration, operation, and delivery of services from the initial request to the final delivery, spanning all involved components and layers. + +As next image depicts, service orchestrators follow some predefined workflows. OpenSlice end-to-end (E2E) service orchestrator follows some predefined workflows to manage a service lifecycle (They are described in BPMN language and included in our orchestration engine). + +[![SO](./so/img01.png)](./so/img01.png) + +This section provides a high level overview of the Service Orchestration process. + + + + + diff --git a/doc/naas/so_servicespec_to_services_kubernetes.md b/doc/naas/so_servicespec_to_services_kubernetes.md new file mode 100644 index 0000000000000000000000000000000000000000..a376782caed3846b81cc0dcb45f3e5903d068a7f --- /dev/null +++ b/doc/naas/so_servicespec_to_services_kubernetes.md @@ -0,0 +1 @@ +_This section is WIP._ \ No newline at end of file diff --git a/doc/service_inventory.md b/doc/naas/so_servicespec_to_services_nfv.md similarity index 91% rename from doc/service_inventory.md rename to doc/naas/so_servicespec_to_services_nfv.md index 480b92f111424c67ab3b4efbba089f4339ddb732..7ca3911dae86d5bf9b704184d11415fda1dac81f 100644 --- a/doc/service_inventory.md +++ b/doc/naas/so_servicespec_to_services_nfv.md @@ -1,4 +1,4 @@ -# Service Inventory +# From Service Specification to NFV based services After a Service Order completion, active services with their additional characteristics are found: @@ -10,7 +10,7 @@ After a Service Order completion, active services with their additional characte Openslice creates a Service for the requested CFS. Customers make Service Orders and Openslice instantiates the requested Service Specifications for each Service Order Item of a Service Order. Running Services instantiated by Openslice, reside in Openslice Service Inventory. The following picture displays how Service Specifications are related to Running Services and how Running Services relate with instantiated running Network Services. -[![Openslice Service Specification instantiation](./images/service_specification_instantiation.png)](./images/service_specification_instantiation.png) +[![Openslice Service Specification instantiation](./so/service_specification_instantiation.png)](./so/service_specification_instantiation.png) There is a hierarchy of services. Usually an Instantiated CFS has Supporting Services some Instantiated RFSs. Then an Instantiated RFS is related to some running NS managed by NFVO diff --git a/doc/nfvoconfig.md b/doc/nfvoconfig.md index 91efd366f981905fa7cd16fdf3838b2c6954c4ed..0cd2c77887fb274c77f845082213436dd302f309 100644 --- a/doc/nfvoconfig.md +++ b/doc/nfvoconfig.md @@ -1,19 +1,22 @@ # NFV Orchestrator configuration -NOTE: Currently we support Open Source MANO version SEVEN/EIGHT/TEN/ELEVEN. Later versions of OSM may also be supported by the existing configuration, as from OSM 9+ the project converged to the SOL005 interface, regarding the NBI, and SOL006 (YANG model), regarding the NFV/NSD packaging. Also an implementation of a generic SOL005 interface is supported, but not extensively tested. +> Currently we support Open Source MANO version EIGHT/NINE/TEN/ELEVEN/THIRTEEN. Later versions of OSM may also be supported by the existing configuration, as from OSM 9+ the project converged to the SOL005 interface, regarding the NBI, and SOL006 (YANG model), regarding the NFV/NS packaging. Also an implementation of a generic SOL005 interface is supported, but not extensively tested. Configuration of your target(s) NFVOs/MANO services with Openslice is performed through the NFV portal. -Login to http://yourdomain/nfvportal/ +1. Login to {{yourdomain}}/nfvportal/ -Navigate to Admin->Manage MANO Platforms and pick one of the supported MANO platform(s), e.g. Name=OSMvTEN, Version=OSMvTEN and save +2. Navigate to Admin > Manage MANO Platforms > Add New MANO Platform, pick one of the supported MANO platform(s), e.g. Name=OSMvTHIRTEEN, Version=OSMvTHIRTEEN and save. You may edit the saved MANO platforms after this. -Navigate to Admin->Manage MANO providers and enter a New MANO Provider: +3. Navigate to Admin > Manage MANO providers > Add New MANO Provider and enter its details: -* Name whatever you wish -* API URL Endpoint, eg: https://10.10.10.10:9999 (This is the SOL005 NBI endpoint) -* Username, password and Project of your OSM tenant. + - Name and description of your choice. The selected name will supplement the NFV artifacts of this provider. + - One of the already defined MANO platforms + - API URL Endpoint, eg: https://10.10.10.10:9999 (This is the SOL005 NBI endpoint - *Note the port 9999*) + - Username, Password and Project of your OSM tenant. -Check EnabledForONBOARDING, so when users onboard VNFs/NSDs they will be automatically ONBOARDED to this MANO. If left unchecked, the onboarding must be performed manually after the VNF/NSD is uploaded to the portal. +Check EnabledForONBOARDING, if you want VNF/NS packages uploaded through the UI by the user, to also be automatically ONBOARDED to this MANO (1 step process). If left unchecked, the onboarding process must be performed manually after the VNF/NS package is uploaded to the portal, by the designated UI (2 step process). -Check EnabledForSYNC, if you want to support MANO->Openslice auto synchronization. When enabled, the existing VNFs/NSDs and VIMs (and any updates on them) of the registered MANO are also reflected to the portal. \ No newline at end of file +Check EnabledForSYNC, if you want to support the automatic synchronization of this MANO with OpenSlice. When enabled, the existing VNF/NS packages and VIMs (and any updates on them) of the registered MANO are also reflected to the portal to the respective UIs (Registered VNFs/NSDs and Manage Infrastructures). + +The synchronization is a continuous process that will confirm that the artifacts are still present in the MANO, updating the status field of the respective artifacts to `OSM_PRESENT`. If during this process, an artifact is deleted from the MANO, the respective status field will be updated to `OSM_MISSING`. \ No newline at end of file diff --git a/doc/ole_keycloak_management.md b/doc/ole_keycloak_management.md new file mode 100644 index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391 diff --git a/doc/architecture/tmfweb.md b/doc/portals_intro.md similarity index 68% rename from doc/architecture/tmfweb.md rename to doc/portals_intro.md index 729eed65fa1833982885623ca9108e67b44ab20c..995cb5de8a59be612e8663b45ba9e4cfb65be441 100644 --- a/doc/architecture/tmfweb.md +++ b/doc/portals_intro.md @@ -1,20 +1,32 @@ -# Openslice TMF Web Portal +# OpenSlice Portals -Openslice comprises of a [web landing page](http://portal.openslice.io/) that navigates to the respective TMF Portal. +OpenSlice comprises of a web landing page [(See Demo)](http://portal.openslice.io/) that navigates to the respective Portals: -- [Services Portal](http://portal.openslice.io/services) -- [Products Portal](http://portal.openslice.io/products) -- [Testing Portal](http://portal.openslice.io/testing) -- [Resources Portal](http://portal.openslice.io/resources) +- Services Portal [(See Demo)](http://portal.openslice.io/services) +- NFV Portal [(See Demo)](http://portal.openslice.io/nfvportal) +- Products Portal [(See Demo)](http://portal.openslice.io/products) +- Testing Portal [(See Demo)](http://portal.openslice.io/testing) +- Resources Portal [(See Demo)](http://portal.openslice.io/resources) -The landing page and the TMF portals (Services, Products, Testing, Resources) are written in Angular and are maintained under the same Angular project. -Following you may find the scope each portal focuses on and the main TMF APIs it supports. +Following you may find the scope each portal focuses on and the main TMF APIs it supports: **Services Portal** is a designated portal for the: - Service Designer - To design Customer Facing Services as bundles of Resource Facing Services that map to specific Resourses (e.g. NFV, Testing, General Resources). Then, it is charged with the designed Services' exposure to public Service Catalogs. - Service Customer - To browse the public Service Catalogs and order the offered Services. The fulfilment process of the Service Order is also captured and the final deployed Services are exposed to the Customer. +**NFV Portal** is a designated portal for the: +Indicatively, the portal can be used to: +- Register new a new MANO provider (e.g. OSM) +- Synchronize the onboarded VNF/NS packages, and the VIMs of the registered MANO provider +- Onboard/Delete VNF/NS packages on specific MANO provider +- Deploy a NS to a target MANO provider + +More information can be found at [NFV Services](./naas/nfv/nfvservices.md). + +**Resources Portal** is a designated portal for the: +- Resource Administrator - To view the available Resources that are being synchronized from the underlying infrastructure. +- **Products Portal** is a designated portal for the: - Product Designer - To design Products as bundles of available Services. Then, it is charged with the designed Products' exposure to public Product Catalogs. - Product Customer - To browse the public Product Catalogs and navigate to the respective offered Services. @@ -22,9 +34,6 @@ Following you may find the scope each portal focuses on and the main TMF APIs it **Testing Portal** is a designated portal for the: - Testing Designer - To design Tests and provide the testing scripts as attachments to the latter. The Tests can be imported as Services at the Services Portal, and can be included in a Service Bundle. -**Resources Portal** is a designated portal for the: -- Resource Administrator - To view the available Resources that are being synchronized from the underlying infrastructure. - @@ -35,5 +44,4 @@ Following you may find the scope each portal focuses on and the main TMF APIs it |**Testing Portal** | |x | | | | | | | |x | | |**Resources Portal** | |x | |x | |x | | | | |x | - -From the landing page, the user can also navigate towards the NFV portal. See [NFV WEB](./nfvweb.md). \ No newline at end of file +The NFV Portal uses a proprietary API. \ No newline at end of file diff --git a/doc/role_keycloak_management.md b/doc/role_keycloak_management.md new file mode 100644 index 0000000000000000000000000000000000000000..153d5c312b3b30b8020097d6dd2a0346446c3e3c --- /dev/null +++ b/doc/role_keycloak_management.md @@ -0,0 +1,11 @@ +# Role management in Keycloak + +Some initial configuration of Keycloak happens at Installation/Deployment time. Here are some notes regarding user management + +## Intended Audience: OpenSlice administrators + +There are cases that OpenSlice administrators need to configure Keycloak: + +* Change user roles, e.g. make a Simple user a Service Designer +* Domain management +* User Password reset \ No newline at end of file diff --git a/doc/catalogs.md b/doc/service_design/catalogs.md similarity index 69% rename from doc/catalogs.md rename to doc/service_design/catalogs.md index 3b3538d0b5dcaedf1690154bea22e70caf85551b..ebaf24fc0d524ce6729038ae6dadfca2d02752c0 100644 --- a/doc/catalogs.md +++ b/doc/service_design/catalogs.md @@ -96,35 +96,6 @@ Openslice offers the GST in a format that is machine readable and aligned with t Providers can clone a GST as e NEST directly in Openslice Web portal and the adjust the default attributes to their Service Specification -### 5G-VINNI Service Blueprint -(Offered only as a design for now. THere is no direct implementation to NFV) -5G-VINNI Service Blueprint is a special Service Specification defined by teh 5G-VINNI project. Many details can be found in document - -5G-VINNI Service Blueprint is a reusable self-contained specification of required network slice service (instances). As described in GST mapping VINNI-SB is also machine readable. - -Here is a tentative approach in JSON : - -5G-VINNI SB has many commonalities with GST as well as it offers Testing as a Service attributes. - - Next figure presents the high-level object model of a 5G-VINNI service blueprint. - -The 5G-VINNI SB as a first prototype approach is conceived as a CFS of a ‘bundle’ of services. It has some characteristics, like name, description, service type (eMBB, etc) and others. The constituent services are: - -- A “Service Topology” Service Specification which is related to a Network Service Resource topology (a Logical Resource Spec). It is considered at this stage as an RFS but is subject to change in future -- A “VINNI SB Service Requirements” Service Specification which is related to Service requirements. This is very similar to GST. It is considered at this stage a CFS. -- A “VINNI SB Service Exposure Level 1” Service Specification which contains characteristics for service exposure on level 1 ( see D3.1 for details). It is considered at this stage a CFS. -- A “VINNI SB Service Exposure Level 2” Service Specification which contains characteristics for service exposure on level 2. It is considered at this stage a CFS. -- A “VINNI SB Service Exposure Level 3” Service Specification which contains characteristics for service exposure on level 3. It is considered at this stage a CFS. -- A “VINNI SB Service Exposure Level 4” Service Specification which contains characteristics for service exposure on level 4. It is considered at this stage a CFS. -- A “VINNI SB Service 3rd part VNF” Service Specification which contains characteristics for support 3rd party VNFs to be included in the service. It is considered at this stage as an RFS but is subject to change in future -- A “VINNI SB Service 3rd part NSD” Service Specification which contains characteristics for support 3rd party NSDs to be included in the service. It is considered at this stage as an RFS but is subject to change in future -- A “VINNI SB Service Monitoring” Service Specification which contains characteristics for offering Monitoring capabilities on the requested Service. It is considered at this stage a CFS. -- A “VINNI SB Service Testing” Service Specification which contains characteristics for offering Testing capabilities on the requested Service. It is considered at this stage a CFS. - - -[![VINNI SB Template Model diagram](../images/vinni_sb_model_diagram.png)](../images/vinni_sb_model_diagram.png) - - ## Manage a Service Specification You can manage them though the Web UI @@ -142,6 +113,6 @@ Delete it from the category ## Consume and expose Service Specifications from other Service Catalogues -See more on [Consuming Services From External Partner Organizations](./architecture/consumingServicesFromExternalPartners.md) +See more on [Consuming Services From External Partner Organizations]( ../architecture/consumingServicesFromExternalPartners.md ) diff --git a/doc/service_design/examples/ExposingCRDs_aaS_Example_Calculator/ExposingCRDs_aaS_Example_Calculator.md b/doc/service_design/examples/ExposingCRDs_aaS_Example_Calculator/ExposingCRDs_aaS_Example_Calculator.md new file mode 100644 index 0000000000000000000000000000000000000000..6d9dd1525590a20b982dee72b212e0d230d5fff5 --- /dev/null +++ b/doc/service_design/examples/ExposingCRDs_aaS_Example_Calculator/ExposingCRDs_aaS_Example_Calculator.md @@ -0,0 +1,271 @@ + +# Exposing Kubernetes Operators as a Service : Offering "Calculator as a Service" through OpenSlice + +## Intended Audience: Service Designers + + +> To illustrate the powerful concept of Kubernetes operators and how they can be utilized to offer a service through OpenSlice, let's provide an example of a "Calculator as a Service." + +> This example will demonstrate the flexibility and capabilities of Kubernetes operators in managing custom resources and automating operational tasks. + + +--- +## Offering "Calculator as a Service" through OpenSlice + +- We have a service that can accept two integers and an action (SUM, SUB, etc) and returns a result +- We would like to offer it as a Service through OpenSlice +- So when a user orders it with some initial parameters, OpenSlice will create it and return the result +- Also while the service is active, we can do further calculations, until we destroy it. + + +Assume the following simple CRD of a calculator model accepting two params (spec section) and an action and returning a result (status section) + +The controller (the calculator code) is implemented in any language and is installed in a Kubernetes cluster + +``` + +apiVersion: apiextensions.k8s.io/v1 +kind: CustomResourceDefinition +metadata: + name: mycalculators.examples.osl.etsi.org +spec: + group: examples.osl.etsi.org + names: + kind: MyCalculator + plural: mycalculators + singular: mycalculator + scope: Namespaced + versions: + - name: v1alpha1 + schema: + openAPIV3Schema: + properties: + spec: + properties: + parama: + type: integer + paramb: + type: integer + action: + type: string + type: object + status: + properties: + result: + type: integer + status: + type: string + type: object + type: object + served: true + storage: true + subresources: + status: {} +``` + + +Request to the cluster (through e.g. kubectl apply) + +``` +apiVersion: examples.osl.etsi.org/v1alpha1 +kind: MyCalculator +metadata: + name: mycalculator.examples.osl.etsi.org +spec: + parama: 170 + paramb: 180 + action: 'SUM' + +``` + +Response + +``` +apiVersion: examples.osl.etsi.org/v1alpha1 +kind: MyCalculator +metadata: +  creationTimestamp: '2023-12-05T12:26:07Z’ + + + +status: +  result: 350 +  status: CALCULATED +spec: +  action: SUM +  parama: 170 +  paramb: 180 + +``` + +To perform this through OpenSlice as a Service Specification ready to be ordered we need to do the following: + +--- +### CRD is saved automatically as Resource Specification + +As soon as the CRD is deployed in the cluster (e.g. by your admin via kubctl or via any installation through the internet) it is automatically transformed and is available in OpenSlice catalogs as a Resource Specification. + +- See also the fully qualified name of the resource specification. + - MyCalculator@examples.osl.etsi.org/v1alpha1@docker-desktop@https://kubernetes.docker.internal:6443/ + - The resource specification name is quite unique, so you can install the CRD in many clusters around the internet. Each CRD on each cluster will appear here, for example: + - MyCalculator@examples.osl.etsi.org/v1alpha1@default_cluster@https://10.10.10.8:6443/ + - MyCalculator@examples.osl.etsi.org/v1alpha1@edge1_cluster@https://172.16.10.10:6443/ + - Having this OpenSlice can manage resources in multiple clusters + + +![img07.png](./img07.png) + + +> See also the detailed characteristics. See how OpenSlice makes all characteristics automatically flat and expanded with key-value style + +![img08.png](./img08.png) + + +--- +# Expose to Users + +## Start by Creating a ResourceFacingServiceSpecification + +From the UI menu create a new Service Specification + + +![img09.png](./img09.png) + +![img10.png](./img10.png) + + + +### Creation of CRD-related characteristics + +- We need now to adjust some characteristics of this CRD as Resource Specification. +- OpenSlice transalted automatically the CRD spec in a flat list of characteristics.So the "spec" section from the original yaml for example, is now unfold into: spec, spec.parama, spec.paramb, etc. the same for "status" object +- We need to make OpenSlice aware of when the service will be active. + - So we go to characteristic _CR_CHECK_FIELD and we define that the field that shows the status of the service is the characteristic "status.status" (is a text field) + - Then we go to _CR_CHECKVAL_AVAILABLE and we define the value CALCULATED, which signals the following: When the characteristic "status.status" has the value "CALCULATED" then OpenSlice will mark the underlying service as "ACTIVE" + - We need also to define the yaml file that OpenSLice will use to create the new resource in the kubernetes cluster + - We insert the YAML in the characteristic _CR_SPEC + + the _CR_SPEC is: + +``` +apiVersion: examples.osl.etsi.org/v1alpha1 +kind: MyCalculator +metadata: + name: mycalculator.examples.osl.etsi.org +spec: + parama: 170 + paramb: 180 + action: 'SUM' + +``` + +![img11.png](./img11.png) + + + +> However the values are fixed. How do we allow a user to pass parameters through OpenSlice + +## Expose in Catalog + +Create a new CustomerFacingServiceSpecification + + - Go to the menu Service Specification>New Service Specification + - Create a service My Calulator and mark it as a Bundle + - Go to Service Specification Relationships and add MyCalculatorRFS + - The service will be automatically transformed to a "CustomerFacingServiceSpecification" + - Add the following characteristics as the image shows: + + +![cfs_img12.png](./cfs_img12.png) + + +### Allow users to pass new values through OpenSlice + + + +We need to Create LCM rules in CustomerFacingServiceSpecification: + + - The goal of the rules is to allow the user to pass parameters to the actual resource towards the cluster. + - we will create one rule that will pass the parameters just before creating the service (PRE_PROVISION phase) + - we will create one rule that will pass the parameters while the service is active (SUPERVISION phase) + - The rules will be the same + +![img12.png](./img12.png) + + + +If we see one rule it will look like the following: + + +![img13.png](./img13.png) + +- We need to change the _CR_SPEC characteristic of the referenced ResourceFacingServiceSpecification +- First bring a block from Service>Relationships>Service Refs and drop the "Service MyCalculatorRFS" block +- Then add a list block from Lists +- Then add the block that modifies a referenced characteristic from Service>Relationships>Service Refs the block "Set value to characteristic of a Referenced Service" +- Add a block for text _CR_SPEC +- We use a block that changes a String according to variables Text>"A formatted text replacing variables from List" +- See that we have as Input string the YAML string lines + - see that parama, paramb has a %d (they accept integers), action is %s (accepts a string) + - See that the variables tha will replace the %d, %d and %s are an list + - the first %d will be replaced with the value from characteristic spec.parama + - the second %d will be replaced with the value from characteristic spec.paramb + - the %s will be replaced with the value from characteristic spec.action + + + +If we see the SUPERVISION rule it will look like the following: + +- It contains also the Result field, which takes the value from the referenced service +- Add a block for the Result field from Service>Number blocks +- Add a str to int block from Number blocks +- Add Service>Relationships>Service Refs and drop the input block [Service MyCalculatorRFS] "Get Service details from current context running service" and select from the drop down the "serviceCharacteristicValue" +- Add as name the "status.result" + + +![img13_1.png](./img13_1.png) + + +![img14.png](./img14.png) + + + +Expose it then to a catalogue for orders through the Service Categories and Service Catalogs + + +![img15.png](./img15.png) + + + +### Order the Service + +When a user orders the service, it will look like this: + +![img16.png](./img16.png) + + + +- After the Service Order we have 2 services in service inventory on CFS and on RFS. Both have references to values +- OpenSlice (via CRIDGE service) updates the Resource in Resource Inventory and OSOM updates the Services in Service Inventory +- The Actual resources are running in the Kubernetes cluster managed by OpenSlice +- The result is in the characteristic status.result of the running service + + +![img17.png](./img17.png) + +![img18.png](./img18.png) + + +### Modify the running service + + The user can modify the service + + ![img19.png](./img19.png) + + + +- After a while the update is applied to the cluster, the controller will pick up the resource update and patch the resource +- OpenSlice (via CRIDGE service) updates the Resource in Resource Inventory and OSOM updates the Services in Service Inventory +- The result will be available to the respective characteristic "Result" after a few seconds, as need to go through various steps (OpenSlice orchestrator, down to kubernetes, to Calculator controller and back) + + ![img20.png](./img20.png) \ No newline at end of file diff --git a/doc/service_design/examples/ExposingCRDs_aaS_Example_Calculator/cfs_img12.png b/doc/service_design/examples/ExposingCRDs_aaS_Example_Calculator/cfs_img12.png new file mode 100644 index 0000000000000000000000000000000000000000..d3f55dad53fef145b49e720afd5a13140a097917 Binary files /dev/null and b/doc/service_design/examples/ExposingCRDs_aaS_Example_Calculator/cfs_img12.png differ diff --git a/doc/service_design/examples/ExposingCRDs_aaS_Example_Calculator/img07.png b/doc/service_design/examples/ExposingCRDs_aaS_Example_Calculator/img07.png new file mode 100644 index 0000000000000000000000000000000000000000..6990bf18122d41d5c3eee345270c4c18b5b0a1dc Binary files /dev/null and b/doc/service_design/examples/ExposingCRDs_aaS_Example_Calculator/img07.png differ diff --git a/doc/service_design/examples/ExposingCRDs_aaS_Example_Calculator/img08.png b/doc/service_design/examples/ExposingCRDs_aaS_Example_Calculator/img08.png new file mode 100644 index 0000000000000000000000000000000000000000..fdb27bf11096f00458a89586ae5efc2cb8e162b8 Binary files /dev/null and b/doc/service_design/examples/ExposingCRDs_aaS_Example_Calculator/img08.png differ diff --git a/doc/service_design/examples/ExposingCRDs_aaS_Example_Calculator/img09.png b/doc/service_design/examples/ExposingCRDs_aaS_Example_Calculator/img09.png new file mode 100644 index 0000000000000000000000000000000000000000..a6b963879355580e242b02b10e007e1434fdceb3 Binary files /dev/null and b/doc/service_design/examples/ExposingCRDs_aaS_Example_Calculator/img09.png differ diff --git a/doc/service_design/examples/ExposingCRDs_aaS_Example_Calculator/img10.png b/doc/service_design/examples/ExposingCRDs_aaS_Example_Calculator/img10.png new file mode 100644 index 0000000000000000000000000000000000000000..73d0ef7c9aaa5e56098c5fca4420fd6c50b8cd2a Binary files /dev/null and b/doc/service_design/examples/ExposingCRDs_aaS_Example_Calculator/img10.png differ diff --git a/doc/service_design/examples/ExposingCRDs_aaS_Example_Calculator/img11.png b/doc/service_design/examples/ExposingCRDs_aaS_Example_Calculator/img11.png new file mode 100644 index 0000000000000000000000000000000000000000..af0be10ddb844714a802343c3cef7d1231049355 Binary files /dev/null and b/doc/service_design/examples/ExposingCRDs_aaS_Example_Calculator/img11.png differ diff --git a/doc/service_design/examples/ExposingCRDs_aaS_Example_Calculator/img12.png b/doc/service_design/examples/ExposingCRDs_aaS_Example_Calculator/img12.png new file mode 100644 index 0000000000000000000000000000000000000000..47b924e5c384702fec7c911f194b45be001fe814 Binary files /dev/null and b/doc/service_design/examples/ExposingCRDs_aaS_Example_Calculator/img12.png differ diff --git a/doc/service_design/examples/ExposingCRDs_aaS_Example_Calculator/img13.png b/doc/service_design/examples/ExposingCRDs_aaS_Example_Calculator/img13.png new file mode 100644 index 0000000000000000000000000000000000000000..f97136493d1c2b6bca4c52a99a2d237a4109b090 Binary files /dev/null and b/doc/service_design/examples/ExposingCRDs_aaS_Example_Calculator/img13.png differ diff --git a/doc/service_design/examples/ExposingCRDs_aaS_Example_Calculator/img13_1.png b/doc/service_design/examples/ExposingCRDs_aaS_Example_Calculator/img13_1.png new file mode 100644 index 0000000000000000000000000000000000000000..f3d019ce3704a7397b9b5049022362dd1b8bc32a Binary files /dev/null and b/doc/service_design/examples/ExposingCRDs_aaS_Example_Calculator/img13_1.png differ diff --git a/doc/service_design/examples/ExposingCRDs_aaS_Example_Calculator/img14.png b/doc/service_design/examples/ExposingCRDs_aaS_Example_Calculator/img14.png new file mode 100644 index 0000000000000000000000000000000000000000..570933dcd05ec67463254237a008515e098699eb Binary files /dev/null and b/doc/service_design/examples/ExposingCRDs_aaS_Example_Calculator/img14.png differ diff --git a/doc/service_design/examples/ExposingCRDs_aaS_Example_Calculator/img15.png b/doc/service_design/examples/ExposingCRDs_aaS_Example_Calculator/img15.png new file mode 100644 index 0000000000000000000000000000000000000000..4e35c0818e4daae0f500ccb0bab4181a5310c4d6 Binary files /dev/null and b/doc/service_design/examples/ExposingCRDs_aaS_Example_Calculator/img15.png differ diff --git a/doc/service_design/examples/ExposingCRDs_aaS_Example_Calculator/img16.png b/doc/service_design/examples/ExposingCRDs_aaS_Example_Calculator/img16.png new file mode 100644 index 0000000000000000000000000000000000000000..11cd78e7cb200ee0506f09a681b01b41331de5bb Binary files /dev/null and b/doc/service_design/examples/ExposingCRDs_aaS_Example_Calculator/img16.png differ diff --git a/doc/service_design/examples/ExposingCRDs_aaS_Example_Calculator/img17.png b/doc/service_design/examples/ExposingCRDs_aaS_Example_Calculator/img17.png new file mode 100644 index 0000000000000000000000000000000000000000..d11c3c47217474cc72f95a746bbb71c5f913b840 Binary files /dev/null and b/doc/service_design/examples/ExposingCRDs_aaS_Example_Calculator/img17.png differ diff --git a/doc/service_design/examples/ExposingCRDs_aaS_Example_Calculator/img18.png b/doc/service_design/examples/ExposingCRDs_aaS_Example_Calculator/img18.png new file mode 100644 index 0000000000000000000000000000000000000000..5dfc8b9a5f7afdfcc63df9ac3c62e2d5f367d28f Binary files /dev/null and b/doc/service_design/examples/ExposingCRDs_aaS_Example_Calculator/img18.png differ diff --git a/doc/service_design/examples/ExposingCRDs_aaS_Example_Calculator/img19.png b/doc/service_design/examples/ExposingCRDs_aaS_Example_Calculator/img19.png new file mode 100644 index 0000000000000000000000000000000000000000..ad9d34b5396d69f7654447e4ee74331386adb2a5 Binary files /dev/null and b/doc/service_design/examples/ExposingCRDs_aaS_Example_Calculator/img19.png differ diff --git a/doc/service_design/examples/ExposingCRDs_aaS_Example_Calculator/img20.png b/doc/service_design/examples/ExposingCRDs_aaS_Example_Calculator/img20.png new file mode 100644 index 0000000000000000000000000000000000000000..be0c6f94c46cfb6d0a5024115ebbe9200ae8812a Binary files /dev/null and b/doc/service_design/examples/ExposingCRDs_aaS_Example_Calculator/img20.png differ diff --git a/doc/service_design/examples/helmInstallation_aaS_Example_Jenkins/HELM_Installation_aaS_Jenkins_Example.md b/doc/service_design/examples/helmInstallation_aaS_Example_Jenkins/HELM_Installation_aaS_Jenkins_Example.md new file mode 100644 index 0000000000000000000000000000000000000000..2a865e1ec32b362e6c75b46a12c67729292732be --- /dev/null +++ b/doc/service_design/examples/helmInstallation_aaS_Example_Jenkins/HELM_Installation_aaS_Jenkins_Example.md @@ -0,0 +1,173 @@ +# Example: Offer Jenkins as a Service via Openslice + +## Design the Jenkins (Resource-Facing) Service + +Before reading this example please make sure that you went through the [Design Helm as a Service](../design_helmaas.md) + +In this example, we will use the ```Kind: Application``` of ArgoCD and create a ResourceFacingServiceSpecification (RFSS) for Jenkins. Eventually, we will offer Jenkins as a Service. + + 1. Go to Service Specifications + 2. Create New Specification + 3. Provide a Name, eg. jenkinsrfs + 4. Go to Resource Specification Relationships + 5. Assign **Application@argoproj.io/v1alpha1@kubernetes@https://10.10.10.144:6443/** as a related Resource Specification + +> Please note that the *https://10.10.10.144:6443/* part of the Resource Specification's name will vary in different Kubernetes environments. + + +![img02.png](./img02.png) + +Now, we shall focus on the Characteristics' configuration of the created Service Specification. This can be achieved from the the "Service Specification Characteristics" tab. + +Specifically, we need to map the lifecycle of ArgoCD Application (e.g. Progressing, Healthy, etc.) to TMF Resource State (e.g. reserved, active, etc.). + +In ArgoCD, the field **status.health.status** has the value that we need to check (Healty, Progressing, etc) for the lifecycle of the application. This is captured by the **_CR_CHECK_FIELD** characteristic. + +Also, the different ArgoCD lifycycle states must be captured by the respective **_CR_CHECKVAL_xxx** characteristics, as show in the figure below: + +![img05.png](./img05.png) + + +After the state mapping, we must provide the template that ArgoCD will use to deploy the Jenkins HELM Chart as an ArgoCD application. For this, we must populate the **_CR_SPEC** characteristic. The _CR_SPEC can be designed first in a YAML or json editor for better parsing. + +Let's see a YAML definition: + +```yaml +apiVersion: argoproj.io/v1alpha1 +kind: Application +metadata: + finalizers: + - resources-finalizer.argocd.argoproj.io + name: openslice-jenkins + namespace: argocd +spec: + project: default + destination: + namespace: opencrdtest + name: in-cluster + source: + repoURL: https://charts.jenkins.io + targetRevision: 5.3.6 + chart: jenkins + helm: + values: | + controller: + serviceType: ClusterIP + persistence: + enabled: false + syncPolicy: + automated: + prune: true + selfHeal: true + allowEmpty: false + syncOptions: + - Validate=false + - CreateNamespace=true + - PrunePropagationPolicy=foreground + - PruneLast=true + - RespectIgnoreDifferences=true +``` +> **NOTE 1**: The above template assumes that the Jenkins Server will acquire a **ClusterIP**. The user should handle the external exposure and access of the Jenkins Server, depending on its cluster configuration. Also, **persistency of the data is disabled** to facilitate the deployment without the need to define storage classes and volumes, as this serves as an example. + +```yaml +helm: + values: | + controller: + serviceType: ClusterIP + persistence: + enabled: false +``` + +> **NOTE 2**: On each installation, OSOM will change the name of the resource in order to be unique (will have a UUID), instead of "openslice-jenkins". + +```yaml +name: openslice-jenkins +``` + +> **NOTE 3**: The namespace that ArgoCD will use to deploy the Jenkins HELM Chart is the "opencrdtest". + +```yaml +destination: + namespace: opencrdtest +``` + +**The latter implies that ArgoCD will always install Jenkins in the same namespace.** + +**To avoid this we will create a simple LCM rule (pre-provision) to change the namespace accordingly with a unique ID, generated with every new Service Order.** + +The LCM rule can be created from the "Life Cycle Rules" tab, pressing the "Create new rule" button. The following image contains the LCM rule that needs to be created for this purpose: + + +![img06.png](./img06.png) + + +Let's create it step-by-step: + +1. Drag-Drop the _CR_SPEC block (Set characteristic value) of jenkinsrfs from the Service > Text blocks +2. Drag-Drop the Text > Formatted text block and attach it after the block from the previous step +3. Drag-Drop the Text > Multi-line text input block and attach it at the Input(String) connector of the block from the previous text +4. Copy paste the previously provided YAML text +5. Change the spec:destination:namespace property to the value %s +6. Drag-Drop the Lists > Create list block, delete the 2 extra items (click the gear icon). Attach it at the Variables(Array) connector of the formatted text block from the previous step. +7. Drag-Drop the Service > Context > Current Service Order block and select the ID from the drop-down menu. Attach it to the List block of the previous step. +8. Save the PRE_PROVISION Rule + +## Expose the Jenkins (Customer-Facing) Service to the users + +To expose a service towards the users, the designer must create the respective CustomerFacingServiceSpecification, by using the previously designed RFSS as a related service. + +1. Go to Service Specifications +2. Create New Specification +3. Create a Jenkins service, mark as Bundle (to enable Service Specification Relationships) and save it +4. Go to the "Service Specification Relationships" tab and assign Jenkinsrfs +5. (Optionally) Add a logo, from the respective "Logo" tab, if you wish + +![img03.png](./img03.png) + +![img04.png](./img04.png) + + +Next, the designer must expose it through an already created Service Catalog and Service Category so as to make it visible to the users, thus available for ordering. + +![img061.png](./img061.png) + + + + +## Order the Jenkins Service + +Order the service from the previously assigned Service Catalog > Service Category. + +As soon as the Service Order is in **ACKNOWLEDGED** state (may require user intervention as the initial Service Order state is "INITIAL"), it will be processed and eventually completed rendering the services active, as seen in the figure below: + + +![img07.png](./img07.png) + +## Access the Jenkins installation + +Starting from the Service Order overview and specifically the Order Item #1 tab > Supporting Services, select the ResourceFacingService (jenkinsrfs). + +Accordingly, the ResourceFacingService has supporting resources from the resource inventory. The latter are available through the "Supporting Resources" tab. + + +![img08.png](./img08.png) + +The supporting resources of the Jenkins service are: + +- A resource reference to the application (e.g. _cr_tmpname_...) +- A secret resource (e.g. cr87893...). + +Select the secret resource, which will navigate you to the Resource Inventory page of OpenSlice. There, you may find the login credentials encoded as Base64. + +![img09.png](./img09.png) + +Use a Base64 decoder to parse the credentials and use them to login in your Jenkins installation, through the exposed Jenkis Server UI. + + +> Exposing Jenkins externally is a matter of cluster configuration and request (nodeport, load balancing, etc), thus is not a topic for this example + + + + + + diff --git a/doc/service_design/examples/helmInstallation_aaS_Example_Jenkins/img01.png b/doc/service_design/examples/helmInstallation_aaS_Example_Jenkins/img01.png new file mode 100644 index 0000000000000000000000000000000000000000..bbe29df97934dd4438f39f2f3e0e0e443ba0e4d3 Binary files /dev/null and b/doc/service_design/examples/helmInstallation_aaS_Example_Jenkins/img01.png differ diff --git a/doc/service_design/examples/helmInstallation_aaS_Example_Jenkins/img02.png b/doc/service_design/examples/helmInstallation_aaS_Example_Jenkins/img02.png new file mode 100644 index 0000000000000000000000000000000000000000..c3719c6c04d5e04fc126d5d8388e8862a524ba2b Binary files /dev/null and b/doc/service_design/examples/helmInstallation_aaS_Example_Jenkins/img02.png differ diff --git a/doc/service_design/examples/helmInstallation_aaS_Example_Jenkins/img03.png b/doc/service_design/examples/helmInstallation_aaS_Example_Jenkins/img03.png new file mode 100644 index 0000000000000000000000000000000000000000..fa3d7327fa68743d247aef9842ace2262cdeb84e Binary files /dev/null and b/doc/service_design/examples/helmInstallation_aaS_Example_Jenkins/img03.png differ diff --git a/doc/service_design/examples/helmInstallation_aaS_Example_Jenkins/img04.png b/doc/service_design/examples/helmInstallation_aaS_Example_Jenkins/img04.png new file mode 100644 index 0000000000000000000000000000000000000000..8a6c0bf1deb000fc1fd494317bbe0a318eb1d3e5 Binary files /dev/null and b/doc/service_design/examples/helmInstallation_aaS_Example_Jenkins/img04.png differ diff --git a/doc/service_design/examples/helmInstallation_aaS_Example_Jenkins/img05.png b/doc/service_design/examples/helmInstallation_aaS_Example_Jenkins/img05.png new file mode 100644 index 0000000000000000000000000000000000000000..a505d800a71024148fe04533d15d7c26d0f1a75f Binary files /dev/null and b/doc/service_design/examples/helmInstallation_aaS_Example_Jenkins/img05.png differ diff --git a/doc/service_design/examples/helmInstallation_aaS_Example_Jenkins/img06.png b/doc/service_design/examples/helmInstallation_aaS_Example_Jenkins/img06.png new file mode 100644 index 0000000000000000000000000000000000000000..2089e793a2c668e24dab0597c7c2965700b57f5f Binary files /dev/null and b/doc/service_design/examples/helmInstallation_aaS_Example_Jenkins/img06.png differ diff --git a/doc/service_design/examples/helmInstallation_aaS_Example_Jenkins/img061.png b/doc/service_design/examples/helmInstallation_aaS_Example_Jenkins/img061.png new file mode 100644 index 0000000000000000000000000000000000000000..f2dcdf951f264b1164804fba435449ad176e8da7 Binary files /dev/null and b/doc/service_design/examples/helmInstallation_aaS_Example_Jenkins/img061.png differ diff --git a/doc/service_design/examples/helmInstallation_aaS_Example_Jenkins/img07.png b/doc/service_design/examples/helmInstallation_aaS_Example_Jenkins/img07.png new file mode 100644 index 0000000000000000000000000000000000000000..d3bced145f17fc2804b6f36ab1a4919ff3ec656a Binary files /dev/null and b/doc/service_design/examples/helmInstallation_aaS_Example_Jenkins/img07.png differ diff --git a/doc/service_design/examples/helmInstallation_aaS_Example_Jenkins/img08.png b/doc/service_design/examples/helmInstallation_aaS_Example_Jenkins/img08.png new file mode 100644 index 0000000000000000000000000000000000000000..979adc4d20afd24eb0aabf78f72171b26e8ef25e Binary files /dev/null and b/doc/service_design/examples/helmInstallation_aaS_Example_Jenkins/img08.png differ diff --git a/doc/service_design/examples/helmInstallation_aaS_Example_Jenkins/img09.png b/doc/service_design/examples/helmInstallation_aaS_Example_Jenkins/img09.png new file mode 100644 index 0000000000000000000000000000000000000000..06b8306a2416fc3a15110672b2971ddada0b4d69 Binary files /dev/null and b/doc/service_design/examples/helmInstallation_aaS_Example_Jenkins/img09.png differ diff --git a/doc/service_design/examples/intro.md b/doc/service_design/examples/intro.md new file mode 100644 index 0000000000000000000000000000000000000000..1c763ca2ba4356cc6b1bfe8e3b4d336ffa03a819 --- /dev/null +++ b/doc/service_design/examples/intro.md @@ -0,0 +1 @@ +This section contains examples on service design, which contain a step-by-step guide to reproduce them in your local environment. \ No newline at end of file diff --git a/doc/service_design/intro.md b/doc/service_design/intro.md new file mode 100644 index 0000000000000000000000000000000000000000..d3ba61cdacab1d4f0ba837cbb228eed7bb126890 --- /dev/null +++ b/doc/service_design/intro.md @@ -0,0 +1,18 @@ +# Service Design in OpenSlice + +This section offers details on how to design Service Specifications and expose them in Service Catalogs + +## Intended Audience: Service Designers + +Service Designers create detailed service specifications, which are then managed and exposed in service catalogs. These services are integrated into OpenSlice E2E service orchestration framework to automate and optimize the delivery of network services. + + +OpenSlice can be used to design service specifications for various services, even not networking related services. Here we cover how service designers can expose services related to the NFV world and the containerized world. + +## Probe further + +* [Design and expose services based on containerized resources via the Kubernetes Operator pattern](./kubernetes/ExposingKubernetesResources.md) +* [Design and expose services based on NFV artifacts](./nfv/design_nfv_services.md) + + + diff --git a/doc/service_design/kubernetes/ExposingKubernetesResources.md b/doc/service_design/kubernetes/ExposingKubernetesResources.md new file mode 100644 index 0000000000000000000000000000000000000000..ade87388eb2de2f30ab269624f72f2b264040071 --- /dev/null +++ b/doc/service_design/kubernetes/ExposingKubernetesResources.md @@ -0,0 +1,169 @@ + +# Expose and manage Kubernetes Custom Resource Definitions (Operators) in a Kubernetes Cluster + +OpenSlice is capable of exposing Kubernetes Resources and Definitions as Service Specifications + +## Intended Audience: Service Designers + + > Kubernetes is an orchestration system for automating software deployment, scaling, and management. One can interact though the Kubernetes API and it has a set of objects ready for use out of the box. Custom Resource Definitions (CRDs) is a way that allows to manage things other than Kubernetes itself and allows to create our own objects The use of CRDs makes the possibilities of Kubernetes management almost limitless. You can extend the base Kubernetes API with any object you like using CRDs. + + > By allowing the design and lifecycle management of services/resources that expose CRDs/CRs in a Kubernetes cluster via the TMF APIs, OSL can be used in many complex scenarios now involing resources from multiple domains. + + +1. OpenSlice is capable to: + - Create and manage Custom Resources (CRs) using installed CRDs on a target Kubernetes cluster. + - Facilitate complex orchestration scenarios by wrapping Kubernetes APIs as TMF APIs and models. + - Handles connectivity to a Kubernetes cluster and manages the lifecycle of CRDs + - Wraps the Kubernetes API, Receives and provides resources towards other OpenSlice services via the service bus + +2. Enabling Loose Coupling and Orchestration + - Language Flexibility: Developers can write CRDs in any language and expose them via the Kubernetes APIs. OSL will reuse these CRDs, enhancing flexibility and integration capabilities. + - Familiar Deployment: Developers can create and deploy applications using familiar tools such as Helm charts, simplifying the process and reducing the learning curve. + +3. Ecosystem Reusability + - OpenSlice capitalizes on the extensive Kubernetes ecosystem, particularly focusing on operators (CRDs). + - Key repositories and hubs such as artifacthub.io and Operatorhub.io can be utilized for finding and deploying operators. + +4. Service Catalog Exposure and Deployment + - OpenSlice can expose CRs in service catalogs, facilitating their deployment in complex scenarios. + - These scenarios may include service bundles that involve multiple systems, such as RAN controllers or other Kubernetes clusters, providing a robust and versatile deployment framework. + +# Approach + + > OpenSlice in general is responible for exposing service specifications which are ready to be ordered and orchestrated, through tmforum Open APIs as defined in the OSL Service Spec Catalog. Usually for a service specification a corresponding (one or more) resource specification (resourceSpecificationReference) is registered in the OSL Resource Spec Catalog. + +The following image illustrates the approach. + + +![img01.png](./img01.png) + +1. A CRD in a cluster will be mapped in TMF model as a Resource specification and therefore can be exposed as a service specification in a catalog +2. Service Orders can be created for this service specification. +3. OSOM creates a Resource in OSL Resource inventory and requests new Custom Resource (CR) in the target cluster + - The resource is created in a specific namespace (for example the UUID of the Service Order) + - A CR in a cluster will be mapped in TMF model as a Resource in the resource Inventory + - Other related resources created by the CRD Controller within the namespace are automatically created in OSL Resource Inventory under the same Service Order + + +# Awareness for CRDs and CRs in cluster + +> CRDs and CRs can appear (disappear) or change status at any time in a cluster. OpenSlice Resource Inventory need to be aware of these events. + + When installing OpenSlice you can configure at least one management cluster. OpenSlice connects via a provided kubeconf + +- On Start up OSL tries to register this cluster and context to OSL catalogs. +- After the registration of this cluster as a Resource in OSL OSL is always aware of all CRDs and their CRs in the cluster, even if a CRD or CR is added/updated/deleted in the K8S cluster outside of OSL +- Resources created by OpenSlice have labels, e.g. (org.etsi.osl.*) + +# Expose CRDs as Service Specifications in OpenSlice catalogs + +**A CRD by default is exposed as a Resource Specification** + +To ensure unique names across the clusters that OpenSlice can manage, the name of a CRD is constructed as follows: + +```Kind @ ApiGroup/version @ ContextCluster @ masterURL``` + +For example you might see resource Specifications like: + + - ```Application@argoproj.io/v1alpha1@kubernetes@https://10.10.10.144:6443/``` + - ```IPAddressPool@metallb.io/v1beta1@kubernetes@https://10.10.10.144:6443/``` + - ```Provider@pkg.crossplane.io/v1@kubernetes@https://10.10.10.144:6443/``` + +All attributes of the CRD are translated into characteristics + +The following specific characteristics are **added**: + + - _CR_SPEC: Used for providing the json Custom Resource description to apply + - _CR_CHECK_FIELD: Used for providing the field that need to be checked for the resource status + - _CR_CHECKVAL_STANDBY: Used for providing the equivalent value from resource to signal the standby status + - _CR_CHECKVAL_ALARM: Used for providing the equivalent value from resource to signal the alarm status + - _CR_CHECKVAL_AVAILABLE: Used for providing the equivalent value from resource to signal the available status + - _CR_CHECKVAL_RESERVED: Used for providing the equivalent value from resource to signal the reserved status + - _CR_CHECKVAL_UNKNOWN: Used for providing the equivalent value from resource to signal the unknown status + - _CR_CHECKVAL_SUSPENDED: Used for providing the equivalent value from resource to signal the suspended status + + +1. Create a new Service Specification and use this Resource Specification in Resource Specification Relationships + - Then the Service Specification is saved as ResourceFacingServiceSpecification + + 1.1. You can give at this stage values to the characteristics: + + - _CR_SPEC, + - _CR_CHECK_FIELD + - _CR_CHECKVAL_STANDBY + - _CR_CHECKVAL_ALARM + - _CR_CHECKVAL_AVAILABLE + - _CR_CHECKVAL_RESERVED + - _CR_CHECKVAL_UNKNOWN + - _CR_CHECKVAL_SUSPENDED + + 1.2. You can now create LCM rules if you wish + +2. Create a new Service Specification and use the Resource Facing Service Specification in Service Specification Relationships + - Then the Service Specification is saved as CustomerFacingServiceSpecification + + 2.1. You can give at this stage values to the characteristics: + + - _CR_SPEC, + - _CR_CHECK_FIELD + - _CR_CHECKVAL_STANDBY + - _CR_CHECKVAL_ALARM + - _CR_CHECKVAL_AVAILABLE + - _CR_CHECKVAL_RESERVED + - _CR_CHECKVAL_UNKNOWN + - _CR_CHECKVAL_SUSPENDED + + 2.2. You We can create LCM rules for this new Service Specification + + 2.3. You Expose configurable values for users to configure during service order + +![img06.png](./img06.png) + +# Service Orchestration and CRDs/CRs + +OSOM - OpenSlice Service Orchestrator, checks the presence of attribute _CR_SPEC at the RFS to make a request for a CR deployment + +- _CR_SPEC is a JSON or YAML string that is used for the request + - It is similar to what one will do with e.g. a kubectl apply + - There are tools to translate a yaml file to a json + +> LCM rules can be used to change attributes of this yaml/json file, before sending this for orchestration + + +## Mapping the CR lifecycle that is defined in the CRD with the OpenSLice (TMF-based) resource Lifecycle + +OpenSlice adds automatically as we see the following characteristics: + + - _CR_CHECK_FIELD + - _CR_CHECKVAL_STANDBY + - _CR_CHECKVAL_ALARM + - _CR_CHECKVAL_AVAILABLE + - _CR_CHECKVAL_RESERVED + - _CR_CHECKVAL_UNKNOWN + - _CR_CHECKVAL_SUSPENDED + +**These characteristics instrument OpenSlice services to manage and reflect the lifecycle of a kubernetes resource to OpenSlice's (TMF based) lifecycle** + + +- _CR_CHECK_FIELD: The name of the field that is needed to be monitored in order to monitor the status of the service and translate it to TMF resource statys (RESERVED AVAILABLE, etc) +- _CR_CHECKVAL_STANDBY: The CR specific value (of the CheckFieldName) that needs to me mapped to the TMF resource state STANDBY (see org.etsi.osl.tmf.ri639.model.ResourceStatusType) +- _CR_CHECKVAL_ALARM: The CR specific value (of the CheckFieldName) that needs to me mapped to the TMF resource state ALARMS (see org.etsi.osl.tmf.ri639.model.ResourceStatusType) +- _CR_CHECKVAL_AVAILABLE: The CR specific value (of the CheckFieldName) that needs to me mapped to the TMF resource state AVAILABLE (see org.etsi.osl.tmf.ri639.model.ResourceStatusType) +- _CR_CHECKVAL_RESERVED: The CR specific value (of the CheckFieldName) that needs to me mapped to the TMF resource state RESERVED (see org.etsi.osl.tmf.ri639.model.ResourceStatusType) +- _CR_CHECKVAL_UNKNOWN: The CR specific value (of the CheckFieldName) that needs to me mapped to the TMF resource state UNKNOWN (see org.etsi.osl.tmf.ri639.model.ResourceStatusType) +- _CR_CHECKVAL_SUSPENDED: The CR specific value (of the CheckFieldName) that needs to me mapped to the TMF resource state SUSPENDED (see org.etsi.osl.tmf.ri639.model.ResourceStatusType) + + +--- + +## Probe further + + + - See examples of exposing operators via OpenSlice: + - [Exposing Kubernetes Operators as a Service : Offering "Calculator as a Service" through OpenSlice](ExposingCRDs_aaS_Example_Calculator.md) + - [Learn more about CRIDGE, the service in OSL that manages CRDs/CRs](CRIDGEforDevelopers_Jenkins_Example.md) + + + + + diff --git a/doc/service_design/kubernetes/helm/design_helmaas.md b/doc/service_design/kubernetes/helm/design_helmaas.md new file mode 100644 index 0000000000000000000000000000000000000000..411910eacb6a72b489a9cad5a0a9e7e40248a9de --- /dev/null +++ b/doc/service_design/kubernetes/helm/design_helmaas.md @@ -0,0 +1,67 @@ +# Expose HELM charts as Service Specifications +Manage Helm charts installations via OpenSlice Service Specifications and Service Orders. +## Intended Audience: Service Designers + + +> Kubernetes is an orchestration system for automating software deployment, scaling, and management. One can interact though the Kubernetes API and it has a set of objects ready for use out of the box. + +> Helm is a tool that automates the creation, packaging, configuration, and deployment of Kubernetes applications by combining your configuration files into a single reusable package + +> At the heart of Helm is the packaging format called charts. Each chart comprises one or more Kubernetes manifests -- and a given chart can have child charts and dependent charts, as well. Using Helm charts: + +> - Reduces the complexity of deploying Microservices +> - Enhances deployment speed +> - Developers already know the technology + +> There are many Helm charts and Helm repositories there that are ready to be used + +> Enable loose coupling and more orchestration scenarios + +> Developers create and deploy applications in things they already know (e.g. Helm charts) + +> Use the TMF models as wrapper entities around Helm charts + + +Use OpenSlice to expose them in service catalogs and deploy them in complex scenarios (service bundles) involving also other systems: + + - Include e.g. RAN controllers, + - Pass values through life cycle rules from one service to another, + - Manage multiple Helms in multiple clusters + + +## The installation of HELM charts is based on OpenSlice CRD support + +Please read more [here](../ExposingKubernetesResources.md) + + +For installing HELM charts we will use ArgoCD a well known Kubernetes-native continuous deployment (CD) tool + +> ArgoCD is a Kubernetes-native continuous deployment (CD) tool + +> While just deploying Heml charts is just a scenario for ArgoCD , in future one can exploit it for many things + +> Despite some other tools like FluxCD, it provides also a UI which is useful for management and troubleshooting + + +We will mainly use the CRD of ```Kind: Application``` that ArgoCD can manage + + + +Before proceeding, install ArgoCD in your management cluster, by following ArgoCD instructions + +As soon as you install ArgoCD, OpenSlice is automatically aware for specific new Kinds. The one we will use is is the ```Kind: Application``` that ArgoCD can manage under the apiGroup argoproj.io + +Browse to Resource Specifications. You will see an entry like the following: + +```Application@argoproj.io/v1alpha1@kubernetes@https://10.10.10.144:6443/``` + +see image: + +![img01.png](./img01.png) + + + +## What's next + + +See the [Example: Offer Jenkins as a Service via Openslice](HELM_Installation_aaS_Jenkins_Example.md) diff --git a/doc/service_design/kubernetes/img01.png b/doc/service_design/kubernetes/img01.png new file mode 100644 index 0000000000000000000000000000000000000000..d9f6f73dd21ff94572fd411c68e31a2915426f70 Binary files /dev/null and b/doc/service_design/kubernetes/img01.png differ diff --git a/doc/service_design/kubernetes/img02.png b/doc/service_design/kubernetes/img02.png new file mode 100644 index 0000000000000000000000000000000000000000..fb546ad61cce1ce5c9cc593507f816ef64c7bcc5 Binary files /dev/null and b/doc/service_design/kubernetes/img02.png differ diff --git a/doc/service_design/kubernetes/img03.png b/doc/service_design/kubernetes/img03.png new file mode 100644 index 0000000000000000000000000000000000000000..79d0d2a208ca3c63489264a87d4a155d44d12cc4 Binary files /dev/null and b/doc/service_design/kubernetes/img03.png differ diff --git a/doc/service_design/kubernetes/img04.png b/doc/service_design/kubernetes/img04.png new file mode 100644 index 0000000000000000000000000000000000000000..233831d1bb986c92432fdaff602db44fc2c0df48 Binary files /dev/null and b/doc/service_design/kubernetes/img04.png differ diff --git a/doc/service_design/kubernetes/img05.png b/doc/service_design/kubernetes/img05.png new file mode 100644 index 0000000000000000000000000000000000000000..3b05561502893694d3d72d12cbbfc154786da853 Binary files /dev/null and b/doc/service_design/kubernetes/img05.png differ diff --git a/doc/service_design/kubernetes/img06.png b/doc/service_design/kubernetes/img06.png new file mode 100644 index 0000000000000000000000000000000000000000..ef8d3879cbb887e5ce686a246b981da14cb6e64c Binary files /dev/null and b/doc/service_design/kubernetes/img06.png differ diff --git a/doc/service_design/kubernetes/img07.png b/doc/service_design/kubernetes/img07.png new file mode 100644 index 0000000000000000000000000000000000000000..6990bf18122d41d5c3eee345270c4c18b5b0a1dc Binary files /dev/null and b/doc/service_design/kubernetes/img07.png differ diff --git a/doc/service_design/kubernetes/img08.png b/doc/service_design/kubernetes/img08.png new file mode 100644 index 0000000000000000000000000000000000000000..fdb27bf11096f00458a89586ae5efc2cb8e162b8 Binary files /dev/null and b/doc/service_design/kubernetes/img08.png differ diff --git a/doc/service_design/kubernetes/img09.png b/doc/service_design/kubernetes/img09.png new file mode 100644 index 0000000000000000000000000000000000000000..a6b963879355580e242b02b10e007e1434fdceb3 Binary files /dev/null and b/doc/service_design/kubernetes/img09.png differ diff --git a/doc/service_design/kubernetes/img10.png b/doc/service_design/kubernetes/img10.png new file mode 100644 index 0000000000000000000000000000000000000000..73d0ef7c9aaa5e56098c5fca4420fd6c50b8cd2a Binary files /dev/null and b/doc/service_design/kubernetes/img10.png differ diff --git a/doc/service_design/kubernetes/intro.md b/doc/service_design/kubernetes/intro.md new file mode 100644 index 0000000000000000000000000000000000000000..8fad353e29bd24d4024b51c016caadb056f12b86 --- /dev/null +++ b/doc/service_design/kubernetes/intro.md @@ -0,0 +1,3 @@ +# OpenSlice and support for kubernetes + +This section contains information on how Service Designers can expose Kubernetes resources as services \ No newline at end of file diff --git a/doc/service_design/lcmrules/examples.md b/doc/service_design/lcmrules/examples.md new file mode 100644 index 0000000000000000000000000000000000000000..52065b0742c5cd841f154b145ce2582baa3fd897 --- /dev/null +++ b/doc/service_design/lcmrules/examples.md @@ -0,0 +1,79 @@ +# Examples of Rules + + +The following images provide some examples of rules. + +### Define variables according to cases + +In the following example we : + +* define a String variable. +* Then according to the Area of Service selected from the Service Order of the Service Specification we need to define it properly. +* We output the value to the OSOM Log +* Define dynamically the value of another parameter (This is fictional) and then do some other condition check + +The strAreaCodes could be passed then e.g. to NFVO for instantiation of services to these cells. + + +[![lcmrules](./images/lcm/lcmfig9.png)](./images/lcm/lcmfig9.png) + + + + +### Define Rules to create a resource for a Kubernetes Operator + +* Modify the _CR_SPEC characteristic +* Add an "Input with variables block" +* Add a multiline Text block +* Mark with %s, %d, etc the parameters to modify with some action +* Add a list with the variables and their values + +in the example we modify a YAML spec with parama, paramb, action values from the characteristics spec.parama, spec.paramb, spec.action + +[![lcmrules](./images/lcm/lcmfig15.png)](./images/lcm/lcmfig15.png) + + +### Define complex OSM configs for DAY 0 + +The following displays some complex examples for defining the parameters to pass to the NFV. In this case is OSM. + +* NOTE: The OSM_CONFIG characteristic of a service is the one that it is used in orchestration to instantiate NS from OSM + +* check the variable strTargetsParam. It is passed to the variable strOsmConfig3 which is executed if the Number of Cameras is more than 100. +* if the Video quality requested is 3, then the Maximum Namber of camers will be 8. Check the OSM detailed configuration block and its syntax. +* if the Video quality requested is 2, we use a simpler OSM Config block to configure the parameter OSM_CONFIG. We just injected a json text ( watch the Escape of the string for the Quotes!) +* if the Video quality requested is 1, again we use a simpler OSM Config block to configure the parameter OSM_CONFIG. We use as injected json text a variable constructed later + + +[![lcmrules](./images/lcm/lcmfig10.png)](./images/lcm/lcmfig10.png) + + +### Define and instantiate different services according to Service Order request + +In the following example we would like to offer a service either as Platinum, Gold or Silver. Depending on the selection we need to instantiate different services. + +There are different ways to accomplish this: + +* create dynamically New Service Orders of RFSs with equivalent quality of Services +* change for example the VIMs that you deploy the NS +* change the NSD (that is use different VNFs) + +The following image displays for example the latter case. + +[![lcmrules](./images/lcm/lcmfig11.png)](./images/lcm/lcmfig11.png) + + +### Call an external RESTful service + +This is useful in cases for example of alarms , external logging, calling other services e.g. email or even a complex algorithm written in other language e.g. call an external service and get a result. (service e.g. a Python service) + + +[![lcmrules](./images/lcm/lcmfig12.png)](./images/lcm/lcmfig12.png) + +[![lcmrules](./images/lcm/lcmfig13.png)](./images/lcm/lcmfig13.png) + +### Create New Service Orders + +The following example calls to Order a New Service Specification with specific Parameter Values + +[![lcmrules](./images/lcm/lcmfig14.png)](./images/lcm/lcmfig14.png) \ No newline at end of file diff --git a/doc/images/lcm/lcmfig1.png b/doc/service_design/lcmrules/images/lcm/lcmfig1.png similarity index 100% rename from doc/images/lcm/lcmfig1.png rename to doc/service_design/lcmrules/images/lcm/lcmfig1.png diff --git a/doc/images/lcm/lcmfig10.png b/doc/service_design/lcmrules/images/lcm/lcmfig10.png similarity index 100% rename from doc/images/lcm/lcmfig10.png rename to doc/service_design/lcmrules/images/lcm/lcmfig10.png diff --git a/doc/images/lcm/lcmfig11.png b/doc/service_design/lcmrules/images/lcm/lcmfig11.png similarity index 100% rename from doc/images/lcm/lcmfig11.png rename to doc/service_design/lcmrules/images/lcm/lcmfig11.png diff --git a/doc/images/lcm/lcmfig12.png b/doc/service_design/lcmrules/images/lcm/lcmfig12.png similarity index 100% rename from doc/images/lcm/lcmfig12.png rename to doc/service_design/lcmrules/images/lcm/lcmfig12.png diff --git a/doc/images/lcm/lcmfig13.png b/doc/service_design/lcmrules/images/lcm/lcmfig13.png similarity index 100% rename from doc/images/lcm/lcmfig13.png rename to doc/service_design/lcmrules/images/lcm/lcmfig13.png diff --git a/doc/images/lcm/lcmfig14.png b/doc/service_design/lcmrules/images/lcm/lcmfig14.png similarity index 100% rename from doc/images/lcm/lcmfig14.png rename to doc/service_design/lcmrules/images/lcm/lcmfig14.png diff --git a/doc/service_design/lcmrules/images/lcm/lcmfig15.png b/doc/service_design/lcmrules/images/lcm/lcmfig15.png new file mode 100644 index 0000000000000000000000000000000000000000..0005c110adce2a14ba143ee54b46e948d4f81c19 Binary files /dev/null and b/doc/service_design/lcmrules/images/lcm/lcmfig15.png differ diff --git a/doc/images/lcm/lcmfig1_osom.png b/doc/service_design/lcmrules/images/lcm/lcmfig1_osom.png similarity index 100% rename from doc/images/lcm/lcmfig1_osom.png rename to doc/service_design/lcmrules/images/lcm/lcmfig1_osom.png diff --git a/doc/images/lcm/lcmfig2.png b/doc/service_design/lcmrules/images/lcm/lcmfig2.png similarity index 100% rename from doc/images/lcm/lcmfig2.png rename to doc/service_design/lcmrules/images/lcm/lcmfig2.png diff --git a/doc/images/lcm/lcmfig3.png b/doc/service_design/lcmrules/images/lcm/lcmfig3.png similarity index 100% rename from doc/images/lcm/lcmfig3.png rename to doc/service_design/lcmrules/images/lcm/lcmfig3.png diff --git a/doc/images/lcm/lcmfig4.png b/doc/service_design/lcmrules/images/lcm/lcmfig4.png similarity index 100% rename from doc/images/lcm/lcmfig4.png rename to doc/service_design/lcmrules/images/lcm/lcmfig4.png diff --git a/doc/images/lcm/lcmfig5.png b/doc/service_design/lcmrules/images/lcm/lcmfig5.png similarity index 100% rename from doc/images/lcm/lcmfig5.png rename to doc/service_design/lcmrules/images/lcm/lcmfig5.png diff --git a/doc/images/lcm/lcmfig6.png b/doc/service_design/lcmrules/images/lcm/lcmfig6.png similarity index 100% rename from doc/images/lcm/lcmfig6.png rename to doc/service_design/lcmrules/images/lcm/lcmfig6.png diff --git a/doc/images/lcm/lcmfig7.png b/doc/service_design/lcmrules/images/lcm/lcmfig7.png similarity index 100% rename from doc/images/lcm/lcmfig7.png rename to doc/service_design/lcmrules/images/lcm/lcmfig7.png diff --git a/doc/images/lcm/lcmfig8.png b/doc/service_design/lcmrules/images/lcm/lcmfig8.png similarity index 100% rename from doc/images/lcm/lcmfig8.png rename to doc/service_design/lcmrules/images/lcm/lcmfig8.png diff --git a/doc/images/lcm/lcmfig9.png b/doc/service_design/lcmrules/images/lcm/lcmfig9.png similarity index 100% rename from doc/images/lcm/lcmfig9.png rename to doc/service_design/lcmrules/images/lcm/lcmfig9.png diff --git a/doc/service_design/lcmrules/intro.md b/doc/service_design/lcmrules/intro.md new file mode 100644 index 0000000000000000000000000000000000000000..651f83c8b5526a6775c09e1d1d4ca2f4a5727c17 --- /dev/null +++ b/doc/service_design/lcmrules/intro.md @@ -0,0 +1,99 @@ +# LCM Rules introduction + + +Lifecycle Management Rules: Defining complex conditions and actions during the lifecycle of a service and any necessary modifications throughout the service lifecycle. + + +## Intended Audience: Service Designers + +In [Naas LCM Introduction](../../naas/lcm_intro.md) it was presented briefly the LCM Rules concept. + +This section goes deeply on how Service Designers can use them. + + + +LCM Rules are used for defining complex conditions and actions during the lifecycle of a service. In Openslice there are four types of rules defined: + +* PRE_PROVISION +* CREATION +* AFTER_ACTIVATION +* SUPERVISION +* AFTER_DEACTIVATION + + +The following figure displays the different phases that the rules are performed, during the lifecycle of a Network Slice Instance. + +[![Rules in NSI](./images/lcm/lcmfig1.png)](./images/lcm/lcmfig1.png) + +* PRE_PROVISION rules: Run only once just before creating a service with a given priority. +* CREATION rules: Run while the referenced service dependencies of a service are created +* AFTER_ACTIVATION rules: Run only once just after a service get the ACTIVE state +* SUPERVISION rules: Run when a characteristic of a service is changed and the service is in the ACTIVE state +* AFTER_DEACTIVATION rules: Run only once just after a service get the INACTIVE/TERMINATED state + +In general the rules allow to perform many actions during service LCM. Thes are some examples: + +* Modify service specification parameters before the instantiation of a service (or during operation) based on other dependencies. These parameters might be part of other services already included in Service order +* Translate GST/NEST parameter values to other values passed later to NFVO for instantiation or control +* Define complex OSM Configs based on other dependencies and passing variables +* Define any dependencies when creating the referenced services +* Dynamically include new service dependencies +* Create new service orders so include dynamically other services +* Call external (RESTful) services (via http(s), define payload, examine response) + + + + +## Examine if the rules are executed successfully + +Rules are transformed automatically to executable code (currently is Java). If a rule is performed successfully or has any issues (e.g. unexpected syntax errors or exceptions) appear in OSOM logfiles and also tey are attached as Notes to the running Service. + +## LCM Rules and OSOM Service Orchestration + +OSOM is the responsible service for executing the rules on a specific phase. The following image explains the design in the BPMN phases: + + +[![Rules](./images/lcm/lcmfig1_osom.png)](./images/lcm/lcmfig1_osom.png) + + + +## Define rules + +Rules are defined when designing a Service Spec. Here is an example of a list of rules: + + +[![lcmrules](./images/lcm/lcmfig2.png)](./images/lcm/lcmfig2.png) + +Execution order of rules on a specific phase is random + +* NOTE: There is a priority field. The lower the number the highest the priority of rule execution. For example Rule with priority 0 will run before rule with priority 1. + + +### Definition language + +* The visual language that Openslice used is based on Google's Blockly (see https://developers.google.com/blockly) +* The blockly graph is automatically translated to Java internally and then dynamically executed during orchestration phases. + +The following figure is an example of such a rule design. The rule for example will run in PRE_PROVISION phase: + +[![lcmrules](./images/lcm/lcmfig3.png)](./images/lcm/lcmfig3.png) + +* The goal of the above rule is to properly define a variable AreaCodes given the chosen AreaOfService from a Service Order. +* On the right side the user can define some rule properties or observe the underlying generated java code. + + +## The blocks library + +See our [LCM Blocks specification](./specification.md) + + + + +## Probe further + +* Check our [examples](../examples/intro.md) for more usages +* See next the complete [specification](./specification.md) + + + + diff --git a/doc/lcmrules_main.pu b/doc/service_design/lcmrules/lcmrules_main.pu similarity index 100% rename from doc/lcmrules_main.pu rename to doc/service_design/lcmrules/lcmrules_main.pu diff --git a/doc/service_design/lcmrules/specification.md b/doc/service_design/lcmrules/specification.md new file mode 100644 index 0000000000000000000000000000000000000000..b89323f14dbf1551c403df86a7b38efb0e0cbb3c --- /dev/null +++ b/doc/service_design/lcmrules/specification.md @@ -0,0 +1,17 @@ + +# LCM Blocks specification + + +## Intended Audience: Service Designers + +The following images describe some blocks found in the library. + +Blockly has syntax rules. It helps with colours to define them. + +So for example a parameter that is a Number cannot be "glued" with a String. Will need some conversion first + +[![lcmrules](./images/lcm/lcmfig4.png)](./images/lcm/lcmfig4.png) +[![lcmrules](./images/lcm/lcmfig5.png)](./images/lcm/lcmfig5.png) +[![lcmrules](./images/lcm/lcmfig6.png)](./images/lcm/lcmfig6.png) +[![lcmrules](./images/lcm/lcmfig7.png)](./images/lcm/lcmfig7.png) +[![lcmrules](./images/lcm/lcmfig8.png)](./images/lcm/lcmfig8.png) diff --git a/doc/service_design/nfv/design_nfv_services.md b/doc/service_design/nfv/design_nfv_services.md new file mode 100644 index 0000000000000000000000000000000000000000..a376782caed3846b81cc0dcb45f3e5903d068a7f --- /dev/null +++ b/doc/service_design/nfv/design_nfv_services.md @@ -0,0 +1 @@ +_This section is WIP._ \ No newline at end of file diff --git a/doc/service_ordering/ordering_services.md b/doc/service_ordering/ordering_services.md new file mode 100644 index 0000000000000000000000000000000000000000..4041aa09440367caf7e861ba5dfc18c4c91d91f0 --- /dev/null +++ b/doc/service_ordering/ordering_services.md @@ -0,0 +1,5 @@ +# Service Ordering + +## Intended Audience: Users + +_This section is WIP._ \ No newline at end of file diff --git a/doc/terminology.md b/doc/terminology.md new file mode 100644 index 0000000000000000000000000000000000000000..c021048c7d57bf77db58d6dee32b0a4f348f44f9 --- /dev/null +++ b/doc/terminology.md @@ -0,0 +1,17 @@ +# User Roles + +* User +* Service Designer +* OpenSlice administrator + + +# Terms + +* Resource Facing Service Specification (RFSSpec): A Service that exposes a resource Specification as a Service. +* Customer Facing Service Specification (CFSSpec): Service exposed to users for Service Orders. Usually it exposes other CFSSpec(Service Bundle) or other RFSSpecs +* OpenSlice management cluster +* Service Specification: Detailed descriptions of services, including attributes, configurations, performance metrics, and SLAs. +* Service Catalog +* Service Categories +* Service Inventory + diff --git a/doc/under_construction.md b/doc/under_construction.md new file mode 100644 index 0000000000000000000000000000000000000000..387d132b2e2add5f8e68916e26935e7a7adb6ca6 --- /dev/null +++ b/doc/under_construction.md @@ -0,0 +1 @@ +under construction \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 2236d6a58e132d88d413d4b156c44b7b3ce958bf..cccde1c63bc8e0430e0d2b4c198df1aa62fb8a30 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -49,7 +49,7 @@ theme: repo: fontawesome/brands/gitlab # Copyright -copyright: "Copyright © 2019-2024 Openslice Project" +copyright: "Copyright © 2024 ETSI OSL" # Options extra: @@ -70,26 +70,91 @@ extra: # Page tree nav: - Overview: - - Introduction: index.md + - Introduction: index.md + - OpenSlice deployment examples: OpenSlice_deployment_examples.md + - History: history.md + - ETSI OSL: etsi_osl.md - Getting Started: - - Deployment/Installation: deployment.md + - Deployment: + - Introduction: deployment.md + - Docker Compose: deploymentCompose.md + - Kubernetes: deploymentK8s.md + - Portals: + - Introduction: portals_intro.md + - Configuration/Management: + - Introduction: config_intro.md + - Role/Keycloak management: role_keycloak_management.md - NFV Orchestrator Configuration: nfvoconfig.md - - Service Catalogs: catalogs.md - - NFV Catalogs: nfvcatalogs.md - - LCM Rules: lcm.md - - Consuming Services From External OSS: ./architecture/consumingServicesFromExternalPartners.md - - Service Inventory: service_inventory.md - - Alarms and Actions: alarms_actions.md + - Advanced topics: + - Consuming Services From External OSS: ./architecture/consumingServicesFromExternalPartners.md + - NaaS: + - Introduction: ./naas/introduction.md + - Services: + - Service Catalogs: ./naas/service_catalog.md + - Service Specification: ./naas/service_spec.md + - Service Ordering: ./naas/service_ordering.md + - Service Inventory: ./naas/service_inventory.md + - GSMA GST to TMF Service: ./naas/gst_to_tmf.md + - Resources: + - Resources Catalogs: ./naas/resource_catalog.md + - Resources Specification: ./naas/resource_spec.md + - Resources Inventory: ./naas/resource_inventory.md + - Service orchestration: + - Introduction: ./naas/so_intro.md + - Service Lifecycle management: ./naas/lcm_intro.md + - LCM Rules Introduction: ./naas/lcm_rules_intro.md + - From Service order to services/resources: + - Exposing Kubernetes services: ./naas/so_servicespec_to_services_kubernetes.md + - Exposing NFV Services: ./naas/so_servicespec_to_services_nfv.md + - Supported TMFORUM exposed APIs: ./naas/exposed_apis.md + - NFV support: + - Introduction: ./naas/nfv/intro.md + - NFV Services: ./naas/nfv/nfvservices.md + - Service design: + - Introduction: ./service_design/intro.md + - Catalogs: ./service_design/catalogs.md + - Support for Kubernetes: + - Introduction: ./service_design/kubernetes/intro.md + - Exposing Kubernetes Resources: ./service_design/kubernetes/ExposingKubernetesResources.md + - Design Helm as a Service: ./service_design/kubernetes/helm/design_helmaas.md + - Support for NFV: + - Design NFV Services: ./service_design/nfv/design_nfv_services.md + - LCM Rules: + - Introduction: ./service_design/lcmrules/intro.md + - Specification: ./service_design/lcmrules/specification.md + - Typical Examples: ./service_design/lcmrules/examples.md + - Service Specification Examples: + - Introduction: ./service_design/examples/intro.md + - Open5GS (NFV approach): ./service_design/examples/open5gs_nfv.md + - Open5GS (Kubernetes approach): ./service_design/examples/open5gs_kubernetes.md + - Exposing CRDs_aaS_Example_Calculator: ./service_design/examples/ExposingCRDs_aaS_Example_Calculator/ExposingCRDs_aaS_Example_Calculator.md + - HELM Installation aaS Jenkins Example: ./service_design\examples\helmInstallation_aaS_Example_Jenkins/HELM_Installation_aaS_Jenkins_Example.md + - Service Ordering: + - Ordering Services from catalogs: ./service_ordering/ordering_services.md + - Testing services: + - Testing Specification: ./testing_services/test_spec.md + - Testing Catalogs: ./testing_services/test_catalogs.md + - Testing Inventory: ./testing_services/test_inventory.md + - Service as a Product: + - Product Specification: ./product_model/product_spec.md + - Product Catalogs: ./product_model/product_catalogs.md + - Product Inventory: ./product_model/product_inventory.md + - Assurance services: + - Introduction: ./assurance_services/intro.md + - Alarms and Actions: ./assurance_services/alarms_actions.md - Design & Architecture: - Architecture: ./architecture/architecture.md + - Cloud native support: + - Introduction: ./architecture/CRIDGE_cloud_native_intro.md + - CRIDGE for Developers: ./architecture/CRIDGE/CRIDGEforDevelopers.md - Message bus: ./architecture/messagebus.md - OSOM: ./architecture/osom.md - Authentication: ./architecture/oauth.md - - TMF API: ./architecture/tmfapi.md - - NFV API: ./architecture/nfvapi.md - - TMF WEB: ./architecture/tmfweb.md - - NFV WEB: ./architecture/nfvweb.md + - APIs: + - TMF API: ./architecture/tmfapi.md + - NFV API: ./architecture/nfvapi.md - Issue management: ./architecture/issuemgt.md - Central logging: ./architecture/centrallog.md - - Contributing: - - Developing: ./contributing/developing.md + - Contributing to OSL: + - Developing: ./contributing/developing.md + - Terminology: terminology.md